Enforce a policy

Sentinel is an embedded policy-as-code framework integrated with various HashiCorp products. It enables fine-grained, logic-based policy decisions, and can use information from external sources. HCP Terraform lets users enforce Sentinel policies as part of the run workflow.

A policy consists of:

• The policy controls defined as code.
• An enforcement level that determines run behavior in the event of policy failure.

Policy sets are a named grouping of policies and their enforcement levels. To apply a policy to a workspace and it's run, you must first add it to a policy set. Each policy set can apply to specific workspaces, or to all workspaces within an organization. Policy sets are the mapping between policies and workspaces.

In this tutorial, you will define a policy set in a Version Control System (VCS), then connect it to HCP Terraform to verify that the Terraform version is 1.1.0 or above.

Prerequisites

This tutorial assumes that you are familiar with HCP Terraform and you have an existing HCP Terraform workspace configured with AWS access credentials.

If you do not, refer to the Trigger HCP Terraform runs from VCS changes and Create a Variable Set tutorials for guidance.

You must be in the "owners" team or have "Manage Policies" organization-level permissions to create new policy sets and policies.

Fork GitHub Repository

To create a policy set, you will need a VCS repository to host the policy configuration. Fork the example Enforce Policy repository.

In the repository, you will find two files — sentinel.hcl and allowed-terraform-version.sentinel.

Explore a policy set

The sentinel.hcl file defines the policy set. This configuration declares a policy named allowed-terraform-version and sets a soft-mandatory enforcement level. You can define multiple policy blocks in the sentinel.hcl file to configure more policies.

policy "allowed-terraform-version" {
    enforcement_level = "soft-mandatory"
}

Enforcement levels establish whether or not an operation can proceed if a policy fails. Sentinel provides three enforcement levels:

• Hard-mandatory requires that the policy passes. If a policy fails, the run stops. You must resolve the failure to proceed.

• Soft-mandatory lets an organization owner or a user with override privileges proceed with the run in the event of failure. HCP Terraform logs all overrides.

• Advisory will notify you of policy failures, but proceed with the operation.

Explore a policy

The allowed-terraform-version.sentinel file defines the policy declared in the policy set. Sentinel configuration files must follow the naming convention of <policy name>.sentinel.

This policy passes and returns true if the Terraform version is above v1.1.0. You can experiment with this policy and trigger a failure by changing the expression to version.new(tfplan.terraform_version).less_than("1.1.0") or changing the version in the parentheses.

import "tfplan"
import "version"

main = rule {
  version.new(tfplan.terraform_version).greater_than("1.1.0")
}

Connect the Policy to HCP Terraform

You need to connect your policy set to your HCP Terraform organization before you use it. Navigate to your organization's Settings, and then to the Policy Sets page.

Click on the Connect a new policy set button, then click Version control system (VCS) provider.

On the Configure settings page:

1. Select Sentinel as the policy framework.
2. In the Name field, enter learn-terraform-enforce-policies.
3. Under Scope of Policies, select Policies enforced on select projects and workspaces.
4. Specify the workspaces you want this policy set to apply to.
5. Under Execution mode, select Agent.
6. Click the Runtime version dropdown and choose ~>0.40.0 latest.
7. Click the Next button.

On the Connect to VCS page:

1. Select your GitHub VCS provider.
2. Select your forked learn-terraform-enforce-policies repository.
3. Click the Next button.

On the Parameters page, click Connect policy set to finish creating your policy set.

This creates a policy set that checks whether the Terraform version is above v1.1.0 for the workspaces specified.

After creating the policy set, HCP Terraform returns to the policy sets index page. The list now contains your new policy set. The VCS information, including the latest commit SHA, appears within the policy set.

Now that you created the policy set and associated it with a workspace, navigate to your workspace. Click New run and choose Plan only from the Run Type dropdown. Click Start to begin the plan operation.

There is now an additional policy check step in the run, showing that the policy passed.

Now that you completed the tutorial, optionally destroy the workspace.

Next steps

In this tutorial, you created and used a policy check to verify the Terraform version before each run.

To learn more about policies, refer to the HCP Terraform Sentinel documentation.