HCP Terraform: Workspaces, Collaboration, and Governance

HCP Terraform is HashiCorp's managed application for running Terraform collaboratively — a SaaS platform (hosted at app.terraform.io) that executes Terraform runs remotely, stores state, manages variables and secrets, and adds team and governance features on top of the open-source CLI. It was formerly called Terraform Cloud; HashiCorp renamed it when it joined the HashiCorp Cloud Platform family, and the 004 exam uses the new name. The self-hosted version of the same application, installed in your own environment, is Terraform Enterprise.

Why it exists: the core CLI workflow works well for one person, but a team hits problems immediately — where does state live, who is applying right now, how are credentials shared, and who approved this change? Running Terraform locally means every engineer needs cloud credentials on their laptop, and nothing stops two people applying at once. HCP Terraform answers all of these in one place: state is stored centrally and locked automatically during runs, credentials live in the workspace rather than on laptops, runs happen in a consistent remote environment, and every plan and apply is recorded with who triggered and who approved it.

You still write the same HCL and use the same terraform CLI. The difference is where runs execute and where state lives. Keep the naming straight for the exam: HCP Terraform is the managed platform (formerly Terraform Cloud), Terraform Enterprise is self-hosted, and Terraform Community Edition is the open-source CLI on its own.

You connect a working directory to HCP Terraform in two steps: authenticate the CLI with terraform login, then add a cloud block to the configuration. terraform login opens a browser to generate a user API token and stores it locally in credentials.tfrc.json (under ~/.terraform.d/), so subsequent commands can call the HCP Terraform API. By default it targets app.terraform.io; pass a hostname to log in to a Terraform Enterprise instance instead.

$ terraform login
Terraform will request an API token for app.terraform.io
  using your browser.
...
Success! Terraform has obtained and saved an API token.

The cloud block lives inside the top-level terraform block and names your organization and the workspace(s) this configuration maps to — either one workspace by name, or a set of workspaces selected by tags:

terraform {
  cloud {
    organization = "acme-corp"

    workspaces {
      name = "networking-prod"
    }
  }
}

With tags instead of name, terraform workspace select chooses among the matching HCP Terraform workspaces from the CLI. After adding the block, run terraform init; if you have existing local state, init offers to migrate it into the HCP Terraform workspace. You can also configure the integration through environment variables such as TF_CLOUD_ORGANIZATION and TF_WORKSPACE, which is useful in CI.

Exam trap: the cloud block is the recommended replacement for the older remote backend (it shipped in Terraform 1.1 and is the standard method in Terraform 1.12). A configuration cannot contain both a backend block and a cloud block — the cloud block is not a backend, though it plays the same role of deciding where state lives.

HCP Terraform creates infrastructure through remote runs: plan and apply execute on HashiCorp-managed run environments instead of your machine, using credentials stored in the workspace. When you run terraform plan in a directory with a cloud block, the CLI uploads the configuration, the run executes remotely, and the output streams back to your terminal — this is the CLI-driven workflow. Applies can be confirmed from the terminal or from the web UI.

There are three ways to trigger runs, and the exam expects you to know all three:

• CLI-driven — terraform plan / terraform apply from your terminal, executed remotely.
• VCS-driven — the workspace is linked to a repository branch; a merge triggers a plan-and-apply run, and pull requests get automatic speculative plans (plan-only runs that can never be applied) posted as status checks.
• API-driven — external systems (CI pipelines, custom tooling) create runs via the HCP Terraform API using API tokens.

Each workspace also has an execution mode. Remote (the default) runs plans and applies on HCP Terraform's infrastructure. Local executes runs on your own machine while still using the workspace for state storage — useful when runs need access to a private network. Agent mode runs operations on self-hosted HCP Terraform agents you deploy inside private environments, so HCP Terraform can manage isolated infrastructure without inbound network access.

They share a name but are different things, and this is one of the most commonly tested traps in objective 8. A CLI workspace is just an alternate state file for a single configuration in a single working directory — created with terraform workspace new, it changes nothing but which state Terraform reads and writes. An HCP Terraform workspace is a complete unit of infrastructure management: it owns its state and its variables, credentials, run history, VCS connection, permissions, and notification settings.

The standard pattern on HCP Terraform is one workspace per environment per component — for example networking-dev, networking-staging, networking-prod — often all linked to the same repository but with different variables and permissions. This replaces the CLI-workspace habit of switching state files under one directory, and it is what the tags form of the cloud block is designed for: tag all three workspaces networking and select between them with terraform workspace select.

