Workspaces and remote state in Terraform - Commands & Configuration

Introduction

When you manage infrastructure with Terraform, you need to keep track of what you created. Workspaces help you keep different versions of your infrastructure separate. Remote state stores this information safely so teams can share it without conflicts.

When you want to manage multiple environments like development and production using the same Terraform code.

When you work in a team and need to share the current state of your infrastructure safely.

When you want to avoid overwriting infrastructure changes by keeping state files in a central place.

When you want to switch between different infrastructure setups without mixing their resources.

When you want to back up your infrastructure state automatically to avoid losing track of resources.

Config File - main.tf

main.tf

terraform {
  required_version = ">= 1.0"
  backend "s3" {
    bucket = "example-terraform-state"
    key    = "project/terraform.tfstate"
    region = "us-east-1"
    encrypt = true
  }
}

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

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

The terraform block configures the backend to store state remotely in an S3 bucket. This keeps the state file safe and shared.

The provider block sets AWS as the cloud provider.

The resource block creates an S3 bucket named example-terraform-workspace-bucket to demonstrate infrastructure managed by Terraform.

Commands

This command initializes Terraform, setting up the backend and downloading necessary plugins.

Terminal

terraform init

Expected Output

Initializing the backend...



Successfully configured the backend "s3"!



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see any changes required for your infrastructure.

Lists all existing workspaces to see which environments or versions you can switch between.

Terminal

terraform workspace list

Expected Output

* default

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

Terminal

terraform workspace new dev

Expected Output

Created and switched to workspace "dev".



You're now using workspace "dev".

Applies the Terraform configuration in the current workspace, creating or updating resources.

Terminal

terraform apply -auto-approve

Expected Output

aws_s3_bucket.example: Creating...

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



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

→

-auto-approve - Skips the confirmation prompt to apply changes immediately.

Switches back to the default workspace to manage a different environment or version.

Terminal

terraform workspace select default

Expected Output

Switched to workspace "default".

Key Concept

If you remember nothing else from this pattern, remember: workspaces let you manage multiple versions of infrastructure safely, and remote state keeps your infrastructure data shared and secure.

Common Mistakes

Not initializing Terraform before running other commands.

Terraform needs to set up the backend and download plugins first, or commands will fail.

Always run 'terraform init' before other Terraform commands.

Using the same workspace for different environments like dev and prod.

This mixes state files and can cause resource conflicts or accidental changes.

Create and switch to separate workspaces for each environment.

Not configuring remote state backend and storing state locally.

Local state files are not shared and can cause conflicts in team environments.

Configure a remote backend like S3 to store state safely and share it.

Summary

Initialize Terraform with 'terraform init' to set up remote state backend.

Use 'terraform workspace new' and 'terraform workspace select' to manage separate environments.

Apply infrastructure changes with 'terraform apply' in the chosen workspace.

Practice

1. What is the main purpose of Terraform workspaces?

easy

A. To store Terraform state files locally on your computer

B. To manage multiple versions of infrastructure in the same configuration

C. To write Terraform code faster using templates

D. To automatically fix errors in Terraform code

Solution

1. Step 1: Understand what workspaces do

   Workspaces allow you to keep separate state files for the same Terraform configuration, so you can manage different environments or versions.

2. Step 2: Compare options

   Only To manage multiple versions of infrastructure in the same configuration correctly describes this purpose. Options B, C, and D describe unrelated features.

3. Final Answer:

   To manage multiple versions of infrastructure in the same configuration -> Option B

4. Quick Check:

   Workspaces = multiple infrastructure versions [OK]

Hint: Workspaces separate states for different environments [OK]

Common Mistakes:

• Confusing workspaces with local state storage
• Thinking workspaces speed up code writing
• Believing workspaces fix code errors automatically

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

easy

A. terraform workspace select prod

B. terraform switch workspace prod

C. terraform change workspace prod

D. terraform use workspace prod

Solution

1. Step 1: Recall the correct command syntax

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

