Multi-Account Terraform

Software project for the cloud often involve multiple accounts. A typical setup associates a root account with multiple secondary accounts. The root account holds the Terraform state for all infrastructure on the secondary accounts. The secondary accounts commonly represent stages for development, testing and production.

Let’s say you are working with AWS and use an S3 bucket to hold the state. The following Terraform code manages this:

terraform { 
    required_providers { 
        aws = { 
            source = "hashicorp/aws" 
            version = "~> 3.29" 
        } 
    } 
 
    backend "s3" { 
        bucket = "mybucket" 
        key = "terraform.tfstate" 
        region = "eu-central-1" 
    } 
} 
 
provider "aws" { 
    profile = var.profile 
    region = "eu-central-1" 
} 

In a basic scenario with just one account Terraform just uses the current AWS profile normally provided via the environment variable AWS_PROFILE. In a multi-account scenario we want to use the S3 bucket on the root account and the infrastructure should be build on the secondary account. Terraform can be told about two accounts like that:

export AWS_PROFILE='root-account-profile'
terraform apply -var 'profile=secondary-account-profile'

The backend block in Terraform does not allow for variables. Therefor we set the AWS_PROFILE to the root account profile which will apply to the backend block. The secondary account profile will be passed in as variable. We have chosen to use a -var parameter on the command line but you could use -var-file to pass multiple variables in one file.

This works fine until you need to build the next secondary account. You need another state file in the S3 bucket to hold the state of the new account. This is what workspaces are for. At the moment we are in the default workspace which always exists. Export the variable AWS_PROFILE if you have not done already. Show the current workspaces:

> terraform workspace list
* default

Let’s create a new workspace and use that for the new secondary account:

> terraform workspace new prod
Created and switched to workspace "prod"! 

You're now on a new, empty workspace. Workspaces isolate their state, 
so if you run "terraform plan" Terraform will not see any existing state 
for this configuration.

Now that we have another separate state we can repeat the apply for a different secondary account:

terraform apply -var 'profile=another-secondary-profile'

To switch back to another workspace use select and the workspace name:

terraform workspace select default

You can now manage a cloud infrastructure setup with root account and secondary account with Terraform and workspaces.