HCP Terraform / Enterprise Operations · Topic 3 of 3

Policy as Code in a Pipeline

Terraform Professional (002): store Sentinel and OPA policies in version control, connect policy sets, set enforcement levels and handle overrides.

  • 6 min
  • Includes a diagram
In a nutshell
  • sentinel.hcl for Sentinel and policies.hcl for OPA; each set uses one framework.
  • enforcement_level belongs in those files; enforce_mode belongs on tfe_policy.
  • tfe_policy defaults to soft-mandatory for Sentinel.

What it is

Policy as code treats compliance rules like application code: stored in version control, reviewed through pull requests, tested, and applied automatically. In HCP Terraform and Terraform Enterprise, the rules live in policy sets, and every run in scope is checked after its plan and before its apply.

Because the check belongs to the workspace, a run cannot avoid it by starting from a different tool. VCS, CLI and API runs are all evaluated.

How it works

The pipeline

Policy repositorypull requestTests and reviewmergePolicy setVCS connectionWorkspaces in scopePlan checkedApply or stop

Connecting a policy set to a VCS repository is the option HashiCorp calls best for automating enforcement. You choose the framework, the policies path (the directory holding the configuration file, by default the repository root), the branch, and the scope. HCP Terraform refreshes the policy set when relevant files change.

The framework cannot be changed after the set is created. Creating and connecting sets needs the manage policies permission.

Sentinel repository layout

sentinel.hcl lists each policy, and policy files that are not listed are ignored. It must sit in the same directory as its local policy files, and each policy is a separate .sentinel file.

policy "allowed-instance-types" {
  source            = "./allowed-instance-types.sentinel"
  enforcement_level = "hard-mandatory"
}

policy "approved-modules" {
  source            = "./approved-modules.sentinel"
  enforcement_level = "soft-mandatory"
}

A policy passes when its main rule is true. Imports give it data: for example tfplan/v2 for planned values, tfconfig/v2 for configuration such as module sources, and tfrun for run details.

OPA repository layout

policies.hcl sits at the root of the policies path. It names a Rego query for each policy, and enforcement_level defaults to advisory.

policy "public_ingress" {
  query             = "data.terraform.policies.public_ingress.deny"
  enforcement_level = "mandatory"
}

The query refers to the package declared in the .rego file and to the rule name. The result must be an array, and the policy passes when the array is empty. One Rego file can hold several rules, since the query picks the rule.

Managing policies as Terraform

The automated option creates a policy set through the API or the tfe provider rather than a VCS connection.

resource "tfe_policy" "public_ingress" {
  name         = "public-ingress"
  organization = "acme"
  kind         = "opa"
  policy       = file("${path.module}/public_ingress.rego")
  query        = "data.terraform.policies.public_ingress.deny"
  enforce_mode = "mandatory"
}
SettingValuesWhere
enforcement_levelSentinel: advisory, soft-mandatory, hard-mandatory; OPA: advisory, mandatorysentinel.hcl, policies.hcl
enforce_modeSentinel: same three, with soft-mandatory the default; OPA: advisory, mandatorytfe_policy
kindsentinel (default) or opatfe_policy, tfe_policy_set
queryThe OPA rule to evaluatetfe_policy
overridabletrue or false (default)tfe_policy_set

On tfe_policy_set, policy_ids cannot be combined with vcs_repo, and global cannot be combined with workspace_ids.

Testing before merge

Test policy changes in the policy repository's own pipeline, before they can block anyone.

sentinel test
opa test .

Roll out a new rule at advisory first to see what would fail, then raise the level once teams have fixed their code.

What happens during a run

After the plan, policy checks run. An advisory failure only warns, a soft-mandatory or OPA mandatory failure waits for an override that covers this run, and a hard-mandatory failure in a policy check ends in Plan Errored.

ResultEffectRun status
Sentinel or OPA advisory failsWarning; run continuesContinues
Soft-mandatory failsStops for an override or discardPolicy Override
OPA mandatory failsStops for an override or discardPolicy Override
Hard-mandatory fails in a policy checkStops; no overridePlan Errored

A user with the manage policy overrides permission clicks Override and Continue. For soft-mandatory Sentinel policies, you can also run terraform apply and enter override at the prompt. An override covers that run only.

The CLI prints Sentinel results for CLI-driven runs but does not show OPA results, so read those in the UI. Speculative plans check Sentinel policies too, so an author can see a failure on the pull request before merging.

Two details that change the answer

A Sentinel policy set can run as a policy check or, with the agent type, as a policy evaluation. In a policy evaluation, soft-mandatory and hard-mandatory are converted to mandatory, which a user with the override permission can override when the set allows it.

That set-level option is "This policy set can be overridden in the event of mandatory failures" (overridable on tfe_policy_set). It applies to OPA sets and agent-type Sentinel sets, and it takes precedence over each policy's enforcement level.

How the exam asks about this

  • "Policy changes must be reviewed like code and take effect automatically." Store them in a repository and connect a policy set to VCS.
  • "An OPA policy never fails although a violation exists." Check that the query matches the package and rule name, and that the result is a non-empty array.
  • "A new Sentinel file in the repository is not being evaluated." Add it to sentinel.hcl; unlisted files are ignored.

What to remember for the exam

  • sentinel.hcl for Sentinel and policies.hcl for OPA; each set uses one framework.
  • enforcement_level belongs in those files; enforce_mode belongs on tfe_policy.
  • tfe_policy defaults to soft-mandatory for Sentinel.
  • An OPA policy passes when its query returns an empty array.
  • Policies evaluate only after a successful plan and before apply.
  • Overrides need the manage policy overrides permission and affect one run.
Watch out

OPA has no hard-mandatory level. If a rule must not be bypassed, clear the policy set's override option and limit who holds the manage policy overrides permission.

Common mistakes

Mixing the argument names. Writing enforcement_level on tfe_policy or enforce_mode in sentinel.hcl is wrong. Each belongs to one place only.

Assuming hard-mandatory is always absolute. It cannot be overridden in policy checks, but agent-based policy evaluations convert it to mandatory, which can be overridden. Check the policy set type.

Forgetting the OPA query. Without a matching query, HCP Terraform is not evaluating the rule you intend. The query names the package and rule, not the file.

Check yourself

  • Where do you set the enforcement level for a Sentinel policy stored in a repository?

    In the policy block of sentinel.hcl, using the enforcement_level argument.

  • What must an OPA query return for the policy to pass?

    An empty array, since each item in the array represents a violation found by the rule.

  • Can an API-driven run skip a policy set scoped to its workspace?

    No. Policy sets apply to runs in their scope, so VCS, CLI and API runs are all evaluated after the plan.

Topic 3 of 3 in HCP Terraform / Enterprise Operations

Test yourself on HCP Terraform / Enterprise Operations

The full HashiCorp Terraform Infrastructure Engineer Professional question bank has 600 questions, with timed practice exams and an explanation for every answer.

This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.