How to use Terraform workspaces to manage different environments?

You are currently viewing How to use Terraform workspaces to manage different environments?
Please share

Terraform helps you manage your infrastructure by creating, updating and destroying your resources using structured code files; but what about handling several environments at once? With its 0.10 release, Terraform made it possible to deal with multiple environments. Today, you will learn how to easily manage different environments/projects (alpha, staging, production…) without duplicating your Terraform files in different folders. This allows you to clearly separate your different environments and avoid confusion between them. After reading this article, you will know how to set up these workspaces and start working with them on your project. If you are interested in Terraform for your new project, you can start learning about terraform for Kubernetes for GCP, or for AWS EKS.

Main utilization of Terraform workspaces

Since version 0.10, Terraform workspaces allow you to manage different environments for your infrastructure without having to duplicate your configuration files in separate folders. For example, if you have one cloud project per environment (development, staging, production), terraform workspace can help you manage the resources for each project in a seamless way so that each project will get the same configuration without sharing any resources.


Each workspace will use the same .tf configuration files, but different instances of your resources will be created independently by workspace; their state will only depend on the workspace you’re in. Therefore, you can work seamlessly between your development environment or your production environment without worrying about overlapping or conflicts between the resources of each environment.

Even if the .tf configuration files are common between your environments, you can still introduce customization depending on the workspace you’re in. We’ll tackle this part in section 3 of this article.

Setup workspaces in Terraform

To create the workspace alpha, simply use the command below; this will initialize your new workspace alpha.

terraform workspace new alpha

To get the list of your different workspaces:

terraform workspace list

If you want to switch between workspaces, use:

terraform workspace select <workspace_name>

Finally, to delete a workspace, simply use:

terraform workspace delete <workspace_name>

When you’re working in a workspace, the resources created, destroyed, or changed by your .tf apply will be independent of the different environments managed by your workspaces.

⚠️ When working with workspaces, you might want to pay attention to which workspace you’re in before applying changes. Usually, before validating a terraform apply, you will see the following line showing which workspace you’re in.

Do you want to perform these actions in workspace "alpha"?

To know which workspace you’re on currently, use:

terraform workspace show

Adding customization depending on the workspace

You can use the ${terraform.workspace} sequence to introduce differentiation between your resources. This can be useful if you need the same structure for all environments but for some reasons (cost, practicality), you want to differentiate some resources between the workspaces.

Example 1:

Suppose you are using a CloudSQL database in your project. For cost reasons or else, you might want this database to be highly available for your production environment but not for the rest of them.

In your resource block declaration of your file, you can simply add this line to differentiate your databases according to the workspace/environment:

high_availability = (terraform.workspace == "production") ? true : false

Example 2:

Suppose you want to add a resource in only one environment (here, alpha), you can add a count condition at the beginning of your resource block:

count = (terraform.workspace == "alpha") ? 1 : 0

You can also transform this condition if you want the resource to be in each environment except for alpha: 

count = (terraform.workspace == "alpha") ? 0 : 1

Customization when using multiple workspaces should be used cautiously and sparingly. If you are starting to customize every resource of your infrastructure with different options, you might need to separate your files to avoid confusion. Terraform workspaces come very handy but do not fit all use cases 😀

I hope you found this article useful to learn how to manipulate Terraform workspaces to manage different environments for your project.