lwrunner

Documentation

Overview

A runner package that executes commands on remote hosts.

Index

• Constants
• func AddKnownHost(host string, remote net.Addr, key ssh.PublicKey, knownFile string) (err error)
• func CheckKnownHost(host string, remote net.Addr, key ssh.PublicKey, knownFile string) (found bool, err error)
• func DefaultIdentityFilePath() (string, error)
• func DefaultKnownHosts() (ssh.HostKeyCallback, error)
• func DefaultKnownHostsPath() (string, error)
• func EncodePrivateKeyToPEM(privateKey *rsa.PrivateKey) ([]byte, error)
• func GeneratePrivateKey(bitSize int) (*rsa.PrivateKey, error)
• func GetKeyBytes() ([]byte, []byte, error)
• func GetPublicKeyBytes(key *rsa.PublicKey) ([]byte, error)
• func GetSSMCommandInvocationStdErr(out ssm.GetCommandInvocationOutput) string
• func GetSSMCommandInvocationStdOut(out ssm.GetCommandInvocationOutput) string
• type AWSRunner
  • func NewAWSRunner(amiImageId, userFromCLIArg, host, region, availabilityZone, instanceID string, ...) (*AWSRunner, error)
  • func (run AWSRunner) AssociateInstanceProfileWithRunner(cfg aws.Config, instanceProfile types.InstanceProfile) (string, error)
  • func (run AWSRunner) DisassociateInstanceProfileFromRunner(cfg aws.Config, associationID string) error
  • func (run AWSRunner) RunSSMCommandOnRemoteHost(cfg aws.Config, operation string) (ssm.GetCommandInvocationOutput, error)
  • func (run AWSRunner) SendAndUseIdentityFile(cfg aws.Config) error
  • func (run AWSRunner) SendPublicKey(pubBytes []byte, cfg aws.Config) error
• type GCPRunner
  • func NewGCPRunner(host, parentUsername, projectID, availabilityZone, instanceID string, ...) (*GCPRunner, error)
  • func (run GCPRunner) SendAndUseIdentityFile() error
  • func (run GCPRunner) SendPublicKey(pubBytes []byte) error
• type Runner
  • func New(user, host string, callback ssh.HostKeyCallback) *Runner
  • func (run *Runner) Address() string
  • func (run *Runner) Exec(cmd string) (stdout bytes.Buffer, stderr bytes.Buffer, err error)
  • func (run Runner) UseIdentityFile(file string) error
  • func (run Runner) UsePassword(secret string)

Constants

const SSMInstancePolicy string = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"

Functions

func AddKnownHost

func AddKnownHost(host string, remote net.Addr, key ssh.PublicKey, knownFile string) (err error)

AddKnownHost adds a host to the provided known hosts file, if no known hosts file is provided, it will fallback to default known_hosts file

func CheckKnownHost

func CheckKnownHost(host string, remote net.Addr, key ssh.PublicKey, knownFile string) (found bool, err error)

CheckKnownHost checks if a host is in known hosts file, if no known hosts file is provided, it will fallback to default known_hosts file

func DefaultIdentityFilePath

func DefaultIdentityFilePath() (string, error)

func DefaultKnownHosts

func DefaultKnownHosts() (ssh.HostKeyCallback, error)

DefaultKnownHosts returns a host key callback from default known hosts path

func DefaultKnownHostsPath

func DefaultKnownHostsPath() (string, error)

DefaultKnownHostsPath returns default user ~/.ssh/known_hosts file

func EncodePrivateKeyToPEM

func EncodePrivateKeyToPEM(privateKey *rsa.PrivateKey) ([]byte, error)

Encodes private key from RSA struct to PEM formatted bytes

func GeneratePrivateKey

func GeneratePrivateKey(bitSize int) (*rsa.PrivateKey, error)

Helper function to generate a random private key. This key will stay in memory and does not persist across test runs.

func GetKeyBytes

func GetKeyBytes() ([]byte, []byte, error)

Generates SSH keys in EC2-readable format Returns public key bytes, private key bytes, error

func GetPublicKeyBytes

func GetPublicKeyBytes(key *rsa.PublicKey) ([]byte, error)

