HCP Terraform and Terraform Enterprise

HCP Terraform is a hosted service that stores state, runs Terraform for you on disposable virtual machines, connects to version control, and adds governance (teams and permissions, policy enforcement, cost estimation, audit trails). The service was called Terraform Cloud until April 22, 2024, when HashiCorp renamed it to HCP Terraform. Most books, blog posts and error messages written before that date still say "Terraform Cloud", and a few identifiers kept the old names: the cloud block, the tfe provider prefix (for Terraform Enterprise, a name that goes back to Private Terraform Enterprise) and the hostname app.terraform.io. They are all the same product.

Terraform Enterprise is the self-managed distribution of the same application. The official overview describes it as a private instance of HCP Terraform with no resource limits and with additions such as audit logging and SAML single sign-on, and states that information about HCP Terraform generally applies to Terraform Enterprise unless it is marked otherwise. HashiCorp is now part of IBM, and the current pricing page lists the self-managed product as IBM Terraform Enterprise; the documentation on developer.hashicorp.com still uses "Terraform Enterprise".

Source: Terraform Enterprise Docs — Overview, HCP Terraform Docs — Overview

The rest of the page uses "the platform" for statements that are true of both, and names HCP Terraform or Terraform Enterprise when they differ.

Everything on the platform lives in a three-level hierarchy, and most mistakes come from putting a setting at the wrong level.

Source: HCP Terraform Docs — Organizations, HCP Terraform Docs — Manage projects, HCP Terraform Docs — Workspaces

An HCP Terraform workspace is not a CLI workspace. A CLI workspace is another instance of state inside the same working directory; an HCP Terraform workspace is a separate working directory with its own configuration source and settings, as the comparison table in Workspaces, Environments and Project Structure spells out. The official documentation also has a page, "Compare Stacks and workspaces", for the choice between a workspace per environment and one Stack with several deployments.

Access is granted to teams, never to individual users. A user who is in the organization but in no team can sign in and use nothing. Organization-level permissions (manage workspaces, manage policies, manage the private registry, manage agent pools, manage run tasks and so on) are separate from the project and workspace permissions that a team receives, and the project permission levels are read, write, maintain, admin and custom. Free-plan organizations have most features but not custom team permissions; see Pricing and the free tier.

A sensible layout for the Bookshelf scenario follows the blast-radius reasoning of the workspaces page: one organization for the company, one project per product (bookshelf), and inside it one workspace per layer and environment.

Source: HCP Terraform Docs — Workspace tags

Layers that change at different speeds get separate workspaces, and they exchange values through remote-state sharing, run triggers or tfe_outputs (see below), not through shared files.

A configuration uses the platform by adding a cloud block to the terraform block. It replaces a backend block (the two cannot coexist), it needs Terraform 1.1 or later, and like a backend it cannot refer to variables, locals or data source attributes.

Source: Terraform Docs — Connect to HCP Terraform

The arguments are:

A configuration that is shared by several workspaces uses tags and lets the operator pick a workspace:

Source: Terraform Docs — The terraform block, cloud

With tags, Terraform links the working directory to the existing workspaces that match, and terraform init prompts to create a workspace with those tags if none exists. The thing to remember is that these are HCP Terraform workspaces, not state files in a local directory.

A run is one plan, optionally followed by an apply, executed in a workspace. The platform has three ways to start one, and a workspace is bound to one of them by how its configuration arrives.

Source: HCP Terraform Docs — Run workflows

Where Terraform itself runs is a workspace setting, independent of how the run was started.

Source: HCP Terraform Docs — Workspace settings, execution mode

Changing the mode while a run is planned can make that run error on apply; the documented procedure is to disable auto-apply, lock the workspace, change the mode, then unlock and re-enable auto-apply. A workspace in local mode is also the migration step for a team that wants central state first and remote runs later.

