Terraform Workspaces: A Smart Way to Manage Environments

Terraform Workspaces provide a powerful way to manage multiple environments using the same set of configuration files. Instead of duplicating directories for each project or environment, workspaces allow you to isolate infrastructure states and apply changes independently.

This feature is ideal for scenarios like deploying development, staging, and production environments using a single codebase—saving time and improving consistency across environments.

Understanding Terraform State and Its Role

Terraform uses a state file to keep track of existing resources in your infrastructure. Whether the state is stored locally or remotely, it acts as the single source of truth for Terraform’s planning and apply operations.

By default, each configuration directory maps to a single state file. This means if you want to manage different environments (like ProjectA and ProjectB), you’d typically duplicate the entire configuration directory and modify each independently. However, this defeats the purpose of reusable infrastructure as code.

That’s where Terraform Workspaces shine.

What Are Terraform Workspaces?

Terraform Workspaces allow you to manage multiple states using a single configuration. You can think of a workspace as a distinct environment, each with its own isolated state file. Using this feature, you can apply the same infrastructure code to create different environments, such as ProjectA and ProjectB, with unique configurations.

With workspaces, you reduce repetition, increase consistency, and manage environments more efficiently—all without duplicating code.

Creating and Managing Workspaces

Terraform provides a simple command-line interface to manage workspaces.

Creating a Workspace

To create a new workspace, use the following command:

terraform workspace new ProjectA

This command creates a new workspace named ProjectA and switches to it automatically.

Listing Workspaces

To view all available workspaces:

terraform workspace list

The current workspace will be marked with an asterisk *.

Switching Workspaces

You can switch between workspaces like this:

terraform workspace select ProjectB

Now you’re in the ProjectB workspace, and all operations will be scoped to its state.

Using Workspaces in Configuration Files

Terraform provides a special built-in variable called terraform.workspace that returns the name of the current active workspace.

You can use this variable dynamically to define values such as tags, AMIs, or even entire resource blocks based on the workspace.

For example, suppose you have the following requirements:

• ProjectA should use a specific AMI and be tagged accordingly.
• ProjectB should use a different AMI but the same configuration otherwise.

Define Variables

Start by defining your variables in a variables.tf file:

variable "region" {
  default = "ca-central-1"
}

variable "instance_type" {
  default = "t2.micro"
}

variable "ami" {
  type = map(string)
  default = {
    ProjectA = "ami-xxxxxxx279"
    ProjectB = "ami-yyyyyyf4d"
  }
}

Use terraform.workspace for Dynamic Values

In your main.tf file, you can use terraform.workspace and lookup() to dynamically set the values:

resource "aws_instance" "web" {
  ami           = lookup(var.ami, terraform.workspace)
  instance_type = var.instance_type

  tags = {
    Name = terraform.workspace
  }
}

With this setup:

• Running terraform apply in the ProjectA workspace will create an instance with the ProjectA AMI and tag.
• Switching to ProjectB and reapplying will create an instance with ProjectB settings.

No duplicate code. Just smart usage of dynamic values.

How Terraform Stores Workspace States

When workspaces are used, Terraform no longer stores state in the default terraform.tfstate file. Instead, it creates a .terraform directory containing a terraform.tfstate.d folder. Inside this folder, each workspace has its own directory with a separate terraform.tfstate file.

This design ensures total separation of resources between environments while keeping the configuration DRY (Don’t Repeat Yourself).

Key Benefits of Terraform Workspaces

1. Reusability

Avoid maintaining separate directories and duplicating files for each environment.

2. Isolation

Each workspace maintains its own state file, ensuring that changes in one environment do not impact another.

3. Simplicity

Workspaces provide a clean way to manage multiple environments with minimal configuration overhead.

Best Practices for Using Workspaces

• Use clear and meaningful workspace names (e.g., dev, staging, prod, ProjectA, ProjectB).
• Combine workspaces with input variables and maps to maximize flexibility.
• Avoid complex logic that depends too heavily on workspace names; keep configurations maintainable.

Conclusion

Terraform Workspaces offer a clean, scalable solution for managing multiple environments without duplicating configuration files. By leveraging the built-in terraform.workspace variable and organizing your inputs smartly, you can dynamically adjust infrastructure deployments based on the workspace you are in.

This not only simplifies environment management but also enforces consistent practices across teams and projects. If you’re aiming for reusable, scalable, and environment-aware infrastructure as code, Terraform Workspaces are your best friend.

Frequently Asked Questions (FAQ)