Cheat Sheet 8: HCP Terraform
Editions: Community (free CLI, DIY) · HCP Terraform (SaaS, formerly Terraform Cloud) · Terraform Enterprise (self-hosted HCP Terraform)
Hierarchy: Organization → Project → Workspace. There's a Default Project. Team permissions apply at organization, project, or workspace level. The owners team controls the organization.
HCP Terraform workspace = state with version history and rollback, variables, run history, settings (Terraform version, execution mode, working directory, auto-apply, VCS), permissions, and policies. It isn't a CLI workspace, which only provides an extra state in one backend.
Connecting
terraform login [hostname]saves a token to~/.terraform.d/credentials.tfrc.json. In CI, useTF_TOKEN_app_terraform_io.terraform logoutremoves it.- The
cloud { organization = "…" workspaces { name = "…" } | { tags = [...] } }block replacesbackend, so you can't have both.hostnamedefaults toapp.terraform.io. The legacy alternative isbackend "remote". initmigrates existing state and creates the workspace if needed. The env varsTF_CLOUD_ORGANIZATION,TF_CLOUD_HOSTNAME, andTF_WORKSPACEcan supply settings.
Run workflows
| Workflow | Start | Notes |
|---|---|---|
| VCS-driven | push → plan · PR → speculative plan (never applied) | Apply after Confirm & Apply or auto-apply. CLI apply is blocked. |
| CLI-driven | Local plan or apply uploads the configuration and streams the remote run |
CLI plan produces a speculative plan |
| API-driven | Upload a configuration version tarball and create a run | Custom pipelines |
Execution modes: Remote (default; HCP workers, which can't see local files, environment, or private networks) · Local (your machine; HCP stores state only, and workspace variables aren't used) · Agent (self-hosted agents in your network)
Run pipeline: Plan → Cost estimation → Policy check → Confirm → Apply. Run tasks hook in at pre-plan, post-plan, pre-apply, and post-apply.
Variables
- Two categories: Terraform variables and environment variables. The HCL checkbox allows complex values. Sensitive = write-only, never readable again.
- Variable sets apply to the organization, projects, or workspaces. Workspace variables override a set with the same name unless the set is marked priority.
- Prefer dynamic provider credentials (OIDC, short-lived) for AWS, Azure, GCP, Vault, and Kubernetes.
Governance and collaboration
- Teams: Read · Plan · Write · Admin at workspace level, plus project-level and custom permissions.
- Private registry: modules and providers. Source
app.terraform.io/ORG/NAME/PROVIDERwithversion. Publish from VCS. No-code modules. - Policies: Sentinel or OPA, in policy sets. Run after plan, before apply.
- Sentinel: advisory · soft-mandatory (overridable) · hard-mandatory
- OPA: advisory · mandatory
- Run tasks: third-party checks, advisory or mandatory.
- Health assessments: drift detection plus continuous validation (
checkblocks and conditions). They report problems and don't fix them. - Also: cost estimation · state versions and rollback · notifications · workspace locking · run triggers ·
tfe_outputsfor sharing outputs · audit and SSO (check your plan).
Module 8 self-check
Module 8 self-check.
- Coverage: 8a (lessons 8.3–8.4, Labs 8A and 8B, Q1, Q5, Q6, Q10), 8b (lesson 8.5, Lab 8A step 10, Lab 8B steps 6–7, Q8–Q9), 8c (lesson 8.2, Lab 8A step 5, Q3–Q4), and 8d (lesson 8.3, Lab 8A steps 2–4 and 9, Q2, Q7).
- HCL: the
cloudblock (withorganizationandworkspacesusingnameortags) and thetfe_outputsdata source follow documented syntax. Lab configurations use providers that run on HCP workers. - Flagged uncertainty:
- Tier availability of agents, policies, run tasks, health assessments, no-code modules, audit, and SSO is marked "check your plan."
- The full HCP Terraform variable precedence order (especially
*.auto.tfvarsvs. workspace variables) is deliberately not asserted beyond workspace-over-set and priority sets. - Map-style
tagsin thecloudblock (1.10+) is mentioned but not used. - UI menu paths reflect the current layout and may move.
- Answers: rechecked against documented HCP Terraform behavior: speculative plans, the VCS apply restriction, execution modes, Sentinel enforcement levels, and write-only sensitive variables.