Takes an rsa.PublicKey and returns bytes suitable for writing to .pub file Returns in the format "ssh-rsa ..."

func GetSSMCommandInvocationStdErr

func GetSSMCommandInvocationStdErr(out ssm.GetCommandInvocationOutput) string

GetSSMCommandInvocationStdErr is a helper function to safely deference the SSM struct we receive from the AWS API.

func GetSSMCommandInvocationStdOut

func GetSSMCommandInvocationStdOut(out ssm.GetCommandInvocationOutput) string

GetSSMCommandInvocationStdOut is a helper function to safely deference the SSM struct we receive from the AWS API.

Types

type AWSRunner

type AWSRunner struct {
	Runner           Runner
	Region           string
	AvailabilityZone string
	InstanceID       string
	ImageName        string
}

func NewAWSRunner

func NewAWSRunner(
	amiImageId,
	userFromCLIArg,
	host,
	region,
	availabilityZone,
	instanceID string,
	filterSSH bool,
	callback ssh.HostKeyCallback,
	cfg aws.Config) (*AWSRunner, error)

func (AWSRunner) AssociateInstanceProfileWithRunner

func (run AWSRunner) AssociateInstanceProfileWithRunner(
	cfg aws.Config, instanceProfile types.InstanceProfile,
) (string, error)

AssociateInstanceProfileWithRunner associates a given instance profile with the receiving runner. First checks if there are any instance profiles already associated with the runner, and returns an error if so (since a runner can only have one instance profile associated with it). Then associates the instance profile with the runner. Returns the association ID or an error.

func (AWSRunner) DisassociateInstanceProfileFromRunner

func (run AWSRunner) DisassociateInstanceProfileFromRunner(cfg aws.Config, associationID string) error

func (AWSRunner) RunSSMCommandOnRemoteHost

func (run AWSRunner) RunSSMCommandOnRemoteHost(cfg aws.Config, operation string) (
	ssm.GetCommandInvocationOutput, error,
)

RunSSMCommandOnRemoteHost takes a shell command to install the agent on the runner the runner and executes it using SSM. `operation` must be one of the commands allowed by the SSM document. This function will not return until the command is in a terminal state, or until 2min have passed.

func (AWSRunner) SendAndUseIdentityFile

func (run AWSRunner) SendAndUseIdentityFile(cfg aws.Config) error

func (AWSRunner) SendPublicKey

func (run AWSRunner) SendPublicKey(pubBytes []byte, cfg aws.Config) error

Helper function to send a public key to a test instance. Uses EC2InstanceConnect. The AWS account used to run the tests must have EC2InstanceConnect permissions attached to its IAM role. First checks to make sure the instance is still running.

type GCPRunner

type GCPRunner struct {
	Runner           Runner
	ParentUsername   string
	ProjectID        string
	AvailabilityZone string
	InstanceID       string
}

func NewGCPRunner

func NewGCPRunner(
	host, parentUsername, projectID, availabilityZone, instanceID string, callback ssh.HostKeyCallback,
) (*GCPRunner, error)

func (GCPRunner) SendAndUseIdentityFile

func (run GCPRunner) SendAndUseIdentityFile() error

func (GCPRunner) SendPublicKey

func (run GCPRunner) SendPublicKey(pubBytes []byte) error

SendPublicKey is a helper function to send a public key to a GCP account for OSLogin authentication. The account must have the "Compute OS Login" IAM role and "Service Account User" authorization for the GCE default service account. When the SSH key is sent, it will persist in the GCP account for 10min.

type Runner

type Runner struct {
	Hostname string
	Port     int
	*ssh.ClientConfig
}

func New

func New(user, host string, callback ssh.HostKeyCallback) *Runner

func (*Runner) Address

func (run *Runner) Address() string

func (*Runner) Exec

func (run *Runner) Exec(cmd string) (stdout bytes.Buffer, stderr bytes.Buffer, err error)

Exec executes a command on the configured remote host

func (Runner) UseIdentityFile

func (run Runner) UseIdentityFile(file string) error

func (Runner) UsePassword

func (run Runner) UsePassword(secret string)