» Policy Basics

Sentinel policies are easy to write while still supporting advanced constructs for creating complex policies. This page will explain the basics of writing Sentinel policies to get started. You don't need any prior Sentinel knowledge, but we do recommend reading the getting started guide and language guide after this.

Sentinel policies are text files written using the Sentinel language. The policies are evaluated top-to-bottom. The value of main after execution determines whether a policy passes or fails.

» The Simplest Policy

Sentinel only requires that a policy have a main variable that evaluates to a boolean value.

A valid example is shown below:

main = 10 > 5

This type of minimal policy is not purely academic. In practice, simple policies can often be reduced to a single line logical statement resulting in true or false. However, the expression is usually wrapped in a rule for testing reasons.

You can verify Sentinel will execute this minimal policy using the CLI:

$ sentinel apply minimal.sentinel
Pass

» Logical Expressions

Policy is at its core a set of logic: you can or can not perform some action under a certain set of circumstances. Those circumstances are logical expressions. Therefore, Sentinel policies primarily translate into logical expressions.

Detailed documentation on boolean expressions is available in the language guide.

A simple numerical comparison was seen in the first example on this page. Sentinel also provides inclusion operators (contains), any, all, and more. Sentinel allows some operators to have aliases to promote readability while remaining programmer-familiar, such as == which can equivalently be is.

The example below verifies that all numbers in a list are even:

numbers = [6, 22, 8, 4, 12]
main = all numbers as n { n % 2 is 0 }

» Variables

A policy will very often use variables. Applications such as Nomad inject variables into the global scope of a policy for making policy decisions. For example, Nomad injects the job that is being run into the policy scope. Knowing how to use variables is critical to effectively using Sentinel.

Detailed documentation on how to define and access variables is available in the language guide.

Variables can be defined and used explicitly. For example:

value = 10
main = value > 5

But they may also be introduced implictly by the host system. Nomad injects job into policies to describe the job that is being run. The policy below is a valid policy that requires a job have two task groups. Notice that job is not defined anywhere. It is implicitly inserted by the host application (in this case Nomad). Refer to the application you're writing policy for to determine if it implicitly inserts values.

main = length(job.task_groups) is 2

» And more!

The Sentinel language supports many more features such as functions, loops, and more. You can learn about all of this in the complete language guide.

The other pages in the writing policy will cover other information you need to know about writing Sentinel policies that isn't simply a language reference.