Download Policy Mock Data

»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 or public-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.