Projects are how you organize workspaces inside an HCP Terraform organization: a project is a group of related workspaces, typically owned by one team or covering one application or business area. Every workspace belongs to exactly one project (organizations start with a Default Project), and the hierarchy is organization → projects → workspaces.

Projects matter for two practical reasons. First, scoped permissions: you can grant a team access at the project level and it applies to every workspace inside, present and future — far more maintainable than granting workspace-by-workspace. Second, scoped variable sets: a variable set can be applied to a project so that all of its workspaces share the same credentials or common settings automatically.

For the exam, keep the two organizing layers distinct: workspaces separate state and runs (one per environment per component), while projects group workspaces for ownership, access control, and shared configuration.

Every HCP Terraform workspace stores its state remotely, encrypted, and versioned — you can inspect previous state versions and see which run produced each one. State is locked automatically for the duration of every run, so two concurrent applies against the same workspace are impossible; there is nothing to configure, unlike DIY backends where locking support varies. Access to state follows workspace permissions, and workspaces can explicitly share their state outputs with other workspaces for cross-workspace consumption.

Variables are stored on the workspace in two kinds: Terraform variables (input variable values, equivalent to a .tfvars file) and environment variables (shell variables for the run environment — this is where provider credentials such as AWS_ACCESS_KEY_ID or ARM_CLIENT_SECRET usually go). Any variable can be marked sensitive: its value is write-only, never displayed again in the UI or API, and not revealed in run logs. This is how teams keep secrets off laptops entirely — engineers trigger runs, but the credentials only exist in the workspace.

Variable sets solve the reuse problem: define a collection of variables once (for example, cloud credentials for a shared account) and apply it to specific workspaces, to projects, or globally to every workspace in the organization. When the same variable is defined in multiple places, the more specific scope wins — a variable set on the workspace itself overrides one inherited from the project or organization.

Collaboration in HCP Terraform is built on three features. First, VCS integration: connect a workspace to a repository (GitHub, GitLab, Bitbucket, Azure DevOps) and the platform becomes the automation layer for a GitOps-style flow. Opening a pull request triggers a speculative plan whose result is posted to the PR as a status check, so reviewers see exactly what the change would do before merging; merging to the tracked branch triggers the real run. Speculative plans are plan-only and can never be applied.

Second, team-based access management. Users belong to an organization and are grouped into teams; teams are granted permissions on projects and workspaces. The fixed workspace permission sets are read (view runs and settings), plan (queue plans), write (approve and apply runs, edit variables), and admin (manage settings and team access) — with custom permissions available for finer control. Members of the built-in owners team manage the organization itself. This answers the governance question the CLI cannot: who is allowed to apply changes to production?

Third, the private registry. Each organization gets its own registry for sharing modules and providers internally, with the same versioned, documented experience as the public Terraform Registry. Private modules are referenced with a hostname-qualified source:

module "vpc" {
  source  = "app.terraform.io/acme-corp/vpc/aws"
  version = "2.1.0"
}

The private registry is how platform teams publish approved, reusable building blocks — including no-code modules that let non-Terraform users deploy curated infrastructure from the UI.

Governance features let an organization enforce rules on every run rather than trusting reviewers to catch violations. The centerpiece is Sentinel, HashiCorp's policy-as-code framework: policies are written as code, versioned, grouped into policy sets attached to workspaces, and evaluated automatically between the plan and apply phases of a run. A Sentinel policy can inspect the plan and fail the run if it violates a rule — for example, requiring specific tags on every resource, blocking 0.0.0.0/0 ingress rules, or restricting instance types.

Each Sentinel policy has one of three enforcement levels, a frequent exam question:

• Advisory — a failure is logged as a warning; the run proceeds.
• Soft mandatory — a failure blocks the run, but an authorized user can override it and continue.
• Hard mandatory — a failure blocks the run with no override possible.

HCP Terraform also supports Open Policy Agent (OPA) policies as an alternative policy framework. Run tasks extend governance to third-party tools: at defined stages of a run (such as post-plan), HCP Terraform calls an external service — a security scanner, a compliance checker — and the task's pass/fail result can be advisory or mandatory for the run.

Finally, cost estimation: for supported AWS, Azure, and Google Cloud resources, HCP Terraform estimates the monthly cost of the plan and the delta against current cost, shown in the run output before apply. Sentinel policies can read the cost estimate, enabling rules like "fail any run that increases monthly spend by more than 20 percent."