Workspaces vs directory-based separation in Terraform - CLI Comparison

Introduction

When managing infrastructure with Terraform, you often need to separate environments like development and production. You can do this by using Terraform workspaces or by keeping separate directories for each environment. Each method helps keep your infrastructure organized and prevents changes in one environment from affecting another.

When you want to manage multiple environments like dev, staging, and prod using the same Terraform configuration files.

When you want to avoid duplicating code but still keep environment states separate.

When you prefer a simple folder structure to isolate environments completely.

When you want to switch environments quickly without changing directories.

When you want to keep environment configurations fully independent for safety.

Config File - main.tf

main.tf

terraform {
  required_version = ">= 1.3.0"
}

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

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

This Terraform configuration creates an AWS S3 bucket. The bucket name includes the current workspace name, so each workspace creates a separate bucket.

The terraform block sets the required Terraform version.

The provider block configures AWS region.

The resource block defines the S3 bucket with a name that changes based on the workspace.

Commands

Initializes the Terraform working directory, downloads provider plugins, and prepares the environment.

Terminal

terraform init

Expected Output

Initializing the backend...



Initializing provider plugins...

- Finding latest version of hashicorp/aws...

- Installing hashicorp/aws v4.0.0...

- Installed hashicorp/aws v4.0.0 (signed by HashiCorp)



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see

any changes that are required for your infrastructure. All Terraform commands

should now work.

Lists all existing Terraform workspaces to see which environments are available.

Terminal

terraform workspace list

Expected Output

* default

Creates a new workspace named 'dev' to separate the development environment state.

Terminal

terraform workspace new dev

Expected Output

Created and switched to workspace "dev".



You're now on a new workspace called "dev".



If you ever want to switch back to the default workspace, run

  terraform workspace select default

Applies the Terraform configuration in the current workspace, creating resources specific to that workspace.

Terminal

terraform apply -auto-approve

Expected Output

aws_s3_bucket.example: Creating...

aws_s3_bucket.example: Creation complete after 2s [id=example-bucket-dev]



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

→

-auto-approve - Skips interactive approval before applying changes

Switches back to the default workspace to manage or create resources for another environment.

Terminal

terraform workspace select default

Expected Output

Switched to workspace "default".

Key Concept

If you remember nothing else from this pattern, remember: Terraform workspaces let you use the same code to manage multiple environments by keeping their states separate, while directory-based separation uses different folders to isolate environments completely.

Common Mistakes

Using the same workspace for multiple environments without switching workspaces.

This causes Terraform to overwrite or mix states, leading to resource conflicts or accidental changes across environments.

Always create and switch to a separate workspace for each environment before applying changes.

Mixing workspace usage with directory-based separation without clear boundaries.

This can cause confusion about which state is active and where resources are managed, increasing risk of errors.

Choose one method clearly: either use workspaces with a single directory or separate directories with their own state files.

Hardcoding resource names without including workspace or environment identifiers.

Resources may clash or overwrite each other when using multiple environments in the same account.

Include the workspace name or environment identifier in resource names to keep them unique.

Summary

Initialize Terraform with 'terraform init' to prepare the working directory.

Use 'terraform workspace new <name>' to create separate environments sharing the same code.

Apply changes in the current workspace with 'terraform apply' to keep states isolated.

Switch workspaces with 'terraform workspace select <name>' to manage different environments.

Include workspace names in resource identifiers to avoid conflicts.

Practice

1. What is the main difference between Terraform workspaces and directory-based separation?

easy

A. Workspaces require separate folders; directory-based uses one folder with multiple states.

B. Workspaces store state remotely; directory-based stores state locally only.

C. Workspaces and directory-based separation are exactly the same.

D. Workspaces use one folder with multiple states; directory-based uses separate folders for each environment.

Solution

1. Step 1: Understand workspace concept

   Workspaces allow multiple states inside the same folder by switching context.

2. Step 2: Understand directory-based separation

   Directory-based separation uses different folders, each with its own code and state files.

3. Final Answer:

   Workspaces use one folder with multiple states; directory-based uses separate folders for each environment. -> Option D

4. Quick Check:

   Workspaces = one folder, multiple states [OK]

