What Are Terraform Workspaces?

Terraform workspaces provide a mechanism to manage multiple distinct state files for the same configuration. By default, Terraform operates in a workspace named default. When you create a new workspace (e.g., terraform workspace new dev), Terraform creates a separate state file for that workspace (e.g., terraform.tfstate.d/dev/terraform.tfstate). All operations within that workspace read from and write to its dedicated state file.

This allows you to deploy the same infrastructure code to different environments—development, staging, production—without altering the code itself, by simply switching workspaces.

Key Terraform CLI workspace commands include:

• terraform workspace new <workspace-name>: Creates a new workspace
• terraform workspace list: Lists existing workspaces
• terraform workspace select <workspace-name>: Switches to a different workspace
• terraform workspace show: Displays the current workspace name
• terraform workspace delete <workspace-name>: Removes a workspace

The terraform.workspace interpolation allows configurations to dynamically reference the current workspace name, enabling slight variations based on the active environment:

resource "aws_instance" "example" {
  ami           = "ami-0c55b31ad20f0c502"
  instance_type = terraform.workspace == "prod" ? "t2.medium" : "t2.micro"

  tags = {
    Name        = "Server-${terraform.workspace}"
    Environment = terraform.workspace
  }
}

CLI Workspaces vs. Cloud Workspaces

The term "workspace" carries different meanings across Terraform's ecosystem:

Open-Source Terraform CLI Workspaces

CLI workspaces are a local feature for managing multiple state files from a single Terraform configuration. They enable state isolation for different environments or parallel development scenarios. However, they have inherent limitations:

• Shared backend configuration: All workspaces use the same backend settings
• Limited access control: No built-in RBAC; relies on underlying system permissions
• Basic isolation: State files are separate, but variable management is manual
• Scalability constraints: Complex conditional logic using terraform.workspace becomes unwieldy at scale

CLI workspaces are best suited for:

• Individual developers managing multiple test environments
• Small teams with simple, homogeneous environments
• Temporary feature branch testing where each workspace is ephemeral
• Learning and experimentation

Remote Workspaces (Terraform Cloud, Scalr)

Terraform Automation and Collaboration Software (TACOs) like Terraform Cloud and Scalr evolved workspace concepts into comprehensive management units. These remote workspaces serve as distinct deployment targets with:

• Isolated state and variables: Each workspace has its own state file, variable scopes, and credentials
• Granular RBAC: Control who can plan, apply, or approve changes per workspace
• Policy enforcement: Integrate Open Policy Agent (OPA) or Sentinel policies
• VCS integration: Trigger runs automatically based on repository changes
• Remote execution: Terraform runs on the platform's infrastructure
• Audit trails: Complete history of who changed what and when
• Environment-scoped variables: Define variables at different hierarchy levels

Remote workspaces are essential for:

• Multi-team organizations requiring governance and separation of duties
• Production infrastructure requiring strict controls and audit trails
• Complex deployments spanning multiple cloud providers
• Compliance-heavy environments demanding policy enforcement

Managing Multiple Environments: Dev, Staging, Production

Consistency and control are paramount when managing configurations across development, staging, and production environments.

Directory-Based Separation Over Workspaces for Major Environments

A widely-accepted best practice in the Terraform community is using separate directories for distinct, long-lived environments. This approach provides maximum isolation:

.
├── environments
│   ├── development
│   │   ├── backend.tf
│   │   ├── main.tf
│   │   └── dev.tfvars
│   ├── staging
│   │   ├── backend.tf
│   │   ├── main.tf
│   │   └── staging.tfvars
│   └── production
│       ├── backend.tf
│       ├── main.tf
│       └── prod.tfvars
├── modules
│   ├── vpc
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── ec2_instance
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf

Benefits of directory-based separation:

• Each environment has its own backend configuration with different state file paths
• Environment-specific provider versions and module versions possible
• Clear isolation prevents accidental cross-environment changes
• Each environment can have tailored access controls

When to use workspaces instead:

Use CLI workspaces for short-term, temporary environments built from the exact same configuration—such as an isolated sandbox for testing a feature branch or a parallel environment for code review. Workspaces are not recommended for distinct prod/staging/dev environments due to shared backend configurations and the potential for complex conditional logic.

