Manage Terraform Workspaces Across Environments

This skill covers Terraform workspace management for multi-environment infrastructure - isolating dev, staging, and production deployments, configuring remote state backends, and organizing environment-specific variables. The core isolation strategy uses one workspace per environment with a <project>-<environment>-<region> naming convention, a separate state file per workspace, and explicit workspace selection in CI/CD rather than implicit switching. State is backed by an S3 backend with encryption, a DynamoDB lock table, and a workspace_key_prefix that scopes state paths per workspace. Environment-specific configuration is handled with a map(object({...})) variable keyed by terraform.workspace (instance type, min/max capacity, DB instance class per environment), read into a local.env_config alongside common tags that include the workspace name. Resources reference terraform.workspace directly for naming (e.g. "${terraform.workspace}-app-server") and for conditional creation - a CloudWatch dashboard is created with count = terraform.workspace == "dev" ? 0 : 1 so monitoring resources exist only in staging and prod. Cross-workspace references use a terraform_remote_state data source pointing at another workspace's state file, letting an app workspace pull subnet IDs or security group IDs from a shared-infrastructure workspace.

CI/CD integration is demonstrated with a GitHub Actions workflow using a matrix strategy over [dev, staging, prod], selecting or creating the matching workspace with terraform workspace select $ENV || terraform workspace new $ENV, planning against an environment-specific .tfvars file, and applying only on the main branch for non-prod environments (implying prod needs a separate, gated path). Recommended project layout separates environments/*.tfvars from modules/ and the root main.tf/variables.tf/outputs.tf/versions.tf. Troubleshooting commands cover listing, showing, creating, switching, and deleting workspaces, plus importing an existing cloud resource into a specific workspace; state migration between workspaces uses terraform state mv in the source workspace followed by terraform import in the target.

Use this when structuring a Terraform project to manage multiple environments with workspace-based isolation, setting up a remote state backend with locking, wiring environment-aware variables and conditional resources, or building a CI/CD pipeline that deploys per environment through workspace selection.

Security guidance calls for workspace-specific IAM roles and policies, separate AWS accounts for production workspaces (not just a separate workspace within the same account), state file encryption and versioning, approval workflows gating production deployments, and auditing workspace changes through CloudTrail - all of which should be in place before relying on workspace isolation alone as a production safety boundary.

Input is a set of environment-specific requirements (instance sizing, capacity, feature flags) and a target cloud backend for state storage. Output is Terraform configuration - backend blocks, environment-keyed variable maps, workspace-aware resource definitions, and a CI/CD workflow - plus a directory structure separating environment tfvars from reusable modules.

Built on Terraform's native workspace feature with an AWS S3 + DynamoDB state backend (encryption, locking, versioning, KMS-backed server-side encryption) and GitHub Actions for CI/CD, using the hashicorp/setup-terraform action. Cross-workspace composition uses the terraform_remote_state data source to consume another workspace's outputs.

Infrastructure and platform engineers managing multiple environments (dev/staging/prod) with Terraform who need workspace isolation, a locked remote state backend, and a CI/CD pipeline that deploys the right environment safely.

### List all workspaces
terraform workspace list

### Show current workspace
terraform workspace show

### Create new workspace
terraform workspace new production-us-east-1

### Switch workspace safely
terraform workspace select staging

### Delete unused workspace (after moving resources)
terraform workspace delete old-environment

### Import existing resource into specific workspace
terraform workspace select prod
terraform import aws_instance.web i-1234567890abcdef0