HCP Terraform Workspaces and Projects

Scenario: A team fresh off learning CLI workspaces (Module 6) assumes an HCP Terraform workspace is basically the same concept with a web UI on top, and is surprised when it turns out to carry a much stronger isolation boundary than they expected.

It's worth clearing up a genuinely common point of confusion directly: a CLI workspace (Module 6) is just a named alternate state file for one configuration, sharing the same backend and credentials by default. An HCP Terraform workspace (HashiCorp's managed collaboration platform) is a considerably bigger unit - a full operational boundary bundling together which configuration it runs, its own variables, its own state, a complete run history, its own permission model, and its own execution settings. Two HCP Terraform workspaces are far more like the separate root directories pattern from Module 6 than like two CLI-workspace state files sharing one root.

HCP Terraform can trigger runs from the CLI, automatically from a connected VCS repository (a run kicks off when a pull request merges or opens), or via its API for custom automation. "Remote operations" means the actual plan/apply execution - and the credentials it needs - happens on HCP Terraform's own controlled infrastructure rather than on an individual's laptop, which is itself a meaningful security improvement over ad hoc local applies. Projects sit one level above workspaces, letting you group and apply access policy across a whole set of related workspaces at once - useful for a team or platform boundary that spans more than one individual workspace.

Analogy: A CLI workspace is a tab inside one shared local workbook. An HCP Terraform workspace is closer to an entire staffed project room, complete with its own document vault, its own visitor log recording every run, and its own access list controlling who's allowed in - a fundamentally more isolated, more heavily-instrumented unit than a tab in a shared file.

A worked configuration

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

When designing an HCP Terraform organization, organize workspaces primarily by ownership and blast radius - one team's payments infrastructure should not casually share a workspace with an unrelated team's marketing site infrastructure. Use projects to apply consistent policy across a whole team or platform's set of workspaces, variable sets for shared configuration values that genuinely need central, carefully governed management, and private agents where execution needs to reach into a network HCP Terraform's own infrastructure can't otherwise access.

Common mistakes in production

• Assuming an HCP Terraform workspace has the same weak isolation (shared backend, shared credentials) as a CLI workspace - HCP Terraform workspaces are a much stronger boundary with their own permissions and settings.
• Grouping unrelated teams' infrastructure into one workspace or project for convenience, rather than organizing by actual ownership and blast radius.

Goal: Treat the plan as a change contract: understand every create, update, replacement, and destroy before approving it. 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.