HCP Terraform Collaboration and Governance

Local Terraform on one laptop does not need governance features. Once several people share state, modules, and run history in HCP Terraform, you need answers to different questions:

• Who may apply changes, and who may only plan?
• Which planned changes are allowed by organization policy?
• Where do internal modules and providers live?
• Does production still match the code?

HCP Terraform groups those controls around the organization:

Organization
   │
   ├── Teams and permissions
   ├── Projects / workspaces
   ├── Variable sets
   ├── Policy sets
   ├── Private registry
   ├── Run tasks
   └── Health / drift

This lesson maps to objective 8b of the Terraform Associate (004) exam. It stays conceptual with small demonstrations you can run from ~/terraform-labs/hcp-terraform-governance/ against the golinuxcloud-lab organization. If you have not connected the CLI yet, start with the HCP Terraform tutorial. For workspace layout and variable precedence, see HCP Terraform workspaces and projects and HCP Terraform variables.

Teams and permissions

HCP Terraform does not assign permissions to individual users one workspace at a time in large deployments. You add people to teams and grant teams permissions at one or more scopes. Effective access is additive: the highest permission a team holds at any scope wins for that resource.

Organization  ──►  broad roles (manage all workspaces, manage policies, …)
     │
Project       ──►  access to a group of workspaces
     │
Workspace     ──►  read, plan, write, or admin on one state container

Think in terms of least privilege rather than memorizing every checkbox:

• A platform team might manage organization-wide policy sets and the private registry.
• An application team might receive Write on workspaces inside one project but only Read everywhere else.
• Plan vs apply separation is common: reviewers queue speculative plans without apply rights; operators apply only in approved windows.

Permissions also interact with systems outside HCP Terraform:

• A workspace linked to VCS inherits that repository's merge rules — anyone who can merge to the default branch can indirectly queue plans, even without an HCP Terraform seat.
• API tokens and run-task integrations act with the permissions you gave the integration, not only with the human who configured it.

On the Free lab organization, entitlements reported teams: false, so only the built-in owners team existed and an API request to create a platform-operators team returned not found. Paid plans add named teams; the permission model is the same, but you can delegate more finely.

Policy enforcement with Sentinel and OPA

After Terraform builds a plan, HCP Terraform can evaluate that plan against policy sets before the run continues. Policy-as-code here means organizational rules expressed outside .tf files, for example:

• Allowed regions or resource types
• Required tags on new resources
• Workflow rules such as blocking Friday applies

Terraform plan
      ↓
policy evaluation / check
      ↓
pass / advisory / block (per policy configuration)

HCP Terraform supports Sentinel and Open Policy Agent (OPA) with Rego:

• A single policy set uses one framework at a time.
• You can attach multiple policy sets to the same workspace, mixing Sentinel and OPA sets.
• HashiCorp also documents a Terraform policy framework in beta; this Associate-level lesson focuses on Sentinel and OPA because they appear in exam objectives and production orgs today.

Policy set scope controls where a set applies:

• Global — every workspace in the organization unless excluded
• Project — workspaces in selected projects
• Workspace — explicit workspace list
• Workspace tags — workspaces carrying matching tags where your edition supports tag-based scoping

Each policy inside a set has an enforcement level:

• Advisory policies warn without blocking.
• Sentinel adds soft-mandatory and hard-mandatory levels.
• OPA uses mandatory enforcement.
• Whether a failed mandatory policy can be overridden depends on the framework, the user's permissions, and — for Sentinel hard-mandatory policies — whether the policy set explicitly allows overrides.

Policy results appear in the HCP Terraform run UI. For CLI-driven runs:

• Sentinel policy results can also appear in Terraform CLI output.
• OPA policy results currently require the HCP Terraform UI.

This article does not teach Sentinel or Rego syntax. You only need to recognize that policies read plan JSON and return pass or fail.

Demonstration — advisory Sentinel policy on a plan

The lab attaches a global Sentinel policy set named gov-lab-policies with one advisory policy, always-pass.sentinel, that always returns true. The configuration under test is a disposable terraform_data resource in workspace hcp-gov-lab-demo:

terraform {
  cloud {
    organization = "golinuxcloud-lab"

    workspaces {
      project = "hcp-gov-lab"
      name    = "hcp-gov-lab-demo"
    }
  }
}

resource "terraform_data" "governance_lab" {
  input = "governance-lab-v1"
}

Create the lab directory and apply once so the workspace holds state:

mkdir -p ~/terraform-labs/hcp-terraform-governance && cd ~/terraform-labs/hcp-terraform-governance

Write the configuration above into main.tf, initialize, and apply:

terraform init

Sample output:

Initializing HCP Terraform...

Initializing provider plugins...
- terraform.io/builtin/terraform is built in to Terraform

HCP Terraform has been successfully initialized!

With the workspace linked, apply once so policy checks have state to refresh against:

terraform apply -auto-approve

Sample output, trimmed:

terraform_data.governance_lab: Creating...
terraform_data.governance_lab: Creation complete after 0s [id=de7c815b-cdfa-3ba8-f6a4-825fad8a77aa]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Confirm which workspace this directory drives:

terraform workspace show

Sample output:

hcp-gov-lab-demo

Queue a plan that triggers policy evaluation:

terraform plan

Sample output, trimmed to the policy section:

No changes. Your infrastructure matches the configuration.

------------------------------------------------------------------------

Organization Policy Check:

================ Results for policy set: gov-lab-policies ===============

Sentinel Result: true

This result means that all Sentinel policies passed and the protected
behavior is allowed.

1 policies evaluated.

## Policy 1: always-pass.sentinel (advisory)

