Workspaces

Terraform workspaces allow you to manage multiple instances of your infrastructure resources in the same configuration. This is particularly useful when you want to create multiple versions of the same resources, such as staging, testing, or production environments, without having to duplicate your configuration files.

In this section, we will explore how to use Terraform workspaces in your projects.

What is a Terraform Workspace?

A Terraform workspace is a way to create multiple instances of the same resources within the same configuration. Each workspace has its own set of state files, which means that you can create multiple instances of the same resources without affecting the state files of other instances.

For example, you could create a workspace for your development environment and another workspace for your production environment. Each workspace would have its own set of state files, allowing you to manage your resources independently of each other.

Creating a Terraform Workspace

Creating a Terraform workspace is easy. First, you’ll need to initialize your workspace by running the following command:

terraform workspace new my-workspace

In this example, we create a new workspace called “my-workspace”. Once you have created a new workspace, you can switch to it using the following command:

terraform workspace select my-workspace

This command switches your active workspace to “my-workspace”. Once you have switched to a workspace, any changes you make to your configuration will only affect the resources within that workspace.

Using Workspaces with Modules

Workspaces are configured at the Terraform backend level, not inside individual modules. When you use workspaces, all modules called from your root configuration share the same workspace context. The terraform.workspace variable is available throughout your configuration, including inside modules, so you can use it to customise resource behaviour per workspace.

Here’s an example of calling a module and passing the current workspace name as a variable:

module "example" {
  source    = "./modules/example"
  workspace = terraform.workspace
}

In this example, the module receives the current workspace name as an input variable. The backend and workspace-specific state storage are handled by the terraform {} block in your root configuration, not inside the module itself.

Workspaces Work with Supported Backends

When using workspaces with supported remote backends, Terraform will automatically create and manage state files in separate locations within the backend. You don’t need to manually configure the state storage for each workspace—Terraform handles that for you.

For example, with the S3 backend:

• Workspace dev stores state in s3://mybucket/dev/terraform.tfstate.
• Workspace prod stores state in s3://mybucket/prod/terraform.tfstate.

In this setup, each workspace effectively maintains its own isolated state, so changes in one workspace do not impact the others.

::alert[ You can read more about support Workspace Backends [here](https://developer.hashicorp.com/terraform/language/state/workspaces#backends-supporting-multiple-workspaces).]

The terraform.workspace Variable

Terraform provides the terraform.workspace variable, which returns the name of the currently selected workspace. You can use this variable anywhere in your configuration to change behaviour based on which workspace is active.

A common pattern is setting resource sizes or instance counts per environment:

variable "instance_type" {
  default = {
    dev  = "t3.micro"
    prod = "t3.large"
  }
}

resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = var.instance_type[terraform.workspace]
}

You can also use terraform.workspace in resource names and tags to keep resources identifiable across environments:

resource "aws_s3_bucket" "assets" {
  bucket = "myapp-assets-${terraform.workspace}"
}

This avoids naming collisions when the same configuration is deployed to multiple workspaces.

CLI Workspace Limitations

CLI workspaces work well for short-lived environments like feature branches or testing, but they have limitations when used for long-lived environment separation (such as dev, staging, and production).

Some things to keep in mind:

• All workspaces share the same backend configuration and credentials. There is no way to use different IAM roles or access policies per workspace.
• All workspaces share the same Terraform configuration. If your environments need different variables, provider settings, or module versions, you need to handle that entirely through conditional logic.
• There is no built-in access control between workspaces. Anyone who can run Terraform against the backend can switch to any workspace, including production.
• It is easy to forget which workspace is active. Running terraform apply in the wrong workspace can modify the wrong environment.

For production multi-environment management, HashiCorp recommends using HCP Terraform workspaces (formerly Terraform Cloud) instead of CLI workspaces. HCP Terraform workspaces provide separate variables, credentials, access controls, and run history per workspace, which makes them a better fit for managing distinct environments at scale.

Conclusion

Terraform workspaces allow you to manage multiple instances of your infrastructure resources in the same configuration. This can be particularly useful when you want to create multiple versions of the same resources, such as staging, testing, or production environments.