Writing and Testing Sentinel Policies for Terraform Enterprise

Introduction

I’m excited to announce the publication of my Writing and Testing Sentinel Policies for Terraform Enterprise Guide to HashiCorp’s Resource Library. This comprehensive guide teaches you how to write and test governance policies that restrict the infrastructure provisioned by Terraform Enterprise. The guide includes many examples (for AWS, Google, and Azure) and five exercises that are carefully matched to the sections of the guide that precede them. I’ve shared most of what I’ve learned about writing and testing Sentinel policies during the past year and a half while working as a solutions engineer at HashiCorp.

Sentinel

HashiCorp’s Sentinel is a language and framework that implements Policy as Code with fine-grained, logic-based policy decisions just as HashiCorp’s Terraform implements Infrastructure as Code. Terraform Enterprise (TFE) enforces Sentinel policies between the plan and apply stages of runs, ensuring that resources can only be created or modified if all policies checked against them pass or are overridden by authorized users. Using Sentinel policies is much more reliable than using policy spreadsheets since the policies are codified and executed as part of your provisioning pipeline.

What the Guide Covers

The guide covers the following topics:

• Types of Sentinel policies and imports in TFE
• Three Methods for testing TFE Sentinel policies
• A 4-step methodology for restricting resources with the tfplan import
• Some useful Sentinel operators, functions, and concepts
• Using the Sentinel print function in policies for debugging and clarity
• Evaluating data sources in Sentinel policies with the tfstate import
• Dealing with lists, maps, and blocks that occur in Terraform code
• Using TFE’s tfconfig import
• Using the Sentinel Simulator with Sentinel mocks

In this blog post, I only give a brief synopsis of these topics. The guide goes into much more detail.

There are three primary types of Sentinel policies in Terraform Enterprise, corresponding to the tfplan, tfstate, and tfconfig Sentinel imports mentioned above.

Sentinel polices written for use with TFE can be tested against actual Terraform code by triggering runs against TFE workspaces. One method does this manually while a second method automates the process. A third method tests TFE Sentinel policies against mocked data with the Sentinel Simulator.

The four steps of the guide’s methodology for restricting attributes of resources with the tfplan import are:

1. Create Terraform configurations (code) that create instances of the resource you want to restrict with the TFE Sentinel policy you will write.
2. Create TFE workspaces that use your Terraform configurations.
3. Create a new TFE Sentinel policy that restricts specific resource attributes.
4. Test your Sentinel policy against your workspaces by triggering runs against them, either in the TFE UI or with the Terraform CLI.

The guide covers the following useful Sentinel concepts: rules, for loops, any/all expressions, set operators, comparison operators, logical operators, the matches operator (which does regex comparisons), the else operator (which avoids undefined expressions), the built-in length function, the strings import, and the types import.

The guide also shows you the following:

• How to use the Sentinel print function to debug errors in Sentinel policies as you are writing and testing them.
• How to restrict Terraform data sources with the tfstate import.
• How to use the Terraform code with the tfconfig import.
• How to restrict attributes of resources that are nested inside lists, maps, or blocks.

Finally, the guide shows you how to use the Sentinel Simulator to test your TFE Sentinel policies with TFE Sentinel mocks without actually running your Terraform code on a TFE server. The mocks give Sentinel data that simulate what an actual terraform plan would provide. There are three kinds of TFE Sentinel mocks, corresponding to the three TFE Sentinel imports. The guide gives an example of using the tfconfig mock.

I hope you do read the entire guide and find it and the five exercises useful.