Imagine you’re running three Lego cities called dev, staging, and prod all from the same blueprint. Workspaces are the drawers that keep each city’s state separate. But just like organizing drawers at home, you need rules: don’t mix socks with tools, don’t keep junk in the production drawer.

Terraform workspaces are powerful, but they work best when used with discipline. This chapter teaches you the best practices for managing workspaces and highlights common pitfalls to avoid.

Key Concepts

✅ Best Practices

• Use for environment separation: Ideal for dev, staging, and prod.
• Keep naming consistent: Stick to simple names (dev, staging, prod).
• Leverage terraform.workspace: Use it for environment‑specific variables.
• Document usage: Explain workspace strategy in project README.
• Confirm before apply: Always check current workspace with terraform workspace show.
• Combine with remote backends: Store workspace states in S3, GCS, or Azure Blob for team collaboration.
• Limit scope: Use workspaces for logical separation, not for every minor variation.

❌ Pitfalls to Avoid

• Overusing workspaces: Don’t create a workspace for every feature branch—it becomes messy.
• Mixing environments: Never run production resources in the default workspace.
• Hidden complexity: Too many workspace‑specific conditions can make configs hard to read.
• Ignoring state isolation: Remember each workspace has its own state—resources won’t overlap.
• Team confusion: Without documentation, teammates may apply changes in the wrong workspace.

Hands‑On Lab / Demo

Lab: Safe Workspace Usage

1. Run terraform apply → Deploys resources according to environment rules.

Confirm workspace before applying:

terraform workspace show

Use terraform.workspace variable for environment logic:

variable "replica_count" {
  default = terraform.workspace == "prod" ? 5 : terraform.workspace == "staging" ? 2 : 1
}

Create workspaces:

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

Pro Tips & Best Practices

• Treat workspaces as environment drawers, not feature branches.
• Always confirm workspace before running apply.
• Document workspace strategy for your team.
• Use remote backends for collaboration.
• Keep workspace logic simple and transparent.

Summary & Cheatsheet

• Workspaces = Environment isolation with shared config.
• Best practices: consistent naming, documentation, remote backends, confirm before apply.
• Pitfalls: overuse, mixing environments, hidden complexity, lack of documentation.

Quick mnemonic: Separate, Simplify, Document

The Hackers Notebook

Workspaces are Terraform’s environment management tool, but they require discipline. By following best practices and avoiding pitfalls, you ensure dev, staging, and prod remain isolated yet consistent. Think of them as drawers in your infrastructure cabinet which organized, documented, and never mixed.