Each workspace has variables of two categories: Terraform variables, which set the root module’s input variables (and, unlike environment variables, can be lists and maps written in HCL), and environment variables, which exist in the run’s process environment and carry provider credentials such as AWS_REGION. Both can be marked sensitive: the value becomes write-only in the interface and the API. It can still appear in logs and state in some cases, which is why the sensitive data page is the companion of this section.

A variable set is a named group of variables that can be applied to many workspaces, which is how one set of credentials or tags reaches many places without copy-paste.

Source: HCP Terraform Docs — Manage variables and variable sets

The language-level precedence rules (defaults, -var-file, TF_VAR_) are in Variables, Outputs and Locals; the platform adds its own layers below the command line.

The best credential is one that does not exist until it is needed. Dynamic provider credentials replace long-lived keys stored in workspace variables with short-lived credentials that the platform obtains for each run through workload identity (OIDC), the platform-side counterpart of the CI pattern described in CI/CD and Automation.

How it works, as documented:

The token’s sub claim has the form organization:<org>:project:<project>:workspace:<workspace>:run_phase:<plan|apply>, and aud is the audience for the target platform (aws.workload.identity for AWS, for instance, which can be changed). Further claims name the organization, project, workspace and run (terraform_organization_name, terraform_project_name, terraform_workspace_name, terraform_run_phase and others). A trust policy must check at least the audience and the organization name in sub; without that check, any HCP Terraform organization could assume the role.

Source: HCP Terraform Docs — Dynamic provider credentials, HCP Terraform Docs — Workload identity tokens

Every integration has the same three steps: establish trust between the platform and the cloud, create a role or identity with the permissions the workspace needs, and add environment variables to the workspace (or to a variable set that many workspaces share). The supported targets are Vault, AWS, Google Cloud, Azure, Kubernetes, HCP and Tencent Cloud, and every variable also exists with a TFC_DEFAULT_ prefix (shared defaults) and a _TAG suffix (named provider aliases).

Source: HCP Terraform Docs — AWS configuration, HCP Terraform Docs — Azure configuration, HCP Terraform Docs — Google Cloud configuration, HCP Terraform Docs — Vault configuration

The AWS trust policy is the part people get wrong, so here is its documented shape, with placeholders:

Source: HCP Terraform Docs — AWS configuration

The condition keys use the hostname without https://. To use one role for both phases, the documentation switches the sub comparison to StringLike and ends the value with run_phase:*; the safer layout is separate plan and apply roles, with a read-only plan role. The cloud side of this trust (the identity provider, the roles, the least-privilege reasoning) is described in AWS Identity and Access Management, Azure Identity and Access and Google Cloud Identity and Access.

The provider block of a configuration that uses dynamic credentials contains no secrets at all:

Source: HCP Terraform Docs — AWS configuration

The same OIDC idea appears on the other side of the pipeline: a CI job outside the platform presents its own token to the cloud, and the platform presents its token for the runs it executes. Both remove the static key that the earlier generation of tutorials stored in a CI secret.

The private registry works like the public Terraform Registry but is visible only to the organization’s members. It can host private modules and private providers, and it can synchronise selected public providers and modules so that the organization marks which ones it recommends.

Source: HCP Terraform Docs — Private registry, HCP Terraform Docs — Publish private modules

No-code provisioning lets people deploy a module’s resources without writing Terraform: a platform team marks a registry module "no-code ready", and a consumer picks it from the registry, answers a form and gets a new workspace. It requires the Standard or Premium edition, and a few rules shape the module:

Source: HCP Terraform Docs — Designing no-code ready modules

A Bookshelf platform team might publish one no-code module called bookshelf-service that wraps the container, load balancer and database pattern, so that a new service team gets a workspace with the right network, tags and policies without learning HCL. When that team later needs more control, the module’s source is still the ordinary module that they can read and call from code.

A run task calls an external service at a defined point of the run, passes it context, and lets the answer pass or stop the run. Typical tasks are security scanners, cost tools, ticket checks and internal approval systems.

Source: HCP Terraform Docs — Run tasks, HCP Terraform Docs — Run states and stages

