Upload Your Sentinel Policy Set to Terraform Cloud
To enable Sentinel policy enforcement on your Terraform runs, you must upload your policy to your Terraform Cloud organization. In this tutorial, you will create a new Sentinel policy set in your organization, configure a workspace to apply your policy, and trigger the Sentinel policy checks.
Note
This functionality is available in the Terraform Cloud Team & Governance tier, as well as Enterprise. Organization owners can enable a 30-day free trial in their settings under "Plan & Billing".
Prerequisites
For this tutorial you will need:
- A Terraform Cloud Team & Governance tier account or a Terraform Enterprise account
- Access to the
owners
group of your Terraform organization - A GitHub account
- An AWS account to create example resources
You should also be familiar with how to configure a VCS-driven workspace and destroy Terraform Cloud workspaces.
Fork the sample repository
Fork the sample repository, which contains an example Terraform configuration to provision an EC2 instance.
Navigate to the versions.tf
file in your fork of the repository in the Github web
UI, and click the pencil icon in the top right corner.
In the backend configuration block, replace "<YOUR_TERRAFORM_ORG>"
with the name of your Terraform Cloud
organization. Commit the change.
Create a Terraform Cloud workspace
Navigate to your Terraform Cloud organization and create a new VCS-backed
workspace connected to your fork of the learn-sentinel-tfc
repository.
Configure workspace variables
Navigate to your learn-sentinel-tfc
workspace's "Variables" page.
Define a variable called instance_type
and set the value to t2.large
.
Define environment variables for your AWS_ACCESS_KEY_ID
and
AWS_SECRET_ACCESS_KEY
. Be sure to set both as sensitive
.
When complete, your variable definitions will match the following:
Fork the Sentinel policy set repository
Now fork the sample repository containing a Sentinel policy and rule enforcement definition.
The restrict-aws-instances-type-and-tag.sentinel
file contains a Sentinel
policy that defines a main
rule that consists of two other rules defining
infrastructure requirements:
mandatory_instance_tags
: Ensures that all EC2 instances have aName
tag.instance_types_allowed
: Ensures that EC2 instances are of typet2.micro
,t2.small
, ort2.medium
.
Tip
To review the policy used in this tutorial and how to use Sentinel mock data when writing Sentinel policies in more detail, visit the Write a Sentinel Policy for a Terraform Deployment tutorial.
The sentinel.hcl
file defines the level of enforcement for your Sentinel
policies. If you have multiple policies in your
policy repository, you must list them all here. Terraform Cloud applies the
policies in the order they appear in this file.
Notice the configured enforcement_level
for your policy. There are three
levels of enforcement associated with policies in Terraform Cloud: advisory,
soft mandatory, and hard mandatory. From most permissive to least permissive:
Advisory | Soft Mandatory | Hard Mandatory |
---|---|---|
Logged but allowed to pass | Teams based permissions for overrides | Default enforcement level |
Overrides logged for audit if the policy fails | This policy must pass | |
Only way to override is to explicitly remove the policy |
Connect the policy set
In the Terraform Cloud UI, navigate to "Settings" > "Policy Sets". Then, click on "Connect a new policy set" to create a new policy set.
Select your fork of the learn-sentinel-policy-upload
repository as the source. For more information or for other
VCS connection settings, visit our documentation on VCS
Integrations.
Tip
The search bar for policy repositories is case sensitive.
Terraform Cloud applies policy sets either across your organization, or to specific workspaces.
On the "Configure Settings" page:
- Select "Policies enforced on selected workspaces" under "Scope of Policies"
- Select your
learn-sentinel-tfc
workspace and click the purple "Add workspace button" - Click "Connect policy set"
Trigger a Sentinel Check
Navigate to your learn-sentinel-tfc
workspace. Select "Start new plan" from
the "Actions" menu, and run the default "Plan (most common)" option.
This plan run will fail because your configuration violates the
instance_types_allowed
rule. Terraform will not allow you to apply the plan.
Navigate to the workspace's "Variables" page and update the value of
instance_type
to t2.small
. Save the variable.
Start another plan run. This time, Sentinel will validate the proposed changes and allow you to apply the plan.
Since this is the end of the tutorial, click "Discard the run".
Delete the policy set
Navigate back to your policy set under "Settings" > "Policy Sets". Under workspaces, click "Delete policy set". Confirm by clicking "Yes, delete policy set".
Delete workspace
If you do not plan on exploring other Sentinel tutorials, you can delete the workspace you created. Terraform Cloud does not charge per workspace, so you are free to leave it if you would like.
Under your workspace's "Settings" menu, select the "Destruction and Deletion" option and then delete the workspace.
Next steps
You have now uploaded a Sentinel policy set to Terraform Cloud and triggered policy failures and passes. To learn more about Sentinel, review the following resources:
- Learn how to Generate Mock Policy Data
- Review how to Write a Sentinel Policy
- Review how to Test a Sentinel Policy
- Review Sentinel and Terraform Cloud documentation
- Experiment in the Sentinel Playground
- Review Sentinel Language Specification documentation