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.
»Create passing mock data
Although your policy passes in the Sentinel CLI, you need to also write an explicit passing test. Copy your known passing mock data to a new file with "pass" in the filename.
$ cp mock-tfplan-v2.sentinel mock-tfplan-pass-v2.sentinel
Tip: If you are writing your policy against infrastructure that already exists, that infrastructure might 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
In the passing case file, supply Sentinel the path to the passing mock data you created, which ensures the main rule will evaluate it as true.
Create a new folder called test
and a subfolder for the policy name restrict-s3-buckets
. Sentinel requires your folder structure match test/<policy>/*.json
where <policy>
is the name of your policy file without the file extension.
$ mkdir -p ~/learn-sentinel-policies/test/restrict-s3-buckets && cd $_
Create a new file at ./test/restrict-s3-buckets/pass.json
. Copy and paste the contents below and save the file.
{
"mock": {
"tfplan/v2": "../../mock-tfplan-pass-v2.sentinel"
},
"test": {
"main": true
}
}
»Create failing mock data
To write a failing test case, you need to create a mock import data file with values outside of your criteria, to simulate infrastructure that doesn’t comply with the policy. Copy the mock-tfplan-v2.sentinel
file to a new file with "fail" in the filename.
$ cp mock-tfplan-v2.sentinel mock-tfplan-fail-v2.sentinel
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.
Edit the value for resource_changes.aws_s3_bucket.demo.change.after.acl
to public-read-write
.
resource_changes = {
"aws_s3_bucket.demo": {
"address": "aws_s3_bucket.demo",
"change": {
"actions": [
"create",
],
"after": {
- "acl": "public-read",
+ "acl": "public-read-write",
Remove the identifiers for resource_changes.aws_s3_bucket.demo.change.after.tags
, Name
& Environment
and replace the value of the "Name" and "Environment" tags
with "NotName" and "NotEnvironment" and save your changes in your `learn-sentinel-policies' directory.
resource_changes = {
"aws_s3_bucket.demo": {
"address": "aws_s3_bucket.demo",
"change": {
"actions": [
"create",
],
"after": {
##...
- "tags": {
- "Name": "HashiCorp",
- "Environment: "Learn"
- },
+ "tags": {
+ "NotName": "HashiCorp",
+ "NotEnvironment: "Learn"
+ },
»Write a failing test case
Sentinel requires passing and failing test files in a test
directory, under a subdirectory for the policy file name. In the failing case file, supply Sentinel the path to the failing mock data you created.
Create a new file called fail.json
in the test/restrict-s3-buckets
directory. Copy and paste the contents below and save the file.
{
"mock": {
"tfplan/v2": "../../mock-tfplan-fail-v2.sentinel"
},
"test": {
"main": false
}
}
»Test your policy in the Sentinel CLI
You created passing and failing mock import data to mimic scenarios in which your policy should pass or fail. Sentinel validates these with the test
command. Change into your root policy directory.
$ cd ~/learn-sentinel-policies
Test the sentinel policy providing the policy file. Sentinel will automatically find the test cases in the /test
directory and the subdirectory that matches the policy name.
$ sentinel test restrict-s3-buckets.sentinel
Both your passing and failing tests will return PASS
because the scenario for success validated to true and the scenario for failure validated to false - the expected values from the test cases.
To see more information about the test data, add the -verbose
flag in your command.
$ sentinel test -verbose restrict-s3-buckets.sentinel
The -verbose
flag returns the steps at which each test passes or fails your criteria.
»Check your policy and tests into source control
Create a new repository on GitHub called learn-sentinel-policies
. To avoid errors, do not initialize the new repository with README, license, or gitignore files. You can add these files after you push your project to GitHub.
Warning: Mock data can contain sensitive values from state. Do not copy these from your source control repository before you run your git add
command.
Remove your mock data files from your local repository.
$ rm mock-tfconfig.sentinel mock-tfplan-pass-v2.sentinel mock-tfrun.sentinel mock-tfconfig-v2.sentinel mock-tfplan.sentinel mock-tfstate.sentinel mock-tfplan-fail-v2.sentinel mock-tfplan-v2.sentinel mock-tfstate-v2.sentinel sentinel.json
Initialize your local directory as a git
repo.
$ git init
Add the tests and policy to your new repository.
$ git add .
Commit with an initial upload message.
$ git commit -m "Initial upload"
Add your new repository to your local repository and validate your new remote repository link.
$ git remote add origin https://github.com/<YOUR-GITHUB-USERNAME>/learn-sentinel-policies && git remote -v
Push your policy and tests to your remote repository.
$ git push -u origin master
»Next steps
You created test policies and ran test cases with the Sentinel CLI. In the following tutorial, you will upload your tested policies to your Terraform Cloud organization.