Result: true

The Organization Policy Check block is the signal that governance ran against the plan:

• A mandatory policy that failed would stop the run before apply.
• Advisory policies record the result but allow the run to continue.

On the Free plan, HashiCorp limits you to one policy set with up to five policies, and connecting policy sets to a VCS repository for versioned policy workflows requires a paid edition per current documentation.

HCP Terraform private registry

The public Terraform Registry distributes community modules and providers. Teams that outgrow copy-pasted module folders use the private registry inside their organization: a searchable, versioned catalog of modules and providers restricted to organization members. Private modules use the HCP Terraform module registry source format; private providers use normal provider source addresses under the organization's HCP Terraform registry namespace.

The registry solves distribution and versioning, not trust by itself. Even modules published internally still need:

• Code review and testing before promotion
• Policy checks on plans that call those modules
• Least-privilege credentials for the workspaces that consume them

Publishing workflow — VCS-connected modules, API-uploaded provider releases, and module tests — is out of scope here. The Associate exam expects you to know why teams centralize reusable infrastructure in a registry rather than emailing zip files.

On the lab organization the registry module list was empty, which is normal for a teaching account that has not published modules yet.

Run tasks

Run tasks call external HTTPS endpoints at one of four points in the run lifecycle:

• pre-plan
• post-plan
• pre-apply
• post-apply

Partners and custom integrations use them for security scanning, cost visibility, compliance ticketing, or internal approval systems. The run pauses until the task reports success or failure according to its enforcement setting.

Plan complete
      ↓
Run task (post-plan)  ──► external system
      ↓
Apply allowed or blocked

Run tasks complement policy sets:

• Policy sets evaluate plan content with Sentinel or OPA inside HCP Terraform.
• Run tasks delegate to systems outside the plan JSON.

On the Free lab organization, entitlements included run tasks with a low limit on how many tasks and workspaces could use them; global run tasks that apply organization-wide required a higher edition. This article does not catalog vendors or walk through configuring a specific integration.

Health assessments and drift detection

Health assessments let HCP Terraform run scheduled, non-destructive checks against managed infrastructure. Three related ideas often appear together:

• Drift detection compares live resources to the configuration recorded in workspace state.
• Health checks re-evaluate custom conditions you declared in configuration, such as certificate expiry checks, when assessments are enabled.
• Assessments schedule those checks without applying changes.

Assessments do not change state or apply fixes. They surface drift and failing conditions so operators can open a normal plan or follow your change process. That is different from:

• Running terraform apply on a schedule
• The interactive terraform plan -refresh-only workflow in the Terraform drift detection lesson, which you run deliberately from a workstation when you already suspect drift

On the Free lab organization, entitlements reported assessments: false, so drift detection and continuous validation in the UI were not available to exercise. HashiCorp documents assessments from the Standard edition upward. When you do have access, you enable assessments per workspace or organization-wide; they run only after the workspace's last apply succeeded.

Governance workflow example

Separate UI tours for every governance feature are hard to remember. A single end-to-end story ties them together:

Developer proposes change
        ↓
Terraform plan (remote or VCS-driven)
        ↓
Team permissions (can this identity queue or approve?)
        ↓
Policy evaluation (Sentinel / OPA)
        ↓
Optional run task (external check)
        ↓
Approved apply
        ↓
Health / drift monitoring (paid editions)

A developer opens a pull request or runs terraform plan from the CLI. HCP Terraform records the plan. From there:

1. Permissions decide whether that identity may proceed.
2. Policy sets judge the planned changes.
3. An optional run task posts results to another system.
4. An operator applies when policy and process allow.
5. Assessments — where licensed — flag resources that changed outside Terraform.

Variable sets from the HCP Terraform variables lesson feed the same runs with defaults and secrets; governance sits around the run, not instead of workspace configuration.

Common governance design mistakes

Clean up the lab

When you finish experimenting, destroy the disposable resource and remove the HCP objects you created for this lesson. Leave the API token in place if you are continuing with other HCP Terraform lessons.

cd ~/terraform-labs/hcp-terraform-governance && terraform destroy -auto-approve

Delete the gov-lab-policies policy set from Settings → Policies, delete workspace hcp-gov-lab-demo from its Destruction and Deletion settings, then delete project hcp-gov-lab. Remove the lab directory when you no longer need the files.

References

• HCP Terraform plans and features
• Permissions overview in HCP Terraform
• Policy enforcement overview
• Manage policy sets
• Private registry
• Run tasks
• Health assessments

Summary

HCP Terraform governance is how shared infrastructure stays controllable once Terraform leaves a single laptop:

• Teams and permissions decide who can read, plan, and apply across organization, project, and workspace boundaries.
• Policy sets evaluate real plans with Sentinel or OPA after Terraform computes changes — a different layer from terraform validate syntax checks.
• The private registry versions internal modules for reuse.
• Run tasks hook external systems into the run lifecycle.
• Health assessments and drift detection — on editions that include them — watch whether live infrastructure still matches code.

The lab plan on workspace hcp-gov-lab-demo reported No changes and then an Organization Policy Check with advisory Sentinel result true, which is the CLI proof that Sentinel policy enforcement participated in an ordinary plan. OPA results would appear in the run UI instead. On a Free organization, custom teams and assessments were not entitled, and policy sets were capped, so treat plan-specific documentation and your Plan and billing page as the source of truth for what you can enable today.

For exam study, remember the flow: plan first, then permissions and policies, then optional run tasks, then apply, then monitoring where licensed. Deeper lessons cover variables, workspace layout, and local drift tooling; this article connects those pieces into the collaboration story objective 8b expects.