terrafirm

Terrafirm performs integration tests of Watchmaker using Terraform to launch Windows and Linux builds.

Terrafirm can be run locally or with AWS CodeBuild. In order to use it, you will need AWS credentials and to provide environment variables.

May 2020 Changes

Previously, pkg was used in S3 prefixes, environment variables, and code to indicate something related to standalone packages. Now standalone is used for that purpose.
There are two separate input variables for source and standalone builds: TF_VAR_source_builds and TF_VAR_standalone_builds. See below for more information.
A GNUMakefile now provides shortcuts for Terrafirm tasks:
- make (a/k/a make again) - using environment/Terraform variables or a .env file, apply the configuration (perform init if needed)
- make valid - using environment/Terraform variables or a .env file, validate the configuration (perform init if needed)
- make clean - destroy the configuration
- make fresh - clean actions plus delete the log, state files, and provider plugins
- make neat - format the .tf files
- make state - show what is in the Terraform state
- make count - count of the items in the Terraform state
If you prefer to disable color in Terraform's output while using the GNUMakefile, set the environment variable COLOR_OPTION to -no-color.

Instance Test Options

Several environment variables allow you to control what builds Terrafirm runs. Each of them is described in more detail in this section.

TF_VAR_source_builds and TF_VAR_standalone_builds

To pick specific operating system builds, set the TF_VAR_source_builds and TF_VAR_standalone_builds environment variables to one or more the following operating system values. In the variable names, standalone/source refers to the standalone package test or the from source test.

centos7
rhel7
win16
win19

For example, to set the TF_VAR_source_builds environment variable in Bash-like shells, use this syntax:

export TF_VAR_source_builds='["centos7","win16"]'

You would expect Terraform's output to include lines like these if you run Terrafirm with these settings:

aws_instance.source_build["win16"]: Still creating... [1m10s elapsed]
aws_instance.source_build["centos7"]: Still creating... [1m10s elapsed]

Requirements

Name	Version
terraform	>= 0.12
aws	>= 4.0
http	>= 3.0
random	>= 3.0
tls	>= 4.0

Providers

Name	Version
aws	>= 4.0
http	>= 3.0
random	>= 3.0
tls	>= 4.0

Resources

Name	Type
aws_ami.amis	data source
aws_subnet.tfi	data source
aws_vpc.tfi	data source
http_http.ip	data source

Inputs

Name	Description	Type	Default	Required
subnet_ids	n/a	`list(string)`	n/a	yes
assign_public_ip	n/a	`bool`	`false`	no
availability_zone	n/a	`string`	`"us-east-1c"`	no
aws_region	n/a	`string`	`"us-east-1"`	no
codebuild_id	n/a	`string`	`""`	no
common_args	n/a	`string`	`"-n --log-level debug"`	no
debug	n/a	`bool`	`true`	no
docker_slug	n/a	`string`	`""`	no
git_ref	n/a	`string`	`"main"`	no
git_repo	n/a	`string`	`"https://github.com/plus3it/watchmaker.git"`	no
instance_profile	n/a	`string`	`""`	no
lx_args	n/a	`string`	`"--log-dir=/var/log/watchmaker"`	no
lx_instance_type	n/a	`string`	`"t2.medium"`	no
lx_user	n/a	`string`	`"root"`	no
lx_userdata_log	n/a	`string`	`"/var/log/userdata.log"`	no
s3_bucket	n/a	`string`	`"mybucket"`	no
scan_s3_url	n/a	`string`	`""`	no
source_builds	n/a	`list(string)`	[ "win16", "win19", "rhel7", "centos7", "rhel8", "centos8stream", "ol8" ]	no
standalone_builds	n/a	`list(string)`	[ "win16", "win19", "rhel7", "centos7", "rhel8", "centos8stream", "ol8" ]	no
win_args	n/a	`string`	`"--log-dir=C:\\Watchmaker\\Logs"`	no
win_instance_type	n/a	`string`	`"t2.large"`	no
win_user	n/a	`string`	`"Administrator"`	no
win_userdata_log	n/a	`string`	`"C:\\Temp\\userdata.log"`	no

Outputs

Name	Description
build_date_hm	n/a
build_date_ymd	n/a
build_id	n/a
build_slug	n/a
builders	n/a
private_key	n/a
public_key	n/a
source_builds	n/a
standalone_builds	n/a
unique_builds_needed	n/a
winrm_pass	n/a

TERRAFIRM ENVIRONMENT VARIABLES

Variable	Default	Req/Opt (in CodeBuild)	Description
`TF_DESTROY_AFTER_TEST`	true	optional	(CodeBuild only) Whether or not to destroy all resources created after the test. (WARNING: Depending on failure, Terraform may not always be able to destroy provisioned resources.)

Development Paths

Terrafirm performs integration tests of Watchmaker. Development of Terrafirm also involves testing: Terrafirm testing. Keep these development paths separate to avoid confusion.

Terrafirm development, Terrafirm testing

Local testing of a Terrafirm branch involves checking out the development branch on the local system. Environment variables do not indicate the correct Terrafirm reference to test because you have used Git to put the correct Terrafirm code in play on your local development system.

CodeBuild testing of a remote Terrafirm branch involves commenting go codebuild go on a Terrafirm repository pull request. Through the Terrafirm webhook, the correct Git reference to Terrafirm is passed to CodeBuild and CodeBuild fetches that Terrafirm reference. You can verify which Terrafirm reference was used by checking the Build details of an individual build in Codebuild. This will list, for example, Source provider: GitHub, Repository: plus3it/terrafirm, Source version: pr/55.

Additionally, remember that the Terrafirm reference (e.g., pull request) to test is used either on your local system or the CodeBuild test instance but not on each EC2 instance built though Terraform.

Watchmaker development, Watchmaker testing

On the other hand, integration testing of Watchmaker begins by commenting go codebuild go on a Watchmaker repository pull request. The Watchmaker-Terrafirm webhook will set an environment variable to pass the correct Watchmaker reference (e.g., pull request #330) to Terrafirm. On each server that Terrafirm builds, the Watchmaker reference will be used when retrieving Watchmaker with Git.

In contrast to Terrafirm development, the Watchmaker reference (e.g., pull request) to test is used on each EC2 instance built through Terraform but is not used either on your local system or the CodeBuild test instance.

lorengordon / terrafirm