TFBuild

Terraform build management wrapper. This wrapper is primarily built to standardise:

• AWS deployments with distributed per account, per environment S3 backed terraform states
• Azure deployments with central Storage Account backed states
• VMware deployments with TF Cloud to store states in per execution TF Cloud Workspaces, which it will create dynamically during the init process.
• GCP implementation also possible, coming soon...

Support

Currently tfbuild supports the following Operating Systems:

• MacOS (64bit/Arm)
• Linux (64bit/Arm)
• Windows

Installation

1. Python > 3.8 required (3.10 and higher on MacOS M1)

2. Install with pip:

pip install tfbuild

3. Install TFBuild from wheel package published to custom pypi repo URL:

$ pip install --extra-index-url https://<repo_url>/pypi-repo/simple tfbuild

4. Install TFBuild from source repo:

clone <repo_url>.git
cd <local_repo_folder>
pip install -e .

Terraform execution prerequisites

tfbuild assumes that the deployment is executed from a git repository with the following setup:

GIT Repository - Naming Conventions and Architecture

Repository Naming Standard: <Cloud_ID>-<Project_Acronym> Branch Naming Standard: <Account_ID>-<Environment>

Cloud_ID: aws, azr, gcp, vmw

Example:

• Repository: aws-k8s
• Branch: 234625632123-dev os something like AWSShared-dev, with no dashes in <Account_ID>

GIT Repository - Environment Specific branch layout

Terraform Configurations *.tf are templatized, and should not change between branches.
Managed SDLC practices are advised to merge changes from lower environments and up.
Terraform variables should be introduced separately for each environment and site at the lowest environmental banch, and PRs used for moving the changes to the required branch.

Terraform State - AWS S3 Bucket Name

S3 buckets are an execution prerequisite, usually built as part of an AWS deployment. TFState, S3 bucket naming standard:

• Primary Bucket Naming Standard: <Bucket_Prefix>.<Account_ID>.<Environment>
• DR Bucket Naming Standards: <Bucket_Prefix>.<Account_ID>.<Environment>.dr

Example:

• Primary Bucket Name: inf.tfstate.234625632123.dev
• DR Bucket Name: inf.tfstate.234625632123.dev.dr

( dr = "true" needs to exist in the ../common/environments/env_<Environment>.hcl global declarations file )

Buckets are bi-directionally replicated.
Primary and a DR bucket are available, per account per environment.
When using account targeted S3 buckets for account and environment, there should be no conflicts between states, but uniformity for ease of usage.

Backend Path:

• General resources backend path: <Project_acronym>/<Region>/<Current_Dir>/terraform.tfvars
• Backend resources backend path: <Project_acronym>/<Current_Dir>/terraform.tfvars

Curently the only global resource that is automatically detected is Route-53.

For declaring all resources in the project global, as in Active-Passive deployments,
global_resource = "true" needs to exist in the ../common/environments/env_<Environment>.hcl global declarations file

Terraform State - TF Cloud Workspaces

• Workspace Naming standard: <Environment>-<Project_Acronym>-<Current_Dir>

As workspaces are curently only used for VMware deployment, a <Cloud_ID> is not used but will be introduced:

• Future Workspace Naming Standard: <Cloud_ID>-<Environment>-<Project_Acronym>-<Current_Dir>

Terraform State - Azure Storage Accounts

Storage Accounts are an execution prerequisite, should be created during a Subscription creation.
Similar naming as S3 buckets, but without dots, as SA names need to be alpha-numeric:

Storage Account Naming Standard:

• Primary SA Naming Standard: <Bucket_Prefix><Subscription_ID><Environment>
• DR SA Naming Standards: <Bucket_Prefix><Subscription_ID><Environment>.dr

Example:

• Primary SA Name: inftfstateshareddev
• DR SA Name: inftfstateshareddevdr

Usage

App name is tfbuild or tfb

tfbuild <command>
tfbuild <command>-<site>

tfb <command>
tfb <command>-<site>

Commands, execute specific Terraform task:

Deployment Regions allow the deployment of the same code to multiple regions.
Example:

• Deploy in the designated DR site: tfbuild apply-dr

# Usage Examples:

$ tfbuild init
$ tfbuild update
$ tfbuild plan
$ tfbuild plan-dr
$ tfbuild plan-us-west-2
$ tfbuild replan
$ tfbuild plandestroy
$ tfbuild apply
$ tfbuild apply-dr
$ tfbuild apply-us-west-2
$ tfbuild destroy
$ tfbuild taint
$ tfbuild test
$ tfbuild tfimport
$ tfbuild config --bucket_prefix=test_bucket --tf_cloud_org=test_org

Commands directly coresponding to Terraform actions, such as init, plan, apply, destroy, validate, can take the coresponding terraform options.

# Example:

$ tfbuild plan -json
$ tfbuild apply -compact-warnings -no-color

Deployment Global Variable Reference

Install Configuration file

Terraform Cloud credentials are sourced from the Terraform CLI Config File.
TF_TOKEN updates the credentials in the Terraform CLI Config File or creates a new file if one does not exist in the Terraform predefined locations.

Introducing the ability to set global wrapper variables that preceede Git global variables for any deployment.

Here are the default search paths for each platform:

• MacOS: ~/.config/tfbuild and ~/Library/Application Support/tfbuild
• Other Unix: $XDG_CONFIG_HOME/tfbuild and ~/.config/tfbuild
• Windows: %APPDATA%\tfbuild where the APPDATA environment variable falls back to %HOME%\AppData\Roaming if undefined

Variables sourced from Git Deployment scripts repository naming conventions

Variables sourced from Git Deployment scripts repository common shell files

Project environment and site specific:

• The <REPO_PATH>/common/environments/env_<Environment>.hcl environment file, for unisite deployments.
• The <REPO_PATH>/common/environments/env_<Environment>_<SITE_NAME>.hcl environment file, for multi-site deployments.
  Environment and site specific, not changeable per resource.

Variables declared in the environment file are declared as runtime variables, usable both in Linux and Windows deployments.
Example: dr = "true"

Speciffic deployment site can be configured as per the Repo architecture above, and can be called by appending a -<site>' to any command: Example: tfbuild -`

Variables exposed to the Terraform deployment scripts:

These variables are useful for resource naming, and in same deployment, inter-execution linking of remote state outputs

Terraform env speciffic wrapper variables injected into Terraform.
Variable declarations are needed in coresponding deployment variables.tf file"

Upgrade

$ pip install --upgrade tfbuild

Uninstall

$ pip uninstall tfbuild