Hint: Workspaces = one folder, directory = multiple folders [OK]

Common Mistakes:

• Confusing workspace with directory-based separation
• Thinking workspaces require multiple folders
• Assuming directory-based uses one state file

2. Which Terraform command correctly switches to a workspace named dev?

easy

A. terraform workspace select dev

B. terraform select workspace dev

C. terraform switch workspace dev

D. terraform workspace change dev

Solution

1. Step 1: Recall Terraform workspace commands

   The correct command to switch workspace is terraform workspace select <name>.

2. Step 2: Match command to options

   Only terraform workspace select dev matches the correct syntax exactly.

3. Final Answer:

   terraform workspace select dev -> Option A

4. Quick Check:

   Switch workspace = terraform workspace select [OK]

Hint: Use 'terraform workspace select' to switch workspaces [OK]

Common Mistakes:

• Using incorrect command order
• Using non-existent commands like 'switch' or 'change'
• Confusing workspace commands with other terraform commands

3. Given this folder structure:

envs/
  ├─ dev/
  │    └─ main.tf
  └─ prod/
       └─ main.tf

and using directory-based separation, what happens if you run terraform apply inside envs/dev?

medium

A. Terraform applies changes to both dev and prod environments simultaneously.

B. Terraform applies changes only to the dev environment using its own state.

C. Terraform throws an error because state is missing.

D. Terraform applies changes to the prod environment instead.

Solution

1. Step 1: Understand directory-based separation behavior

   Each folder has its own Terraform code and state, so running inside envs/dev affects only dev.

2. Step 2: Analyze command effect

   terraform apply in envs/dev applies changes only to dev environment's resources.

3. Final Answer:

   Terraform applies changes only to the dev environment using its own state. -> Option B

4. Quick Check:

   Directory-based apply affects current folder environment [OK]

Hint: Apply runs in current folder's environment only [OK]

Common Mistakes:

• Assuming apply affects all environments
• Thinking state is shared across folders
• Expecting errors due to missing state

4. You created a new workspace named staging but when running terraform apply, changes apply to the default workspace instead. What is the likely cause?

medium

A. You forgot to run terraform workspace select staging before applying.

B. The staging workspace does not exist.

C. Terraform does not support multiple workspaces.

D. You need to rename the default workspace to staging.

Solution

1. Step 1: Check workspace usage

   Creating a workspace does not switch to it automatically; you must select it explicitly.

2. Step 2: Identify missing command

   If you don't run terraform workspace select staging, Terraform stays in default workspace.

3. Final Answer:

   You forgot to run terraform workspace select staging before applying. -> Option A

4. Quick Check:

   Must select workspace before apply [OK]

Hint: Always select workspace before applying changes [OK]

Common Mistakes:

• Assuming workspace auto-switches after creation
• Thinking workspace names must be renamed
• Believing Terraform lacks workspace support

5. You want to manage three environments: dev, staging, and prod. You want to keep code DRY (Don't Repeat Yourself) and share most configuration but keep states isolated. Which approach is best?

hard

A. Use one folder and switch backend configuration files for each environment.

B. Create three separate folders, each with full copies of code and state.

C. Use one folder with Terraform workspaces for each environment.

D. Use one folder and manually rename state files for each environment.

Solution

1. Step 1: Analyze DRY and state isolation needs

   Sharing code but isolating state fits well with workspaces, which share code folder but separate states.

2. Step 2: Compare options

   Use one folder with Terraform workspaces for each environment uses workspaces to keep one codebase and separate states per environment, avoiding code duplication.

3. Step 3: Evaluate other options

   Create three separate folders, each with full copies of code and state duplicates code, violating DRY. Use one folder and manually rename state files for each environment is error-prone and manual. Use one folder and switch backend configuration files for each environment requires backend changes, complex to manage.

4. Final Answer:

   Use one folder with Terraform workspaces for each environment. -> Option C

5. Quick Check:

   Workspaces = shared code, separate states [OK]

Hint: Workspaces share code, separate states for DRY environments [OK]

Common Mistakes:

• Duplicating code in multiple folders unnecessarily
• Trying manual state file renaming
• Switching backend configs frequently