myfaasmctl 0.0.1__py3-none-any.whl

faasmctl/__init__.py

@@ -0,0 +1,4 @@
+# flake8: noqa
+
+from . import tasks
+from . import util

faasmctl/bin/gen_proto_files.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+
+from os import environ, listdir, makedirs
+from os.path import dirname, exists, join, realpath
+from shutil import rmtree
+from sys import argv
+from subprocess import run
+
+FAASMCTL_ROOT = dirname(dirname(realpath(__file__)))
+
+# Unfortunately, we need to duplicate this constants here as we need to be
+# able to run this file in standalone mode, as if the proto files are not
+# generated, some imports in `faasmctl` will fail
+GEN_PROTO_DIR = join(FAASMCTL_ROOT, "util", "gen_proto")
+FAASM_CLI_IMAGE = "faasm.azurecr.io/cli"
+
+PROTO_FILES = [
+    "faabric_pb2.py",
+    "planner_pb2.py",
+]
+
+
+# We can not import faasmctl here
+def get_faasm_version():
+    ver_file = join(FAASMCTL_ROOT, "util", "faasm.py")
+    cmd = "cat {} | grep 'FAASM_VERSION =' | cut -d' ' -f3".format(ver_file)
+    version = (
+        run(cmd, shell=True, check=True, capture_output=True)
+        .stdout.decode("utf-8")
+        .strip()[1:-1]
+    )
+
+    return version
+
+
+def gen_proto_files(clean=False):
+    """
+    Generate python proto files to interact with the Faasm cluster
+    """
+    if clean:
+        rmtree(GEN_PROTO_DIR)
+
+    if not exists(GEN_PROTO_DIR):
+        makedirs(GEN_PROTO_DIR)
+
+    pb_files = [f for f in listdir(GEN_PROTO_DIR) if f.endswith("pb2.py")]
+    pb_files.sort()
+
+    if pb_files == PROTO_FILES:
+        return
+
+    if "FAASM_VERSION" in environ:
+        faasm_ver = environ["FAASM_VERSION"]
+    else:
+        faasm_ver = get_faasm_version()
+
+    print("Generating Faasm (v{}) protobuf files...".format(faasm_ver))
+    tmp_ctr_name = "faasm_gen_proto"
+    cm = "docker run -d -i --name {} {}:{}".format(
+        tmp_ctr_name, FAASM_CLI_IMAGE, faasm_ver
+    )
+    run(cm, shell=True, check=True)
+
+    # Find the right protoc binary
+    docker_exec_prefix = "docker exec {}".format(tmp_ctr_name)
+    find_protoc_cmd = "{} bash -c 'find ~/.conan -name protoc'".format(
+        docker_exec_prefix
+    )
+    protoc_bin = (
+        run(find_protoc_cmd, shell=True, capture_output=True)
+        .stdout.decode("utf-8")
+        .split("\n")
+    )
+    p_bin = [p_bin for p_bin in protoc_bin if "build_subfolder" in p_bin]
+    p_bin = p_bin[0].strip()
+
+    # Generate python protobuf files
+    code_dir = "/usr/local/code/faasm/faabric"
+    protoc_cmd = [
+        p_bin,
+        "--proto_path={}".format(code_dir),
+        "--python_out={}".format(code_dir),
+        "{}/src/planner/planner.proto".format(code_dir),
+        "{}/src/proto/faabric.proto".format(code_dir),
+    ]
+    protoc_cmd = " ".join(protoc_cmd)
+    docker_cmd = "{} bash -c '{}'".format(docker_exec_prefix, protoc_cmd)
+    run(docker_cmd, shell=True, check=True)
+
+    # Finally, copy the generated protobuf files to the desired location
+    for proto_file in PROTO_FILES:
+        if "planner" in proto_file:
+            proto_ctr_path = join(code_dir, "src", "planner", proto_file)
+        else:
+            proto_ctr_path = join(code_dir, "src", "proto", proto_file)
+        proto_faasmctl_path = join(GEN_PROTO_DIR, proto_file)
+
+        docker_cp_cmd = "docker cp {}:{} {}".format(
+            tmp_ctr_name, proto_ctr_path, proto_faasmctl_path
+        )
+        run(docker_cp_cmd, shell=True, check=True)
+
+    # Delete container
+    run("docker rm -f {}".format(tmp_ctr_name), shell=True, check=True)
+    print("Done generating protobuf files!")
+
+
+if __name__ == "__main__":
+    clean = len(argv) == 2 and argv[1] == "--clean"
+    gen_proto_files(clean)

