Terraform Workspaces: Managing Multiple Environments the Right Way

👋 Hey there, I’m Dheeraj Choudhary an AI/ML educator, cloud enthusiast, and content creator on a mission to simplify tech for the world.
After years of building on YouTube and LinkedIn, I’ve finally launched TechInsight Neuron a no-fluff, insight-packed newsletter where I break down the latest in AI, Machine Learning, DevOps, and Cloud.
🎯 What to expect: actionable tutorials, tool breakdowns, industry trends, and career insights all crafted for engineers, builders, and the curious.
🧠 If you're someone who learns by doing and wants to stay ahead in the tech game you're in the right place.

What Are Terraform Workspaces?

A Terraform workspace is a named instance of state. That's it.

When you run terraform init, Terraform creates a default workspace named default. If you create a new workspace called staging, Terraform keeps a separate state file for it.

This means:

• Same code

• Different state

• Different resources in the cloud

• Fully isolated environments

Creating and Using Workspaces

🔧 Create a new workspace:

terraform workspace new dev
terraform workspace new staging
terraform workspace new prod

🔁 Switch between them:

terraform workspace select staging

📋 List all workspaces:

terraform workspace list 

🧽 Delete a workspace:

terraform workspace delete dev

When you switch workspaces, Terraform automatically uses a separate state backend under the hood (e.g., terraform.tfstate.d/staging/terraform.tfstate locally).

Using Workspaces in Code

You can access the active workspace using:

terraform.workspace 

Example:

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

This will create:

• logs-dev in the dev workspace

• logs-prod in the prod workspace

Workspace Gotchas and Anti-Patterns

Workspaces can be powerful — but they’re often misused.

❌ Common Anti-Patterns:

• Using workspaces as your main environment management strategy

• Trying to manage non-identical infrastructure (e.g., dev has no RDS, prod does)

• Running workspaces in CI/CD pipelines that expect clean state control

Workspaces are not a replacement for separate codebases or modules when your environments have meaningful infrastructure differences.

Alternative Approach: Folder-Based Environments

Many teams choose to create one folder per environment, each with its own:

• .tfvars file

• Backend configuration

• Provider config

• Module inputs

environments/
├── dev/
│   ├── main.tf
│   ├── variables.tf
│   └── terraform.tfvars
├── staging/
└── prod/

This approach provides stronger separation, better CI/CD integration, and more flexibility.

When to Use Workspaces

✅ For lightweight, identical environments (e.g., dev/staging with same infra)
 ✅ When you want quick local switching without duplicating code
 ✅ When infrastructure structure stays the same across all workspaces
 ✅ In conjunction with a remote state backend that supports isolation

When NOT to Use Workspaces

❌ When environments require different resources or structure
 ❌ When you're deploying via CI/CD pipelines that don't support context switching
 ❌ When you want stronger boundaries between teams or regions
 ❌ If you need to manage secrets or providers differently per env

Hands-On: Deploying Two Environments with Workspaces

Step 1: Create Workspace

terraform workspace new dev

Step 2: Apply Config

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

terraform apply

Step 3: Switch and Repeat

terraform workspace new prod
terraform apply

You now have two buckets:

• logs-dev

• logs-prod

Same code, separate state, cleanly isolated.

💡 Tip of the Day:

📚 Resources & References

1️⃣ Terraform Workspaces Docs
🔗 Docs
Official documentation on workspace usage, state behavior, and lifecycle.

2️⃣ Managing Environments in Terraform
🔗 Learn
Tutorial comparing workspaces vs folders for environment management.

3️⃣ Using terraform.workspace Variable
🔗 Docs
Reference for dynamic workspace access in config.

4️⃣ State File Management per Workspace
🔗 Deep Dive
Understand how workspaces isolate state and resources.

🔗Let’s Stay Connected

📱 Join Our WhatsApp Community
Get early access to AI/ML, Cloud & Devops resources, behind-the-scenes updates, and connect with like-minded learners.
➡️ Join the WhatsApp Group

✅ Follow Me for Daily Tech Insights
➡️ LinkedIN
➡️ YouTube
➡️ X (Twitter)
➡️ Website