Terraform Workspaces – Manage Multiple Environments

Imagine you have a Terraform configuration and you want to apply it to create infrastructure in multiple environments such as development, staging and production.

With Terraform Workspaces, you can manage multiple environments with relative ease.

In this post, I’m going to explain the utility of Terraform Workspaces and answer the most pressing questions about the topic.

1 – What is the purpose of Terraform Workspaces?

Terraform Workspaces make it possible to create a named and isolated environment for storing state data.

Each workspace acts like its own universe with its own state file. In other words, you are able to generate multiple state files for the same set of Terraform configuration files. This allows you to make changes in one environment without affecting others.

Terraform Workspaces are extremely useful for:

• Managing different environments (e.g. dev, staging, production)
• Separating resources that should not interact (e.g. different departments or projects)

The below illustration depicts the role of Terraform workspaces in the overall big picture of provisioning infrastructure.

By the way, if you are interested in Cloud & Infrastructure topics, you’d love my free weekly newsletter where I explain such concepts in a fun and interesting approach.

2 – Terraform Default Workspace

Terraform default workspace is the first workspace that is created when you start using Terraform.

Basically, when you run the terraform init command on a configuration directory, the default workspace is automatically created for you. You’d notice this by the presence of a new file named terraform.tfstate that contains the current state of your infrastructure.

This workspace serves as the default environment for your Terraform state. Also, note that you cannot delete the Terraform default workspace.

3 – How to create a Terraform Workspace?

To create a new Terraform workspace, you have to execute the terraform workspace new <workspace_name> in the source directory of the Terraform configuration.

See the below example:

$ terraform workspace new development
Created and switched to workspace "development"!

You're now on a new, empty workspace. Workspaces isolate their state,
so if you run "terraform plan" Terraform will not see any existing state
for this configuration.

Here, the command creates a new workspace development and also switches the context to the new workspace.

Understanding the Terraform Workspace Internals

When you create a new Terraform workspace, Terraform creates a folder named terraform.tfstate.d. Within the folder, it creates individual folders for each workspace.

For example, in our case, the terraform.tfstate.d folder will contain a folder named development. This development folder will contain the state files for the ‘development’ workspace.

Use of terraform.workspace variable

The terraform.workspace variable is a special built-in variable in Terraform that allows you to access the current workspace name from within your Terraform code.

This variable is very useful when you want to create resources specific to a particular workspace.

For example, you can use it to create a resource identifier that associates the resource to the workspace as below:

resource "aws_instance" "hello_aws" {
    ami = data.aws_ami.ubuntu.id
    instance_type = "t2.micro"
    tags = {
        Name = "HelloAWS-${terraform.workspace}"
    }
}

Here, the Name tag’s value is dynamically generated by using the expression HelloAWS-${terraform.workspace}.

When you run terraform plan for this configuration, you will see the below tag values being generated.

+ tags     = {
   + "Name" = "HelloAWS-development"
  }
+ tags_all = {
   + "Name" = "HelloAWS-development"
  }

As you can see, this lets you manage resources for multiple environments with ease.

If interested, you can read more about creating an AWS EC2 Instance with Terraform.

4 – How to switch Terraform Workspaces?

To switch between Terraform workspaces, you can use the terraform workspace select command followed by the name of the workspace you want to switch to.

See the below example:

$ terraform workspace select development
Switched to workspace "development".

Note that each Terraform workspace has its own state. Therefore, switching between workspaces will cause Terraform to use a different state file that contains information about the resources in that specific workspace.

5 – Deleting a Terraform Workspace

To delete a Terraform workspace, you need to execute the terraform workspace delete command followed by the name of the workspace you want to delete.

Check the below example:

$ terraform workspace delete production
Deleted workspace "production"!

Deleting a Terraform workspace is a destructive operation and you cannot undo it. Therefore, don’t forget to back up your state files before deleting them in case you need them later.

Note that you cannot delete the workspace you are currently using i.e. the active workspace. For example, if you are in the development workspace and try to delete it, you get the below error message:

Workspace "development" is your active workspace.

You cannot delete the currently active workspace. Please switch
to another workspace and try again.

6 – Frequently Asked Questions