faasmctl/main.py

@@ -0,0 +1,14 @@
+from invoke import Program
+from faasmctl.tasks import task_ns
+from faasmctl.util.version import get_version
+
+
+def main():
+    program = Program(
+        name="faasmctl",
+        binary="faasmctl",
+        binary_names=["faasmctl"],
+        namespace=task_ns,
+        version=get_version(),
+    )
+    program.run()

faasmctl/tasks/__init__.py

@@ -0,0 +1,29 @@
+from invoke import Collection
+
+from . import cli
+from . import delete
+from . import deploy
+from . import flush
+from . import generate
+from . import invoke
+from . import logs
+from . import monitor
+from . import restart
+from . import scale
+from . import status
+from . import upload
+
+task_ns = Collection(
+    cli,
+    delete,
+    deploy,
+    generate,
+    flush,
+    invoke,
+    logs,
+    monitor,
+    restart,
+    scale,
+    status,
+    upload,
+)

faasmctl/tasks/cli.py

@@ -0,0 +1,150 @@
+from faasmctl.util.compose import run_compose_cmd, wait_for_venv
+from faasmctl.util.config import (
+    BACKEND_INI_STRING,
+    get_faasm_ini_file,
+    get_faasm_ini_value,
+)
+from faasmctl.util.docker import get_docker_tag
+from invoke import task
+from os.path import abspath, exists
+from subprocess import run
+
+
+def do_run_cmd(cli, cmd, cp_in, cp_out, env, ini_file):
+    if not ini_file:
+        ini_file = get_faasm_ini_file()
+
+    backend = get_faasm_ini_value(ini_file, "Faasm", BACKEND_INI_STRING)
+    if backend == "compose":
+        # To run a command in a `compose` backend, we fist start the CLI
+        # container in dettached mode (if it does not exist yet) and then we
+        # exec into it, copying the ini file
+        up_cmd = "up -d --no-recreate {}".format(cli)
+        run_compose_cmd(ini_file, up_cmd)
+
+        # Second, copy the the ini file inside the container
+        ini_file = abspath(ini_file)
+        ini_file_ctr_path = "/tmp/faasm.ini"
+        cp_cmd = "cp {} {}:{}".format(ini_file, cli, ini_file_ctr_path)
+        run_compose_cmd(ini_file, cp_cmd)
+
+        # Third, wait for the virtual environment to be ready if we need to. We
+        # only need to wait for the virtual environment if we are either
+        # mounting the source, or using one of the clients
+        wait_for_venv(ini_file, cli)
+
+        # Copy files in before execution
+        if cp_in:
+            host_path = abspath(cp_in.split(":")[0])
+            if not exists(host_path):
+                print("Host path to copy from does not exist ({})".format(host_path))
+                raise RuntimeError("Host path to copy from does not exist")
+            ctr_path = cp_in.split(":")[1]
+
+            cp_cmd = "cp {} {}:{}".format(host_path, cli, ctr_path)
+            run_compose_cmd(ini_file, cp_cmd)
+
+        # Lastly, actually run the requested command
+        compose_cmd = [
+            "exec",
+            "-e FAASM_INI_FILE={}".format(ini_file_ctr_path),
+            " ".join(["-e {}".format(var) for var in env.split(",")])
+            if env is not None
+            else "",
+            "-it" if not cmd else "",
+            cli,
+            "bash" if not cmd else cmd,
+        ]
+        compose_cmd = " ".join(compose_cmd)
+        run_compose_cmd(ini_file, compose_cmd)
+
+        # Copy files out after execution
+        if cp_out:
+            ctr_path = cp_out.split(":")[0]
+            host_path = abspath(cp_out.split(":")[1])
+
+            cp_cmd = "cp {}:{} {}".format(cli, ctr_path, host_path)
+            run_compose_cmd(ini_file, cp_cmd)
+
+    elif backend == "k8s":
+        # Using a CLI container with a cluster that runs on a `k8s` backend is
+        # only supported to upload functions from the CPP or Python container.
+        # As such we: (i) disable cli.faasm calls on a `k8s` backend, and (ii)
+        # use a standalone container to execute the command that we remove
+        # immediately after (without mounting any files)
+        ini_file_ctr_path = "/tmp/faasm.ini"
+        work_dir = get_faasm_ini_value(ini_file, "Faasm", "working_dir")
+
+        if cli == "cpp":
+            image_tag = get_docker_tag(work_dir, "CPP_CLI_IMAGE")
+        elif cli == "python":
+            image_tag = get_docker_tag(work_dir, "PYTHON_CLI_IMAGE")
+        else:
+            raise RuntimeError("Can't call cli.faasm on a `k8s` cluster!")
+
+        docker_cmd = [
+            "docker run --rm",
+            "-v {}:{}".format(ini_file, ini_file_ctr_path),
+            "-e FAASM_INI_FILE={}".format(ini_file_ctr_path),
+            "-it" if not cmd else "",
+            image_tag,
+            "bash" if not cmd else cmd,
+        ]
+        docker_cmd = " ".join(docker_cmd)
+
+        run(docker_cmd, shell=True)
+
+    else:
+        raise RuntimeError("Unrecognised backend: {}".format(backend))
+
+
+@task
+def faasm(ctx, cmd=None, cp_in=None, cp_out=None, env=None, ini_file=None):
+    """
+    Run a command in the Faasm CLI container
+
+    By default, if --cmd is set to None, we will get a shell into the
+    container. If the --cmd argument is set, we execute the cmd string
+
+    Parameters:
+    - cmd (str): command to run in the CLI container
+    - cp_in (str): file to copy into the CLI as host_path:ctr_path
+    - cp_out (str): file to copy out of the CLI as ctr_path:host_path
+    - env (str): comma-separated ENV=VAR environment variables for cmd
+    - ini_file (str): path to the cluster's INI file
+    """
+    do_run_cmd("faasm-cli", cmd, cp_in, cp_out, env, ini_file)
+
+
+@task
+def cpp(ctx, cmd=None, cp_in=None, cp_out=None, env=None, ini_file=None):
+    """
+    Run a command in the CPP CLI container
+
+    By default, if --cmd is set to None, we will get a shell into the
+    container. If the --cmd argument is set, we execute the cmd string
+
+    Parameters:
+    - cmd (str): command to run in the CLI container
+    - cp_in (str): file to copy into the CLI as host_path:ctr_path
+    - cp_out (str): file to copy out of the CLI as ctr_path:host_path
+    - ini_file (str): path to the cluster's INI file
+    """
+    do_run_cmd("cpp", cmd, cp_in, cp_out, env, ini_file)
+
+
+@task
+def python(ctx, cmd=None, cp_in=None, cp_out=None, env=None, ini_file=None):
+    """
+    Run a command in the Python CLI container
+
+    By default, if --cmd is set to None, we will get a shell into the
+    container. If the --cmd argument is set, we execute the cmd string
+
+    Parameters:
+    - cmd (str): command to run in the CLI container
+    - cp_in (str): file to copy into the CLI as host_path:ctr_path
+    - cp_out (str): file to copy out of the CLI as ctr_path:host_path
+    - ini_file (str): path to the cluster's INI file
+    """
+    do_run_cmd("python", cmd, cp_in, cp_out, env, ini_file)

