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.
Sentinel only requires that a policy have a
main variable that evaluates to
a boolean value.
A valid example is shown below:
This type of minimal policy is not purely academic. In practice, simple
policies can often be reduced to a single line logical statement resulting
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
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 such as
more. Sentinel allows some operators to have aliases to promote readability
while remaining programmer-familiar, such as
== which can equivalently be
The example below verifies that all numbers in a list are even:
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:
But they may also be introduced implictly by the host system. Nomad
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.
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.
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.