The integrated Sentinel language and policy framework is embedded into Terraform Cloud to enable fine-grained, logic-based policy decisions. A Sentinel Policy is a guard-rail for Terraform deployments and defines the circumstances which certain behaviors are allowed.
Policies are verified with the Sentinel CLI tool, a command-line interface which will let us apply instant rule validation locally without kicking off a Terraform plan. Sentinel can also use external information for policy decisions with imports from other resources. In this guide, you will learn how Sentinel can be used to enhance your current workflows and install the Sentinel CLI. Over the course of this track you will learn how to use the Sentinel CLI to write policies for Terraform Cloud, how to test Sentinel policies with mock data, and how to import policy sets to your Terraform Cloud organization.
Broadly, Sentinel functions as a safeguard, preventing Terraform from performing specific actions as defined by Sentinel policies. Sentinel also allows cost-centric policies to be created and then automatically enforced in the Terraform workflow. Administrators then have the ability to approve significant changes or to completely prevent specific workspaces from exceeding predetermined thresholds. For more information, review the Cost Estimation announcement.
Most systems today have some degree of access control. You are able to define identities and what they have access to. These ACL systems solve an immediate and necessary problem of locking down a system in very broad strokes. Sentinel is a reusable system for more advanced software policy decisions.
Sentinel enables:. Sentinel enables fine-grained behavior such as disallowing a certain API call when specific parameters are present. Logic-Based Policy : You can write policy using full conditional logic. For example, you may only allow a certain application behavior on Monday to Thursday unless there is a manager override.
Advisory policies warn if they fail, soft mandatory policies can have their failures overridden, and hard mandatory policies must pass for the action to continue.
Having this as a built-in concept enables you to model policy more accurately and completely for your organization. To install the Sentinel CLI, find the appropriate package for your system and download it.
The CLI is packaged as a zip archive. After downloading Sentinel, unzip the package.
The CLI runs as a single binary named sentinel. Any other files in the package can be safely removed and Sentinel will still function. After installing Sentinel CLI, verify the installation was successful by opening a new terminal session and checking that the sentinel binary is available. By executing sentinelyou should see help output similar to the following:.
If you get an error that the binary could not be found, then your PATH environment variable was not setup properly. Please go back and ensure that your PATH variable contains the directory where Sentinel was installed. Virtual Event.This guide provides instruction for writing and testing Sentinel policies for Terraform. Download Guide. Sentinel allows customers to implement governance policies as code in the same way that Terraform allows them to implement infrastructure as code.
Sentinel policies define rules that restrict the provisioning of resources by Terraform configurations.
Terraform enforces Sentinel policies between the plan and apply phases of a run, preventing out of policy infrastructure from being provisioned.
Unless overridden by an authorized user, only plans that pass all Sentinel policies checked against them are allowed to proceed to the apply step. This guide discusses the types of Sentinel policies in Terraform and lays out a general methodology for writing and testing Sentinel policies for Terraform. It also covers useful Sentinel operators, functions, and concepts, and how to use the Sentinel Simulator to test your policies. It also discusses the differences between policies meant for use with Terraform 0.
Finally, it includes examples and exercises to practice writing Sentinel policies and test your understanding of them. There are essentially three types of Sentinel policies for Terraform which correspond to these three Sentinel imports: tfplantfconfigand tfstate.
The first and most common type of policy uses the tfplan import to restrict attributes of specific resources or data sources. The second type uses the tfconfig import to restrict the configuration of Terraform modules, variables, resources, data sources, providers, provisioners, and outputs. The third type uses the tfstate import to check whether any previously provisioned resources, data sources, or outputs have attribute values that are no longer allowed by your governance policies.
We expect additional Sentinel imports to be added to Terraform in the near future to allow Sentinel policies to inspect workspace metadata attributes and cost estimates.
This guide focuses primarily on the first type of Sentinel policy that uses the tfplan import, but we do cover the other imports in later sections. You can manually test policies against actual Terraform code by using the Terraform UI or the Terraform CLI with the remote backend to trigger runs against workspaces that use that Terraform code.
You can use the Sentinel Simulator with mocks generated from Terraform plans. In the first two methods, you are executing plans against your Terraform code and then testing the Sentinel policies against the generated plans. In the third method, you only use Terraform to generate your mocks.
Because this method employs simulated testing, we recommend deploying policies to a Terraform server and running final testing against actual Terraform plans as well. While the first method is sometimes easier for new Terraform users to start with, it does have some disadvantages:.
Each test will take longer than if you used the Sentinel Simulator since Terraform has to run a plan against your workspace before it even invokes any Sentinel policies.
Unless you use Terraform policy sets carefully, you might end up running multiple policies for each test even though you only care about the one you are testing. If you use the Terraform UI, all the runs you do to test your policy will end up in the histories of your workspaces and you will need to discard each run you do that passes your policies. Using the Terraform CLI with the remote backend instead of the Terraform UI avoids the fourth problem because it runs speculative plans which cannot be applied and do not show up in the workspace history in the Terraform UI.
This means that you do not need to discard any runs and won't have a long history of them in your workspaces. In this section, we lay out a basic methodology for restricting specific attributes of specific Terraform resources and data sources in Sentinel policies.
We initially focus on resources but will cover data sources later. Before proceeding, we want to make an important point about the scope of these Sentinel policies within Terraform: They are intended to ensure that specific attributes of resources are included in all Terraform code that creates those resources and have specific values.
They are not intended to ensure that the specified values are actually valid. In fact, invalid values will cause the plan or apply to fail since Terraform and its providers ensure that attribute values are legitimate.
Together, Sentinel and Terraform do ensure that all resources have attribute values that are both compliant with governance policies and valid. In general, when you write a Sentinel policy to restrict attributes of Terraform resources or data sources, you should have the following documents at hand:.
The tfplan import documentation. Documentation from the cloud service or other technology vendor about the resource that is being created.A mock simulates what the output of a Terraform plan would produce. Since there are four Terraform Cloud Sentinel imports tfplan, tfstate, tfconfig, and tfrunthere are four corresponding mocks. We'll use the tfconfig mock. Each test of a policy with the Sentinel CLI with mocks is faster since the test will not run a Terraform plan.
Using the CLI avoids having to discard runs against workspaces and avoids having those runs in your workspace history. If you want to automate testing of policies that need frequent changes, then using the CLI is the best choice since each test will be faster and will not place extra load on your Terraform Cloud server.
Using the CLI with mocks carries the potential risk that you might make a mistake due to human error and end up with an invalid test of your Sentinel policy.
In contrast, testing policies against actual Terraform code gives users more certainty that their Sentinel policies are really behaving as intended. In the near future, HashiCorp expects to release a mock generator that will make the creation of mocks for the four Terraform Sentinel imports less error-prone.
At that point, using the Sentinel CLI with mocks will become much easier. Terraform Cloud makes it easy for users to generate the tfplan, tfconfig, tfstate, and tfrun mocks against any plan they have run in the past seven days. In the TFC UI, you can select a run from a workspace, expand the plan, and click the "Download Sentinel mocks" button to download a tar file with the mocks.
Sentinel and Terraform Enterprise demo
Create a Sentinel CLI configuration file called sentinel. You can now use the CLI to run your policy against the mock data by running the command sentinel apply check-policy. You should see one line of output with "Pass" written in green. You can make the CLI print a full trace more like what you would see if using the Sentinel policy in TFE by adding the -trace option before the name of the policy.
In this case, the command would be sentinel apply -trace check-policy. You should see output like this with some extra text that we have trimmed :. Writing and running test suites against your Sentinel policies can also be helpful in cases where you do not have mock data. In this example, our Sentinel policy will test that any AWS instances are sized at t2.
Save this policy locally in the root of a directory called policies as instance. This policy has two rules, the main rule and the instance rule.
Rules can be composed of other rules. When debugging or testing a policy, it is much easier to work with several small rules rather than one rule that has many conditions in it.Introduction to Sentinel, HashiCorp Policy as Code Framework
We should first implement a test that defines global values expected by the policy. We can pre-populate the variables that are passed in to the policy. Then we can specify whether the policy should pass or fail based on the test data we've provided.
In your policies directory, create a directory called test.Learn the Learn how Terraform fits into the. Learn more about Terraform Cloud pricing here. Note: This is documentation for the next version of the tfplan Sentinel import, designed specifically for Terraform 0. This import requires Terraform 0. A Terraform plan is the file created as a result of terraform plan and is the input to terraform apply.
The plan represents the changes that Terraform needs to make to infrastructure to reach the desired state represented by the configuration. This collection presents the Terraform state as how it might look after the plan data is applied, but is not guaranteed to be the final state. This allows direct, low-level access to the JSON data, but should only be used in complex situations where the higher-level collections do not serve the purpose.
These collections are specifically designed to be used with the filter quantifier expression in Sentinel, so that one can collect a list of resources to perform policy checks on without having to write complex discovery code.
You can add specific attributes to the filter to narrow the search, such as the module address, or the operation being performed. The following code would return resources in a module named foo only, and further narrow the search down to only resources that were being created:. As mentioned above, actions show up within the actions field of a change representation and indicate the type of actions being performed as part of the change, and the order that they are being performed in.
The actions field is a list, as some real-world actions are actually a composite of more than one primitive action.
At this point in time, this is generally only applicable to resource replacement, in which the following action orders apply:. Note that, in most situations, the plan will list all "changes", including no-op changes. This makes filtering on change type crucial to the accurate selection of data if you are concerned with the state change of a particular resource.
To filter on a change type, use exact list comparison. For example, the following example from the Import Overview filters on exactly the resources being created only :. The exact attribute changes for a particular operation are outlined in the before and after attributes. For resources, if a field cannot be found in afterit generally means one of two things:. This can be used to do version validation. NOTE: The above example will give errors when working with pre-release versions example: 0.
Future versions of this import will include helpers to assist with processing versions that will account for these kinds of exceptions. The variables collection is a collection of the variables set in the root module when creating the plan. This is the best prediction of what the state will look like after the plan is executed. This includes all resources that have been found in the configuration and state, regardless of whether or not they are changing.
This collection is indexed on the complete resource address as the key. This collection is indexed by the name of the output. The fields in a collection value are below:.Explore Sentinel, HashiCorp's policy-as-code framework, and its integration into Terraform Enterprise.
Sentinel is an embeddable policy as code framework to enable fine-grained, logic-based policy decisions that can be extended to source external information to make decisions. This is the Terraform Enterprise UI. As you can see, I've already created a workspace called Sentinel demo. I haven't run any Terraform plans yet. If we come over into the console, you can see that I have a relatively simple AWS configuration in my Terraform config.
This configuration is already hooked up in my workspace in Terraform Enterprise. Come back over here into the UI and enter our organization's settings page, you'll see on the left-hand side we have a new item called Sentinel Policy. This allows us to create organization level policies. Organization level policies apply to all workspaces within that organization.
Let's create a new policy. The policy name is a simple string identifier to identify the policy. We'll call this one all-instances-have-tags. The enforcement mode determines what happens in policy failure scenarios. We're going to choose advisory to start, which simply logs the errors and moves on.
Policy code is where we enter the Sentinel policy. This policy uses the tfplan import to grant us access to the Terraform plan data. Down here in the main rule, we iterate all AWS instance resources and check that each one of them has at least one tag.
If we save this policy, we can head over into the workspace view to then queue our first plan. During the run, we should see the plan run normally. Shortly after, we should see it enter the new policy check phase. This is where the policy is actually enforced. You can see that here we have an advisory failure on the organization policy.
If we expand the output, we can see which policy it was that has the failure.We are proud to announce that the next generation of Sentinel imports for Terraform Cloud are almost here!
This is a completely re-designed import API meant to better reflect Terraform 0. To get some context around why we've released a new version of the imports, let's discuss the history of the old Sentinel imports, some of the issues that have arisen from their use, and how the new imports, along with recent changes in the Sentinel runtime, have been designed to address some of these shortcomings.
Terraform Cloud's Sentinel imports were originally designed around the lower-level details of a Terraform plan. The imports hooked directly into the raw configuration, binary plan, and lower-level JSON state—with most of this data being provided by the singular binary plan data for a particular run within Terraform Cloud. While this made implementing the imports relatively straightforward, the user experience has been a bit more complicated and exposed certain shortcomings of Terraform's pre Additionally, due to mostly following convention with how modules and data was laid out in the binary plan, module traversal has historically been done with module traversal functions.
These ultimately need to be combined with other functions in order to effectively extract subject resources, creating significant boilerplate examples can be seen in the example policies found in our terraform-guides repository. When Terraform 0. Reflective of Terraform 0. However, in the spirit of backwards compatibility, we ultimately shimmed this new data format on to the existing Sentinel API, meaning that none of these benefits have been able to be realized—until now.
If your workspace is running a version of Terraform 0. Note that these imports are in technology preview and are not yet fully stable. This plan may specifically be tied to your workspace's Terraform version, so it will be important to note for your specific organization's policy sets. One of the most important changes is the restructuring of the data layout into a series of collections in a way that is easily traversed with the recently added Sentinel filter expression.
This is a direct response to the large amount of boilerplate we were seeing in policies that were designed for both resource discovery and attribute filtering. As can be seen in the policy, there is a lot of code that is required for not only module traversal, but also address construction and filtering of resources based on attribute.
This code can now be significantly simplified. With some slight modifications, the entirety of the discovery can be fit into a single filter expression, giving us this policy, complete with preservation of the reporting of violations:.
This format is much more expressive than the pre First off, the type of change is now expressed as a list of operations, versus a set of flags. This makes it easier to filter out specific kinds of changes, and identify certain operations, such as create-before-destroy operations.
The below filter would, for example, filter out all resources that are being created, regardless of if they are being replaced, or created new:. At the same time, this filter will select instances that are only being created, but not replaced:. Additionally, the new change structure addresses the long-running issues relating to structure of changes and typing of changes.
Rather than a flat map of diff sets, attributes are now organized into the before and after values within the change, and are fully typed, meaning that you will now see numbers and booleans be represented by their correct types, and lists and maps will be properly expanded.
An expression such as the following will now work properly:. We also know that some advanced uses of Sentinel may call for having access to the raw data produced by the JSON output, or there might be scenarios that the higher-level collections might not cover.
This data is presented as a map, so no additional processing is necessary to access the fields via Sentinel itself.Watch an Introduction to Sentinel with Armon Dadgar. Sentinel is an embeddable policy as code framework to enable fine-grained, logic-based policy decisions that can be extended to source external information to make decisions. Treat policy like an application — version control, pull review, and automate tests. Use real programming constructs to determine policy decisions beyond the limited constraints of typical ACL systems.
Reject actions on any available input rather than coarse-grained read, write, and admin policies. Make policy decisions based on the condition of other values.
Sentinel is embedded to enable policy enforcement in the data path to actively reject violating behavior instead of passively detecting. Advisory, soft-mandatory, and hard-mandatory levels allow policy writers to warn on or reject offending behavior. Source external information to make holistic policy decisions. For example, Terraform cannot execute while Consul health checks are failing. Ensure infrastructure changes are within business and regulatory policy on every infrastructure provider.
Infrastructure as Code was the first phase, which enables codification and automation for the four main components of infrastructure — provision, secure, connect, and run. Infrastructure as Code empowers more users to create and manage infrastructure; however, that comes with risks as less experienced users could make significant mistakes that impact business operations.
Policy as code limits exposure by codifying business and regulatory policies to ensure infrastructure changes are safe.
Together Infrastructure as Code and Policy as code empower users to safely and quickly provision, secure, connect, and run any infrastructure for any application. Read the announcement. Try Sentinel Explore Docs. What is Sentinel Sentinel is an embeddable policy as code framework to enable fine-grained, logic-based policy decisions that can be extended to source external information to make decisions. Policy as code Treat policy like an application — version control, pull review, and automate tests.
How AGL Uses HashiCorp Terraform Enterprise and Sentinel to Enable Cloud Native Capabilities
Fine-grained, condition-based policy Reject actions on any available input rather than coarse-grained read, write, and admin policies. Embedded Sentinel is embedded to enable policy enforcement in the data path to actively reject violating behavior instead of passively detecting. Multiple enforcement levels Advisory, soft-mandatory, and hard-mandatory levels allow policy writers to warn on or reject offending behavior. External information Source external information to make holistic policy decisions.
Multi-cloud compatible Ensure infrastructure changes are within business and regulatory policy on every infrastructure provider. Policy as Code in Terraform Enterprise. Do not allow resources to be provisioned without tags Only provision staging resources in us-west and production resources in us-east Do not allow AWS security groups to have egress set to 0. Policy as Code in Vault Enterprise.
Ensure that modification of critical data can only be performed by authorized sysops with valid MFA Require LDAP logins to come from internal IP space and successfully pass a Ping MFA check Applied to all endpoints in response to a breach, ensure that any token generated more than four hours ago cannot be used Code Sample. Policy as Code in Nomad Enterprise. Policy as Code in Consul Enterprise. Consul keys can only be updated during business hours Code Sample.
Policy as code is the next phase of infrastructure automation Infrastructure as Code was the first phase, which enables codification and automation for the four main components of infrastructure — provision, secure, connect, and run.
Watch Overview Video. Get in touch or start exploring the documentation. Talk to Sales Explore Docs.