faasmctl/tasks/delete.py

@@ -0,0 +1,28 @@
+from faasmctl.util.compose import delete_compose_cluster
+from faasmctl.util.config import get_faasm_ini_file, get_faasm_ini_value
+from faasmctl.util.k8s import delete_k8s_cluster
+from invoke import task
+from os import remove
+
+
+@task(default=True)
+def delete(ctx, ini_file=None):
+    """
+    Delete a running Faasm cluster
+
+    Parameters:
+    - ini_file (str): path to the cluster's INI file (FAASM_INI_FILE env. var
+                      if not found)
+    """
+    if not ini_file:
+        ini_file = get_faasm_ini_file()
+
+    backend = get_faasm_ini_value(ini_file, "Faasm", "backend")
+    if backend == "compose":
+        delete_compose_cluster(ini_file)
+    elif backend == "k8s":
+        delete_k8s_cluster(ini_file)
+    else:
+        raise RuntimeError("Unsupported backend: {}".format(backend))
+
+    remove(ini_file)

faasmctl/tasks/deploy.py

@@ -0,0 +1,103 @@
+from faasmctl.util.compose import (
+    deploy_compose_cluster,
+    populate_host_sysroot,
+    run_compose_cmd,
+)
+from faasmctl.util.deploy import fetch_faasm_code
+from faasmctl.util.k8s import DEFAULT_KUBECONFIG_PATH, deploy_k8s_cluster
+from invoke import task
+from os import environ
+from os.path import abspath
+
+
+@task
+def compose(ctx, workers=2, mount_source=None, clean=False, ini_file=None):
+    """
+    Deploy a Faasm cluster on docker compose
+
+    Parameters:
+    - workers (int): number of workers to deploy
+    - mount_source (str): path to the Faasm's source code checkout
+    - clean (bool): flag to indicate whether we clean cached checkouts
+    - ini_file (str): path to the ini_file to generate (if selected)
+
+    Returns:
+    - (str): path to the generated ini_file
+    """
+    # First, check-out the Faasm source if necessary
+    if mount_source:
+        mount_source = abspath(mount_source)
+        if clean:
+            print(
+                "WARNING: using the --clean flag with --mount_source "
+                "env. variable is disabled, as local changes could be "
+                "erased!"
+            )
+        faasm_checkout, faasm_ver = fetch_faasm_code(
+            faasm_source=mount_source, force=False
+        )
+        mount_source = True
+
+        # If mounting the source code, we need to populate the host's
+        # sysroot to mount it into the containers
+        populate_host_sysroot(faasm_checkout)
+    else:
+        # Otherwise, we will check out the code in a faasmctl-specific working
+        # directoy
+        mount_source = False
+        faasm_checkout, faasm_ver = fetch_faasm_code(force=clean)
+
+    return deploy_compose_cluster(faasm_checkout, workers, mount_source, ini_file)
+
+
+@task
+def dist_tests(ctx, mount_source=None, ini_file=None):
+    """
+    Deploy a development Faasm cluster to run distributed tests
+
+    Parameters:
+    - mount_source (str): path to the Faasm's source code checkout
+    - ini_file (str): optional path to a running cluster
+    """
+    # If the user provided a path to the ini_file, it means that we are
+    # deploying the dist-tests on top of an existing cluster. Otherwise start
+    # a new compose clustter
+    if ini_file is None:
+        if not mount_source:
+            raise RuntimeError(
+                "When deploying a dist-tests cluster, you need to"
+                " specify the --mount-source"
+            )
+
+        ini_file = compose(ctx, workers=0, mount_source=mount_source, clean=False)
+
+    # Second, start the dist-test-server
+    run_compose_cmd(ini_file, "up -d dist-test-server")
+
+
+@task
+def k8s(ctx, workers=2, context=None, clean=False, ini_file=None):
+    """
+    Deploy a Faasm cluster on k8s
+
+    Parameters:
+    - workers (int): number of workers to deploy
+    - context (str): path to the k8s config to use (defaults to ~/.kube/config)
+    - clean (bool): flag to clean the local checkout of the code tag
+    - ini_file (str): path to the ini_file to generate (if selected)
+
+    Returns:
+    - (str): path to the generated ini_file
+    """
+    # First, check-out the Faasm source if necessary (we need it for the k8s
+    # deployment files, eventually we could publish them as helm charts)
+    faasm_checkout, faasm_ver = fetch_faasm_code(force=clean)
+
+    if context:
+        context = abspath(context)
+    elif "KUBECONFIG" in environ:
+        context = abspath(environ["KUBECONFIG"])
+    else:
+        context = DEFAULT_KUBECONFIG_PATH
+
+    return deploy_k8s_cluster(context, faasm_checkout, workers, ini_file)