Here are the frequently asked questions about Terraform Workspaces that can help you get more clarity.

What is the difference between modules and workspaces in Terraform?

Modules and workspaces are two entirely different concepts in Terraform.

Modules are a way to organize and reuse Terraform code. A module is a collection of Terraform files that define resources and their relationships. You can reuse a module across multiple Terraform configurations. In case you are interested to know more, check out my post on using Terraform modules to create an EC2 cluster.

On the other hand, workspaces in Terraform are a way to manage multiple versions of the same infrastructure using the same set of configuration files. Workspaces allow you to maintain separate state files for each environment or department and switch between them easily as and when required.

What is the difference between Terraform workspaces and Terraform Cloud?

Terraform workspaces and Terraform Cloud are two completely different things in the context of Terraform,

As we saw workspaces in Terraform are used to manage multiple versions of the same infrastructure defined by a set of configuration files. With workspaces, you maintain separate state files for each environment and switch between them as per your need.

However, Terraform Cloud is a paid service offered by HashiCorp (the company that created Terraform). It provides a centralized place to manage Terraform runs, state files and infrastructure. With features like version control, remote state management and collaboration tools, Terraform Cloud makes it easier to manage Terraform infrastructure at scale.

What is the difference between Terraform Workspace and directory?

There is often confusion between the role of workspace and directory in Terraform. At face value, they might seem similar but in reality, they are not.

Terraform workspaces allow you to manage multiple versions of the infrastructure within the same directory. All of your configuration files are shared across individual workspaces and you don’t need to modify them for a different environment or team.

On the other hand, a directory is basically a location on your file system where you are storing your Terraform configuration files. You can store Terraform configuration for a particular environment in its own directory. But it will essentially be a completely different configuration. In the context of Terraform, directories have no special meaning.

Why not use Terraform workspaces?

While Terraform workspaces are extremely useful in certain situations, you might not want to use them in all scenarios.

• Workspaces can add complexity to a Terraform configuration especially if you are managing multiple environments and multiple workspaces in the same directory. If your infrastructure is relatively simple and you don’t need to manage multiple versions of the same infrastructure, you should stay away from workspaces.
• Workspaces can also result in collaboration issues when multiple people are pushing changes to the same set of configuration files. The complexity of the configuration files in the case of workspaces can lead to confusion and errors.

How do you list Terraform Workspaces?

To list Terraform workspaces, you can use the terraform list command. It displays the list of all the workspaces including the default workspace.

Check the below example:

$ terraform workspace list
  default
* development
  production

Here, the asterisk symbol denotes the currently active workspace.

Does Terraform init command create a workspace?

Yes, the Terraform init command creates the default workspace when you execute it on a fresh Terraform configuration source directory.

As discussed earlier, you cannot delete the default workspace. When you try to do so, you get the below error.

$ terraform workspace delete default
cannot delete default state

7 – Best Practices of using Terraform Workspaces

Here are a few best practices you should keep in mind while using Terraform workspaces

• Use descriptive names – When naming your workspaces, make sure to use descriptive names that clearly indicate the purpose of the workspace. For example, you might use names like development, staging, or production to indicate different environments. This helps you keep track of what each workspace is used for at a glance.
• Use separate workspaces for different environments – Don’t mix multiple environments in the same workspace. It’s always good to create a separate workspace to ensure you get flexibility in managing your infrastructure.
• Test your changes before applying – Use terraform plan to test your changes before applying them while using Terraform workspaces. This will help you make sure you don’t accidentally use the wrong workspace for a particular environment.

Conclusion

To conclude, Terraform workspaces are a powerful way to manage multiple environments within a single Terraform configuration.

With the ability to use multiple state files, Terraform workspaces are an essential tool for anyone wanting to use the same configuration files for different environments or multiple teams.

If you found this post useful, consider sharing it with friends and colleagues. Also, in case of any queries, please mention them in the comments section below.

Anyways, before we end this post, a quick reminder about the Progressive Code Newsletter where I explain Cloud & Infrastructure concepts in a fun & interesting manner so that you never forget what you’ve learned.

I’m 100% sure you’d love it.

Subscribe now and see you over there.