tester

Documentation

Overview

Package tester enables execution of test commands on target EC2 instances via the AWS Systems Manager(SSM). tester will poll AWS SSM API for the success or failure of the command sent to target VMs and report success of failures accordingly.

Index

• func NewSSMClientWithDefaultConfig(t *testing.T) *ssm.Client
• func RunTestCaseForTarget(t *testing.T, client commandSenderLister, testCase commandParameterBuilder, ...)
• func RunTestCaseForTargetE(t *testing.T, client commandSenderLister, testCase commandParameterBuilder, ...) (bool, error)
• func TcpConnectionTestWithTagName(t *testing.T, client commandSenderLister, tagName string, endpoint string, ...)
• func TcpConnectionTestWithTagNameE(t *testing.T, client commandSenderLister, tagName, endpoint string, ...) (bool, error)
• type RetryConfig
  • func NewRetryConfig(maxRetries int, waitBetweenRetries time.Duration) RetryConfig
  • func NewRetryDefaultConfig() RetryConfig
• type ShellTestCase
  • func NewShellTestCase(command string, condition bool) ShellTestCase
• type TagNameTarget
  • func NewTagNameTarget(tagNameValue string) TagNameTarget

Functions

func NewSSMClientWithDefaultConfig

func NewSSMClientWithDefaultConfig(t *testing.T) *ssm.Client

NewSSMClientWithDefaultConfig initialises and returns and instance of AWS SSM Service Client with default config.

func RunTestCaseForTarget

func RunTestCaseForTarget(t *testing.T, client commandSenderLister, testCase commandParameterBuilder, target targetParamBuilder,
	retryConfig RetryConfig)

RunTestCaseForTarget runs a test for the provided testCase, target and retry related configuration It fails the test if no instances are found to match the target. It fails the test if any one of the instances cannot run the testCase successfully or within timeout, or any other error. It passes the test if all found instances targets run the testCase successfully in the given timeouts.

testCase provides configuration for what command to send via the SendCommand API of SSM and whether to check for success or failure. target provides the configuration of which ec2 instances should be targeted for the test.

retryConfig provides configuration for how the tester would poll aws ssm api for the test results

func RunTestCaseForTargetE

func RunTestCaseForTargetE(t *testing.T, client commandSenderLister, testCase commandParameterBuilder, target targetParamBuilder,
	retryConfig RetryConfig) (bool, error)

RunTestCaseForTargetE is like RunTestCaseForTarget but returns a bool and error It returns true and nil if instances are found and all instance can run connection command successfully. It returns false and an error if no instances are found to match the Name tag. It returns false and an error if any one of the instances cannot run the command successfully or within timeout. It returns false and error for any other error.

func TcpConnectionTestWithTagName

func TcpConnectionTestWithTagName(t *testing.T, client commandSenderLister, tagName string, endpoint string, port string, retryConfig RetryConfig)

TcpConnectionTestWithTagName is meant as a helper and to demonstrate how to use tester.RunTestCaseForTarget for other custom tests. It configures the test command as "timeout 3 bash -c '</dev/tcp/endpoint/port'", which should test tcp connectivity to endpoint:port in 3 seconds or fail. The command relies on native bash capability and hence has minimal dependency on installed binaries and should work across wide range of linux/mac systems (as opposed to using netcat or curl for example).

It passes the test if instances are found and all instance can run connection command successfully. It fails the test if no instances are found to match the Name tag. It fails the test if any one of the instances cannot run the command successfully or within timeout, or any other error. It passes the test if all found instances for tag Name run the command successfully in the given timeouts.

tagName should be the string tagNameValue of the tag:Name of the target EC2 instances. endpoint, and port should be the network endpoint to validate tcp connectivity to.

maxRetries specifies the number of times the test should poll AWS API for results of the command sent to the target EC2 VMs. waitBetweenRetires specifies the duration in time.Seconds to wait between each retry. these values may need to be adjusted for the total number of ec2 instances that are expected to run the test command.

func TcpConnectionTestWithTagNameE

func TcpConnectionTestWithTagNameE(t *testing.T, client commandSenderLister, tagName, endpoint string, port string, retryConfig RetryConfig) (bool, error)

TcpConnectionTestWithTagNameE is like TcpConnectionTestWithTagName but returns a bool and error. It returns true and nil if instances are found and all instance can run connection command successfully. It returns false and an error if no instances are found to match the Name tag. It returns false and an error if any one of the instances cannot run the command successfully or within timeout. It returns false and error for any other error.

Types

type RetryConfig

type RetryConfig struct {
	// contains filtered or unexported fields
}

RetryConfig contains configuration for the testers retry logic while polling AWS SSM API for test results. It should be configured with larger values for commands that take longer to run, may have to run on a large number ec2 targets

func NewRetryConfig

func NewRetryConfig(maxRetries int, waitBetweenRetries time.Duration) RetryConfig

NewRetryConfig returns a instance of RetryConfig where maxRetries is the total number of times the tester will poll ssm api to check for results of the test commands. waitBetweenRetries is the amount of time to wait between each retry.

These values may need to be adjusted if the test command is expected to be long running, or the total number of target instance is fairly large, then you may want to increase waitBetweenRetries and maxRetries values.

func NewRetryDefaultConfig

func NewRetryDefaultConfig() RetryConfig

NewRetryDefaultConfig is like NewRetryConfig but it creates a RetryConfig with fixed values where maxRetries is 5, and waitBetweenRetries is 5 seconds. This should be appropriate for a wide variety of test commands

type ShellTestCase

type ShellTestCase struct {
	// contains filtered or unexported fields
}

ShellTestCase configuration for a shell script command and a condition

func NewShellTestCase

func NewShellTestCase(command string, condition bool) ShellTestCase

NewShellTestCase is a constructor for ShellTestCase type. It expects command and condition arguments. command is a string representation of the shell test command that should be run in a test. eg. "echo foo" or "timeout 2 bash -c '</dev/tcp/google.com/443'" to test tcp connectivity to google.com:443 in 2 seconds. condition is bool that represents if the test should check of success(i.e exit code is 0) or failure(i.e exit code is not 0).

Important Note - validity of the command depends on the OS and Binaries installed on the target instances. It is up to the user to ensure that that is the command uses a binary, it is installed on the target instance. Eg. if the command is 'aws s3 ls' then the user should ensure that the aws cli is installed on the target instance of the test would always fail.

type TagNameTarget

type TagNameTarget struct {
	// contains filtered or unexported fields
}

TagNameTarget fulfills the tagParamBuilder interface for targets instances to be selected by the tag:Name

func NewTagNameTarget

func NewTagNameTarget(tagNameValue string) TagNameTarget

NewTagNameTarget returns and instance of TagNameTarget that can be supplied to the tester NewTagNameTarget expects a tagNameValue that should be the string value of the tag:Name of the instances to be targeted.