State Isolation: Workspaces vs File Layouts — When to Use Each

Isolation

Terraform infrastructure code is sensitive, and one of the things you do not want to do as an engineer is destroy your infrastructure because of a single line of code or misconfiguration. You always want your production environment to be isolated from your staging and development environments. In Terraform, there are two ways of doing this: workspaces and file layouts.

Isolation via workspaces

Workspaces are a good way to do quick isolation environments.

Create a new workspace. terraform workspace new example1

Created and switched to workspace "example1"!

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.

List workspaces. terraform workspace list

Show your current workspace. terraform workspace show

Whenever you perform changes in a workspace, the changes are isolated to that workspace, and Terraform only sees the state file of that workspace.

terraform {
  backend "s3" {
    bucket = "terraform-up-and-running-state-2c1ab3b29e8ffc0221983305ac2bce60"
    key = "global/s3/terraform.tfstate"
    region = "us-east-2"

    dynamodb_table = "terraform-up-and-running-locks"
    encrypt = true
  }
}

key is where your state file will be stored in your bucket.

If I created a workspace terraform workspace new test-workspace,

an env:/ folder will be created in the bucket. This folder will have the workspace folder you created, test-workspace/. Inside test-workspace/ is whatever you specified in the key.

path: terraform-up-and-running-state-2c1ab3b29e8ffc0221983305ac2bce60/env:/test-workspace/global/s3/terraform.tfstate

If I have another workspace.

terraform workspace new example1

path: terraform-up-and-running-state-2c1ab3b29e8ffc0221983305ac2bce60/env:/example1/global/s3/terraform.tfstate

Pro

Workspaces are quick and easy to create. It can be done with a few commands, without having the code redundancy.

Con

It is easy to forget which workspace you are in and find yourself applying changes to the wrong one.

Isolation via File layout

This isolation method involves separating folders in your configuration code. Example, having a separate folder for staging code and production.

In the above example, the S3 folder is for creating the S3 bucket and DynamoDB used by the backend, while the MySQL has code for the database, and the webserver-cluster has code for the robust web cluster. Each folder has its own backend linked to the S3 bucket and a key defining where to store the state file.

terraform {
  backend "s3" {
    bucket = "terraform-up-and-running-state-2c1ab3b29e8ffc0221983305ac2bce60"
    key = "stage/data-stores/mysql/terraform.tfstate"
    region = "us-east-2"

    dynamodb_table = "terraform-up-and-running-locks"
    encrypt = true
  }
}

If you want to apply changes, you have to terraform apply in each folder.

Pro

When making changes, you are aware of where they are getting applied

Con

You need to terraform apply multiple times.