How to Use Workspace for Environments in Terraform

In Terraform, use workspaces to create separate environments like dev and prod within the same configuration. Each workspace keeps its own state, letting you switch environments easily with terraform workspace select.

Syntax

Terraform workspaces let you manage multiple states for the same configuration. The main commands are:

• terraform workspace new <name>: Create a new workspace.
• terraform workspace select <name>: Switch to an existing workspace.
• terraform workspace list: List all workspaces.
• terraform workspace show: Show the current workspace.

Each workspace has its own state file, so resources are managed separately.

bash

terraform workspace new dev
terraform workspace select dev
terraform workspace list
terraform workspace show

Output

Created and switched to workspace "dev".
* default
  dev
Current workspace: dev

Example

This example shows how to create two workspaces dev and prod and deploy a simple AWS S3 bucket with different names per environment.

terraform

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
  backend "local" {}
}

provider "aws" {
  region = "us-east-1"
}

resource "aws_s3_bucket" "example" {
  bucket = "my-app-bucket-${terraform.workspace}"
  acl    = "private"
}

output "bucket_name" {
  value = aws_s3_bucket.example.bucket
}

Output

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

bucket_name = "my-app-bucket-dev"

Common Pitfalls

Common mistakes when using workspaces include:

• Assuming workspaces isolate all configuration variables; they only isolate state files.
• Not using terraform.workspace in resource names or variables, causing resource conflicts.
• Mixing manual state file changes with workspaces, which can corrupt state.
• Using workspaces for very different environments with different resources; modules or separate configs may be better.

terraform

### Wrong: Not using workspace in resource names
resource "aws_s3_bucket" "example" {
  bucket = "my-app-bucket"
  acl    = "private"
}

### Right: Use workspace to differentiate
resource "aws_s3_bucket" "example" {
  bucket = "my-app-bucket-${terraform.workspace}"
  acl    = "private"
}

Quick Reference

Command	Description
terraform workspace new	Create a new workspace
terraform workspace select	Switch to a workspace
terraform workspace list	List all workspaces
terraform workspace show	Show current workspace
terraform.workspace	Built-in variable for current workspace name

Key Takeaways

Terraform workspaces isolate state files to manage multiple environments in one config.

Use terraform.workspace in resource names to avoid conflicts between environments.

Switch environments with terraform workspace select before applying changes.

Workspaces are best for similar environments; use separate configs for very different setups.

Avoid manual state edits to prevent workspace state corruption.