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".
In this tutorial, you will create policies and test them in the Sentinel CLI using data from the mock import data you downloaded in the previous tutorial.
You will choose the data to import based on what characteristics you want your policy to restrict. For example, you could use the tfrun
import to restrict resources based on cost estimation. You could specify a limited number of providers to use in configuration with the tfconfig/v2
import. For more information about each import type, review the Terraform Cloud docs.
If you weren't successful installing Sentinel or generating mock data, you can use pre-generated Terraform data to build a multi-requirement Sentinel policy from your web browser. Launch it here.
»Review the tfplan/v2
import mock data structure
Open the file named mock-tfplan-v2.sentinel
in your text editor. Find the resource_changes
collection. This Terraform data is a key/value collection for all of the resources in your configuration file. The data below is truncated, but your file should contain this collection with these values.
resource_changes = {
"aws_s3_bucket.demo": {
"address": "aws_s3_bucket.demo",
"change": {
"actions": [
"create",
],
"after": {
"acl": "public-read",
"bucket_prefix": null,
"cors_rule": [],
"force_destroy": true,
"grant": [],
"lifecycle_rule": [],
"logging": [],
"object_lock_configuration": [],
"replication_configuration": [],
"server_side_encryption_configuration": [],
"tags": {
"Environment": "Learn",
"Name": "HashiCorp",
},
##...
},
"deposed": "",
"index": null,
"mode": "managed",
"module_address": "",
"name": "demo",
"provider_name": "aws",
"type": "aws_s3_bucket",
},
Terraform captures the attributes of any created or modified resource in the plan. You use this data in your Sentinel policies to determine which resources or attributes to restrict while in the planning stage.
»Build your policy
At the core of a policy, Sentinel evaluates your requirements against your imported data to two possible outcomes: Pass or Fail. Sentinel defines conditions with variables and operators to store values and make comparisons of logical expressions.
Change into the local machine named learn-sentinel-policies
.
$ cd ~/learn-sentinel-policies
Create a file called restrict-s3-buckets.sentinel
. Copy and paste the policy below.
import "tfplan/v2" as tfplan
s3_buckets = filter tfplan.resource_changes as _, rc {
rc.type is "aws_s3_bucket" and
(rc.change.actions contains "create" or rc.change.actions is ["update"])
}
required_tags = [
"Name",
"Environment",
]
allowed_acls = [
"private",
"public-read",
]
bucket_tags = rule {
all s3_buckets as _, instances {
all required_tags as rt {
instances.change.after.tags contains rt
}
}
}
acl_allowed = rule {
all s3_buckets as _, buckets {
buckets.change.after.acl in allowed_acls
}
}
main = rule {
(bucket_tags and acl_allowed) else false
}
Sentinel determines what specific resources or data to evaluate from the import based on a filter
expression. In the above policy, you will find a variable identifier called s3_buckets
assigned to the filter
expression. The expression returns a map of tfplan.resource_changes
: a selector that searches the tfplan
data collection for a field called resource_changes
for S3 buckets created or updated in the plan data.
The next section of this policy contains the list of required_tags
, "Name" and "Environment", defined as variables. These are the tags your plan data are required to contain.
The two rules in this policy search for the ACLs and buckets in your variables and compare them to the values found in your tfplan/v2
import rule and the main rule. The contains
operator in the bucket_tags
rule means the bucket_tags
must contain both of the values in your variable. The in
operator in the acl_allowed
rule means at least one value in the list of your allowed_acls
variable must match your return data.
The main
rule evaluates both the bucket_tags
and acl_allowed
rules. If both are true, Sentinel allows the policy to pass. The Sentinel policy divides rules this way to keep the main rule short and allows you to evaluate your policy based on multiple rule criteria.
»Run your policy in the Sentinel CLI
Now, apply the Sentinel logic to the policy with the mock data and ensure your policy runs as expected.
In your terminal, apply the policy and provide the policy name.
$ sentinel apply restrict-s3-buckets.sentinel
Your policy will pass because your plan data meets your criteria.
»Next steps
You created and identified the parts of a Sentinel policy in this tutorial. In the next tutorial, you will write tests for this policy against Terraform Cloud data with the Sentinel CLI.