faasmctl/tasks/flush.py

@@ -0,0 +1,31 @@
+from faasmctl.util.flush import flush_hosts, flush_workers
+from invoke import task
+
+
+@task()
+def hosts(ctx):
+    """
+    Flush the list of registered and available hosts in the Faasm cluster
+    """
+    flush_hosts()
+
+
+@task()
+def workers(ctx):
+    """
+    Flush the state and wasm files cached in each worker
+    """
+    flush_workers()
+
+
+@task()
+def all(ctx):
+    """
+    Flush functions, state and shared files from all workers
+    """
+    # First flush the workers
+    workers(ctx)
+
+    # Last flush the available host list (note that after this call no other
+    # flushing works, as the planner is unaware of any hosts in the cluster)
+    hosts(ctx)

faasmctl/tasks/generate.py

@@ -0,0 +1,14 @@
+from invoke import task
+from os.path import join
+from subprocess import run
+from faasmctl.util.env import PROJ_ROOT
+
+
+@task
+def proto(ctx):
+    """
+    (Re)generate the Python protobuf files necessary to interact with Faasm
+    """
+    gen_proto_bin = join(PROJ_ROOT, "bin", "gen_proto_files.py")
+    gen_cmd = "python3 {} --clean".format(gen_proto_bin)
+    run(gen_cmd, shell=True, check=True)