Run tasks and policies overlap in purpose. Use a policy (Sentinel, OPA or Terraform Policy) for a rule that can be written over the plan; use a run task for a decision that needs an outside system or a third-party product.

Infrastructure changes behind Terraform’s back, and a Terraform that is run only on pull requests will not notice. Health assessments are scheduled checks that run without a pull request or a person.

Source: HCP Terraform Docs — Health

The explorer answers questions about the whole organization from a single query interface. It has four views (workspaces, modules, providers and Terraform versions), pre-built queries (top module versions, workspaces without a VCS connection, workspaces with failed checks, drifted workspaces, the most recently updated), a query builder whose conditions combine with AND, and saved views. It needs the organization owner role, or the "View all workspaces" permission or higher.

A change request turns an explorer finding into a task on the affected workspaces: an administrator selects the workspaces from a query result and writes a message, for instance "upgrade the network module to 2.x" because an old version was revoked. The request stays on each workspace’s backlog until the team archives it as done, and a team notification can alert the workspace’s owners. Change requests are available in the Standard and Premium editions.

Source: HCP Terraform Docs — Explorer, HCP Terraform Docs — Change requests

Together with the private registry, these features are the platform’s answer to the module-upgrade problem described in Module Development and Publishing: the registry publishes the new version, the explorer lists the workspaces that still use the old one, and change requests ask their owners to move.

The run stages above include the governance gates; this page only locates them. Sentinel, OPA and Terraform Policy are configured as policy sets attached to workspaces, projects or Stacks, with the enforcement levels and examples in Policy as Code. The tfe_policy_set documentation names the same three frameworks (Sentinel, Open Policy Agent and Terraform policy, tfpolicy) and notes that on Terraform Enterprise, Terraform policy requires v2.1.0 or later. According to the changelog, HCP Terraform started evaluating Terraform policy (beta) on July 16, 2026 and policies against Stacks on September 10, 2026. Free organizations have one policy set of up to five policies.

Cost estimation shows the estimated monthly cost change before the apply and can feed Sentinel policies; it is part of the Standard and Premium editions. Notifications send run events per workspace to Slack or any webhook-capable service, and the Premium edition adds audit logging.

Source: HCP Terraform Docs — Policy enforcement, HCP Terraform Docs — Overview

The platform is billed by managed resources (the documentation also says "resources under management"), not by user.

The plans, as the overview page and the pricing page showed them on October 23, 2026:

Source: HCP Terraform Docs — Overview, HashiCorp — Pricing

Workspaces, Stacks and projects are unlimited on every plan, and the API rate limit is 30 requests per minute on every plan. Additional concurrency can be bought on Standard and Premium. The self-managed edition has no resource limit and is priced by contract.

Terraform Enterprise (TFE) is the same application packaged for your own infrastructure. It exists for organizations whose rules prevent a hosted service: air-gapped or regulated networks, strict data residency, or an integration with internal identity and storage that the hosted service cannot reach. In exchange you operate it.

Almost everything above is available through the API, and the hashicorp/tfe provider exposes it as resources, which is the way to avoid a platform configured by clicking. One provider covers HCP Terraform and Terraform Enterprise. It is at version zero, so the documentation recommends constraining the minor version (~> 0.82.0 at the time of writing), and since provider v0.70.0 it requires Terraform 1.0 or later.

The provider takes a hostname (default app.terraform.io, or TFE_HOSTNAME), a token (or TFE_TOKEN, or credentials from terraform login) and a default organization (or TFE_ORGANIZATION). To manage the full set of resources the token should be a user token of a member of the owners team; an organization or team token limits what can be managed and cannot manage resources across organizations. Mark the token variable sensitive, and never write it in the configuration.

The Bookshelf platform from the layout above, as code:

Source: Terraform Registry — tfe provider, Terraform Registry — tfe_project, Terraform Registry — tfe_workspace, Terraform Registry — tfe_workspace_settings