Environment-Specific Variables

Define all variables in variables.tf and use .tfvars files for environment-specific values:

# variables.tf
variable "aws_region" {
  description = "AWS region"
  type        = string
}

variable "instance_count" {
  description = "Number of instances"
  type        = number
}

variable "instance_type" {
  description = "EC2 instance type"
  type        = string
}

Then create environment-specific files:

# environments/production/prod.tfvars
aws_region     = "us-east-1"
instance_count = 5
instance_type  = "m5.large"

# environments/development/dev.tfvars
aws_region     = "us-west-2"
instance_count = 1
instance_type  = "t2.micro"

Critical rule: Never store sensitive data in .tfvars files. Use dedicated secret managers (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) and integrate them with your CI/CD pipeline or Terraform provider.

Environment Parity and Drift Minimization

Strive for staging environments that closely mirror production:

• Use the same versioned modules across environments
• Drive differences via configuration (variables), not forked code
• Implement consistent CI/CD pipelines across environments
• Regularly detect and remediate configuration drift

Promotion Strategy: Dev → Staging → Prod

Establish a clear progression path:

1. Use version control (Git) with branching strategies (develop, staging, main)
2. Enforce pull/merge requests with mandatory code reviews
3. Automate promotions via CI/CD pipelines
4. Incorporate manual approval gates for production changes
5. Include terraform plan output in PRs for visibility

Directory-Per-Environment vs. Workspace-Per-Environment

The Problem with Workspace-Centric Approaches

Overreliance on workspaces for environment separation leads to hidden risks:

# ❌ Problematic: Workspace-based environment separation
terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "terraform.tfstate"
    region = "us-west-2"
  }
}

resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = terraform.workspace == "prod" ? "m5.large" : "t2.micro"

  tags = {
    Environment = terraform.workspace
  }
}

Problems with this approach:

• All workspaces share the same backend configuration
• Production and development state files exist in the same bucket path
• Complex conditional logic makes configurations hard to read
• Increased risk of accidental changes to the wrong environment
• Difficult to implement environment-specific policies or provider versions

The Solution: Directory Structure

# ✅ Recommended: Directory-based separation

# ./environments/prod/main.tf
terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "environments/prod/terraform.tfstate"
    region = "us-west-2"
  }
}

module "application" {
  source = "../../modules/application"

  environment   = "prod"
  instance_type = "m5.large"
}

# ./environments/dev/main.tf
terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "environments/dev/terraform.tfstate"
    region = "us-west-2"
  }
}

module "application" {
  source = "../../modules/application"

  environment   = "dev"
  instance_type = "t2.micro"
}

Advantages:

• Each environment has complete configuration isolation
• Unique backend paths prevent state file collisions
• Environment-specific provider versions possible
• Clear, easily auditable separation
• Reduces risk of catastrophic cross-environment mistakes

Monorepo vs. Polyrepo Patterns

The choice between centralized (monorepo) and distributed (polyrepo) repository structures fundamentally affects scalability, collaboration, and operational complexity.

Monorepo: All IaC in One Repository

Architecture:

my-infrastructure-monorepo/
├── environments/
│   ├── dev/
│   ├── staging/
│   └── prod/
├── modules/
│   ├── vpc/
│   ├── database/
│   └── app-tier/
├── policies/
└── docs/

Advantages:

• Unified visibility across all infrastructure
• Atomic cross-component changes (commit once, deploy consistently)
• Easier internal dependency management
• Simplified module discovery and reuse
• Single source of truth for configuration

Disadvantages:

• CI/CD bottlenecks (large repo, slow operations)
• Complex permission management (repo-level access control insufficient)
• Large repository size impacts clone/fetch times
• Risk of unintended changes to unrelated components
• Steep onboarding curve for new team members

Best for:

• Smaller teams (<20 people) with unified infrastructure
• Tightly coupled infrastructure where atomic deployments matter
• Organizations with strong DevOps maturity and robust CI/CD

Polyrepo: IaC Split Across Multiple Repositories

Architecture:

my-org/
├── infra-networking/ (VPC, subnets, routing)
├── infra-database/ (RDS, data warehouse)
├── infra-app/ (Application tier resources)
├── terraform-modules/ (Shared module library)
└── platform-policies/ (OPA policies)

