Note

The documentation you're currently reading is for version 2.3.2. Click here to view documentation for the latest stable version.

Action Runners

An action runner is the execution environment for user-implemented actions. BWC comes with pre-canned action runners such as a remote runner and shell runner which provide for user-implemented actions to be run remotely (via SSH) and locally. The objective is to allow the Action author to concentrate only on the implementation of the action itself rather than setting up the environment.

Exit Codes

Normally an exit code of a runner is defined by an exit code of a script or a command they execute. All runners return timeout exit code (-9) if a command or a script did not complete its execution within the specified timeout.

Local command runner (local-shell-cmd)

This is the local runner. This runner executes a Linux command on the same host where BWC components are running.

Note

stdout and stderr attributes in the runner result object have the last ‘n’ or ‘r’ or ‘rn’ characters removed if present. This is done so you can re-use the result of common commands that include a trailing line break of carriage return, such as uptime, whoami, etc., in other actions and workflows. If you have an action which requires a trailing line break character to be present, you can add it explicitly to the result, e.g. echo -e 'test\n' (this will result into two line break characters and only one of them will be stripped/removed from the result).

Runner parameters

  • kwarg_op (string) - Operator to use in front of keyword args i.e. “–” or “-”.
  • cmd (string) - Arbitrary Linux command to be executed on the host.
  • timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.
  • env (object) - Environment variables which will be available to the command(e.g. key1=val1,key2=val2)
  • sudo (boolean) - The command will be executed with sudo.
  • cwd (string) - Working directory where the command will be executed in

Local script runner (local-shell-script)

This is the local runner. Actions are implemented as scripts. They are executed on the same hosts where BWC components are running. The last newline character is stripped from stdout and stderr fields in the output.

Runner parameters

  • kwarg_op (string) - Operator to use in front of keyword args i.e. “–” or “-”.
  • sudo (boolean) - The command will be executed with sudo.
  • cwd (string) - Working directory where the script will be executed in
  • timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.
  • env (object) - Environment variables which will be available to the script(e.g. key1=val1,key2=val2)

Remote command runner (remote-shell-cmd)

This is a remote runner. This runner executes a Linux command on one or more remote hosts provided by the user. The last newline character is stripped from stdout and stderr fields in the output.

Runner parameters

  • username (string) - Username used to log-in. If not provided, default username from config is used.
  • private_key (string) - Private key material or path to the private key file on disk used to log in.
  • cmd (string) - Arbitrary Linux command to be executed on the remote host(s).
  • timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.
  • env (object) - Environment variables which will be available to the command(e.g. key1=val1,key2=val2)
  • sudo (boolean) - The remote command will be executed with sudo.
  • cwd (string) - Working directory where the script will be executed in
  • kwarg_op (string) - Operator to use in front of keyword args i.e. “–” or “-”.
  • bastion_host (string) - The host SSH connections will be proxied through. Note: This connection is made using the same parameters as the final connection, and is only used in ParamikoSSHRunner.
  • hosts (string) - A comma delimited string of a list of hosts where the remote command will be executed.
  • passphrase (string) - Passphrase for the private key, if needed.
  • parallel (boolean) - Default to parallel execution.
  • password (string) - Password used to log in. If not provided, private key from the config file is used.
  • port (integer) - SSH port. Note: This parameter is used only in ParamikoSSHRunner.
  • dir (string) - The working directory where the script will be copied to on the remote host.

Note

If a value you specify for the private_key parameter is a path to the private key file, you need to make sure that the user under which action runner process is running (stanley by default) has read access to this key file. This private key file also needs be deployed and present in the same location on all the servers where action runner component is running.

In addition to that, if you utilize path to the private key file functionality, you are strongly encouraged to disable local runner in the config. If you don’t do that, any BWC user which has access to core.local action will be able to read this key and this can pose a security risk.

Remote script runner (remote-shell-script)

This is a remote runner. Actions are implemented as scripts. They run on one or more remote hosts provided by the user. The last newline character is stripped from stdout and stderr fields in the output.

Runner parameters

  • username (string) - Username used to log-in. If not provided, default username from config is used.
  • private_key (string) - Private key material to log in. Note: This needs to be actual private key data and NOT path.
  • timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.
  • env (object) - Environment variables which will be available to the script(e.g. key1=val1,key2=val2)
  • sudo (boolean) - The remote command will be executed with sudo.
  • cwd (string) - Working directory where the script will be executed in.
  • kwarg_op (string) - Operator to use in front of keyword args i.e. “–” or “-”.
  • bastion_host (string) - The host SSH connections will be proxied through. Note: This connection is made using the same parameters as the final connection, and is only used in ParamikoSSHRunner.
  • hosts (string) - A comma delimited string of a list of hosts where the remote command will be executed.
  • passphrase (string) - Passphrase for the private key, if needed.
  • parallel (boolean) - Default to parallel execution.
  • password (string) - Password used to log in. If not provided, private key from the config file is used.
  • port (integer) - SSH port. Note: This parameter is used only in ParamikoSSHRunner.
  • dir (string) - The working directory where the script will be copied to on the remote host.

Note

If a value you specify for the private_key parameter is a path to the private key file, you need to make sure that the user under which action runner process is running (stanley by default) has read access to this key file. This private key file also needs be deployed and present in the same location on all the servers where action runner component is running.

In addition to that, if you utilize path to the private key file functionality, you are strongly encouraged to disable local runner in the config. If you don’t do that, any BWC user which has access to core.local action will be able to read this key and this can pose a security risk.

Windows command runner (windows-cmd)

Windows command runner allows you to run you to run command-line interpreter (cmd) and PowerShell commands on Windows hosts.

For more information on enabling and setting up the Windows runner, please see the following section - Windows Runners Configuration.

Runner parameters

  • username (string) - Username used to log-in.
  • cmd (string) - Arbitrary command to be executed on the remote host.
  • host (string) - Host to execute the command on
  • password (string) - Password used to log in.
  • timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.

Windows script runner (windows-script)

Windows script runner allows you to run PowerShell scripts on Windows hosts.

For more information on enabling and setting up the Windows runner, please see the following section - Windows Runners Configuration.

Runner parameters

  • username (string) - Username used to log-in.
  • host (string) - Host to execute the command on
  • password (string) - Password used to log in.
  • share (string) - Name of the Windows share where script files are uploaded
  • timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.

HTTP runner (http-request)

HTTP runner works by performing HTTP request to the provided URL.

Runner parameters

  • username (string) - Username required by basic authentication.
  • cookies (object) - Optional cookies to send with the request.
  • headers (object) - HTTP headers for the request.
  • url (string) - URL to the HTTP endpoint.
  • http_proxy (string) - URL of HTTP proxy to use (e.g. http://10.10.1.10:3128).
  • https_proxy (string) - URL of HTTPS proxy to use (e.g. http://10.10.1.10:3128).
  • allow_redirects (boolean) - Set to True if POST/PUT/DELETE redirect following is allowed.
  • password (string) - Password required by basic authentication.
  • verify_ssl_cert (boolean) - Certificate for HTTPS request is verified by default using requests CA bundle which comes from Mozilla. Verification using a custom CA bundle is not yet supported. Set to False to skip verification.

Keep in mind that other parameters such as body, method, headers, etc. are defined as part of the core.http action.

Runner result

The result object from this runner contains the following keys:

  • status_code (integer) - Response status code (e.g. 200, 404, etc.)
  • body (string / object) - Response body. If the response body contains JSON and the response Content-Type header is application/json, the body will be automatically parsed as JSON.
  • parsed (boolean) - Flag which indicates if the response body has been parsed.
  • headers - Response headers.

Python runner (python-script)

This is a Python runner. Actions are implemented as Python classes with a run method. They run locally on the same machine where BWC components are running.

Python runner actions return an execution status (success, failure) by returning a tuple from the Python action class run() method. First item in this tuple is a boolean flag indicating a success and the second one is the result. However, execution status is optional i.e. the return value from action runner can either be a tuple of success status and result or just the result object.

Runner parameters

  • env (object) - Environment variables which will be available to the script.
  • timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.

Runner result

The return value from this action runner is a tuple consisting of a boolean flag indicating a success and the second one is the result:

  • status (boolean) - Flag indicating action’s success, i.e. Succeeded status is True/False. Note: This is an optional flag.
  • result (object) - result returned by the action based on success or failure.

The status flag allows users to return a result from a failing action. When the status flag is not used the only way for action to be considered as failed is to throw an exception or exit with a non-zero exit code.

ActionChain runner (action-chain)

ActionChain is a no-frills linear workflow, a simple chain of action invocations. For more information, please refer to the Workflows and ActionChain section of documentation.

Runner parameters

  • display_published (boolean) - Intermediate published variables will be stored and displayed.
  • skip_notify (array) - List of tasks to skip notifications for.

Mistral runner (mistral-v2)

Those runners are built on top of the Mistral OpenStack project and support executing complex work-flows. For more information, please refer to the Workflows and Mistral sections of the documentation.

Runner parameters

  • skip_notify (array) - List of tasks to skip notifications for.
  • task (string) - The name of the task to run for reverse workflow.
  • context (object) - Additional workflow inputs.
  • workflow (string) - The name of the workflow to run if the entry_point is a workbook of many workflows. The name should be in the format “<pack_name>.<action_name>.<workflow_name>”. If entry point is a workflow or a workbook with a single workflow, the runner will identify the workflow automatically.

CloudSlang runner (cloudslang)

This runner is built on top of the CloudSlang project and supports executing complex workflows. For more information, please refer to the Workflows and CloudSlang sections of the documentation.

Note: This runner is currently in an experimental phase which means that there might be bugs and the external user facing API might change.

Runner parameters

  • inputs (object) - Inputs which will be available to CloudSlang flow execution(e.g. input1=val1,input2=val2)
  • timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.