After you have successfully tested your policy with the Sentinel CLI, you are ready to apply it to a real infrastructure setting by uploading it to Terraform Cloud.
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 account with Team & Governance or a Terraform Enterprise account
- Access to the
owners
group of your Terraform organization - A GitHub account
- An AWS account to create example resources
»Write a Policy Set
Create a new file called sentinel.hcl
in your learn-sentinel-policies
directory which is the configuration file Terraform uses to apply your policies and how strictly to enforce them. If you have multiple policies in your policy repo, they must be listed here. Terraform Cloud applies them in the order they appear in this file.
policy "restrict-s3-buckets" {
enforcement_level = "hard-mandatory"
}
Add this new file to your GitHub repository.
$ git add sentinel.hcl
Commit and push the new file to your remote policy repository
$ git commit -m "Adding sentinel config file" && git push
Notice the configured enforcement_level
for the policy you created. 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 > Connect a new policy set.
Select the policy set repository you just created as the source. For more information or for other VCS connection settings, visit our documentation on VCS Integrations.
Tip: The search bar for policy repos is case sensitive.
Terraform Cloud applies policy sets either across your organization, or to specific workspaces. Choose the workspace with your example Terraform configuration sentinel-example
. Add and save to create the policy set.
Your policy sets appear in the Policy Sets Settings and you can edit the policy set permissions and scope:
»Trigger a Sentinel Check
Change into your Terraform configuration directory.
$ cd ~/learn-sentinel-tfc
Edit your main.tf
file with a failing ACL.
## ...
resource "aws_s3_bucket" "bucket" {
bucket = "${var.refix}-${random_pet.petname.id}"
- acl = "public-read"
+ acl = "public-read-write"
## ...
Run the Terraform apply command in your terminal.
$ terraform apply
Your organization policy check returns false in your terminal and you cannot apply this configuration.
Running apply in the remote backend. Output will stream here. Pressing Ctrl-C
will cancel the remote apply if it's still pending. If the apply started it
will stop streaming the logs, but will not stop the apply running remotely.
Preparing the remote apply...
To view this run in a browser, visit:
https://app.terraform.io/app/hashicorp-rachel/sentinel-example/runs/run-QuSj5offbgipboDv
Waiting for the plan to start...
Terraform v0.12.24
Configuring remote state backend...
Initializing Terraform configuration...
## ...
------------------------------------------------------------------------
Organization policy check:
========================= Results for policy set: learn-sentinel-policies ========================
Sentinel Result: false
Sentinel evaluated to false because one or more Sentinel policies evaluated
to false. This false was not due to an undefined value or runtime error.
1 policies evaluated.
## Policy 1: learn-sentinel-policies/restrict-s3-buckets (hard-mandatory)
Result: false
FALSE - ./restrict-s3-buckets.sentinel:34:1 - Rule "main"
FALSE - ./restrict-s3-buckets.sentinel:35:6 - acl_allowed
FALSE - ./restrict-s3-buckets.sentinel:28:5 - all s3_buckets as _, buckets {
buckets.change.after.acl in allowed_acls
}
FALSE - ./restrict-s3-buckets.sentinel:27:1 - Rule "acl_allowed"
Error: Organization policy check hard failed.
Revert your changes in your main.tf
file to the original parameters.
## ...
resource "aws_s3_bucket" "bucket" {
bucket = "${var.refix}-${random_pet.petname.id}"
- acl = "public-read-write"
+ acl = "public-read"
## ...
Run terraform apply
again to observe a successful policy check.
$ terraform apply
Your successful policy check returns true and gives you a prompt to approve the changes. Type yes
.
------------------------------------------------------------------------
Organization policy check:
========================= Results for policy set: learn-sentinel-policies ========================
Sentinel Result: true
This result means that Sentinel policies returned true and the protected
behavior is allowed by Sentinel policies.
1 policies evaluated.
## Policy 1: learn-sentinel-policies/restrict-s3-buckets (hard-mandatory)
Result: true
TRUE - ./restrict-s3-buckets.sentinel:34:1 - Rule "main"
TRUE - ./restrict-s3-buckets.sentinel:35:6 - acl_allowed
TRUE - ./restrict-s3-buckets.sentinel:28:5 - all s3_buckets as _, buckets {
buckets.change.after.acl in allowed_acls
}
TRUE - ./restrict-s3-buckets.sentinel:35:22 - bucket_tags
TRUE - ./restrict-s3-buckets.sentinel:15:5 - all s3_buckets as _, buckets {
all required_tags as rt {
buckets.change.after.tags contains rt
}
}
TRUE - ./restrict-s3-buckets.sentinel:27:1 - Rule "acl_allowed"
TRUE - ./restrict-s3-buckets.sentinel:14:1 - Rule "bucket_tags"
------------------------------------------------------------------------
Do you want to perform these actions in workspace "sentinel-example"?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.
Enter a value:
Note: on VCS Connected Terraform infrastructure workspaces Terraform Cloud triggers an apply operation when you merge your changes and Sentinel runs as a step between your Plan and Apply jobs.
»Destroy your infrastructure
Your apply operation creates real resources. Run the terraform destroy
command to avoid unnecessary charges to your AWS account.
$ terraform destroy
»Further reading
- Sentinel and Terraform Cloud documentation
- Experiment in the Sentinel Playground
- Sentinel Language Specification documentation
- Extending Sentinel for modules and developing plugins
- The Terraform Enterprise Provider - upload your GitHub connected policy set to your Terraform organization with Terraform Enterprise provider