How to use Workspaces in Terraform?

Terraform worksapces is a very logical concept where you can have multiple states of your infrastructure configuration. To put this in simple words if you are running an infrastructure configuration in development environment then the same infrastructure can be run in the production environment.

The main benefit of terraforming workspaces we get is we can have more than one state associated with a single terraform configuration.

If you have not defined any workspace then there is always a default workspace created by terraform, so you always work in a default workspace of terraform. You can list the number of terraform workspaces by running the command terraform workspace show. Also, you can not delete the default workspace

Here is our Table of Content on How to work with Terraform workspaces

1. How to create a new Terraform workspace
2. How to List all the Terraform workspaces
3. How to Show Terraform workspaces
4. How to Switch Terraform workspaces
5. How to use the name of Current Workspace using ${terraform.workspace} Interpolation
6. Terraform workspace and terraform.tfstate, terraform.tfstate.d
7. When to use multiple terraform workspaces?

1. How to create a new Terraform workspace

To create a terraform workspace first you make sure that you have installed terraform. After that, you simply need to run the following terraform workspace command -

1terraform workspace new dev 

Here are few points to keep in mind -

1. To create a workspace you must type in the keyword workspace after terraform
2. You must also type in new for creating a new workspace
3. The third and last thing is your workspace name, in the above command I have taken the workspace name as dev

1.1 Create one more workspace with name test

To get a better understanding of workspace and how it isolates then I would highly recommend creating one more workspace where we run the terraform commands respectively on each workspace without affecting their states

Here is the command for creating another workspace with the name test

1 terraform workspace new test 

2. How to List all the Terraform workspaces?

Now in step 1 we have seen how to create a new workspace in terraform. But then how to list all the workspaces which we have created previously.

So to list all the available workspaces use the following terraform command -

1terraform workspace list 

The above command will list down all the available workspaces including the default workspace also

The active workspace is always prefixed with a star.

3. How to Show Terraform workspaces?

Now we know how to create a terraform workspace and how to list all the available workspace in terraform.

But is there a way to show active workspace?

Terraform provides a command terraform workspace show which can help you to show the active running workspace in which you are working.

1terraform workspace show

Here is one example screenshot below which will tell you that test is active running state

4. How to switch Terraform workspaces?

It might be possible that you have created multiple workspaces to isolate your infrastructure code and you want to switch between the workspaces to apply your infrastructure changes.

So to switch the workspace you should following terraform command -

1terraform workspace select test  

The above terraform command will make a switch to test workspace. In your case, you simply need to put your workspace name to make the switch between the workspaces

5. How to use the name of Current Workspace using ${terraform.workspace} Interpolation?

While working with longer terraform infrastructure code it often needed to name or tag your resources based on the environment profile such as dev, test, stage, prod, etc.

With the help of ${terraform.workspace} interpolation sequence you can use the current workspace name to define terraform locals.

Here is a simple example of provisioning a simple EC2 instance -

1. I have defined a terraform local instance_name
2. The terraform local have a name prefixed with the current workspace name .i.e. - "${terraform.workspace}-instance"
3. And the terraform local is used to tag the aws_instance

 1 provider "aws" {
 2   region     = "eu-central-1"
 3   access_key = "AKIATspmbXB2EPCJFO4Y"
 4   secret_key = "AH9Hw//EfW6OJM8EFrWllkKdlgovpihIvYpu9TTxr"
 5   
 6}
 7
 8locals {
 9  instance_name = "${terraform.workspace}-instance" 
10}
11
12resource "aws_instance" "ec2_example" {
13
14    ami = "ami-0767046d1677be5a0" 
15
16    instance_type = var.instance_type
17
18    tags = {
19      Name = local.instance_name
20    }
21}

6. Terraform workspace and terraform.tfstate, terraform.tfstate.d

Whenever you work with terraform workspace and when you create multiple workspaces then you will get one directory created for each workspace inside your terraform project.

Here is an example where I have created two workspace - dev, test

So with each workspace, you end up with its own terraform.tfstate and terraform.tfstate.d file which will help you to separate and isolate the infrastructure behavior based on your configuration settings.

7. When to use multiple terraform workspaces?

Here are some key points where I felt you should use terraform workspaces -

1. When you feel that you need a parallel, distinct copy of your infrastructure which you can test and verify in the development, test, and staging environment before putting it into the production environment.
2. Secondly terraform workspaces acts as feature branch. If you have ever worked with a versioning tool then you might be familiar with main or master where every developer merges their code from the feature branch. So assume the default workspace as your main or master and the workspaces` as your featured branch where you will test and verify your changes.
3. Do not presume that with terraform workspaces you can separate or decompose your infrastructure component. Terraform workspaces are not meant to decompose your infrastructure. If you really want to separate or decompose your infrastructure then I would recommend using a separate set of configuration and backend to achieve that.
4. If you have your infrastructure where each deployment requires you to put different setup credentials then you should not use Terraform workspaces for that.

Read More - Terragrunt -

1. How to use Terragrunt?