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.