faasmctl/tasks/invoke.py

@@ -0,0 +1,102 @@
+from base64 import b64encode
+from faasmctl.util.invoke import invoke_wasm
+from faasmctl.util.planner import get_available_hosts
+from faasmctl.util.results import (
+    get_execution_time_from_message_results,
+    get_return_code_from_message_results,
+)
+from invoke import task
+from sys import exit
+from time import time
+
+
+@task(default=True)
+def invoke(
+    ctx,
+    user,
+    func,
+    ini_file=None,
+    cmdline=None,
+    input_data=None,
+    mpi_world_size=None,
+    single_host=False,
+    host_dist=None,
+):
+    """
+    Invoke the execution of a user/func pair
+
+    TODO: think how to enable all the possible command line values in a
+    scalable way.
+    """
+    num_messages = 1
+    req_dict = {"user": user, "function": func}
+    msg_dict = {"user": user, "function": func}
+
+    if cmdline is not None:
+        msg_dict["cmdline"] = cmdline
+    if input_data is not None:
+        msg_dict["input_data"] = b64encode(input_data.encode("utf-8")).decode("utf-8")
+    if mpi_world_size is not None:
+        msg_dict["mpi_world_size"] = int(mpi_world_size)
+    if single_host:
+        req_dict["singleHostHint"] = single_host
+    if host_dist:
+        host_dist = host_dist.split(",")
+        # Prepare a host distribution
+        available_hosts = get_available_hosts()
+
+        if len(host_dist) > len(available_hosts.hosts):
+            print(
+                "ERROR: requested execution among {} hosts but only {} "
+                "available!".format(len(host_dist), len(available_hosts.hosts))
+            )
+            return 1
+
+        # We assume that the available host list will always come in the same
+        # order (for the same set of hosts)
+
+        host_list = []
+        for host in host_dist:
+            host_ind = int(host.split(":")[0])
+            num_in_host = int(host.split(":")[1])
+            host_list += [available_hosts.hosts[host_ind].ip] * num_in_host
+    else:
+        host_list = None
+
+    # Invoke WASM using main API function
+    start_ts = time()
+    result = invoke_wasm(
+        msg_dict,
+        num_messages=num_messages,
+        req_dict=req_dict,
+        ini_file=ini_file,
+        host_list=host_list,
+    )
+    end_ts = time()
+
+    # Pretty-print a summary of the execution
+
+    user = result.messageResults[0].user
+    function = result.messageResults[0].function
+    output = result.messageResults[0].outputData
+    ret_val = get_return_code_from_message_results(result)
+    # Wall time is the time elapsed as measured from the calling python script
+    wall_time = "{:.2f} s".format(end_ts - start_ts)
+    # Exec time is the time the function actually executed inside Faasm
+    exec_time = "{:.2f} s".format(
+        get_execution_time_from_message_results(result, unit="s")
+    )
+
+    print("======================= Faasm Execution =========================")
+    print("Function: \t\t\t{}/{}".format(user, function))
+    print("Return value: \t\t\t{}".format(ret_val))
+    print("Wall time: \t\t\t{}".format(wall_time))
+    print("Execution time: \t\t{}".format(exec_time))
+    print("-----------------------------------------------------------------")
+    print("Output:\n{}".format(output))
+    print("=================================================================")
+
+    # Use sys/exit to propagate the error code to the bash process. If
+    # execution fails, we want the bash process to have a non-zero exit code.
+    # This is very helpful for testing environments like GHA
+    exit(ret_val)

