Terraform workspace explained!!!

What is Terraform workspace?

Have you worked with terraform workflow? such as terraform init/plan/apply/destroy with terraform configuration file? If Yes, you already have worked with Terraform workspace. YES. Thats a default workspace which you always been working with.

It allows you to create different and independent states on the same configuration. And as it’s compatible with remote backend this workspaces are shared with your team.

Each Terraform configuration has an associated backend that defines how operations are executed and where persistent data such as the Terraform state are stored.

The persistent data stored in the backend belongs to a workspace. Initially the backend has only one workspace, called “default”, and thus there is only one Terraform state associated with that configuration.

Certain backends support multiple named workspaces, allowing multiple states to be associated with a single configuration.

Terraform Workspace — 10 Basic but Real Use Cases

1. Separate environments (dev, stage, prod) using same code
   Use one Terraform codebase and create workspaces like dev, stage, prod to deploy identical infrastructure with different sizes, tags, or configs.
2. Testing infrastructure changes safely before production
   Apply new Terraform changes in a test workspace first to validate behavior without impacting production resources.
3. Deploying same application for multiple customers (multi-tenant setup)
   Create workspaces like customer-a, customer-b, each provisioning isolated infrastructure using shared modules.
4. Managing region-specific deployments
   Use workspaces like us-east, eu-west, asia-south to deploy the same infrastructure in multiple regions.
5. Running feature branch infrastructure testing
   Developers create temporary workspaces like feature-login to test infrastructure related to a feature before merging code.
6. Isolating developer sandbox environments
   Each developer uses a workspace such as dev-rajesh, dev-amit to safely test infrastructure changes without affecting others.
7. Maintaining separate state files for the same infrastructure pattern
   Each workspace automatically maintains its own Terraform state file, avoiding conflicts between deployments.
8. Blue-Green deployment environments
   Create workspaces like blue and green to deploy parallel environments and switch traffic during release.
9. Running infrastructure performance or load testing environments
   Use a loadtest workspace to spin up temporary large-scale infrastructure for performance testing.
10. Temporary infrastructure for training, demos, or labs
    Create workspaces like training or demo to provision short-lived infrastructure without affecting production state.

Multiple workspaces are currently supported by the following backends:

• AzureRM
• Consul
• GCS
• Local
• Manta
• Postgres
• Remote
• S3

In the 0.9 line of Terraform releases, this concept was known as “environment”. It was renamed in 0.10 based on feedback to workspace.

Terraform starts with a single workspace named “default”. This workspace is special both because it is the default and also because it cannot ever be deleted. If you’ve never explicitly used workspaces, then you’ve only ever worked on the “default” workspace

There are a couple of advantages to using Workspaces:

• They are defined by Hashicorp, so it’s possible that improved features could be developed in the future
• They reduce the usage of code

However, Workspaces also present a couple of challenges:

• They are still an early implementation
• They are not yet supported by all backends
• It is not clear at the time of deployment (terraform apply) which workspace will be used (terraform workspace show)

Working with Terraform workspace?

$ terraform -help workspace
Usage: terraform workspace

  New, list, show, select and delete Terraform workspaces.

Subcommands:
    delete    Delete a workspace
    list      List Workspaces
    new       Create a new workspace
    select    Select a workspace
    show      Show the name of the current workspaceCode language: PHP (php)

Demo Code – https://github.com/devopsschool-sample-projects/terraform/tree/master/demo.3

So lets create a new dev workspace by running terraform workspace new dev and then run terraform apply. As we can see below instead of creating a terraform.tfstate file in the working folder Terraform created a new folder called terraform.tfstate.d/dev and places the state file within that.

├── deploy_website.sh
├── instance.tf
├── provider.tf
├── terraform.tfstate.d
│   └── dev
│       └── terraform.tfstate
├── terraform.tfvars
└── vars.tfCode language: CSS (css)

Ok so our webserver is now up and we are happy with the results, lets create and switch to a prod workspace. So we run terraform workspace new prod. This automatically places us in the prod workspace.

