Skip to content

Latest commit

 

History

History
99 lines (83 loc) · 6.02 KB

README.md

File metadata and controls

99 lines (83 loc) · 6.02 KB
Raw

ssh Plugin

This plugin connects to a remote system and performs a block of commands. It can extract variables from the shell back to the output of its enclosing step.

The step will be considered successful if the script returns exit code 0, otherwise, it will be considered as a SERVER_ERROR (and will be retried). For unrecoverable errors (for instance, invalid parameters), it is possible to configure a list of exit codes (see exit_codes_unrecoverable) that should halt the execution (CLIENT_ERROR).

Configuration

Fields Description
user username for the connection
target address of the remote machine
hops a list of intermediate addresses (bastions)
script multiline text, commands to be run on the machine's shell
output_mode indicates how to retrieve the output values ; valid values are: auto-result (default), disabled, manual-delimiters, manual-lastline
result an object to extract the values of variables from the machine's shell (only used when output_mode is configured to auto-result)
output_manual_delimiters array of 2 strings ; look for a JSON formatted string in the script output between specific delimiters (only used when output_mode is configured to manual-delimiters)
ssh_key private ssh key, preferably retrieved from {{.config}}
ssh_key_passphrase passphrase for the key, if any
exit_codes_unrecoverable a list of non-zero exit codes (1, 2, 3, ...) or ranges (1-10, ...) which should be considered unrecoverable and halt execution ; these will be returned to the main engine as a CLIENT_ERROR
timeout defines the maximum duration of the SSH session (connection time not included). Default to 5m.

Example

An action of type ssh requires the following kind of configuration:

action:
  type: ssh
  configuration:
    # user name connecting to the machine
    user: ubuntu
    # target machine
    target: frontend.ha.example.org
    # intermediate machines
    hops:
    - bastion.example.org
    # the commands to be executed, with variable declarations for value extraction
    script: |-
      PID=$(systemctl show --property MainPID {{.input.serviceName}} | cut -d= -f2)
      SERVICE_UPTIME=$(ps -h -p ${PID} -o etimes)
    # this is the default mode
    output_mode: auto-result
    # value extraction
    result:
      pid: $PID
      uptime: $SERVICE_UPTIME
    # credentials
    ssh_key: '{{.config.mySSHKey.privateKey}}'
    # optional delimiters to look for an output -- requires output_mode set to manual-delimiters
    #output_manual_delimiters: ["JSON_START", "JSON_END"]
    exit_codes_unrecoverable:
      - "1-10"
      - "100"
      - "110"
    timeout: 30s

Requirements

None. SSH credentials should be retrieved from e.g. {{.config.mySSHKey.privateKey}} rather than hardcoded in the template. Example configuration object mySSHKey (yaml):

privateKey: |-
  -----BEGIN OPENSSH PRIVATE KEY-----
  ...
  -----END OPENSSH PRIVATE KEY-----

Note

The plugin returns two objects, output and metadata. output depends on the output_mode configuration. It is read as formatted JSON from the stdout of the SSH session. The default output_mode (auto-result) injects an escaped echo command as the last command in the SSH session, to craft a JSON payload where all the values are interpolated by the shell (e.g. shell variables get replaced). The format of this payload is configured via the result configuration. Other modes expect the JSON output on the last line (manual-lastline) or between given delimiters (manual-delimiters).

{
  "pid": "3931",
  "uptime": "1715606"
}

metadata contains information about plugin execution:

{
  "output": "Connecting...\nWelcome to Ubuntu 19.04 (GNU/Linux ... x86_64)\n[...]\n{\"pid\":\"3931\",\"service_name\":\"nginx\",\"service_uptime\":\"1715606\"}",
  "exit_code": "0",
  "exit_signal": "0",
  "exit_msg": "exited 0"
}

Resources

The ssh plugin declares automatically resources for its steps:

  • socket to rate-limit concurrent execution on the number of open outgoing sockets
  • url:target (where target is the outgoing SSH target of the plugin configuration) to rate-limit concurrent execution on a specific target
  • url:hop (where hop is one of the intermediate machine of the plugin configuration) to rate-limit concurrent execution on the intermediate machines