Manage policies and policy sets in HCP Terraform

Policies are rules that HCP Terraform enforces on Terraform runs. You can define policies using either the Sentinel or Open Policy Agent (OPA) policy-as-code frameworks.

Policy sets are collections of policies you can apply globally or to specific projects and workspaces in your organization. For each run in the applicable workspaces, HCP Terraform checks the Terraform plan against the policy set. Depending on the enforcement level, failed policies can stop a run in a workspace. If you do not want to enforce a policy set on a specific workspace, you can exclude the workspace from that set.

Policy checks versus policy evaluations

Policy checks and evaluations can access different types of data and enable slightly different workflows.

Policy checks

Only Sentinel policies can run as policy checks. Checks can access cost estimation data but can only use the latest version of Sentinel.

Policy evaluations

OPA policy sets can only run as policy evaluations, and you can enable policy evaluations for Sentinel policy sets by selecting the Agent policy set type.

HCP Terraform runs a workspace's policy evaluation in your self-managed agent pool if you meet the following requirements:

• You are on the HCP Terraform Premium edition.
• You configure the workspace to run Terraform operations in your self-managed agent pool. Refer to Configure Workspaces to use the Agent for more information.
• You configure at least one agent in the agent pool to accept policy jobs. Refer to the HCP Terraform agent reference for more information.

If you do not meet all of the above requirements, then policy evaluations run within HCP Terraform's infrastructure.

For Sentinel policy sets, using policy evaluations lets you:

• Enable overrides for soft-mandatory and hard-mandatory policies, letting any user with Manage Policy Overrides permission proceed with a run in the event of policy failure.
• Select a specific Sentinel runtime version for the policy set.

Policy evaluations cannot access cost estimation data, so use policy checks if your policies rely on cost estimates.

Policy enforcement levels

You can set an enforcement level for each policy that determines what happens when a Terraform plan does not pass the policy rule. Sentinel and OPA policies have different enforcement levels available.

Sentinel

You can enable one of the following options to set the enforcement level when creating a Sentinel policy:

• Advisory: Failed policies never interrupt the run. They provide information about policy check failures in the UI.
• Soft mandatory: Failed policies stop the run, but any user with Manage Policy Overrides permission can override these failures and allow the run to complete.
• Hard mandatory: Failed policies stop the run. Unless the set containing the policy is configured to allow overrides, Terraform does not apply runs until a user fixes the issue that caused the failure.

Allow policy level overrides

When adding policies to a policy set, you can enable the This policy set can be overridden in the event of mandatory failures option. Enabling this option lets users with the appropriate permissions, such as admins or team owners, override any failed policy checks in that set, even policies set to Hard mandatory. This override setting takes precedence over the individual policy’s enforcement level.

OPA

OPA provides two policy enforcement levels:

• advisory Failed policies never interrupt the run. They provide information about policy failures in the UI.
• mandatory: Failed policies stop the run, but any user with Manage Policy Overrides permission can override these failures and allow the run to complete.

Policy publishing workflows

You can create policies and policy sets for your HCP Terraform organization in one of three ways:

• HCP Terraform web UI: Add individually-managed policies manually in the HCP Terraform UI, and store your policy code in HCP Terraform. This workflow is ideal for initial experimentation with policy enforcement, but we do not recommend it for organizations with large numbers of policies.
• Version control: Connect HCP Terraform to a version control repository containing a policy set. When you push changes to the repository, HCP Terraform automatically uses the updated policy set.
• Automated: Push versions of policy sets to HCP Terraform with the HCP Terraform Policy Sets API or the tfe provider tfe_policy_set resource. This workflow is ideal for automated Continuous Integration and Deployment (CI/CD) pipelines.

Manage individual policies in the web UI

You can add policies directly to HCP Terraform using the web UI. This process requires you to paste completed, valid Sentinel or Rego code into the UI. We recommend validating your policy code before adding it to HCP Terraform.

Add managed policies

To add an individually managed policy:

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to the organization you want to add policies to.
2. Choose Settings from the sidebar, then Policies. A list of managed policies in HCP Terraform appears. Each policy designates its policy framework (Sentinel or OPA) and associated policy sets.
3. Click Create a new policy.
4. Choose the Policy framework you want to use. You can only create a policy set from policies written using the same framework. You cannot change the framework type after you create the policy.
5. Complete the following fields to define the policy:
   • Policy Name: Add a name containing letters, numbers, -, and _. HCP Terraform displays this name in the UI. The name must be unique within your organization.
   • Description: Describe the policy’s purpose. The description supports Markdown rendering, and HCP Terraform displays this text in the UI.
   • Enforcement mode: Choose whether this policy can stop Terraform runs and whether users can override it. Refer to policy enforcement levels for more details.
   • (OPA Only) Query: Write a query to identify a specific policy rule within your rego code. HCP Terraform uses this query to determine the result of the policy. The query is typically a combination of the policy package name and rule name, such as terraform.deny. The result of this query must be an array. The policy passes when the array is empty.
   • Policy code: Paste the code for the policy: either Sentinel code or Rego code for OPA policies. The UI provides syntax highlighting for the policy language.
   • (Optional) Policy sets: Select one or more existing managed policy sets where you want to add the new policy. You can only select policy sets compatible with the chosen policy set framework. If there are no policy sets available, you can create a new one.

The policy is now available in the HCP Terraform UI for you to edit and add to one or more policy sets.

Edit managed policies

To edit a managed policy:

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to the organization you want to edit policies for.
2. Choose Settings from the sidebar, then Policies.
3. Click the policy you want to edit to go to its details page.
4. Edit the policy's fields and then click Update policy.

Delete managed policies

You can not restore policies after deletion. You must manually re-add them to HCP Terraform. You may want to save the policy code in a separate location before you delete the policy.

To delete a managed policy:

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to the organization you want to delete a policy in.
2. Choose Settings from the sidebar, then Policies.
3. Click the policy you want to delete to go to its details page.
4. Click Delete policy and then click Yes, delete policy to confirm.

The policy no longer appears in HCP Terraform and in any associated policy sets.