Policies and policy sets

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.

Permissions

To view and manage policies and policy sets, you must have manage policy permissions for your organization.

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 Enhanced policy set type. Policy evaluations run within the HCP Terraform agent in 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

Sentinel provides three policy enforcement levels:

• 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. Terraform does not apply runs with failed hard mandatory policies until a user fixes the issue that caused the failure.

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. Go to Policies in your organization’s settings. A list of managed policies in HCP Terraform appears. Each policy designates its policy framework (Sentinel or OPA) and associated policy sets.
2. Click Create a new policy.
3. 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.
4. 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:

• Go to Policies in your organization’s settings.
• Click the policy you want to edit to go to its details page.
• 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:

• Go to Policies in your organization’s settings.
• Click the policy you want to delete to go to its details page.
• 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.

Manage policy sets

Policy sets are collections of policies that you can apply globally or to specific projects and workspaces.

To view and manage policy sets, go to the Policy Sets section of your organization’s settings. This page contains all of the policy sets available in the organization, including those added through the API.

The way you set up and configure a new policy set depends on your workflow and where you store policies.

• For managed policies, you use the UI to create a policy set and add managed policies.
• For policy sets in a version control system, you use the UI to create a policy set connected to that repository. HCP Terraform automatically refreshes the policy set when you change relevant files in that repository. Version control policy sets have specific organization and formatting requirements. Refer to Sentinel VCS Repositories and OPA VCS Repositories for details.
• For automated workflows like continuous deployment, you can use the UI to create an empty policy set and then use the Policy Sets API to add policies. You can also use the API or the tfe provider (Sentinel Only) to add an entire, packaged policy set.

Create policy sets

To create a policy set:

1. Go to Policy Sets in your organization’s settings.

2. Click Connect a new policy set.

3. Choose your workflow.

   • For managed policies, click create a policy set with individually managed policies. HCP Terraform shows a form to create a policy set and add individually managed policies.
   • For version control policies, choose a version control provider and then select the repository with your policy set. HCP Terraform shows a form to create a policy set connected to that repository.
   • For automated workflows, click No VCS Connection. HCP Terraform shows a form to create an empty policy set. You can use the API to add policies to this empty policy set later.

4. Choose a Policy framework for the policies you want to add. A policy set can only contain policies that use the same framework (OPA or Sentinel). You cannot change a policy set's framework type after creation.

5. Choose a policy set scope:

   • Policies enforced globally: HCP Terraform automatically enforces this global policy set on all of an organization's existing and future workspaces.
   • Policies enforced on selected projects and workspaces: Use the text fields to find and select the workspaces and projects to enforce this policy set on. This affects all current and future workspaces for any chosen projects.

6. (Optional) Add Policy exclusions for this policy set. Specify any workspaces in the policy set's scope that HCP Terraform will not enforce this policy set on.

7. (Sentinel Only) Choose a policy set type:

   • Standard: This is the default workflow. A Sentinel policy set uses a policy check in HCP Terraform and lets you access cost estimation data.
   • Enhanced: A Sentinel policy set uses a policy evaluation in HCP Terraform. This lets you enable policy overrides and enforce a Sentinel runtime version

8. (OPA Only) Select a Runtime version for this policy set.

9. (OPA Only) Allow Overrides, which enables users with override policy permissions to apply plans that have mandatory policy failures.

10. (VCS Only) Optionally specify the VCS branch within your VCS repository where HCP Terraform should import new versions of policies. If you do not set this field, HCP Terraform uses your selected VCS repository's default branch.

11. (VCS Only) Specify where your policy set files live using the Policies path. This lets you maintain multiple policy sets within a single repository. Use a relative path from your root directory to the directory that contains either the sentinel.hcl (Sentinel) or policies.hcl (OPA) configuration files. If you do not set this field, HCP Terraform uses the repository's root directory.

12. (Managed Policies Only) Select managed Policies to add to the policy set. You can only add policies written with the same policy framework you selected for this set.

13. Choose a descriptive and unique Name for the policy set. You can use any combination of letters, numbers, -, and _.

14. Write an optional Description that tells other users about the purpose of the policy set and what it contains.

Edit policy sets

To edit a policy set:

1. Go to the Policy Sets section of your organization’s settings.
2. Click the policy set you want to edit to go to its settings page.
3. Adjust the settings and click Update policy set.

Evaluate a policy runtime upgrade

You can validate that changing a policy runtime version does not introduce any breaking changes.

To perform a policy evaluation:

1. Go to the Policy Sets section of your organization’s settings.
2. Click the policy set you want to upgrade.
3. Click the Evaluate tab.
4. Select the Runtime version you wish to upgrade to.
5. Select a Workspace to test the policy and upgraded version against.
6. Click Evaluate.

HCP Terraform will execute the policy set using the specified version and the latest plan data for the selected workspace. It will display the evaluation results. If the evaluation returns a Failed status, inspect the JSON output to determine whether the issue is related to a non-compliant resource or is due to a syntax issue. If the evaluation results in an error, check that the policy configuration is valid.

Delete policy sets

You can not restore policy sets after deletion. You must manually re-add them to HCP Terraform.

To delete a policy set:

1. Go to Policy Sets in your organization’s settings.
2. Click the policy set you want to delete to go to its details page.
3. Click Delete policy and then click Yes, delete policy set to confirm.

The policy set no longer appears on the UI and HCP Terraform no longer applies it to any workspaces. For managed policy sets, all of the individual policies are still available in HCP Terraform. You must delete each policy individually to remove it from your organization.

(Sentinel only) Sentinel parameters

Sentinel parameters are a list of key/value pairs that HCP Terraform sends to the Sentinel runtime when performing policy checks on workspaces. If the value parses as JSON, HCP Terraform sends it to Sentinel as the corresponding type (string, boolean, integer, map, or list). If the value fails JSON validation, HCP Terraform sends it as a string.

You can set Sentinel parameters when you edit a policy set.

You can only set parameters for policy sets added through:

• A connected VCS repository
• The policy sets API
• The tfe provider's tfe_policy_set resource

Individually managed policies created through HCP Terraform's UI, API, or the TFE provider do not support attaching parameters.