Configure connections to policy sets

Policy sets are collections of policies that you can apply to an entire organization or to specific projects and workspaces. For more information about defining policies, refer to Define policies. For information about using policies created and maintained by HashiCorp, refer to Run pre-written Sentinel policies.

Overview

The way you set up and configure a new policy set depends on your workflow and where you store policies. HCP Terraform and Terraform Enterprise support the following workflows:

• Managed policies: Create a policy set and add policies to it in the HCP Terraform or Terraform Enterprise interface.
• Policy sets hosted in a version control system: Create a policy set in the HCP Terraform or Terraform Enterprise interface and then connect it to a repository. HCP Terraform automatically refreshes the policy set when you change relevant files. Version control policy sets have specific organization and formatting requirements. Refer to Sentinel VCS Repositories and OPA VCS Repositories for details.
• Automated workflows: For workflows such as continuous deployment, use the HCP Terraform or Terraform Enterprise interface to create an empty policy set, then call the /policy-sets API endpoint to add policies. You can use the API or the tfe provider to add an entire policy set.

Requirements

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

View existing policy set connections

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to your organization.
2. Click Settings, then Policy Sets in the sidebar.

This page contains all of the policy sets available in the organization, including those added through the API.

Create a new policy set connection

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to your organization.

2. Choose Settings from the sidebar, then Policy sets.

3. Choose one of the following sources:

   • Version control system (VCS) provider: Choose this option to run policy sets hosted in your VCS. This option is best for automating policy enforcement.
   • Individually managed policies: Choose this option to create a policy set in the UI and add individually managed policies to the set. This option is best for small teams and teams with less complex policy management requirements.
   • Automated: Choose this option to create an empty policy set and use the API to add policies later. This option is best for advanced policy management tools or to integrate with third-party systems.

4. Click Next, then choose either Sentinel or Open policy agent (OPA) as the policy framework. A policy set can only contain policies that use the same framework. You cannot change a policy set's framework type after creation.

5. Specify a unique and descriptive name for the policy set. You can use any combination of letters, numbers, -, and _. A name is required.

6. It is optional, but you can add a description. We recommend adding a description so that the purpose of the policy set is clear to team members.

7. Choose a policy set scope:

   • Enable the Policies enforced globally option to automatically enforce this policy set on all of the organization's existing and future workspaces. You can optionally click Add exclusions and choose workspaces to exempt from the policy set.
   • Enable the Policies enforced on selected projects and workspaces option to enforce the policy set on specific workspaces or all workspaces in project. This affects all current and future workspaces for any projects you choose.

8. For Sentinal policy sets, choose a policy execution mode. Refer to Policy set execution modes for details about each option. For OPA policy sets, configure the following settings:

   • Choose an OPA version from the Runtime version drop-down menu.
   • Enable the This policy set can be overridden in the event of mandatory failures option to let users with override policy permissions apply plans, even when a mandatory policy fails. Refer to Policy enforcement levels for more information.

9. Click Next, then configure the following settings depending on the source you chose in step 3:

   • Version control system (VCS) provider:

     1. Choose the VCS provider. Refer to Connect to VCS for more information.
     2. Specify the repository where the policy set is stored.
     3. If the repository contains multiple sets, specify the relative path from your root directory to the directory that contains either the sentinel.hcl or policies.hcl configuration files. By default, HCP Terraform and Terraform Enterprise use the repository's root directory.
     4. You can specify a VCS branch to import new versions of policies from. By default, HCP Terraform and Terraform Enterprise use your selected VCS repository's default branch.

   • Individually managed policies: Select managed policies from the Policies drop-down to add to the policy set. You can only add policies written with the same policy framework you selected for this set.

   • Automated: Specify a list of key-value pairs that HCP Terraform or Terraform Enterprise sends to the Sentinel runtime when performing policy checks on workspaces. Refer to Sentinel parameters for more information.

10. Click Create policy set to finish.

Depending on the type of policy set you choose to create, you can then add policies to the set using the UI, connected VCS repository, the API, or the tfe provider. If you are creating an OPA policy set or a Sentinel policy set using agents, we recommend choosing a specific runtime version for your policy set to ensure consistent behavior.

Policy set execution modes

When using Sentinel as the policy framework, you can set the execution mode to either platform environment mode or HCP Terraform Agent mode. The mode determines the environment that policies run in.

Platform environment mode

When a policy run starts, the job is executed internally by the HCP Terraform or Terraform Enterprise control plane. In this mode, HCP Terraform and Terraform Enterprise use Sentinel 0.40.x to evaluate policies. The latest language features are not supported.

Use this mode when you want to quickly start policy runs with minimal overhead and when your Sentinel policies require access to cost estimation data.

Platform environment mode may lead to slower overall application performance during high policy run volumes. This is because the policy run shares CPU and memory allocations with the HCP Terraform or Terraform Enterprise control plane.

HCP Terraform Agent mode

When a policy run starts, HCP Terraform or Terraform Enterprise checks the workspace settings to determine the execution environment. To learn more about workspace execution modes, refer to Workspace settings.

When your workspace exeuction mode is also set to Agent, HCP Terraform and Terraform Enterprise use the same agent instance to evaluate policies and run Terraform operations. When the workspace execution mode is set to Local or Remote, HCP Terraform or Terraform Enterprise starts a new agent to evaluate the policy.

You can explicitly set your workspace execution mode to Agent or configure your workspace to inherit an execution mode from project settings or organization settings.

Use HCP Terraform Agent mode to execute your policy set using a specific version of Sentinel. Because your policies run in an isolated environment, you can also use this mode to offload resource consumption from HCP Terraform or Terraform Enterprise.

HCP Terraform Agent mode can result in slower startup times because of the time necessary to dispatch an agent or start the control plane. This mode cannot access cost estimation data.

Edit policy sets

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to the organization you want to edit a policy set in.
2. Choose Settings from the sidebar, then Policies.
3. Click the policy set you want to edit to go to its settings page.
4. Adjust the settings and click Update policy set.

Evaluate a policy runtime upgrade

For OPA and Sentinel policy sets using agents, we recommend choosing a specific runtime version for your policy set to ensure consistent behavior.

You can test a new runtime version for a policy set to ensure your policies work as expected before upgrading to that version. To test a new policy set runtime version, perform the following steps:

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to your organization.
2. Choose Settings from the sidebar, then Policies in your organization’s settings.
3. Click the policy set you want to upgrade.
4. Click the Evaluate tab.
5. Select the Runtime version you want to upgrade to.
6. Select a Workspace to test the policy set and upgraded version against.
7. Click Evaluate.

HCP Terraform executes the policy set using the specified version and the latest plan data for the specified workspace, then displays the evaluation results. If the evaluation returns a Failed status, inspect the JSON output to determine if the issue is related to a non-compliant resource or a syntax issue.

If the evaluation results in an error, check that the policy configuration is valid with your new runtime version.

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. Sign in to HCP Terraform or Terraform Enterprise and navigate to the organization you want to delete a policy set in.
2. Choose Settings from the sidebar, then Policies in your organization’s settings.
3. Click the policy set you want to delete to go to its details page.
4. 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 parameters

Sentinel parameters are a list of key-value pairs that HCP Terraform and Terraform Enterprise send to the Sentinel runtime when performing policy checks on workspaces. If the value parses as JSON, HCP Terraform and Terraform Enterprise send it to Sentinel as the corresponding type, such as string, Boolean, integer, map, or list. If the value fails JSON validation, the value is sent as a string.

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