Managing Policy Sets
Note: Terraform Cloud Free Edition includes one policy set of up to five policies. In Terraform Cloud Plus Edition, you can connect a policy set to a version control repository or create policy set versions via the API. Refer to Terraform Cloud pricing for details.
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, Terraform Cloud 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.
To view and manage policies and policy sets, you must have manage policy permissions for your organization.
Though policy checks and policy evaluations seem like synonyms, there is a fundamental difference between the policy check and policy evaluation workflow.
Sentinel policies are currently run as a policy check. This is the default workflow for Sentinel. Policy checks use the latest version of the Sentinel runtime and have access to cost estimation data.
Policy evaluations are run within the Terraform Cloud Agent in Terraform Cloud's infrastructure. Policy evaluations do not have access to cost estimation data.
Note: Sentinel policy evaluations are currently in beta. Sentinel policies can run as a policy evaluation on an opt-in basis.
You can use the following workflows to manage policies and policy sets for your Terraform Cloud organization:
- Individually Managed: Add policies directly in the Terraform Cloud UI, and Terraform Cloud stores your policy code. 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 Terraform Cloud to a version control repository containing a policy set. When you push changes to the repository, Terraform Cloud automatically uses the updated policy set.
- Automated: Push versions of policy sets to Terraform Cloud with the Terraform Cloud Policy Sets API. For Sentinel only, you can also use the
tfe_policy_setresource. This workflow is ideal for automated Continuous Integration and Deployment (CI/CD) pipelines.
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 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 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.
You can add policies directly to Terraform Cloud. 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 Terraform Cloud.
To add an individually managed policy:
- Go to Policies in your organization’s settings. A list of managed policies in Terraform Cloud appears. Each policy designates its policy framework (Sentinel or OPA) and associated policy sets.
- Click Create a new policy.
- 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.
- Complete the following fields to define the policy:
- Policy Name: Add a name containing letters, numbers,
_. Terraform Cloud 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 Terraform Cloud 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. Terraform Cloud 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.
- Policy Name: Add a name containing letters, numbers,
The policy is now available in the Terraform Cloud UI for you to edit and add to one or more policy sets.
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.
Warning: Deleting a policy that applies to an active run causes that run’s policy evaluation stage to error. We recommend warning other members of your organization before you delete widely used policies.
You can not restore policies after deletion. You must manually re-add them to Terraform Cloud. 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 Terraform Cloud and in any associated 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. Terraform Cloud 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
tfeprovider (Sentinel Only) to add an entire, packaged policy set.
To create a policy set:
Go to Policy Sets in your organization’s settings.
Click Connect a new policy set.
Choose your workflow.
- For managed policies, click create a policy set with individually managed policies. Terraform Cloud 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. Terraform Cloud shows a form to create a policy set connected to that repository.
- For automated workflows, click No VCS Connection. Terraform Cloud shows a form to create an empty policy set. You can use the API to add policies to this empty policy set later.
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.
Choose a policy set scope:
- Policies enforced globally: Terraform Cloud 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.
(Sentinel Only) Choose a policy set type:
(Optional) Add Policy exclusions for this policy set. Specify any workspaces in the policy set's scope that Terraform Cloud will not enforce this policy set on.
(OPA Only) Allow Overrides, which enables users with override policy permissions to apply plans that have mandatory policy failures.
(VCS Only) Optionally specify the VCS branch within your VCS repository where Terraform Cloud should import new versions of policies. If you do not set this field, Terraform Cloud uses your selected VCS repository's default branch.
(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
policies.hcl(OPA) configuration files. If you do not set this field, Terraform Cloud uses the repository's root directory.
(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.
Choose a descriptive and unique Name for the policy set. You can use any combination of letters, numbers,
Write an optional Description that tells other users about the purpose of the policy set and what it contains.
To edit a policy set:
- Go to the Policy Sets section of your organization’s settings.
- Click the policy set you want to edit to go to its settings page.
- Adjust the settings and click Update policy set.
Warning: Deleting a policy set that applies to an active run causes that run’s policy evaluation stage to error. We recommend warning other members of your organization before you delete widely used policy sets.
You can not restore policy sets after deletion. You must manually re-add them to Terraform Cloud.
To delete a policy set:
- Go to Policy Sets in your organization’s settings.
- Click the policy set you want to delete to go to its details page.
- Click Delete policy and then click Yes, delete policy set to confirm.
The policy set no longer appears on the UI and Terraform Cloud no longer applies it to any workspaces. For managed policy sets, all of the individual policies are still available in Terraform Cloud. You must delete each policy individually to remove it from your organization.
Sentinel parameters are a list of key/value pairs that Terraform Cloud sends to the Sentinel runtime when performing policy checks on workspaces. If the value parses as JSON, Terraform Cloud sends it to Sentinel as the corresponding type (string, boolean, integer, map, or list). If the value fails JSON validation, Terraform Cloud sends it as a string.
You can set Sentinel parameters when you edit a policy set.
You can only set parameters for existing policy sets that you added through the
tfe provider, API, or a connected VCS repository. Parameters are not available for managed policy sets.
Note: Policy runtime version management is currently in beta.
You can pin a policy set to a specific runtime version. This provides control over the versioning of the policy-as-code runtime.
For OPA Policy sets, a
Runtime version drop-down selector is available that allows you to choose supported versions of OPA. All policies within this policy set will be evaluated against the chosen policy runtime version.
For Sentinel Policy sets, policy runtime version selection is available on an opt-in basis. Sentinel policy sets will default to using the policy check flow, and you can opt in to the policy evaluation flow for each policy set individually through a radio button located in the Sentinel policy set configuration form.
After opting in to the
enhanced workflow, you can select the Sentinel runtime version (via the
Runtime version drop-down selector) against which the policies in the policy set will be evaluated.
All policy sets that are configured to use the
enhanced workflows will run as a policy evaluation.
The Sentinel Policy sets will also have an
override checkbox (similar to OPA). Failed policies stop the run, but any user with Manage Policy Overrides permission can override these failures and allow the run to complete.
Both soft-mandatory and hard-mandatory policies can be overriden.
Note: Sentinel runtime version pinning is supported only for Sentinel 0.23.1 and above, as well as Terraform Cloud agent versions 1.13.1 and above