Workspaces

Terraform workspace#

A workspace in Terraform creates many instances of Terraform code using a single project. One of the advantages of Terraform is that you can use the infrastructure as code to create your environments, reducing human error and ensuring uniformity.

You may have wondered how to create multiple environments using the same code. Everything we have done up until this point has been around creating a single instance of the infrastructure using our Terraform project, after all. If we rerun the project, it would not create another copy of the infrastructure, but would instead simply say “no changes to make”.

Workspaces are Terraform’s solution to this problem.

Project example#

Let’s dive straight into an example to go into some detail about how it is working. We’ll create a new file called main.tf:

Most of this code should look familiar to you. The one part you probably will not have seen before is how we are setting the queue name to "＄{terraform.workspace}-queue". The special variable terraform.workspace will assume the value of the current workspace we are running in. All Terraform projects run in a workspace. Up until now, we have been running in the default workspace. The default workspace cannot be deleted and is the workspace you will be working in unless you specify otherwise

Running the project#

Clicking the terminal will run terraform init followed by terraform apply. Confirm the apply with yes when prompted to do so.

Terraform will create a queue in AWS with the name default-queue since we are working in the default workspace.

To list all available workspaces in the current project, run the following command:

This will produce the following output:

The asterisk indicates the workspace we are currently working in. Now let’s create a new workspace for our dev environment by running the following command

The new workspace command takes the name of the new workspace as an argument. The output will show that Terraform has created a new workspace and automatically switched to it. If we run the list command again, the following output will now be displayed:

The asterisk has now moved to the newly created dev workspace. Run terraform apply again to apply this Terraform project.

Terraform has created a second queue named dev-queue. This happened because we have changed the workspace that we are in. Because we are in the dev workspace, all the Terraform commands we run to apply the project or manipulate state will only be applied to resources that are part of the dev workspace. The default workspace where the default-queue lives is completely separate. You can think of this as two Terraform projects in two separate folders that happen to be sharing the same code. You can use this functionality to create as many instances of your infrastructure as you wish.

Switching back to default workspace#

To switch back to the default workspace, use the command terraform workspace select default. If you change the project now, such as changing one of the queue properties and running terraform apply then Terraform will make changes to the default-queue. If you go to the AWS console and check the dev-queue, that will remain unchanged. The apply will have only affected the default-queue.

How switching works#

Under the surface, workspace switch is possible because Terraform stores multiple copies of the state. Depending on the state backend you are using, the technique for how these are stored varies slightly. If you want to take advantage of workspaces, you need to pick a state backend that supports them, such as AWS S3.

How Terraform saves workspaces#

As we have been using the default local state in this example, Terraform simply stores the different workspaces in different local paths on the disk. The default workspace is stored in the file in the top-level folder called terraform.tfstate, as we learned in the previous chapter.

Take a look at the state file. You will see the representation of the default-queue there. The dev workspace is in a file at the path ./terraform.tfstate.d/dev/terraform.tfstate. The special folder terraform.tfstate.d is where Terraform stores its local workspaces. Each workspace’s terraform.tfstate file is stored in a folder with the workspace’s name. Terraform uses a special marker file at the path .terraform/environment to store which workspace you are currently using.

📝Note: Do not rely on this fact. It is an internal detail and subject to change. We’re detailing how it works to improve your understanding of Terraform as a whole.

Switching back to dev workspace#

Switch back to the dev workspace by running:

And destroy the infrastructure (to save the pennies) by running:

And confirming at the prompt.

Switching back to the default workspace#

Switch back to the default workspace (terraform workspace select default). We are now done with the dev workspace, so we can safely delete it. To delete a workspace, use this command:

It is important to note that the delete command will remove the Terraform state but will NOT destroy the infrastructure. This is why we ran the destroy command first!

With the dev workspace deleted, it will no longer appear in our list of workspaces when we run terraform workspace list. Do not forget to destroy the infrastructure in the default workspace when you are finished. But remember, there is no way to delete the default workspace.

Conclusion#

Workspaces are an important feature of Terraform that can be used to create several copies of your infrastructure. You can use the workspace name to drive different values for variables that make up your infrastructure. However, the amount that you can drive just from the workspace alone does not scale well. You instead will need a method to change your input variables at the top level.

Solution#