Workspaces

Terraform workspaces allow you to manage multiple distinct infrastructure environments using the same configuration by maintaining separate state files for each workspace.

What You'll Learn

In this tutorial, you will learn how to create and manage Terraform workspaces, use workspace-specific variables, isolate state between environments, and choose between workspaces and directory-based environment strategies.

Why It Matters

Teams need to deploy the same infrastructure pattern to dev, staging, and production environments. Workspaces provide a built-in mechanism for environment separation using a single configuration, reducing duplication and maintenance overhead.

Real-World Use

DodaTech uses Terraform workspaces for Durga Antivirus Pro's backend infrastructure. The dev workspace lets engineers experiment freely, staging runs integration tests, and production enforces strict access controls. All three use the same module configuration with workspace-specific variable values.

What Are Workspaces?

Workspaces are named instances of the same Terraform configuration. Each workspace has its own isolated state file. The default workspace is called "default".

terraform workspace list

Expected output:

  default
* dev
  staging
  production

The asterisk indicates the current active workspace.

Managing Workspaces

Create a Workspace

terraform workspace new staging

Expected output:

Created and switched to workspace "staging"!

Switch Workspaces

terraform workspace select production

Expected output:

Switched to workspace "production".

Show Current Workspace

terraform workspace show

Expected output:

production

Using Workspace Values in Configuration

The <a href="/devops/terraform/">terraform</a>.workspace expression returns the current workspace name:

locals {
  environment = terraform.workspace

  instance_type = {
    dev        = "t2.micro"
    staging    = "t3.small"
    production = "t3.large"
  }

  instance_count = {
    dev        = 1
    staging    = 2
    production = 5
  }
}

resource "aws_instance" "web" {
  count         = local.instance_count[local.environment]
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = local.instance_type[local.environment]

  tags = {
    Name        = "web-${local.environment}-${count.index + 1}"
    Environment = local.environment
    ManagedBy   = "Terraform"
  }
}

Expected output: In dev, one t2.micro instance. In staging, two t3.small instances. In production, five t3.large instances. The instance names include the workspace name.

Workspace-Aware Variables

Use a map variable keyed by workspace name for environment-specific values:

variable "env_config" {
  type = map(object({
    instance_type  = string
    instance_count = number
    vpc_cidr       = string
  }))

  default = {
    dev = {
      instance_type  = "t2.micro"
      instance_count = 1
      vpc_cidr       = "10.0.0.0/16"
    }
    staging = {
      instance_type  = "t3.small"
      instance_count = 2
      vpc_cidr       = "10.1.0.0/16"
    }
    production = {
      instance_type  = "t3.large"
      instance_count = 5
      vpc_cidr       = "10.2.0.0/16"
    }
  }
}

locals {
  config = var.env_config[terraform.workspace]
}

resource "aws_vpc" "main" {
  cidr_block = local.config.vpc_cidr
}

Expected output: Each workspace creates a VPC with a different CIDR block and different compute resources, all from the same configuration.

Remote State and Workspaces

With remote backends, workspaces create separate state files:

terraform {
  backend "s3" {
    bucket         = "dodatech-terraform-state"
    key            = "infrastructure/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-state-lock"
  }
}

Expected output: With S3 backend, workspaces create state files at env:/workspace_name/infrastructure/<a href="/devops/terraform/">terraform</a>.tfstate. Each workspace has its own state and lock.

Workspaces vs Directory Structure

Workspaces are best for simple environment separation within the same configuration. Directory structure with separate root modules is better when environments need different provider configurations, backends, or drastically different configurations.

Common Mistakes

1. Forgetting to Switch Workspaces

Running <a href="/devops/terraform/">terraform</a> apply in the wrong workspace modifies the wrong environment. Always verify with <a href="/devops/terraform/">terraform</a> workspace show.

2. Not Using Workspace References

Hardcoding environment names instead of using <a href="/devops/terraform/">terraform</a>.workspace creates duplication and drift between workspaces.

3. Workspace Name Conflicts

Workspace names must be unique. Using spaces or special characters in names causes errors.

4. Mixing Backend Types

Switching from local to remote backend requires migration. Workspaces do not automatically transfer between backends.

5. Overusing Workspaces for Major Differences

If environments need different provider versions or regions, use separate directories instead of workspaces.

Practice Questions

1. What is a Terraform workspace? A named instance of a Terraform configuration with its own isolated state file, enabling multiple environments from one configuration.

2. How do you reference the current workspace in a configuration? Using the <a href="/devops/terraform/">terraform</a>.workspace expression, which returns the workspace name as a string.

3. What happens to state when you use workspaces with a remote backend? Each workspace creates a separate state file path under env:/workspace_name/ in the backend.

4. When should you use directories instead of workspaces? When environments need different provider configurations, backends, regions, or drastically different infrastructure layouts.

5. Challenge: Create three workspaces (dev, staging, prod) with workspace-aware variables for instance count and type. Apply each workspace and verify isolated infrastructure.

Mini Project: Multi-Environment Deployment

Create a configuration with three workspaces. Define a map variable keyed by workspace name containing instance type, count, and CIDR. Apply all three workspaces and verify each creates independent infrastructure with workspace-specific values.

Related Concepts

What's Next

Use Terraform workspaces for environment isolation, then master the Plan and Apply workflow for safe, predictable deployments.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro.