HCP Terraform Workspaces and Projects

Scenario: A team confuses CLI workspaces with HCP Terraform workspaces and expects them to share the same isolation model.

An HCP Terraform workspace is an operational boundary containing configuration linkage, variables, state, run history, permissions, and execution settings. Projects organize workspaces and apply access or governance at a broader boundary. CLI, VCS-driven, and API-driven workflows can start runs. Remote operations move execution and credentials to controlled workers. Do not equate an HCP workspace with a CLI state-name selection.

Analogy: A CLI workspace is a tab in a local workbook; an HCP workspace is a staffed project room with its own vault, history, and access list.

A worked configuration

terraform {
  cloud {
    organization = "example-platform"
    workspaces { name = "payments-prod" }
  }
}

Organize by ownership and blast radius. Use projects for team or platform boundaries, variable sets for carefully governed shared configuration, and agents for private-network execution where appropriate.

Note: Treat the plan as a change contract: understand every create, update, replacement, and destroy before approving it.

Goal: Reinforce this lesson in the tf-cross-state-outputs Terraform lab. Open /labs/terraform and choose slug tf-cross-state-outputs; the lab runs real Terraform against the offline FakeCloud provider.