Terraform Starter Kit

The basic building blocks for configuring a cloud infrastructure inside of a monorepo project using Terraform.

Requirements

Node.js v16+ with Yarn package manager
Google Cloud SDK and Terraform CLI
VS Code editor with recommended extensions

Initial Setup

How to install Terraform CLI on macOS?

$ brew tap hashicorp/tap
$ brew install hashicorp/tap/terraform
$ brew update
$ brew upgrade hashicorp/tap/terraform
$ yarn tf -version

How to create Google Cloud Platform projects?

Simply navigate to Google Cloud Resource Manager and create two GCP projects for both test (QA) and prod (production) environments, e.g. "example" and "example-test".

Fore more information visit https://cloud.google.com/resource-manager/docs/creating-managing-projects

How to configure Terraform Cloud workspaces?

Sign in to Terraform Cloud dashboard.
Create or join an organization.
Create two workspaces — app-test and app-prod for test/QA and production environments.
In each of these workspaces create an environment variable called GOOGLE_CREDENTIALS with the value containing JSON key of a GCP service account. Note, this GCP service account needs to have Owner or Editor + Service Usage Admin roles.

For more information visit https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference

How to authenticate Terraform CLI in Terraform Cloud?

Create a personal or team API Token via Terraform Cloud dashboard → Settings.
Save API token to the .terraformrc file in root of the project:

credentials "app.terraform.io" {
  token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
}

NOTE: This would allow to using different Terraform credentials per software project if you want to.

Customize the project

Run yarn install to bootstrap .terraformrc and infra/overrides.tf files
Create a Terraform API Token and save it to .terraformrc file
Update Terraform Cloud organization name in infra/backend.tf
Update other variables in the infra/locals.tf file
Ensure that Terraform Cloud workspaces exist and have all the required environment variables

Getting Started

Once the initial configuration steps are done (see infra/backend.tf, infra/locals.tf), you should be able to run Terraform CLI commands either directly or via a Yarn-based wrapper:

$ terraform -chdir=infra init -upgrade
$ terraform -chdir=infra plan
$ terraform -chdir=infra apply -auto-approve

Note that it uses test as the default workspace environment defined in VSCode's integrated terminal settings.

To use a different environment set the TF_WORKSPACE environment variable:

$ TF_WORKSPACE=prod terraform -chdir=infra plan
$ TF_WORKSPACE=prod terraform -chdir=infra apply -auto-approve

Alternatively, use the wrapper CLI:

# Uses `test` environment by default
$ yarn plan
$ yarn apply -auto-approve

# Explicitly setting `prod` as the selected workspace environment
$ yarn plan --env=prod
$ yarn apply --env=prod -auto-approve