Requirements

• tfenv - This is used in order to manage different Terraform versions
• terraform-docs - This is used in our pre-commit hook in order to generate documentation from Terraform modules in various output formats.
• pre-commit-configuration to run code standardization (terraform fmt) and documentation (terraform docs) automation on git commit
• Granted (optional) - tooling to help assume your SSO role into an AWS account
• Public cloud provider access credentials (if not using Granted)

---

Prerequisites

This codebase uses the following Terraform and Golang versions. Code has not be tested and verified to work with any other versions other than what is listed below:

• Terraform: 1.2.0
• Go: 1.18

Installation Steps (MacOS)

brew install pre-commit gawk terraform-docs coreutils tfenv awscli jq cfn-lint

tfenv

---

List current Terraform versions installed on your system

tfenv list

Install a specific version of Terraform

tfenv install 1.2.0

Select Terraform version to be used, this could be used to switch between versions

tfenv use 1.2.0

pre-commit

---

Pre-Commit Usage

• Pre-Commit documentation
• Hook documentation

You must git add . your files before the pre-commit hook will run against them.

Check the version

pre-commit --version

Install the git hook scripts

pre-commit install

Run against all files (git add must be run first)

pre-commit run -a

Authenticate to AWS environments with Granted (Optional)

---

Below are steps to ensure easy access to AWS environments by assuming your SSO role with Granted

# install with Homebrew
brew tap common-fate/granted
brew install granted

# verify installation
➜ granted -v

Granted v0.3.0

Setup your AWS profile

Follow the steps as outlined by executing the command in your terminal: aws configure sso

aws configure sso
> SSO start URL [None]: <Start URL> (the redirect URL after you login to AWS Control Tower through an SSO provider)
> SSO Region: us-west-2

# after the above values are entered your browser will open to and have you confirm
# a few prompts.  Allow the authorize request.

#When successful, you will see a "Request Approved" AWS Modal in your browser tab.

# Go back to the Terminal session to finish the prompts

# Pick the account to which you wish to create a profile, you may also see all accounts to which you have access.

# Pick your assigned role, this will vary based on your organization
# Default CLI region: us-west-2
# Output format: JSON

# CLI Profile name: you can keep what is generated (not recommended) or use something explicit to the environment, like "shared-services-admin"

Test your credentials

$ assume
 Please select the profile you would like to assume:  [Use arrows to move, type to filter]
> shared-services-admin (this is the profile you created in the previous step)

# You will then see a message like: 
[shared-services-admin](us-west-2) session credentials will expire 2022-09-27 14:15:48 -0400 EDT
>

# check to be sure you can query sts and receive your assume role arn back
$ aws sts get-caller-identiy
> 
{
    "UserId": "(redacted):[email protected]",
    "Account": "1111111111",
    "Arn": "arn:aws:sts::1111111111:assumed-role/AWSReservedSSO_AWSPowerUserAccess_(redacted)/[email protected]"
}

# if the above commands are successful, then you can now use Terraform or Run terrestest from your local machine

Go

---

# Update and Install Go (for a specfic version, append @{version}, like `brew install [email protected]`)
brew update && brew install [email protected]

# Following Go best practices, create 3 new directories ($HOME/go/bin, $HOME/go/src, $HOME/go/pkg)
mkdir -p $HOME/go/{bin,src,pkg}

# Set important environment variables
# Add the below to your .bashrc, or .zshrc
export GOPATH=$HOME/go
export GOROOT="$(brew --prefix golang)/libexec"
export PATH="$PATH:${GOPATH}/bin:${GOROOT}/bin"

# If you're on an M1 mac, make Go play nicely with Rosetta
export GODEBUG=asyncpreemptoff=1

# source your shell
source $HOME/.bashrc (or .zshrc)

Terratest - Recommended Test Practices

---

Use table driven tests

• These tests are a fairly standard practice
• They let you clearly and easily create multiple test-cases for a single test
• They are defined as an array of structs, where fields of the struct are variables for each test case

When defining essential variables, USE hard-coded fixed fields

• Repository examples should hard-code fixed fields, which are essential to the spirit of the example

When defining field variables to be tested, DO NOT USE use hard-coded fixed fields

• Repository examples should use variables for fields which are to be tested (i.e., so that they can be fed in via terratest)

Useful packages

• testify/assert library -- assertion library to assert test results against expected fields
• aws api helper library -- library to help us query the AWS API directly

Helpful terminal commands

You must be authenticated to the target AWS account before executing the below commands

# run all tests cases with no verbose output (not recommended, as you can't see errors)
go test

# apply verbose output and extend the timeout past the default of 10m (helpful for tests that need longer to run -- like AWS RDS examples)
go test -v -timeout 30m

# run a single test, be sure the test case matches the regex TestSimpleDynamoDb
to test run eks-example-cluster

# print the test output to a file
go test -v -timeout 30m | tee ~/Desktop/module_terratest_output.txt

Supporting Documentation

• Terratest documentation

Terraform

---

Prerequisites:

• You can successfully authenticate to AWS via CLI using Granted or your preferred method of authentication.
• You have the correct version of Terraform installed through tfenv

When developing modules, it is easier to run these commands from your example directory where you have already defined an example for your tests to run against.

Navigate to the directory where you would like to run your terraform configuration, authenticate to AWS through the CLI (optionally through Granted)

terraform init (install modules, both local and external)
terraform validate (validate your configuration will not error before the plan/apply stage)
terraform plan (check what you're going to provision)
terraform apply (deploy the infrastructure)
terraform destroy (destroy the infrastructure)

Supporting Documentation

• Terratest documentation

Requirements

Name	Version
terraform	1.2.0
aws	>=4.28

Providers

Name	Version
some	n/a

Modules

Name	Source	Version
foo	../../	n/a

Resources

Name	Type
some_aws_resource.bar	resource

Inputs

Name	Description	Type	Default	Required
bar	value	map(any)	{}	no
baz	value	list(string)	[ "value" ]	no
foo	value	string	""	no

Outputs

No outputs.