Chapter 34: Terraform State Remote S3 Backend Locking and Workspaces

34.5 Workspaces — several states from one folder

By Ravindra Bagale · Last updated: 25 October 2026

Story. A Netflix-style engineer wanted short-lived test stacks for each feature branch without copying folders. Workspaces give one configuration several separate state files. terraform.workspace returns the current name so you can vary names and sizes. For long-lived dev, stage and prod with different accounts, separate folders or backends are clearer, which Chapter 41 shows.

terraform workspace list
terraform workspace new feat-login
terraform workspace select feat-login

# main.tf
resource "aws_s3_bucket" "preview" {
  bucket = "badge-${terraform.workspace}-preview-<your-account-id>"
}

terraform apply
terraform destroy
terraform workspace select default
terraform workspace delete feat-login

What each line does

• terraform workspace list — Shows all workspaces; the current one has a star.
• terraform workspace new feat-login — Creates a workspace with an empty state and switches to it.
• terraform workspace select feat-login — Switches to an existing workspace.
• bucket = "badge-${terraform.workspace}-preview-..." — Puts the workspace name into the bucket name so stacks do not collide.
• terraform apply — Creates resources tracked only in this workspace state.
• terraform destroy — Removes this workspace's resources to avoid cost.
• terraform workspace select default — Moves back to the default workspace.
• terraform workspace delete feat-login — Deletes the now-empty workspace.

When it is green.

  default
* feat-login

Plan: 1 to add, 0 to change, 0 to destroy.
Deleted workspace "feat-login"!

When it is red.

Error: Workspace is not empty
Workspace "feat-login" is currently tracking the following resource instances:
  - aws_s3_bucket.preview

Fix. You tried to delete a workspace before destroying its resources. Select it, run terraform destroy, then delete it.

What: every term in plain English

• workspace — A named state inside one backend. Each workspace has its own state file but shares the code.
• default workspace — The workspace you are in when you never create one. It cannot be deleted.
• terraform.workspace — A value you can use in code that holds the current workspace name.
• env:/ prefix — Where S3 stores non-default workspace states, such as env:/stage/badge-api/terraform.tfstate.
• workspace_key_prefix — Backend option that changes the env:/ folder name.
• directory per environment — The other pattern: envs/dev and envs/prod folders with their own backend keys.
• blast radius — How much breaks if one command goes wrong. Separate folders keep it small.

Example 1: Create and switch workspaces

A startup team in Bengaluru wanted quick test copies of a stack for each feature branch. Workspaces are perfect for short-lived copies.

1. Show the current workspace.
2. Create feature-login.
3. List workspaces.
4. Switch back to default.

terraform workspace show
terraform workspace new feature-login
terraform workspace list
terraform workspace select default

Output

default
Created and switched to workspace "feature-login"!
  default
* feature-login
Switched to workspace "default".

What it shows: The star marks where you are. Every plan and apply uses that workspace's state.

Example 2: Use terraform.workspace in names and sizes

Two copies in one account need different names, or AWS will refuse the second bucket. Use the workspace name in every name.

1. Add a locals block with sizes per workspace.
2. Use the name in the bucket and the size in the instance.
3. Plan in two workspaces.

locals {
  size = {
    default = "t3.micro"
    stage   = "t3.small"
    prod    = "t3.medium"
  }
}

resource "aws_s3_bucket" "logs" {
  bucket = "badge-logs-${terraform.workspace}-123456789012"
}

resource "aws_instance" "web" {
  ami           = data.aws_ami.al2023.id
  instance_type = lookup(local.size, terraform.workspace, "t3.micro")
  tags = { Name = "badge-web-${terraform.workspace}" }
}

terraform workspace select stage
terraform plan | grep -E "bucket |instance_type"

Output

+ bucket        = "badge-logs-stage-123456789012"
+ instance_type = "t3.small"

What it shows: lookup with a default keeps new feature workspaces small and cheap.

Example 3: See where workspace states live in S3

During an audit at an ICICI vendor, nobody could find the stage state. It was under env:/. Know the path before you need it.

1. Apply in stage.
2. List the bucket recursively.

terraform apply -auto-approve
aws s3 ls s3://badge-tfstate-123456789012/ --recursive | grep badge-api

Output

2026-10-25 11:40:02       4980 badge-api/dev/terraform.tfstate
2026-10-25 11:52:19       4990 env:/stage/badge-api/dev/terraform.tfstate

What it shows: The default workspace uses the key as written. Others get env:/NAME/ in front.

Example 4: Delete a feature workspace cleanly

Leftover workspaces cost money because their resources keep running. Destroy first, then delete.

1. Select the workspace.
2. Destroy.
3. Select default.
4. Delete the workspace.

terraform workspace select feature-login
terraform destroy -auto-approve
terraform workspace select default
terraform workspace delete feature-login

Output

Destroy complete! Resources: 2 destroyed.
Switched to workspace "default".
Deleted workspace "feature-login"!

What it shows: Terraform refuses to delete a workspace whose state still has resources unless you add -force. Do not use -force; destroy first.

Command cheat sheet

Verify: did it work?

1. Right workspace

   terraform workspace show
   

   Output

   stage
   

2. State path

   aws s3 ls s3://badge-tfstate-123456789012/env:/stage/ --recursive
   

   Output

   2026-10-25 11:52:19       4990 env:/stage/badge-api/dev/terraform.tfstate
   

When it is red 1

Error: creating S3 Bucket (badge-logs-123456789012): BucketAlreadyOwnedByYou

Cause. The name does not include terraform.workspace, so two workspaces want the same bucket.

Fix, step by step

1. Add ${terraform.workspace} to every unique name.
2. Plan again in both workspaces.

When it is red 2

Workspace "feature-login" is not empty.

Cause. You tried to delete a workspace that still has resources.

Fix, step by step

1. Select the workspace.
2. Run terraform destroy.
3. Delete it again.

When it is red 3

Plan: 0 to add, 1 to change, 0 to destroy.  (instance_type t3.medium -> t3.micro, you meant prod)

Cause. You are in the wrong workspace.

Fix, step by step

1. Stop. Do not apply.
2. Run terraform workspace show.
3. Select the right workspace and plan again.

Cleanup

for w in $(terraform workspace list | tr -d '* ' | grep -v default); do
  terraform workspace select $w && terraform destroy -auto-approve
  terraform workspace select default && terraform workspace delete $w
done

Practice tasks

Homework: try at home

Recap

• A workspace is a separate state for the same code.
• terraform.workspace makes names unique.
• S3 stores them under env:/NAME/.
• Destroy before deleting a workspace.
• Prefer folders for real dev, stage and prod.

FAQ

Are workspaces the same as environments?

Not quite. They share code, backend and credentials, so a mistake can hit prod. Folders separate more.

Can I delete the default workspace?

No.

Do workspaces share variables?

Yes. Use terraform.workspace or a tfvars file per workspace to change values.

Does Jenkins support workspaces?

Yes, use terraform workspace select -or-create NAME in the pipeline.

Can I rename a workspace?

No. Create a new one and move state with state mv or a pull and push.

Interview questions

1. What is a Terraform workspace?

   A separate named state for the same configuration and backend.

2. Workspaces or folders for prod?

   Folders with separate backends and roles, to reduce blast radius.

3. How do you use the workspace name in code?

   With terraform.workspace.

4. Where are workspace states stored in S3?

   Under env:/NAME/ followed by the key.

5. How do you safely remove a workspace?

   Destroy its resources, select default, then delete it.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards