Lab: Workspaces for Short-Lived Environments

Objective

By the end of this lab, you will have:

• Created a configuration with multiple workspaces.
• Switched between workspaces.
• Applied the same configuration to different workspaces.
• Verified the workspaces are separate.

Requirements

• A Linux or macOS workstation with shell access.
• The Terraform CLI 1.9.x or later installed.

Scenario

You have a configuration that creates a file. You want to manage dev and staging environments with the same configuration. Workspaces are the right tool for short-lived, similar environments.

Tasks

Task 1: Create the working directory

mkdir -p ~/rb-workspace-lab
cd ~/rb-workspace-lab

Task 2: Initial configuration

Create main.tf:

terraform {
  required_version = ">= 1.9.0"
  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.5"
    }
  }
}

resource "local_file" "readme" {
  filename = "${path.module}/README.md"
  content  = "Initial content.\n"
}

Task 3: Initialise

terraform init

Task 4: Create the workspaces

terraform workspace new dev
terraform workspace new staging
terraform workspace list

The output:

  default
* dev
  staging

The current workspace is dev.

Task 5: Apply to dev

terraform workspace select dev
terraform apply

Verify:

cat ~/rb-workspace-lab/README.md

The file is created.

Task 6: Apply to staging

terraform workspace select staging
terraform apply

Verify:

cat ~/rb-workspace-lab/README.md

The file is created (or overwritten).

Task 7: Inspect the state per workspace

terraform workspace select dev
terraform state list

The state has the resource.

terraform workspace select staging
terraform state list

The state also has the resource (a separate resource in a separate state).

Task 8: Modify the configuration per workspace

Edit main.tf to use a variable:

variable "environment" {
  type    = string
  default = "default"
}

resource "local_file" "readme" {
  filename = "${path.module}/README.md"
  content  = "Content for ${var.environment}\n"
}

Apply to dev:

terraform workspace select dev
terraform apply -var=environment=dev

Apply to staging:

terraform workspace select staging
terraform apply -var=environment=staging

Task 9: Verify the workspaces are separate

terraform workspace select dev
cat ~/rb-workspace-lab/README.md

The file content is the dev content.

terraform workspace select staging
cat ~/rb-workspace-lab/README.md

The file content is the staging content.

But the file is the same path! Each apply overwrites the file. This is the production antipattern: workspaces without isolation share the same real-world resources.

Task 10: Recognise the limitation

Workspaces are appropriate for:

• Short-lived environments (e.g. a dev environment that is rebuilt daily).
• Similar environments (e.g. dev and staging with the same configuration).

Workspaces are not appropriate for:

• Production isolation (production needs its own backend, its own credentials, its own state).
• Different real-world resources per environment (each environment needs its own configuration).

Validation

The lab is successful if:

• The workspaces were created.
• The configuration was applied to each workspace.
• The two workspaces have separate states.
• The same file path was used in both workspaces.

Expected Outcome

At the end of the lab:

+---------------------------------+
| ~/rb-workspace-lab/                |
|   .terraform/                    |
|   .terraform.lock.hcl            |
|   README.md                       |
|   main.tf                        |
+---------------------------------+

The state file is in .terraform/. The two workspaces have separate state files.

Cleanup

cd ~/rb-workspace-lab
terraform workspace select default
terraform workspace delete dev
terraform workspace delete staging
terraform destroy
rm -rf .terraform .terraform.lock.hcl terraform.tfstate*

The main.tf is the only artefact worth keeping.

What You Learned

You learned the workspace pattern:

1. Workspaces are separate states in the same backend. The state path includes the workspace name.
2. Workspaces share the same configuration. The same main.tf is applied to each workspace.
3. Workspaces are not isolated. They share the same credentials and lock table.
4. Workspaces are appropriate for short-lived, similar environments. They are not appropriate for production isolation.
5. Workspaces do not separate real-world resources by default. Each workspace must declare its own paths.