Terraform Workspaces: Manage Multiple Environments

Terraform Workspaces allow you to manage multiple environments using a single Terraform configuration. Instead of maintaining separate directories for development, staging, and production, you can reuse the same code while keeping each environment's state isolated.

This approach reduces duplication, improves consistency, and makes infrastructure management easier as your deployments grow.

If you're already familiar with Terraform state, workspaces provide a practical way to maintain multiple state files without creating separate Terraform projects.

Terraform State and Why Workspaces Depend on It

Terraform uses a state file to track the infrastructure it manages. During planning and apply operations, Terraform compares your configuration against the current state to determine what changes are required.

The state file is one of the most important components of Terraform. If you're new to this concept, start with our guide on Terraform State.

By default, a Terraform configuration directory is associated with a single state file. This means that if you want to manage separate environments, such as development and production, you would traditionally create separate directories and maintain multiple copies of the same code.

That works, but it introduces duplication and increases maintenance effort.

Terraform Workspaces solve this problem by allowing a single configuration to maintain multiple isolated state files.

What Are Terraform Workspaces and Why Are They Useful?

A Terraform Workspace is an isolated instance of state within the same Terraform configuration.

Think of a workspace as a separate notebook for the same project. The Terraform code remains identical, but each notebook keeps its own record of deployed resources.

For example, the same configuration can be used to create:

• Development environment
• Staging environment
• Production environment
• Customer-specific environments
• Project-specific deployments

Each workspace maintains its own state, ensuring resources created in one workspace do not interfere with resources in another.

Pro Tip

Terraform Workspaces work best when environments are largely identical and differ only in configuration values.

If production requires a separate AWS account, different networking architecture, or stricter security controls, maintaining separate Terraform configurations is often easier than relying heavily on workspace-based logic.

Creating and Managing Terraform Workspaces

Terraform provides built-in commands for creating, selecting, and managing workspaces.

Create a New Workspace

Use the following command:

terraform workspace new ProjectA

Terraform creates the workspace and automatically switches to it.

List Available Workspaces

To see all workspaces:

terraform workspace list

Example output:

default
* ProjectA
ProjectB

The asterisk (*) indicates the currently active workspace.

Switch Between Workspaces

To switch to another workspace:

terraform workspace select ProjectB

After switching, all Terraform operations use the state associated with that workspace.

Display the Current Workspace

To view the active workspace:

terraform workspace show

Using terraform.workspace for Environment-Specific Configuration

Terraform provides a built-in expression called terraform.workspace.

It returns the name of the currently selected workspace and can be used to dynamically configure resources.

This pattern is commonly used when deploying the same application stack into development, staging, and production environments while keeping the infrastructure code identical.

Define Variables

Create a variables.tf file:

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

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

variable "ami" {
  type = map(string)

  default = {
    ProjectA = "ami-xxxxxxxxx"
    ProjectB = "ami-yyyyyyyyy"
  }
}

If you're unfamiliar with variable definitions, see our guide on the Terraform Variable Block.

Use terraform.workspace in Resources

Create the resource definition:

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

  tags = {
    Name = terraform.workspace
  }
}

In this example:

• ProjectA uses its mapped AMI
• ProjectB uses a different AMI
• Resource tags automatically reflect the workspace name
• No duplicate Terraform code is required

When you run:

terraform apply

Terraform deploys resources based on the currently selected workspace.

Where Terraform Stores State Files for Each Workspace

Terraform stores state differently when workspaces are used.

For local backends, Terraform creates workspace-specific state files under:

terraform.tfstate.d/

Example structure:

terraform.tfstate.d/
├── ProjectA/
│   └── terraform.tfstate
├── ProjectB/
│   └── terraform.tfstate

Each workspace receives its own state file, providing clear separation between environments.

Common Mistake

Many engineers assume workspaces provide complete environment isolation.

Workspaces only isolate Terraform state. They do not automatically isolate:

• AWS accounts
• IAM permissions
• Backend configurations
• Networking resources
• Security boundaries

Those controls must be configured separately.

Using Workspaces with Remote Backends

Terraform Workspaces also work with remote backends.

Many teams combine workspaces with:

• Terraform Remote State and State Locking
• AWS S3 Remote Backends
• Terraform Cloud

Remote state improves collaboration by storing state centrally and preventing concurrent modifications.

For backend-specific behavior, always refer to the official Terraform Backend Documentation.

Key Benefits of Terraform Workspaces

Reusability

You can manage multiple environments using the same Terraform configuration.

This reduces duplication and simplifies maintenance.

State Isolation

Every workspace maintains its own state file.

Changes made in one workspace do not affect another workspace.

Consistency

Development, staging, and production environments can be provisioned from the same infrastructure definition.

This reduces configuration drift.

Simplified Environment Management

Instead of managing multiple copies of Terraform code, teams can focus on a single source of truth.

Best Practices for Terraform Workspaces

When using Terraform Workspaces in production environments:

• Use clear workspace names such as dev, staging, and prod.
• Keep environment-specific values in variables or maps.
• Avoid embedding complex business logic around workspace names.
• Use version-controlled modules whenever possible.
• Combine workspaces with reusable Terraform Modules.
• Store state remotely for team-based deployments.
• Review workspace selection before running terraform apply.

For larger organizations, workspaces are often combined with:

• Terraform Modules
• Terraform Providers
• Input Variables
• Remote State

When You Should Not Use Terraform Workspaces

Terraform Workspaces are not always the right solution.

Separate Terraform configurations are often a better choice when:

• Development and production use different AWS accounts.
• Environments require different network architectures.
• Compliance requirements differ between environments.
• Teams need strict separation of infrastructure ownership.
• Environment-specific logic becomes difficult to maintain.

If workspaces introduce excessive conditional logic, consider separating environments into dedicated Terraform projects.

Terraform Workspaces vs Separate Directories

A common question is whether workspaces are better than separate directories.

Use workspaces when:

• Infrastructure is nearly identical.
• Only configuration values change.
• Teams want to reduce code duplication.

Use separate directories when:

• Infrastructure designs differ significantly.
• Accounts and permissions are isolated.
• Environment-specific requirements continue to grow.

The right choice depends on your operational model and organizational requirements.

Conclusion

Terraform Workspaces provide a practical way to manage multiple environments using a single codebase.

They help reduce duplication, maintain isolated state files, and simplify infrastructure management for environments that share the same architecture.

Used correctly, workspaces can improve consistency across development, staging, and production deployments while keeping Terraform configurations easier to maintain.

For official details and the latest behavior, review the Terraform Workspace documentation and resources available through the Terraform Registry and HashiCorp documentation.

Frequently Asked Questions (FAQ)

What is a Terraform Workspace?

A Terraform Workspace is an isolated instance of Terraform state. It allows multiple environments to share the same configuration while maintaining separate state files.

How does terraform.workspace work?

terraform.workspace returns the name of the currently selected workspace. You can use it to dynamically configure resources, tags, variables, and environment-specific settings.

Can Terraform Workspaces be used with remote backends?

Yes. Terraform Workspaces work with both local and remote backends, including S3 backends and Terraform Cloud.

How is state managed across workspaces?

Each workspace maintains its own isolated state file. Terraform automatically loads the state associated with the currently selected workspace, ensuring resources remain separate between environments.

Should I use Terraform Workspaces for staging and production?

Workspaces are a good choice when staging and production environments share the same architecture and differ mainly in configuration values.

If environments use different AWS accounts, networking designs, or security requirements, separate Terraform configurations are often a better option.