faasmctl/tasks/logs.py

@@ -0,0 +1,73 @@
+from faasmctl.util.backend import COMPOSE_BACKEND, K8S_BACKEND
+from faasmctl.util.compose import run_compose_cmd
+from faasmctl.util.config import (
+    BACKEND_INI_STRING,
+    get_faasm_ini_file,
+    get_faasm_ini_value,
+)
+from faasmctl.util.k8s import run_k8s_cmd
+from invoke import task
+
+
+def get_compose_logs(s, follow, ini_file, last_restart):
+    compose_cmd = [
+        "logs",
+        "--since {}".format(last_restart),
+        "-f" if follow else "",
+        "{}".format(" ".join(s)),
+    ]
+    compose_cmd = " ".join(compose_cmd)
+    run_compose_cmd(ini_file, compose_cmd)
+
+
+def get_k8s_logs(s, follow, ini_file, last_restart):
+    if len(s) > 1:
+        raise RuntimeError(
+            "Getting the logs for a K8s service only works with one service at a time!"
+        )
+
+    service_to_k8s_str = {
+        "planner": "pod/planner",
+        "worker": "-l run=faasm-worker",
+        "upload": "pod/upload",
+    }
+
+    service = s[0]
+    if service not in service_to_k8s_str:
+        raise RuntimeError(
+            "Unrecognised service name: {} (must be one in: {})".format(
+                service, service_to_k8s_str.keys()
+            )
+        )
+
+    k8s_cmd = [
+        "logs",
+        "-f" if follow else "",
+        service_to_k8s_str[service],
+        "--tail=-1",
+    ]
+    k8s_cmd = " ".join(k8s_cmd)
+    k8s_config = get_faasm_ini_value(ini_file, "Faasm", "k8s_config")
+    run_k8s_cmd(k8s_config, "faasm", k8s_cmd)
+
+
+@task(default=True, iterable=["s"])
+def logs(ctx, s, follow=False, ini_file=None):
+    """
+    Get the logs of a running service in the cluster
+
+    Parameters:
+    - s (str, repeateble): service to get the logs from
+    - ini_file (str): path to the cluster's INI file
+    """
+    if not ini_file:
+        ini_file = get_faasm_ini_file()
+
+    backend = get_faasm_ini_value(ini_file, "Faasm", BACKEND_INI_STRING)
+    last_restart = get_faasm_ini_value(ini_file, "Faasm", "last_restart")
+    if backend == COMPOSE_BACKEND:
+        get_compose_logs(s, follow, ini_file, last_restart)
+    elif backend == K8S_BACKEND:
+        get_k8s_logs(s, follow, ini_file, last_restart)
+    else:
+        raise RuntimeError("Unrecognised backend: {}".format(backend))