Compose Command

The pycompose command makes it possible to deploy compositions from the command line.

The pycompose command is intended as a minimal complement to the OpenWhisk CLI. The OpenWhisk CLI already has the capability to configure, invoke, and delete compositions (since these are just OpenWhisk actions) but lacks the capability to create composition actions. The compose command bridges this gap. It makes it possible to deploy compositions as part of the development cycle or in shell scripts. It is not a replacement for the OpenWhisk CLI however as it does not duplicate existing OpenWhisk CLI capabilities. Moreover, for a much richer developer experience, we recommend using Shell.

Usage

pycompose

Usage:
  compose composition.[py|json] command [flags]
Commands:
  --json                 output the json representation for the composition (default command)
  --deploy NAME          deploy the composition with name NAME
  --encode               output the conductor action code for the composition
Flags:
  --lower [VERSION]      lower to primitive combinators or specific composer version
  --apihost HOST         API HOST
  -u, --auth KEY         authorization KEY
  -i, --insecure         bypass certificate checking

The pycompose command requires either a Python file that evaluates to a composition (for example demo.py) or a JSON file that encodes a composition (for example demo.json). The JSON format is documented in FORMAT.md.

The pycompose command has three modes of operation:

• By default or when the --json option is specified, the command returns the composition encoded as a JSON dictionary.
• When the --deploy option is specified, the command deploys the composition given the desired name for the composition.
• When the --encode option is specified, the command returns the Python code for the conductor action for the composition.

JSON format

By default, the compose command evaluates the composition code and outputs the resulting JSON dictionary:

pycompose demo.py

{
    "type": "if",
    "test": {
        "type": "action",
        "name": "/_/authenticate",
        "action": {
            "exec": {
                "kind": "nodejs:default",
                "code": "const main = function ({ password }) { return { value: password === 'abc123' } }"
            }
        }
    },
    "consequent": {
        "type": "action",
        "name": "/_/success",
        "action": {
            "exec": {
                "kind": "nodejs:default",
                "code": "const main = function () { return { message: 'success' } }"
            }
        }
    },
    "alternate": {
        "type": "action",
        "name": "/_/failure",
        "action": {
            "exec": {
                "kind": "nodejs:default",
                "code": "const main = function () { return { message: 'failure' } }"
            }
        }
    }
}

The evaluation context includes the composer object implicitly. In other words, there is no need to import the composer module explicitly in the composition code.

Deployment

The --deploy option makes it possible to deploy a composition (Javascript or JSON) given the desired name for the composition:

compose demo.js --deploy demo

ok: created actions /_/authenticate,/_/success,/_/failure,/_/demo

Or:

compose demo.py > demo.json
compose demo.json --deploy demo

ok: created actions /_/authenticate,/_/success,/_/failure,/_/demo

The pycompose command synthesizes and deploys a conductor action that implements the composition with the given name. It also deploys the composed actions for which definitions are provided as part of the composition.

The pycompose command outputs the list of deployed actions or an error result. If an error occurs during deployment, the state of the various actions is unknown.

The pycompose command deletes the deployed actions before recreating them if necessary. As a result, default parameters, limits, and annotations on preexisting actions are lost.

Configuration

Like the OpenWhisk CLI, the compose command supports the following flags for specifying the OpenWhisk deployment to use:

 --apihost HOST         API HOST
  -u, --auth KEY        authorization KEY
  -i, --insecure        bypass certificate checking

If the --apihost flag is absent, the environment variable __OW_API_HOST is used in its place. If neither is available, the compose command extracts the APIHOST key from the whisk property file for the current user.

If the --auth flag is absent, the environment variable __OW_API_KEY is used in its place. If neither is available, the compose command extracts the AUTH key from the whisk property file for the current user.

The default path for the whisk property file is $HOME/.wskprops. It can be altered by setting the WSK_CONFIG_FILE environment variable.

Code generation

The pycompose command returns the code of the conductor action for the composition (Python or JSON) when invoked with the --encode option. For instance, the conductor action code for the demo.py composition is demo-conductor.py:

pycompose demo.py --encode > demo-conductor.py

This code may be deployed using the OpenWhisk CLI:

wsk action create demo demo-conductor.py --kind python:3 -a conductor true

ok: created action demo

The conductor action code does not include definitions for nested actions or compositions.

Lowering (Not supported yet)

If the --lower VERSION option is specified, the pycompose command uses the set of combinators of the specified revision of the composer module. More recently introduced combinators (if any) are translated into combinators of the older set.

If the --lower option is specified without a version number, the pycompose command uses only primitive combinators.

These options may be combined with any of the pycompose commands.