Use a sentinel policy to filter allowed providers in Terraform – HashiCorp Help Center

Introduction

This guide demonstrates how to use Sentinel policies to enforce an allowlist of providers in your HCP Terraform or Terraform Enterprise environment.

You will learn how to access provider details from your Terraform configuration within a Sentinel policy. The example code provided is for educational purposes to help you get familiar with Sentinel and should be adapted before use in a production environment.

In this guide, you will:

Clone a HashiCorp repository containing example Sentinel policies.
Customize a policy to allow only specific providers.
Download Sentinel mock files from an HCP Terraform or Terraform Enterprise workspace.
Test the policy locally using the mock files and the Sentinel CLI.

Prerequisites

A macOS or Linux environment.
Git installed and configured.
Access to an HCP Terraform or Terraform Enterprise workspace.
The Sentinel CLI installed. Refer to the Install Sentinel tutorial for instructions.

Procedure

Step 1: Clone the example repository

First, clone the HashiCorp repository containing Sentinel policy examples to use as a base for your policy set.

Navigate to your home directory.
```
$ cd ~
```

Clone the repository.

$ git clone https://github.com/hashicorp/terraform-sentinel-policies

Change into the newly created directory.
```
$ cd terraform-sentinel-policies
```
Create a new directory for your test policies.
```
$ mkdir my-test-policies
```

Copy the allowed-providers.sentinel policy into your new directory to use as a starting point.

$ cp cloud-agnostic/allowed-providers.sentinel my-test-policies/my-allowed-providers.sentinel

Step 2: Get Sentinel mock files

When you execute a run in an HCP Terraform or Terraform Enterprise workspace, Sentinel mock files are generated. You can download these files to test your policies locally.

Navigate to your workspace in the HCP Terraform or Terraform Enterprise UI and start a new run with the configuration you want to test.
After the plan phase completes, click Download Sentinel mocks.
You can now discard the run by clicking Discard run.
The downloaded file will have a name similar to run-2LrpdkN5Zz5c8ZFJ-sentinel-mocks.tar.gz.

Unzip the mock files into your policy directory. This example assumes the file was downloaded to your Downloads folder and you cloned the repository in your home folder.

$ tar -zxvf ~/Downloads/run-2LrpdkN5Zz5c8ZFJ-sentinel-mocks.tar.gz -C ~/terraform-sentinel-policies/my-test-policies

The command extracts the following mock files.

x mock-tfconfig-v2.sentinel
x mock-tfconfig.sentinel
x mock-tfplan-v2.sentinel
x mock-tfplan.sentinel
x mock-tfstate-v2.sentinel
x mock-tfstate.sentinel
x sentinel.hcl
x mock-tfrun.sentinel

Step 3: Configure the test environment

Next, configure the sentinel.hcl file to define your policy set and enforcement level.

Verify the files are in your my-test-policies directory.

$ ls -l1 ~/terraform-sentinel-policies/my-test-policies

The output should list your policy and the extracted mock files.

my-allowed-providers.sentinel
mock-tfconfig-v2.sentinel
mock-tfconfig.sentinel
mock-tfplan-v2.sentinel
mock-tfplan.sentinel
mock-tfrun.sentinel
mock-tfstate-v2.sentinel
mock-tfstate.sentinel
sentinel.hcl

Open the sentinel.hcl file in a text editor.

Append the following configuration to the file. This configuration imports common functions and defines your my-allowed-providers policy with a hard-mandatory enforcement level.

# The repository you cloned contains some ready to use sentinel functions.
# The code block below allows you to use the tfconfig functions
# which exist in the common-functions directory
module "tfconfig-functions" {
  source = "../common-functions/tfconfig-functions/tfconfig-functions.sentinel"
}

# The code block below sets your policy for allowed providers as hard mandatory
policy "my-allowed-providers" {
  source = "./my-allowed-providers.sentinel"
  enforcement_level = "hard-mandatory"
}

Save the sentinel.hcl file.

Step 4: Test the policy

Now you can test your policy against the mock data from your workspace run.

The my-allowed-providers.sentinel policy file contains a predefined list of allowed providers.

# ...

# List of allowed providers
allowed_list = ["aws", "local", "null", "random", "terraform", "tfe"]

# ...

In this example, the mock-tfconfig-v2.sentinel file (which represents your Terraform configuration) contains the providers aws, azurerm, null, and random. The azurerm provider is not in the allowed_list.

Navigate to your policy directory.

$ cd ~/terraform-sentinel-policies/my-test-policies

Use the Sentinel CLI to apply the policy.

$ sentinel apply my-allowed-providers.sentinel

The output shows that the policy failed because the azurerm provider is not in the allowlist.

Configuration warnings detected.
Sentinel detected issues with your configuration that may be deprecated or
cause other issues when using the runtime. Please review the warnings above
and make any corrections if need be.

Execution trace. The information below will show the values of all
the rules evaluated. Note that some rules may be missing if
short-circuit logic was taken.

Note that for collection types and long strings, output may be
truncated; re-run "sentinel apply" with the -json flag to see the
full contents of these values.

The trace is displayed due to a failed policy.

Fail - my-allowed-providers.sentinel

Description:
This policy uses the tfconfig/v2 import to restrict providers to those
in an allowed list.

Print messages:
Provider azurerm has name with value azurerm that is not in the allowed list: [aws, local, null, random, terraform, tfe]

my-allowed-providers.sentinel:78:1 - Rule "main"

Value:
false

To fix this, edit your my-allowed-providers.sentinel file and add azurerm to the allowed_list.

# ...

# List of allowed providers
allowed_list = ["aws", "local", "null", "random", "terraform", "tfe", "azurerm"]

# ...

Save your changes and test the policy again.
```
$ sentinel apply my-allowed-providers.sentinel
```
The policy now passes, confirming that all providers in your configuration are on the allowlist.
```
Pass - my-allowed-providers.sentinel
```

Additional Information