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 access to the
owners
group - A GitHub account
- An AWS account to create example resources
»Define your infrastructure requirements
Before you begin writing policies, define your organization's requirements for your infrastructure.
In the following tutorials, your Sentinel policy will enforce three infrastructure requirements:
- The operator performing the Terraform Cloud must add their name as a tag to the S3 bucket
- The operator must also tag the S3 bucket with the environment this bucket will service (prod, dev, or qa).
- Restrict the object access to your S3 bucket to
private
orpublic-read
only.
If your S3 buckets do not meet all of these criteria, your Terraform operation will fail with no recovery.
If you tried the embedded tutorial in the last tutorial, you ran a policy against the tfplan/v2
import. This import provides access to Terraform plan data. Sentinel can use several types of imports from the Terraform Cloud API: configuration, plan, state, and run.
The import
keyword at the top of your policy specifies the name of the import you want to use.
This policy uses the tfplan/v2
import. The /v2
imports allow Sentinel to parse the data structure introduced in Terraform 0.12.
To learn more about import
, reference the Sentinel Language Specification Documentation.
Terraform Cloud generates this import data during the terraform plan
operation CLI or a VCS backed Terraform Cloud workspace.
»Generate mock import data
In your browser, navigate to your Terraform Cloud organization and create a new workspace. Choose the CLI-driven workflow.
Name the workspace sentinel-example
and select "Create workspace."
Save the example code block which contains your remote backend configuration. You will add this to your Terraform configuration later on.
Navigate to the "Variables" page and create two Terraform variables named prefix
and region
. The prefix
in your configuration is the environment where Terraform deploys your infrastructure. Use training
for this prefix. Choose an AWS region geographically close to you like us-east-1
.
Create two environment variables for your AWS Access Key IDs and Secret Keys named AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
. For information on obtaining your AWS access keys, see the AWS documentation.
»Clone and plan the example Terraform configuration
In your local terminal, clone the example code repository here.
$ git clone https://github.com/hashicorp/learn-sentinel-tfc
Navigate to the directory.
$ cd learn-sentinel-tfc
This Terraform configuration creates an S3 bucket and deploys a web application. Open the main.tf
file and add the remote backend block to the beginning of this configuration. Update the remote backend block with your organization name.
terraform {
required_providers {
random = {
source = "hashicorp/random"
version = "3.0.1"
}
aws = {
source = "hashicorp/aws"
version = ">= 3.26.0"
}
}
required_version = "~> 0.14"
backend "remote" {
organization = "<YOUR_TERRAFORM_ORG>"
workspaces {
name = "sentinel-example"
}
}
}
Login to your Terraform Cloud organization by using the terraform login
command. This command generates an API token from your Terraform Cloud account in the Terraform Cloud UI, which you copy and paste into your local terminal when prompted. Follow the prompts to log in.
$ terraform login
Initialize the directory and run a plan.
$ terraform init && terraform plan
Terraform will confirm that the plan is running and provide you with a link to the plan in Terraform Cloud.
Running plan in the remote backend. Output will stream here. Pressing Ctrl-C
will stop streaming the logs, but will not stop the plan running remotely.
Preparing the remote plan...
To view this run in a browser, visit:
https://app.terraform.io/app/hashicorp-learn/sentinel-example/runs/run-ymMPBGiphnEELoKy
When you run a remote terraform plan
operation, Terraform Cloud generates a group of files named mocks.
Visit the link in your browser and your Terraform Cloud UI and follow the plan log. When the plan operation finishes, the Terraform Cloud UI will have a new option to "Download Sentinel Mocks".
Click "Download the Sentinel Mocks". Navigate to your downloads directory in your terminal.
»Create a local Sentinel development directory
On your local machine, create a new directory named learn-sentinel-policies
for your Sentinel development environment.
$ mkdir ~/learn-sentinel-policies
Unzip the mock data file you downloaded from Terraform and copy it to the development directory. Change your run-xxx
filename to match the one you downloaded
$ tar xzf ~/Downloads/run-ymMPBGiphnEELoKy-sentinel-mocks -C ~/learn-sentinel-policies
The files in this directory are now in your policy development environment for you to test. Change into that directory.
$ cd ~/learn-sentinel-policies
Review the mock data files available.
$ tree
.
├── mock-tfconfig-v2.sentinel
├── mock-tfconfig.sentinel
├── mock-tfplan-v2.sentinel
├── mock-tfplan.sentinel
├── mock-tfrun.sentinel
├── mock-tfstate-v2.sentinel
├── mock-tfstate.sentinel
└── sentinel.json
Open the sentinel.json
file for review. Your file contents will be similar to those below.
{
"mock": {
"tfconfig": "mock-tfconfig.sentinel",
"tfconfig/v1": "mock-tfconfig.sentinel",
"tfconfig/v2": "mock-tfconfig-v2.sentinel",
"tfplan": "mock-tfplan.sentinel",
"tfplan/v1": "mock-tfplan.sentinel",
"tfplan/v2": "mock-tfplan-v2.sentinel",
"tfrun": "mock-tfrun.sentinel",
"tfstate": "mock-tfstate.sentinel",
"tfstate/v1": "mock-tfstate.sentinel",
"tfstate/v2": "mock-tfstate-v2.sentinel"
}
}
»Review the mock data files
Each of the mock data files contains information Terraform captures during the plan operation. Sentinel parses these files when you import them into your policies. Which mock data file you import depends on the type of restrictions or requirements you implement in your policies.
Sentinel uses the four Terraform Cloud imports to define policy rules: plan
, configuration
, state
, run
, and a library of standard imports. The types of data contained in each of these imports are:
tfplan
- This provides access to a Terraform plan, the file Terraform creates as a result of a plan. The plan data represent the changes that Terraform needs to make to infrastructure to reach the desired state represented by the configuration.tfconfig
- This provides access to data describing a Terraform configuration, the set of ".tf" files that you write to describe the desired infrastructure state.tfstate
- This provides access to data describing the Terraform state, the file Terraform uses to map real-world resources to your configuration.tfrun
- This provides access to data associated with a run in Terraform Cloud, such as the run's workspace.
In the Terraform workflow, your terraform plan
command creates an ephemeral execution plan to determine what operations run against your infrastructure. The output of terraform plan
in the CLI represents what your configuration creates when you approve the plan. For a policy like the one in your requirements above, you would choose the tfplan
import in your Sentinel policy files to determine if the planned resources meet your criteria.
»Next steps
In the next tutorial, you will use this import data in a Sentinel policy.