Two details of that example come from the provider documentation. The execution settings (execution_mode, agent_pool_id) belong to tfe_workspace_settings; the same arguments on tfe_workspace are deprecated, and the documentation warns against managing the same property on both resources because it causes permanent drift. And tfe_workspace defaults queue_all_runs to true, which differs from the API’s default of false, so a freshly created VCS workspace starts planning immediately.

The credentials, shared across the workspaces through a variable set:

Source: Terraform Registry — tfe_variable_set, Terraform Registry — tfe_project_variable_set, Terraform Registry — tfe_variable

tfe_variable_set has global, priority, parent_project_id and description; attach it with tfe_workspace_variable_set or tfe_project_variable_set (the workspace_ids argument of the set itself is deprecated in favour of the attachment resources). tfe_variable takes category (terraform or env), key, value, hcl, sensitive and exactly one of workspace_id or variable_set_id. For a value that must not enter the provider’s own state, the resource offers the write-only pair value_wo and value_wo_version (Terraform 1.11 or later), which connects this page to Sensitive Data, Ephemeral Values and Write-Only Arguments.

Teams, agents, run tasks, the registry and the no-code module follow the same pattern:

Source: Terraform Registry — tfe_team_project_access, Terraform Registry — tfe_agent_pool, Terraform Registry — tfe_organization_run_task, Terraform Registry — tfe_workspace_run_task, Terraform Registry — tfe_run_trigger

The fragment assumes a scanner_hmac_key variable and a tfe_workspace.data_dev resource declared elsewhere in the same configuration; it is a sketch of the argument shapes and not a deployable root module. tfe_agent_token exposes the generated token as a sensitive attribute, which ends up in state: use a secret store to hand it to the agents, and treat the state of this configuration as a secret.

The rest of the resource catalogue, in groups:

Source: Terraform Registry — tfe provider

Data sources complement the resources. tfe_outputs reads another workspace’s outputs, which is the platform-native alternative to terraform_remote_state (see the data-sharing section of Backends and Remote State), and the producing workspace must allow the consumer to read its state (remote state sharing).

HCP Terraform is one of several products that wrap Terraform (and, in some cases, OpenTofu) with remote state, runs, policies and drift detection. The commonly named ones are Spacelift, env0, Scalr, Atlantis (open source, driven by pull request comments and self-hosted), Digger and Terrateam (which run in your existing CI), Harness, Octopus Deploy and Terrakube (open source). They differ in how much they own: some replace the CI system and the state backend, some only orchestrate a CI runner you already have, and some are a thin pull-request bot. All of them need the same decisions as this page: where state lives, who approves, how credentials are issued, how a policy stops a change. Evaluate them with the checklist in Choosing between the platform and your own pipeline and with your own constraints (OpenTofu support, self-hosting, licensing, price per run or per resource), and read each product’s own documentation, because pricing and feature sets change and this guide has not compared them. The general CI pipeline alternative, with GitHub Actions, GitLab CI and Atlantis, is in CI/CD and Automation.

A reasonable path for the Bookshelf is to start with the CLI and a remote backend, move to a pipeline when more than one person applies, and adopt the platform when the governance features (policy, drift detection, the registry, dynamic credentials, per-team permissions) are worth more than the per-resource price. Because the cloud block can be replaced by a backend block by migrating state, the decision is reversible.

Source: HCP Terraform Docs — Changelog, Terraform Enterprise Docs — Releases, hashicorp/terraform-provider-tfe — Releases

The provider version row records the release date and the documentation state of that version; the individual resource changes are listed in the provider’s changelog.

Both reference books call the product Terraform Cloud, which was correct when they were written and has been wrong since April 22, 2024. The pricing and free-tier figures in the continuous-delivery chapter of the more recent book are outdated for the reasons in Pricing and the free tier: the limit is now on managed resources (500 on the enhanced Free tier), the legacy member-based Free plan ended on March 31, 2026, and the paid plans are Essentials, Standard and Premium with per-resource pricing. Where a book shows static cloud keys stored in workspace variables, the current approach is dynamic provider credentials. And the monthly vYYYYMM-N naming of Terraform Enterprise releases has been replaced by semantic versions.