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".
Testing Sentinel policies with the built-in testing suite ensures that you account for all possible behaviors in your policy, and that Sentinel operates as expected when Terraform Cloud applies these policies within your organization.
Writing tests gives you confidence in your policy because you accounted for failures in your development process.
»Prerequisites
For this tutorial, you will need:
»Clone example Terraform configuration
In your terminal, clone the example code repository. This repository contains an example Sentinel policy and mock data.
Navigate to the directory.
»Review Sentinel policy
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.
Open the restrict-aws-instances-type-and-tag.sentinel file, which contains
the Sentinel policy.
This Sentinel policy defines a main rule that consists of two other rules defining infrastructure requirements:
mandatory_instance_tags: Ensures that all EC2 instances have aNametag.instance_types_allowed: Ensures that EC2 instances are of typet2.micro,t2.small, ort2.medium.
If your new or modified EC2 instances do not meet all of these criteria, Sentinel will flag the
run with a FAIL.
»Create passing mock data
The configuration in this repository contains pre-generated Sentinel mock data from a Terraform plan run that satisfies the policy defined. You will use this data as the base for your passing and failing Sentinel test cases.
Copy your known passing mock data to a new file with pass in the filename.
Tip: If you are writing your policy against infrastructure that already exists, that infrastructure may not actually comply with your policy. Run sentinel apply <policy_name> in your local CLI on unedited import data to identify failing data, and edit the data to create your passing test mock..
»Write a passing test case
Sentinel requires that your folder structure
match test/<policy>/*.json, where <policy> is the name of your policy file
without the file extension.
Create a new folder named test with a subdirectory named
restrict-aws-instances-type-and-tag.
Navigate to the subdirectory.
Create a new file named pass.hcl, then add the following configuration to the
file.
This passing test case uses the passing mock data and expects both the
instance_type_allowed and mandatory_instance_tags rules to pass.
»Create failing mock data
To write a failing test case, you need to create a mock import data file with values outside your criteria, to simulate infrastructure that does not comply with the policy.
Change into your root learn-sentinel-write-policy directory.
Copy the mock-tfplan-v2.sentinel file to a new file with "fail" in the filename.
Open the failing mock data file in your text editor and look for the
resource_changes collection.
Tip: Open the failing mock data file in a visual editor like VSCode and hide the first collection in the file called planned_values to find your resource_changes quickly.
In the resource_changes.aws_instance.ubuntu.change.after block, change:
instance_typetot2.large, andtagsfromNametoNumber.
»Write a failing test case
Change back into your test/restrict-aws-instances-type-and-tag directory.
Create a new file named fail.hcl, then add the following configuration to the file.
This configuration passes the failing mock data to Sentinel and asserts that it should fail the policy.
»Test your policy in the Sentinel CLI
Change into your root learn-sentinel-policies directory.
Now use the test command to run the test cases you defined for your policy.
Sentinel automatically loads the test cases in the /test directory and passes the
subdirectory that matches the policy name to the test command.
Both your passing and failing tests return PASS because both test
cases evaluated to their expected values — the passing scenario evaluated to
true and the failing scenario evaluated to false.
Run the test with the -verbose flag to get more information about the test.
The -verbose flag returns the steps at which each test passes or fails your criteria.
»Next steps
You created test policies and ran test cases using the Sentinel CLI. To learn more about Sentinel, review the following resources:
- Learn how to Generate Mock Policy Data
- Review how to Write a Sentinel Policy
- Learn how to Upload a Sentinel Policy Set to Terraform Cloud
