Executor Operator

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

Operator arguments

Name	Type	Values restrictions	Required	Default	Description
command	String		yes		The shell command to be executed on the remote machine
host	Object	See structure documented below	no		Information relative to the target machine onto which the command has to be executed using SSH
component	String	It should match the name of an existing Component of the System under test	no		The name of the Component whose properties can be used as arguments of the operator
detach	Boolean		no	False	The execution mode of the shell command. Default (False) execution will be synchronous, detached (True) execution will be asynchronous and will return immediately

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:

Name	Type	Value Retrictions	Required	Default	Description
hostname	String	should be a valid SSH host address	no, if the Component whose name is defined in component has a property named hostname		SSH endpoint
username	String		no, if the Component whose name is defined in component has a property named username		SSH login username
password	String	cannot be set if key is already set	no, if the Component whose name is defined in component has a property named password		SSH login password
sshPort	Number	1≤sshPort≤65532	no	22	SSH port
key	String	cannot be set if password is already set	no, if the Component whose name is defined in component has a property named key		SSH login key. Either provide directly the key value or specify the path of the file (local to the cli executing the create command) to read the key from. The operator supports RSA and DSA Keys.

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

Component Property	Operator Argument
hostname	host->hostname
username	host->username
sshPort	host->sshPort
password	host->password
key	host->key

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.