$ terraform workspace list
default
dev
* prodCode language: PHP (php)

Now lets run terraform apply again. Note if we were not using a different workspace Terraform would say no changes were needed as the remote and local state would match.

├── deploy_website.sh
├── instance.tf
├── provider.tf
├── terraform.tfstate.d
│   ├── dev
│   │   └── terraform.tfstate
│   └── prod
│       └── terraform.tfstate
├── terraform.tfvars
└── vars.tfCode language: CSS (css)

And now we have a prod folder with a new state file. So as we can see above we can use Terraform workspaces to manage differences between development, staging, and production.

You can also backup the remote state of each workspace to S3

backend.tf:

# Backend configuration is loaded early so we can't use variables
terraform {
  backend "s3" {
    region = "eu-central-1"
    bucket = "devopsschool.com"
    key = "state.tfstate"
    encrypt = true    #AES-256 encryption
  }
}Code language: PHP (php)

Create workspaces:

$ terraform workspace new dev
Created and switched to workspace 'dev'
$ terraform workspace new preprod
Created and switched to workspace 'preprod'
$ terraform workspace new prod
Created and switched to workspace 'prod'Code language: JavaScript (javascript)

Select the dev workspace:

$ terraform workspace select dev

List workspaces:

$ terraform workspace list
default
* dev
preprod
prod
Code language: PHP (php)

With this workspace configuration, when a terraform apply is successfully executed, your tfstate will be now stored in the good environment folder in the s3 bucket:

devopsschool.com
env:/
    dev/
       state.tfstate    
    preprod/
        state.tfstate    
    prod/
        state.tfstate

Terraform Workspace Lab Workflow: Dev, QA, Prod

1. Check workspace help

terraform workspace

2. Initialize Terraform project

terraform init

3. Show current workspace

terraform workspace show

Expected:

default
Code language: JavaScript (javascript)

4. List available workspaces

terraform workspace list
Code language: PHP (php)

Expected:

* default
Code language: JavaScript (javascript)

5. Create dev workspace

terraform workspace new dev
Code language: JavaScript (javascript)

6. Create qa workspace

terraform workspace new qa
Code language: JavaScript (javascript)

7. Create prod workspace

terraform workspace new prod
Code language: JavaScript (javascript)

8. List all workspaces

terraform workspace list
Code language: PHP (php)

Expected:

  default
  dev
  qa
* prod
Code language: JavaScript (javascript)

9. Select dev workspace

terraform workspace select dev

10. Confirm current workspace

terraform workspace show

Expected:

dev

11. Run Terraform for Dev

terraform plan
terraform apply

12. Select qa workspace

terraform workspace select qa

13. Run Terraform for QA

terraform plan
terraform apply

14. Select prod workspace

terraform workspace select prod

15. Run Terraform for Prod

terraform plan
terraform apply

16. Switch back to Dev

terraform workspace select dev

17. Delete QA workspace demo cleanup

First select another workspace:

terraform workspace select default
Code language: JavaScript (javascript)

Then delete QA:

terraform workspace delete qa
Code language: JavaScript (javascript)

18. Final list

terraform workspace list
Code language: PHP (php)

Expected:

* default
  dev
  prod
Code language: JavaScript (javascript)

Rajesh Kumar

I’m a DevOps/SRE/DevSecOps/Cloud Expert passionate about sharing knowledge and experiences. I have worked at Cotocus. I share tech blog at DevOps School, travel stories at Holiday Landmark, stock market tips at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow , and SEO strategies at Wizbrand.

Do you want to learn Quantum Computing?

Please find my social handles as below;

Rajesh Kumar Personal Website
Rajesh Kumar at YOUTUBE
Rajesh Kumar at INSTAGRAM
Rajesh Kumar at X
Rajesh Kumar at FACEBOOK
Rajesh Kumar at LINKEDIN
Rajesh Kumar at WIZBRAND

Rajesh Kumar DailyLogs