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 three steps: authenticate the CLI, add a cloud block to the configuration, and run terraform init. For interactive use, 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. terraform init is mandatory after adding or changing a cloud (or backend) block: until it runs, terraform plan and terraform apply stop with an error saying the working directory needs to be initialized. If you have existing local state, init offers to migrate it into the HCP Terraform workspace.

Non-interactive authentication and workspace selection

In CI there is no browser, so terraform login does not fit. Instead supply the token through an environment variable named TF_TOKEN_ plus the hostname, with dots written as underscores — TF_TOKEN_app_terraform_io for HCP Terraform — holding a team or user API token kept as a pipeline secret. The cloud block also accepts a token argument, but writing a token into configuration commits a secret to the repository, so HashiCorp recommends against it. Other environment variables fill in the block without editing the configuration: TF_CLOUD_ORGANIZATION and TF_CLOUD_HOSTNAME, and TF_WORKSPACE, which selects the workspace to use — handy when the block selects workspaces by tags and the pipeline must target one of them.

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 runs: a plan, any policy checks, run tasks and cost estimation, then an apply. In the default remote execution mode these execute on HashiCorp-managed run environments instead of your machine, using variables and credentials stored in the workspace. When you run terraform plan or terraform apply in a directory with a cloud block, the CLI uploads the configuration, the run executes remotely, and the output streams back to your terminal. Applies can be confirmed from the terminal or from the web UI.

Three run workflows

CLI runs against a VCS-connected workspace, and saved plans

A workspace connected to a repository treats the repository as the source of truth. From a laptop with a cloud block pointing at it, terraform plan still works — it runs remotely as a speculative plan (plan-only, never applicable) and streams its output — but terraform apply is refused; changes must be merged through the repository. On CLI-driven workspaces, a plain terraform plan is also speculative: it previews, and a later terraform apply makes a fresh plan. To review a plan now and apply exactly that plan later, use a saved plan (Terraform 1.6 and later): terraform plan -out=FILE creates a saved plan run in the workspace, and terraform apply FILE applies that run without planning again.

Execution modes

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 because settings scoped to a project reach every workspace inside it, present and future. You can scope team access, variable sets and policy sets to a project instead of maintaining them workspace by workspace.

Project roles

Team access to a project uses fixed roles (custom permissions are also available):

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. Pick the least-privileged role that covers the task.

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; sharing state with other workspaces is covered in the next section.

Variables are stored on the workspace in two categories: Terraform variables (values for the configuration's input variables, equivalent to a .tfvars file) and environment variables (shell variables set in the run environment). Provider credentials such as AWS_ACCESS_KEY_ID or ARM_CLIENT_SECRET belong in the environment category: the provider reads them from the environment, so storing them as Terraform variables does nothing unless the configuration declares matching input variables.

Any variable can be marked sensitive. That makes it write-only for people: the value is never displayed again in the UI or returned by the API, but it is still passed in full to every run. Sensitive is not a log scrubber — if the configuration routes the value into an output or a resource argument, Terraform can still show it in run output and it is stored in state. This is how teams keep secrets off laptops: engineers trigger runs, but the credentials exist only in the workspace.

Variable sets solve the reuse problem: define a collection of variables once (for example, shared cloud credentials or proxy settings) and apply it to specific workspaces, to projects, or globally to every workspace in the organization. Changing the set updates every workspace that uses it.

Which value wins

When the same variable key is set in several places, HCP Terraform applies this order, highest first:

1. Priority variable sets — a set marked priority overrides every other value for the same key, including -var and -var-file values given on the CLI.
2. Values passed on the command line in a CLI-driven run (-var, -var-file).
3. Local environment variables prefixed with TF_VAR_ in a CLI-driven run.
4. Workspace-specific variables.
5. Variable sets (not priority) — a set applied to the workspace directly beats a project-scoped set, which beats a global set.
6. *.auto.tfvars files, then terraform.tfvars, from the configuration.

So workspace-specific variables override variable sets; priority sets are the tool an organization uses when a value must not be overridden anywhere below it.

Workspaces exchange data through outputs and coordinate through run triggers. Splitting infrastructure across workspaces (network, then applications) means a downstream workspace often needs an upstream output such as a VPC ID, and should re-run when that upstream changes.

Reading another workspace's outputs

By default a new workspace shares its state with no other workspace (an organization can change that default). The workspace's remote state sharing setting lists who may read it: specific workspaces, or every workspace in the organization. Two ways to read outputs:

Run triggers

A run trigger connects workspaces so that a successful apply in a source workspace automatically queues a run in a dependent workspace. It is configured on the downstream workspace, which can name up to 20 source workspaces. Triggered runs follow their own setting: the workspace's main auto-apply option covers runs from the UI, API and VCS, while a separate Auto-apply run triggers option decides whether runs queued by a run trigger apply without confirmation. With that option off, triggered runs stop at the plan and wait for someone to confirm.

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; speculative plans are plan-only and can never be applied. Merging to the tracked branch queues a standard plan-and-apply run.

Whether that run applies on its own is the workspace's auto-apply setting. With auto-apply off (the default), every plan that has changes stops and waits for a user with permission to confirm the apply — a built-in human review step. With auto-apply on, a successful plan applies without confirmation. (Runs queued by run triggers use the separate Auto-apply run triggers setting described above.)

Second, team-based access management. Users belong to an organization and are grouped into teams; teams are granted roles on projects (see Projects above) and permission sets on individual workspaces. The fixed workspace permission sets are:

• Read — view runs, state versions and settings.
• Plan — everything in read, plus queue plans; cannot apply, so it cannot change infrastructure.
• Write — plan plus approve and apply runs, lock the workspace and edit variables.
• Admin — write plus manage workspace settings, team access and deletion.

Custom permissions are available for finer control, and 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 of the form <HOSTNAME>/<ORGANIZATION>/<NAME>/<PROVIDER>:

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. HCP Terraform supports two policy-as-code frameworks: Sentinel, HashiCorp's own language, and Open Policy Agent (OPA), whose policies are written in Rego. Policies are evaluated automatically after the plan and before the apply, and can fail a run that violates a rule — for example, requiring tags on every resource, blocking 0.0.0.0/0 ingress or restricting instance types.

Policy sets

Policies are grouped into policy sets, and the set decides where they apply: globally (every workspace in the organization, including ones created later), to specific projects, to specific workspaces, or to workspaces carrying specific tags. A global set can exclude particular projects, workspaces or tagged workspaces, which avoids per-workspace upkeep. Each policy set holds policies for one framework only — Sentinel or OPA — so a team using both creates separate sets; several policy sets can apply to the same workspace.

Enforcement levels

Run tasks

Run tasks extend governance to third-party tools: HCP Terraform calls an external service — a security scanner, a compliance checker — at a chosen stage of the run and waits for its pass/fail result. The four stages are pre-plan (before Terraform builds the plan, so the service can check the configuration files and stop the run early), post-plan (the service can inspect the plan), pre-apply (just before applying) and post-apply (after resources change). Each run task attached to a workspace has an enforcement level: advisory (a failure is a warning) or mandatory (a failure stops the run).

Cost estimation

Cost estimation is a built-in run phase after the plan: for supported AWS, Azure and Google Cloud resources, HCP Terraform estimates the monthly cost of the planned infrastructure and the delta against current cost, shown in the run before apply. Sentinel policies can read the cost estimate — enabling rules like "fail any run that raises monthly spend by more than 20 percent" — but only in legacy policy checks (Sentinel only), not in the newer policy evaluations (Sentinel and OPA), which cannot read cost estimates.