Advantages:

• Clear ownership (team per repo)
• Faster individual builds and deployments
• Independent lifecycle management
• Granular access control aligned with team structure
• Smaller, more navigable repositories

Disadvantages:

• Discovery challenges (modules scattered across repos)
• Complex cross-repo dependency management
• Potential code duplication without central module governance
• Higher coordination overhead between teams
• Risk of version skew between shared dependencies

Best for:

• Larger organizations (>20 people) with specialized teams
• Loosely coupled infrastructure components
• Multi-tenant or multi-product environments
• Organizations with clear team boundaries and autonomy needs

Decision Factors

Choose based on:

1. Team size and structure: Monorepo for unified teams, polyrepo for specialized teams
2. Infrastructure complexity: Simple → monorepo, complex multi-component → polyrepo
3. Organizational culture: Collaboration-focused → monorepo, autonomy-focused → polyrepo
4. CI/CD maturity: Advanced tooling makes both viable; basic tooling favors monorepo
5. Deployment model: Atomic → monorepo, independent → polyrepo

Pro tip: Regardless of choice, use centralized platforms like Scalr that provide unified management across both monorepo and polyrepo structures.

Structuring Terraform Projects for Production

How you organize Terraform code determines your ability to scale, maintain security, and collaborate effectively.

Strategic Code Organization Principles

Standard File Layout:

Every module should follow a consistent structure:

• main.tf: Primary resource definitions
• variables.tf: Input variable declarations with types, descriptions, and defaults
• outputs.tf: Output value definitions for downstream consumption
• versions.tf: Terraform/OpenTofu and provider version constraints
• terraform.tfvars or *.auto.tfvars: Variable value assignments

