Executor Operator

The Executor Operator can be used to execute a shell command on a target machine using SSH.

Operator arguments

Host structure and arguments

Here follows the structure of the host argument:

host:
  hostname: this_is_a_hostname
  username: this_is_a_username
  password: this_is_a_password
  sshPort: 22
  key: this_is_a_key

with its arguments:

Get operator arguments from component

The component argument can refer to a component by name and use its properties as the arguments of the operator (see mapping here below). In case the mapped arguments are already provided to the operator, there is no override.

Component property to operator argument mapping

Examples

Let's assume you want to run a script on a remote host and expect the script to be executed successfully within 30 seconds but might fail occasionally.

Launch a script, wait for its completion, and in case of failures or timeout retry 3 times by waiting 10 seconds between retries:

name: Run Script
operator: Executor
arguments:
  timeout: 30s
  retries: 3
  retry_delay: 10s
  command: bash /tmp/myscript.sh
  host:
    hostname: frontend.akamas.io
    username: akamas
    key: secret.key

Execute a uname command with explicit host information (explicit SSH key)

name: TestConnectivity
operator: Executor
arguments:
  command: bash uname -a
  host:
    hostname: frontend.akamas.io
    username: akamas
    key: |-
      -----BEGIN RSA PRIVATE KEY-----
      RSA KEY HERE
      -----END RSA PRIVATE KEY-----

Execute a uname command with explicit host information (imported SSH key)

name: TestConnectivity
operator: Executor
arguments:
  command: bash uname -a
  host:
    hostname: frontend.akamas.io
    username: akamas
    key: path/to/key

Execute a uname command with host information taken from a Component

name: TestConnectivity
operator: Executor
arguments:
  command: bash uname -a
  component: frontend1

Start a load-testing script and keep it running in the background during the workflow

name: TestConnectivity
operator: Executor
arguments:
  command: bash start_load.sh
  component: tester
  detach: true

Troubleshooting

Troubles in running sh scripts remotely

Due to the stderr configuration, it could happen that invoking a bash script on a server has a different result than running the same script from Akamas Executor Operator. This is quite common with Tomcat startup scripts like $HOME/tomcat/apache-tomcat_1299/bin/startup.sh.

To avoid this issue simply create a wrapper bash file on the target server adding the set -m instruction before the sh command, eg:

#!/bin/bash
set -m;
$HOME/tomcat/apache-tomcat_1299/bin/startup.sh

and then configure the Executor Operator to run the wrapper script like:

command: "bash $HOME/akamasScript/tomcatStart.sh

You can run the following to emulate the same behavior of Akamas running scripts over SSH:

ssh -t <user>@<server> <your command here>

Troubles in keeping a script running in the background

There are cases in which you would like to keep a script running for the whole duration of the test. Some examples could be:

• A script applying load to your system for the duration of the workflow

• The manual start of an application to be tested

• The setup of a listener that gathers logs, metrics, or data

In all the instances where you need to keep a task running beyond the task that started it, you must use the detach: true property. Note that a detached executor task returns immediately, so you should run only the background task in detached mode.

Remember to keep all tasks requiring synchronous (standard) behavior out of the detached task.

Example:

switch on machine and wait for SSH
run application test in background → detached mode
execute test run

Library references

The library used to execute scripts remotely is Fabric, a high-level Python library designed to execute shell commands remotely over SSH, yielding useful Python objects in return.

The Fabric library uses a connection object to execute scripts remotely (see connection — Fabric documentation). The option of a dedicated detach mode comes from implementing the more robust disown property from the Invoke Runner underlying the Connection (see runners — Invoke documentation). This is the reason you should rely on detach whenever possible instead of running the background processes straight into the script.

In the Frequently Asked/Answered Questions (FAQ) — Fabric documentation you may find some further information about the typical problems and solutions due to hanging problems for background processes.