Using Terraform Workspace Prefixes in a Remote Backend

Terraform workspaces let you organize your deployments and keep state isolated between environments. This post covers what workspaces are, then shows how the workspace prefix feature lets you manage several workspaces from a single Terraform configuration.

What Are Terraform Workspaces?

Workspaces let you create separate instances of your infrastructure for different environments (e.g., development, staging, production) or for experimentation. Each workspace keeps its own Terraform state file, so the state of one environment stays separate from the others. They all share the same Terraform configuration files, which keeps the environments consistent.

You can use workspaces with open-source Terraform locally, or in a remote backend such as Scalr or Terraform Cloud. The idea is the same in both cases: they isolate Terraform state files. But workspaces in a remote backend do more, because the runs actually execute inside Scalr. That's what unlocks features like integrations, remote state sharing, and RBAC.

How Do You Create a New Terraform Workspace?

The terraform workspace command can be used to interact with a workspace locally or in a remote backend. When working with Terraform, a default workspace is automatically created, which cannot be deleted. To create more workspaces, you have the following command line options:

How Does workspace_key_prefix Work in a Remote Backend?

The workspace prefix option sets a shared name across your workspaces, so all you change is the value tacked on the end. Say you have an application, call it "application-a", with a dev, stage, and prod workspace. The core Terraform configuration files stay the same, but some variable values might differ. Here's the code you'd set in the Terraform remote backend configuration file:

After setting the remote backend, a new workspace can be created with the following command:

terraform workspace new prod

Upon running terraform init, a new workspace will be seen in Scalr:

Example of a workspace in Scalr

You can run all the standard Terraform commands on this workspace, but it's a good idea to run terraform workspace show or terraform workspace list so you always know which workspace you're in, especially if one of them is production:

That's all it takes to start using the Terraform workspace prefix option in a remote backend such as Scalr or Terraform Cloud.

What's the Difference Between Remote and Local Terraform Workspaces?

Whether you run them remotely or locally, Terraform workspaces let you isolate the state file while reusing the same Terraform code. With a remote backend, the prefix option in the backend block makes it easy to switch between your Scalr or Terraform Cloud workspaces while you develop.