SSH

Description

This plugin is part of the OpenSSH suite of plugins which enables you to use the ssh binary in a Vela pipeline.

Source Code: https://github.com/go-vela/vela-openssh

Registry: https://hub.docker.com/r/target/vela-ssh

Usage

Because the plugin is a thin wrapper around the ssh binary, the syntax and parameters follow from the OpenSSH manual. The plugin will take care of some basic secrets identity management tasks for you, most importantly is that when an identity file is provided as a secret the plugin will place the file into the filesystem and change the permissions to match what the binary expects, and then add it to the list of identity files tried as part of authentication. Additionally, if using a password or passphrase for authentication or for unlocking an identity file, the sshpass binary will be used to provide those credentials without interactive user input.

NOTE:
Users should refrain from using latest as the tag for images.
It is recommended to use a semantically versioned tag instead.

Basic usage with no-auth methods

steps:
  - name: ssh using no-auth
    image: target/vela-ssh:latest
    pull: always
    parameters:
      destination: a_different_user@some_other_host
      command:
        - echo "Hello Vela!"
        - /some/path/to/a/remote/script.sh

Using the `ssh://` schema for non-standard ports

steps:
  - name: ssh to non-standard port
    image: target/vela-ssh:latest
    pull: always
    parameters:
+     destination: ssh://a_different_user@some_remote_host_name:12345
      command:
        - echo "Hello Vela!"

Passing additional `ssh` flags

steps:
  - name: override default ssh flags
    image: target/vela-ssh:latest
    pull: always
    parameters:
      destination: ssh://a_different_user@some_remote_host_name:12345
      command:
        - echo "Hello Vela!"
+     ssh_flag:
+       - "-o StrictHostKeyChecking=yes"

Using a password for authentication

steps:
  - name: password for authentication
    image: target/vela-ssh:latest
    pull: always
+   secrets:
+     - source: my_non_user_account_password
+       target: sshpass_password
    parameters:
      destination: ssh://a_different_user@some_remote_host_name:12345
      command:
        - echo "Hello Vela!"

Using an identity file (WITHOUT a passphrase) from an internal secret

steps:
  - name: identity file contents from an internal secret
    image: target/vela-ssh:latest
    pull: always
+   secrets:
+     - source: my_non_user_account_id_rsa_file_contents
+       target: identity_file_contents
    parameters:
      destination: ssh://a_different_user@some_remote_host_name:12345
      command:
        - echo "Hello Vela!"

Using an identity file (WITH a passphrase) from an internal secret

steps:
  - name: identity file contents with passphrase from an internal secret
    image: target/vela-ssh:latest
    pull: always
+   secrets:
+     - source: my_non_user_account_id_rsa_file_contents
+       target: identity_file_contents
+     - source: my_non_user_account_id_rsa_passphrase
+       target: sshpass_passphrase
    parameters:
      destination: ssh://a_different_user@some_remote_host_name:12345
      command:
        - echo "Hello Vela!"

Using an existing identity file from the workspace

steps:
  - name: identity file from the workspace
    image: target/vela-ssh:latest
    pull: always
    parameters:
      destination: ssh://a_different_user@some_remote_host_name:12345
      command:
        - echo "Hello Vela!"
+     identity_file_path: ./some/workspace/location/id_rsa

Using additional secrets in other parameters

steps:
  - name: additional secrets in other parameters
    image: target/vela-ssh:latest
    pull: always
+   secrets:
+     - source: some_secret_user
+       target: secret_user
+     - source: some_secret_host
+       target: secret_host
+     - source: some_secret_port
+       target: secret_port
    parameters:
+     destination: ssh://$SECRET_USER@$SECRET_HOST:$SECRET_PORT
      command:
        - echo "Hello Vela!"

Using the container without the plugin logic

steps:
  - name: override plugin logic to use ssh directly
    image: target/vela-ssh:latest
    pull: always
    # Note that this ISN'T part of the parameters section.
+   commands:
+     - ssh -i ./some/existing/id_rsa username@hostname some-bin

Parameters & Secrets

NOTE:
The plugin supports reading all parameters via environment variables or files.
Any values set from a file take precedence over values set from the environment.
Don’t confuse the commands parameter in a traditional Vela step with the command option required for the ssh binary.

Name	Description	Required	Accepts Multiple Values?	Default	Environment Variables	File Paths
`destination`	The destination option from the `ssh` manual.	✅	❌		`PARAMETER_DESTINATION` `DESTINATION` `PARAMETER_HOST`	`/vela/parameters/vela-ssh/destination` `/vela/secrets/vela-ssh/destination`
`command`	The command option from the `ssh` manual.	✅	✅		`PARAMETER_COMMAND` `COMMAND` `PARAMETER_SCRIPT` `SCRIPT`	`/vela/parameters/vela-ssh/command` `/vela/secrets/vela-ssh/command`
`identity_file_path`	A path for where the `ssh` binary should look for existing identity files. These are NOT auto created by the plugin as they must be created and managed by a user and only referenced here.	❌	✅		`PARAMETER_IDENTITY_FILE_PATH` `IDENTITY_FILE_PATH` `PARAMETER_SSH_KEY_PATH` `SSH_KEY_PATH`	`/vela/parameters/vela-ssh/identity-file.path` `/vela/secrets/vela-ssh/identity-file.path`
`identity_file_contents`	The raw contents of an identity file for use with `ssh`. The plugin will take the raw contents and place it in a temporary location in the workspace with the correct permissions and inject it as an identity file to use during execution.	❌	❌		`PARAMETER_IDENTITY_FILE_CONTENTS` `IDENTITY_FILE_CONTENTS` `PARAMETER_SSH_KEY` `SSH_KEY`	`/vela/parameters/vela-ssh/identity-file.contents` `/vela/secrets/vela-ssh/identity-file.contents`
`ssh_flag`	Any additional options from the `ssh` manual. These will override the default options and be placed between the identity file options and the destination/command options at the end.	❌	✅	`-o StrictHostKeyChecking=no` `-o UserKnownHostsFile=/dev/null`	`PARAMETER_SSH_FLAG` `SSH_FLAG`	`/vela/parameters/vela-ssh/ssh.flag` `/vela/secrets/vela-ssh/ssh.flag`
`sshpass_password`	If any systems require a password for authentication it can be specified here, and the `sshpass` binary will be used in conjunction with `ssh`.	❌	❌		`PARAMETER_SSHPASS_PASSWORD` `PARAMETER_PASSWORD` `SSHPASS_PASSWORD` `PASSWORD`	`/vela/parameters/vela-ssh/sshpass.password` `/vela/secrets/vela-ssh/sshpass.password`
`sshpass_passphrase`	If any identity files require a passphrase for authentication it can be specified here, and the `sshpass` binary will be used in conjunction with `ssh`.	❌	❌		`PARAMETER_SSHPASS_PASSPHRASE` `SSHPASS_PASSPHRASE`	`/vela/parameters/vela-ssh/sshpass.passphrase` `/vela/secrets/vela-ssh/sshpass.passphrase`
`sshpass_flag`	Any additional options from the `sshpass` manual.	❌	✅		`PARAMETER_SSHPASS_FLAG` `SSHPASS_FLAG`	`/vela/parameters/vela-ssh/sshpass.flag` `/vela/secrets/vela-ssh/sshpass.flag`

Last modified March 8, 2022: feat(openssh): Add SSH & SCP documentation (#287) (fe29de8f)

SSH