Terraform Workspaces Vocabulary

A Terraform workspace is an isolated state context. The same Terraform configuration can be run in multiple workspaces (dev, staging, prod) — each workspace has its own state file, so they manage independent infrastructure. Variable files or tfvars can be used to provide different values (instance sizes, replica counts, domain names) per workspace.

With remote backends (like S3), each workspace typically stores state in a separate location — for example s3://my-bucket/env/staging/terraform.tfstate vs s3://my-bucket/env/prod/terraform.tfstate. This ensures complete state isolation between environments, so a terraform apply in staging can never affect production state.

Many experienced Terraform users prefer separate directories per environment over workspaces — each environment has its own main.tf, tfvars, and remote state. This approach is more explicit (no risk of accidentally running against prod), easier to audit, and avoids workspace pitfalls like state isolation being less obvious. Workspaces work well for simple cases but separate-directory patterns scale better for large organisations.

terraform workspace list shows all workspaces in the current backend configuration, with an asterisk indicating the active workspace. Example output: '* default\n dev\n staging\n prod' — the asterisk shows you're currently in default. This is a quick sanity check before running any terraform plan or apply to ensure you're targeting the correct environment.

Workspace context errors are a real operational risk. If an engineer means to apply changes to staging but is still in the prod workspace, terraform apply will make those changes to production. Best practices to mitigate this: always run terraform workspace show before applying, use CI/CD pipelines that explicitly set the workspace, add the workspace name to the shell prompt, and require manual confirmation for the prod workspace.