# versions.tf
terraform {
  required_version = ">= 1.5"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

Naming Conventions:

• Resources: Singular names (e.g., aws_instance.web_server)
• Variables: Descriptive with units (e.g., ram_size_gb, enable_monitoring)
• Outputs: Descriptive (e.g., vpc_id, database_endpoint)
• Files: Group related resources logically (e.g., network.tf, compute.tf, security.tf)
• General: Use underscores for separation; be descriptive and consistent

Designing Reusable Modules

Modules are your foundation for DRY (Don't Repeat Yourself) infrastructure. Poor module design leads to code duplication and maintenance nightmares.

Module Design Principles:

1. Single responsibility: Each module has one clear purpose
2. Clear interface: Well-defined inputs (variables.tf) and outputs (outputs.tf)
3. Avoid thin wrappers: Modules should add value (enforce standards, simplify complexity), not just wrap a single resource
4. Parameterize sparingly: Expose only necessary variables; use sensible defaults
5. Documentation: Include README.md with purpose, inputs, outputs, and usage examples
6. Semantic versioning: Tag shared modules with meaningful versions for tracking changes

Example well-designed module:

# modules/vpc/main.tf
resource "aws_vpc" "main" {
  cidr_block           = var.cidr_block
  enable_dns_hostnames = var.enable_dns_hostnames

  tags = {
    Name    = "${var.project_name}-vpc"
    Project = var.project_name
  }
}

resource "aws_internet_gateway" "main" {
  vpc_id = aws_vpc.main.id

  tags = {
    Name = "${var.project_name}-igw"
  }
}

# modules/vpc/variables.tf
variable "project_name" {
  description = "The name of the project"
  type        = string
}

variable "cidr_block" {
  description = "The CIDR block for the VPC"
  type        = string
  default     = "10.0.0.0/16"
}

variable "enable_dns_hostnames" {
  description = "Enable DNS hostnames in the VPC"
  type        = bool
  default     = true
}

# modules/vpc/outputs.tf
output "vpc_id" {
  description = "The ID of the VPC"
  value       = aws_vpc.main.id
}

output "internet_gateway_id" {
  description = "The ID of the internet gateway"
  value       = aws_internet_gateway.main.id
}

State Management Best Practices

State is critical. Protect and manage it meticulously.

State Splitting:

Avoid monolithic state files. Break down state by environment, region, and component:

production/
  networking/terraform.tfstate
  app-main/terraform.tfstate
  databases/terraform.tfstate
staging/
  networking/terraform.tfstate
  app-main/terraform.tfstate

Benefits:

• Reduces blast radius of errors
• Improves plan/apply performance
• Allows granular access control
• Simplifies team collaboration

Remote Backends:

Always use remote backends (AWS S3, Azure Blob Storage, Google Cloud Storage) with:

terraform {
  backend "s3" {
    bucket         = "my-tf-state-bucket-prod"
    key            = "production/networking/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "my-tf-state-lock-prod"
    encrypt        = true
  }
}

Essential remote backend features:

• State locking: Prevent concurrent modifications (DynamoDB for S3)
• Versioning: Enable rollback capabilities
• Encryption: Encrypt state at rest and in transit
• Access controls: Implement least-privilege IAM policies

Logical Backend Keys:

Structure paths consistently for easy management:

env:/<environment>/<region>/<component>/terraform.tfstate

Example:

env:/production/us-east-1/networking/terraform.tfstate
env:/production/us-east-1/app-tier/terraform.tfstate
env:/staging/us-east-1/networking/terraform.tfstate

Managing Dependencies:

Use terraform_remote_state to read outputs from other isolated state files:

data "terraform_remote_state" "networking" {
  backend = "s3"

  config = {
    bucket = "my-tf-state-bucket"
    key    = "production/networking/terraform.tfstate"
    region = "us-east-1"
  }
}

resource "aws_instance" "app" {
  subnet_id = data.terraform_remote_state.networking.outputs.subnet_id
  # ...
}

Design dependencies carefully to avoid overly complex or circular relationships.

Workspace Strategies at Scale

As infrastructure grows, basic workspace management becomes insufficient. Sophisticated approaches are required.

Common Sticking Points

• Misunderstanding purpose: Workspaces manage state files, not comprehensive environment configuration
• Overuse of conditional logic: Heavy reliance on terraform.workspace makes configurations complex and error-prone
• False sense of isolation: Separate state doesn't prevent resource naming conflicts or shared service contention
• Limited governance: CLI workspaces lack RBAC, policy enforcement, and audit trails

Scaling Strategies

1. Embrace modularity: Break complex configurations into focused modules with clear responsibilities
2. Adopt a TACO platform: For teams managing hundreds of workspaces, platforms like Scalr provide:
   • Hierarchical variable scoping
   • Federated environment access
   • Workspace dependency management
   • Run triggers for orchestration
   • Integrated policy enforcement
3. Minimize blast radius: Keep state files small and focused
   • One per environment per region per component
   • Avoid "kitchen sink" configurations
   • Use separate state for shared services

Use Terragrunt for orchestration: Manage dependencies and reduce boilerplate:

# environments/prod/vpc/terragrunt.hcl
terraform {
  source = "../../../modules/vpc"
}

inputs = {
  cidr_block = "10.0.0.0/16"
  environment = "prod"
}

Implement hierarchical configuration: Use directory structures and configuration inheritance:

global/terraform.tfvars (common to all envs)
environments/prod/terraform.tfvars (prod-specific)
environments/prod/backend.tf (prod backend)

Workspace Dependencies in Remote Platforms

Terraform Cloud / Scalr:

Remote workspaces support structured dependencies through:

• Run Triggers: Automatically queue downstream workspace runs when upstream workspace succeeds
• Output Sharing: Consumer workspaces read producer workspace outputs via tfe_outputs (TFC) or terraform_remote_state
• Federated Access: Manage cross-environment dependencies with unified RBAC

Example dependency flow:

Networking Workspace (creates VPC, subnets)
  ↓ (Run Trigger)
Application Workspace (references networking outputs)
  ↓ (Run Trigger)
Database Workspace (references app outputs)

Best Practices for 2026

Modern infrastructure requires evolved approaches to environment management.

1. Treat IaC as Production Code

• Maintain the same rigor as application code (reviews, testing, CI/CD)
• Use semantic versioning for modules and infrastructure
• Enforce code standards and consistency checks
• Maintain comprehensive documentation

2. Implement Comprehensive Security

Secret Management:

• Never commit secrets to Git
• Use external secret managers with dynamic credential rotation
• Integrate secret injection into CI/CD pipelines
• Mark sensitive outputs with sensitive = true

Access Control:

• Adhere strictly to least-privilege for Terraform execution roles
• Use separate IAM roles per environment
• Manage IAM policies themselves as code
• Implement RBAC at the platform level (workspace, environment)

Network Security as Code:

• Define all security groups and firewall rules in Terraform
• Enforce policies preventing unintended public exposure
• Use dedicated VPCs per environment

3. Automate Everything

CI/CD Pipeline Stages:

1. Checkout code
2. Initialize and validate Terraform
3. Format check (terraform fmt)
4. Static analysis and linting
5. Security scanning (Checkov, tfsec)
6. Policy as Code evaluation (OPA, Sentinel)
7. Plan generation
8. Manual approval (for production)
9. Apply

Mandatory Approval Gates:

• Require human approval before production applies
• Implement "prevent self-review" for critical changes
• Include terraform plan in PR for visibility

4. Enforce Policy as Code

Use Open Policy Agent (OPA) with Rego or HashiCorp Sentinel to automatically enforce policies:

# Enforce S3 encryption
package terraform.analysis

deny[msg] {
  bucket := input.resource_changes[_]
  bucket.type == "aws_s3_bucket"
  bucket.mode == "managed"
  not bucket.change.after.server_side_encryption_configuration
  msg := sprintf("S3 Bucket '%s' must have server-side encryption", [bucket.name])
}

Policies can enforce:

• Security standards (encryption, public exposure prevention)
• Compliance requirements (tagging, regions, instance types)
• Cost optimization (instance sizing, reserved capacity)
• Operational standards (naming conventions, monitoring)

5. Master Environment Promotion

• Use Git branching for progression (feature → develop → staging → main)
• Automate promotion via CI/CD with manual gates for production
• Test thoroughly in non-production before production deployment
• Maintain environment parity between dev, staging, and prod

6. Leverage Specialized Tooling

Terragrunt: Wrapper for Terraform that:

• Keeps configurations DRY through inheritance
• Automates backend setup
• Manages inter-module dependencies
• Provides run-all commands for bulk operations

Atlantis: Enables GitOps workflows:

• Automates terraform plan on PR creation
• Shows plan output in PR comments
• Enables infrastructure review before apply
• Provides approval workflow

TACO Platforms (Scalr, Terraform Cloud, Spacelift, Env0):

• Centralize state and variable management
• Provide built-in governance and RBAC
• Offer integrated CI/CD and policy engines
• Enable team collaboration with audit trails

7. Implement Drift Detection and Remediation

• Regularly scan infrastructure for drift
• Alert when actual state diverges from declared state
• Establish processes for remediation
• Use drift as an opportunity to update code

8. Continuous Improvement

Key Metrics:

• Lead time for changes
• Deployment frequency
• Change failure rate
• Mean time to recovery (MTTR)
• Code reusability index
• Team onboarding time

Feedback Loops:

• Regular code reviews (including structure)
• Team retrospectives on IaC practices
• Automated testing and validation
• CI/CD pipeline performance monitoring
• Stay current with tooling and best practices

Conclusion

Managing Terraform environments effectively requires moving beyond basic workspace commands to adopt a comprehensive, disciplined approach. The evolution from CLI workspaces to sophisticated remote platforms reflects the growing operational complexity of infrastructure at scale.

Key Takeaways:

• Use directory-based separation for distinct environments (dev/staging/prod)
• Use CLI workspaces only for temporary, ephemeral test scenarios
• Choose monorepo vs. polyrepo based on team structure and infrastructure coupling
• Implement hierarchical state management with separate files per environment/region/component
• Automate everything through robust CI/CD pipelines with policy enforcement
• Treat IaC as production code with reviews, testing, and versioning
• Scale with platforms: Remote workspaces and TACOs provide governance, RBAC, and automation essential for organizational growth

By implementing these practices, you can build robust, secure, and scalable Terraform environments that support your team's growth while maintaining stability, security, and compliance across your entire infrastructure-as-code landscape.

Further Reading

• Structuring Terraform, part 1
• Structuring Terraform, part 2
• Structuring Terraform, part 3
• Structuring Terraform, part 1