2. Step 2: Verify options

   Only terraform workspace select prod uses the correct command and syntax. Options B, C, and D are invalid commands.

3. Final Answer:

   terraform workspace select prod -> Option A

4. Quick Check:

   Switch workspace = terraform workspace select [OK]

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

Common Mistakes:

• Using 'terraform switch' instead of 'workspace select'
• Confusing workspace commands with other Terraform commands
• Omitting the 'workspace' keyword

3. Given this Terraform backend configuration snippet:

terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "envs/${terraform.workspace}/terraform.tfstate"
    region = "us-east-1"
  }
}

What happens when you run terraform workspace select dev and then terraform apply?

medium

A. Terraform stores state in S3 under key 'envs/dev/terraform.tfstate'

B. Terraform stores state in S3 under key 'envs/prod/terraform.tfstate'

C. Terraform throws an error because workspace names cannot be used in backend keys

D. Terraform stores state locally instead of S3

Solution

1. Step 1: Understand backend key interpolation

   The backend key uses ${terraform.workspace} to dynamically set the state file path based on the current workspace.

2. Step 2: Apply workspace selection effect

   After selecting workspace 'dev', the key becomes 'envs/dev/terraform.tfstate', so state is stored there in S3.

3. Final Answer:

   Terraform stores state in S3 under key 'envs/dev/terraform.tfstate' -> Option A

4. Quick Check:

   Workspace name in backend key = state path [OK]

Hint: Workspace name replaces ${terraform.workspace} in backend key [OK]

Common Mistakes:

• Assuming state always stored under 'prod' key
• Thinking workspace names can't be used in backend keys
• Believing state is stored locally despite backend config

4. You run terraform init after changing the backend configuration, but get this error:
Error: Backend reinitialization required
What is the most likely cause?

medium

A. You did not run terraform init after changing backend settings

B. You have multiple state files in the same workspace

C. You switched workspaces without updating the backend

D. You changed the backend configuration but did not confirm reinitialization

Solution

1. Step 1: Understand backend reinitialization

   Changing backend settings requires Terraform to reinitialize and confirm the changes to avoid state corruption.

2. Step 2: Identify cause of error

   The error means Terraform detected backend changes but you did not confirm reinitialization during terraform init.

3. Final Answer:

   You changed the backend configuration but did not confirm reinitialization -> Option D

4. Quick Check:

   Backend change needs confirmed reinit [OK]

Hint: Confirm backend reinit after config changes with terraform init [OK]

Common Mistakes:

• Ignoring the prompt to confirm backend reinitialization
• Confusing workspace switch with backend reinit
• Assuming multiple state files cause this error

5. You want to manage separate infrastructure for dev and prod using the same Terraform code and remote backend. Which setup is best practice?

hard

A. Use one workspace and manually rename state files in the backend

B. Create two separate Terraform configurations with different backend buckets

C. Use Terraform workspaces with backend key including ${terraform.workspace} to separate state files

D. Store all state files locally and switch workspace manually

Solution

1. Step 1: Understand workspace and backend usage

   Workspaces let you use one configuration for multiple environments by separating state files using workspace names.

2. Step 2: Evaluate options for best practice

   Use Terraform workspaces with backend key including ${terraform.workspace} to separate state files uses workspaces and dynamic backend keys to keep states separate and managed centrally, which is best practice.

3. Step 3: Reject other options

   Create two separate Terraform configurations with different backend buckets duplicates code and backend unnecessarily. Use one workspace and manually rename state files in the backend risks state conflicts. Store all state files locally and switch workspace manually loses benefits of remote state.

4. Final Answer:

   Use Terraform workspaces with backend key including ${terraform.workspace} to separate state files -> Option C

5. Quick Check:

   Workspaces + dynamic backend key = best practice [OK]

Hint: Use workspaces with backend key for separate environment states [OK]

Common Mistakes:

• Duplicating configs instead of using workspaces
• Manually renaming state files causing errors
• Storing state locally losing collaboration benefits