HCP Terraform
Introduction
This lesson covers the HCP Terraform area of the Terraform Associate (004) exam, objectives 8a to 8d. The area holds four of the 37 objectives, about 11% of this course's mock questions (HashiCorp does not publish domain weights; that proportion is an OnLevelUp choice). The exam lasts one hour, tests Terraform 1.12, and mixes true/false, multiple-choice and multiple-answer questions.
The Terraform CLI is enough for one engineer. A company with dozens of engineers, several environments and compliance rules needs more: shared state with history, remote execution, access control, policy checks, a private module registry and an audit trail. HCP Terraform (formerly Terraform Cloud) is HashiCorp's managed service that provides these. Terraform Enterprise is the self-hosted version of the same product.
After this lesson you will be able to explain how HCP Terraform runs Terraform for you, describe its collaboration and governance features, organize work with workspaces and projects, and connect the CLI and version control to it.
Learning objectives
- Describe how HCP Terraform creates infrastructure: remote runs, state, variables and credentials.
- Compare the VCS-driven, CLI-driven and API-driven workflows.
- Describe collaboration and governance: teams and permissions, policies (Sentinel and OPA), run tasks, private registry, audit trail, cost estimation.
- Organize resources with organizations, projects and workspaces, and use variable sets.
- Configure the
cloudblock and authenticate withterraform login.
8a. Using HCP Terraform to create infrastructure
HCP Terraform's central idea is remote execution: a run (plan and apply) happens on HashiCorp-managed workers instead of on a laptop or a CI agent. Every run is recorded.
What HCP Terraform stores and does
- State: each workspace has its own state with a version history, encryption at rest and locking handled for you. There is no backend to build or secure.
- Variables and credentials: Terraform variables and environment variables (such as cloud credentials) are stored in the workspace or in variable sets. Values can be marked sensitive, in which case they are write-only in the UI.
- Runs: each run goes through phases: pending, plan, (optional) cost estimation, policy checks, run tasks, confirmation, apply.
- Run history and logs: who started the run, what changed, and the logs.
- Private registry: a place for your organization's modules and providers.
Run types
| Run type | What it does |
|---|---|
| Plan and apply (standard) | Plans, waits for approval (or auto-applies), then applies |
| Speculative plan | Plan-only, to preview changes, for example on a pull request; it can never be applied |
| Refresh-only | Updates state to match reality |
| Destroy | Plans and applies a destroy |
By default, a workspace requires a human to confirm the apply. Turning on auto-apply applies automatically after a successful plan (and passed policies), which is common for development workspaces but rarely for production.
The three workflows
| Workflow | How runs start | Typical use |
|---|---|---|
| VCS-driven | A push or merge to a connected repository branch triggers a run; pull requests trigger speculative plans | GitOps; most common for teams |
| CLI-driven | A user runs terraform plan / terraform apply locally, which execute remotely in HCP Terraform |
Developers who want remote state and execution but a local command line |
| API-driven | Another tool calls the HCP Terraform API (or the tfe provider) to upload configuration and start runs |
Custom pipelines and integrations |
For a workspace in the VCS workflow, the configuration comes from the repository; for the CLI workflow, the CLI uploads your working directory; for the API workflow, your tool uploads a configuration version.
Execution mode
A workspace can run remotely on HCP Terraform workers (default), locally on your machine while still storing state in HCP Terraform, or through agents, small programs you deploy inside private networks so that HCP Terraform can manage infrastructure that is not reachable from the internet (for example an on-premises datacenter).
Worked example: first remote run from the CLI
Scenario. Nadia's team wants to stop storing state on S3 manually. They create an organization acme, a workspace network-prod, and want to run terraform apply from the laptop but have it execute in HCP Terraform with AWS credentials stored there.
Step by step.
- In the workspace, add the environment variables
AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEY, marked sensitive (a dynamic credentials integration is even better because it avoids long-lived secrets). - Add the
cloudblock to the configuration (see 8d). - Run
terraform loginonce, which stores an API token. - Run
terraform init. If a state already exists in another backend, Terraform offers to migrate it. - Run
terraform apply. The CLI streams the remote plan, the confirmation prompt appears, and the apply runs on HCP Terraform.
Why not just a local backend. Local state has no sharing and no locking across the team. Why not S3: it works, but you then build and secure everything else (queueing, policy, UI, history) yourself.
8b. Collaboration and governance
Teams and permissions
Users belong to teams; teams get permissions on projects and workspaces (read, plan, write, admin and custom permission sets). Each person works with the least privilege they need, for instance: developers can plan, only the platform team can apply to production.
Policy as code: Sentinel and OPA
Policies are rules evaluated after the plan and before the apply. They are grouped into policy sets, which are attached to workspaces or projects (or the whole organization).
- Sentinel: HashiCorp's policy language.
- Open Policy Agent (OPA): policies written in Rego.
For Sentinel, each policy has an enforcement level:
| Level | Behaviour on failure |
|---|---|
| Advisory | The run continues; a warning is recorded |
| Soft mandatory | The run stops; a user with override permission may continue |
| Hard mandatory | The run stops; nobody can override it |
Example policy goals: "no security group may open port 22 to 0.0.0.0/0", "all resources must have an Owner tag", "instances are limited to approved types".
Run tasks
Run tasks call external services between plan and apply, passing the plan details. The service replies pass or fail. Examples include security scanners, cost tools and ticketing approvals. Unlike policy sets, a run task applies only to the workspaces it is associated with.
Cost estimation
For supported clouds, HCP Terraform shows an estimate of the monthly cost change that a plan would introduce, which can be used in policy checks (for instance "reject any run that adds more than 500 USD per month").
Private registry
The private registry hosts your organization's modules and providers, with versions and documentation. Teams reference modules with the address app.terraform.io/<ORG>/<NAME>/<PROVIDER> (or the hostname of a Terraform Enterprise installation). It supports publishing from VCS tags and, for modules, no-code provisioning, where non-experts deploy approved infrastructure from a form.
Other collaboration features
- Audit trails list who did what in the organization.
- Run triggers connect workspaces: when workspace A applies successfully, workspace B (which depends on its outputs) can start a run automatically.
- Notifications send run events to Slack, Teams or e-mail via webhooks.
- Health assessments detect drift and check continuously whether infrastructure matches the configuration.
- Sharing outputs between workspaces is possible using the
tfe_outputsdata source or remote state sharing, with explicit consent.
Comparison: governance tools
| Tool | Purpose | Scope |
|---|---|---|
| Teams and permissions | Who can do what | Organization, project, workspace |
| Sentinel / OPA policy sets | Reject non-compliant plans | Organization, project or selected workspaces |
| Run tasks | Call third-party checks | Associated workspaces only |
| Cost estimation | Show or limit spend changes | Workspace runs |
| Variable sets | Distribute credentials and values | Organization or project |
| Audit trail | Record actions | Organization |
Worked example: enforcing a tagging standard
Scenario. The compliance team requires every cloud resource to have an Owner tag. Some teams already violate this. Management wants new violations blocked immediately for production but only reported for development.
Step by step.
- Write one policy "require Owner tag" (Sentinel or OPA).
- Create two policy sets:
tagging-prodwith enforcement hard mandatory attached to theproductionproject, andtagging-devwith advisory attached to thedevelopmentproject. - In production, a run with untagged resources fails at the policy check and cannot be applied; in development, the run shows a warning.
Why not the alternatives. A run task would need to be associated workspace by workspace. A team convention in a wiki is not enforced. A Sentinel rule at the organization level with hard mandatory would also block development, which management did not want.
8c. Organizing workspaces and projects
The hierarchy
Organization
└── Project (a group of workspaces)
└── Workspace (state + variables + runs for one configuration)- Organization: the top-level container with its teams, registry, policies and billing.
- Project: groups workspaces so that you can apply permissions, policy sets and variable sets at once (for example
payments,data-platform). Every workspace belongs to exactly one project; new workspaces go to the Default Project unless you choose another. - Workspace: holds the state, variables, run history and settings for a single configuration. In HCP Terraform a workspace is a unit of infrastructure; each environment (dev, staging, prod) is typically its own workspace.
HCP Terraform workspaces vs CLI workspaces
The CLI also has terraform workspace commands, which create multiple states for one configuration and one backend. HCP Terraform workspaces are broader: each has its own variables, permissions, VCS settings and run history, so they behave like separate working directories. When the cloud block is used with tags, the CLI workspace names map to HCP Terraform workspaces.
| Aspect | CLI workspace (local/remote backend) | HCP Terraform workspace |
|---|---|---|
| Contains | A state | State, variables, settings, permissions, run history |
| Access control | Backend-level only | Team permissions per workspace |
| Variables | Same files for all | Own variables per workspace |
| Typical use | Short-lived copies of one configuration | One environment or component |
Variable sets
A variable set is a reusable collection of variables, either Terraform variables or environment variables, that you apply to many workspaces. Examples: cloud credentials, a region default, a shared tag map.
- Scope: apply to the whole organization, to chosen projects, or to selected workspaces.
- A workspace variable with the same name and category overrides a variable set value (more specific wins);
-varon the CLI overrides both in a CLI-driven run. - Variables can be marked sensitive.
Worked example: structuring for three teams
Scenario. A company has three product teams. Each has dev and prod environments for network, database and application components. Cloud credentials are shared per environment.
Solution.
- One organization
acme. - Three projects:
team-a,team-b,team-c, each giving the team permissions on its workspaces. - Workspaces named by component and environment:
network-dev,network-prod,db-dev,db-prod, and so on. - Two variable sets with credentials:
aws-dev(applied to workspaces tagged dev) andaws-prod, so credentials are rotated in one place. - Run triggers:
app-prodstarts afterdb-prodapplies.
8d. Configuring HCP Terraform integration
The cloud block
terraform {
cloud {
organization = "acme"
workspaces {
name = "network-prod"
}
}
}Instead of name, you can select several workspaces with tags, or a project:
terraform {
cloud {
organization = "acme"
workspaces {
project = "team-a"
tags = ["app:web"]
}
}
}Rules:
- The
cloudblock lives in theterraformblock and cannot be combined with abackendblock. Use one or the other. - The
cloudblock is the recommended way; the olderremotebackend is superseded. - Values must be literal (as with backends); environment variables such as
TF_CLOUD_ORGANIZATIONandTF_WORKSPACEcan supply them. - To point to a self-hosted Terraform Enterprise server, add
hostname = "tfe.example.com".
Authentication
terraform login opens a browser to create a user API token and stores it in credentials.tfrc.json in the Terraform CLI configuration directory. In CI you can supply a token with the TF_TOKEN_app_terraform_io environment variable or a credentials block in the CLI configuration file. Token types: user, team and organization tokens, with decreasing breadth of ownership by a person.
Connecting version control
A VCS-driven workspace requires a VCS provider connection (GitHub, GitLab, Bitbucket, Azure DevOps), which an organization owner sets up with OAuth or a GitHub App. In the workspace you then choose the repository, branch, working directory and trigger patterns. Behaviour:
- A merge or push to the tracked branch starts a plan.
- A pull request starts a speculative plan, and the result is posted back to the pull request as a status check.
- You can restrict triggering to certain paths with trigger patterns, which suits monorepos.
Migrating existing state
If a configuration already uses a different backend, add the cloud block and run terraform init. Terraform recognises the change and asks whether to copy the existing state to HCP Terraform. After the migration, runs are remote and the old backend is no longer used.
Dynamic provider credentials
Rather than store long-lived cloud keys, HCP Terraform can use OIDC-based dynamic credentials: each run requests short-lived credentials from AWS, Azure, GCP or Vault using a trust relationship with HCP Terraform. This reduces risk because there is no secret to leak or rotate.
Comparison: CLI vs VCS vs API integration
| Need | Best fit |
|---|---|
| Review infrastructure changes like code, with PR plans | VCS-driven |
| Run commands from a developer laptop with remote state and policy | CLI-driven (cloud block) |
| Integrate with a custom portal or CI orchestrator | API-driven |
| Reach a private network | Agents with remote execution mode "agent" |
Common pitfalls and exam tips
- Exam tip: the
cloudblock and thebackendblock cannot coexist in one configuration. - Exam tip: a speculative plan cannot be applied.
- Exam tip: policies run after the plan and before the apply. Sentinel enforcement levels are advisory, soft mandatory and hard mandatory; only soft mandatory can be overridden by authorised users.
- Pitfall: storing long-lived cloud keys as non-sensitive variables. Mark them sensitive or use dynamic credentials.
- Pitfall: confusing CLI workspaces with HCP Terraform workspaces.
- Pitfall: enabling auto-apply on production without policy checks.
- Exam tip: every workspace belongs to exactly one project.
- Exam tip: HCP Terraform keeps state versions and locks state automatically.
- Exam tip: run triggers chain workspaces; variable sets share variables; run tasks call external tools.
Mini case study
Situation. A bank's platform team moves Terraform to HCP Terraform. Requirements: developers can preview changes on pull requests but cannot apply to production; no plan that opens SSH to the internet may be applied anywhere; the security scanner Orca must scan every production plan; AWS credentials must not be stored long-term.
Questions. Which features address each requirement?
Answer.
- VCS-driven workflow: pull requests trigger speculative plans, which cannot be applied. Team permissions: developers get plan access on production, only the release team has apply permission.
- A hard mandatory policy (Sentinel or OPA) checking security group rules, attached at the organization level.
- A run task integrated with the scanner, associated with the production workspaces.
- Dynamic provider credentials with OIDC, so every run gets short-lived AWS credentials.
Key terms
- HCP Terraform: HashiCorp's managed service for remote runs, state, policy and collaboration.
- Workspace: state, variables and runs for one configuration.
- Project: group of workspaces for permissions and shared policy.
- Variable set: reusable variables applied to many workspaces.
- Speculative plan: plan-only run that cannot be applied.
- Policy set: group of Sentinel or OPA policies.
- Run task: external check between plan and apply.
cloudblock: connects a configuration to HCP Terraform.
Summary checklist
- I can describe remote execution, state, variables and run phases.
- I can compare VCS-driven, CLI-driven and API-driven workflows.
- I can explain teams, policies, run tasks, cost estimation and the private registry.
- I know the organization, project and workspace hierarchy and what variable sets do.
- I can write a
cloudblock and know it excludes abackendblock. - I know
terraform loginstores a token and VCS connections are set at the organization level.
Official sources
- https://developer.hashicorp.com/terraform/cloud-docs (opens in a new tab)
- https://developer.hashicorp.com/terraform/cloud-docs/workspaces (opens in a new tab)
- https://developer.hashicorp.com/terraform/cloud-docs/projects/manage (opens in a new tab)
- https://developer.hashicorp.com/terraform/cloud-docs/policy-enforcement (opens in a new tab)
- https://developer.hashicorp.com/terraform/cli/cloud/settings (opens in a new tab)
- https://developer.hashicorp.com/terraform/tutorials/certification-004/associate-review-004 (opens in a new tab)
