open-nomad/website/source/guides/sentinel-policy.html.markdown

---
layout: "guides"
page_title: "Sentinel Policies"
sidebar_current: "guides-sentinel"
description: |-
 Nomad integrates with Sentinel for fine grained policy enforcement. Sentinel allows operators to express their policies as code, and have their policies automatically enforced. This allows operators to define a "sandbox" and restrict actions to only those compliant with policy. The Sentinel integration builds on the ACL System.
---

# Sentinel Policies

Nomad integrates with Sentinel for fine grained policy enforcement. Sentinel allows operators to express their policies as code, and have their policies automatically enforced. This allows operators to define a "sandbox" and restrict actions to only those compliant with policy. The Sentinel integration builds on the [ACL System](/guides/acl.html).

~> **Enterprise Only!** This functionality only exists in Nomad Enterprise.
This is not present in the open source version of Nomad.

# Sentinel Overview

Sentinel integrates with the ACL system, and provides the ability to do fine grained policy enforcment. Users must have appropriate permissions to perform an action, and then are subject to any applicable Sentinel policies:

![Sentinel Overview](/assets/images/sentinel.jpg)

 * **Sentinel Policies**. Policies are able to introspect on request arguments and use complex logic to determine if the request meets policy requirements. For example, a Sentinel policy may restrict Nomad jobs to only using the "docker" driver, or prevent jobs from being modified outside of business hours.

 * **Policy Scope**. Sentinel policies declare a "scope", which determines when the policies apply. Currently the only supported scope is "submit-job", which applies to any new jobs being submitted, or existing jobs being updated.

 * **Enforcement Level**. Sentinel policies support multiple enforcement levels. The `advisory` level emits a warning when the policy fails, while `soft-mandatory` and `hard-mandatory` will prevent the operation. A `soft-mandatory` policy can be overridden if the user has necessary permissions.

### Sentinel Policies

Each Sentinel policy has a unique name, an optional description, applicable scope, enforcement level, and a Sentinel rule definition.
If multiple policies are installed for the same scope, all of them are enforced and must pass.

Sentinel policies _cannot_ be used unless the ACL system is enabled.

### Policy Scope

Sentinel policies specify an applicable scope, which limits when the policy is enforced. This allows policies to govern various aspects of the system.

The following table summarizes the scopes that are available for Sentinel policies:

| Scope      | Description                                           |
| ---------- | ----------------------------------------------------- |
| submit-job | Applies to any jobs (new or updated) being registered |


### Enforcement Level

Sentinel policies specify an enforcement level which changes how a policy is enforced. This allows for more flexibility in policy enforcement.

The following table summarizes the enforcement levels that are available:

| Enforcement Level | Description                                                            |
| ----------------- | ---------------------------------------------------------------------- |
| advisory          | Issues a warning when a policy fails                                   |
| soft-mandatory    | Prevents operation when a policy fails, issues a warning if overridden |
| hard-mandatory    | Prevents operation when a policy fails                                 |

The [`sentinel-override` capability](/guides/acl.html#sentinel-override) is required to override a `soft-mandatory` policy. This allows a restricted set of users to have override capability when necessary.

## Multi-Region Configuration

Nomad supports multi-datacenter and multi-region configurations. A single region is able to service multiple datacenters, and all servers in a region replicate their state between each other. In a multi-region configuration, there is a set of servers per region. Each region operates independently and is loosely coupled to allow jobs to be scheduled in any region and requests to flow transparently to the correct region.

When ACLs are enabled, Nomad depends on an "authoritative region" to act as a single source of truth for ACL policies, global ACL tokens, and Sentinel policies. The authoritative region is configured in the [`server` stanza](/docs/agent/configuration/server.html) of agents, and all regions must share a single a single authoritative source. Any Sentinel policies are created in the authoritative region first. All other regions replicate Sentinel policies, ACL policies, and global ACL tokens to act as local mirrors. This allows policies to be administered centrally, and for enforcement to be local to each region for low latency.

## Configuring Sentinel Policies

Sentinel policies are tied to the ACL system, which is not enabled by default.
See the [ACL guide](/guides/acl.html) for details on how to configure ACLs.

## Example: Installing Sentinel Policies

This example shows how to install a Sentinel policy. It assumes that ACLs have already
been bootstrapped (see the [ACL guide](/guides/acl.html)), and that a `NOMAD_TOKEN` environment variable
is set to a management token.

First, create a Sentinel policy, named `test.sentinel`:

```
# Test policy always fails for demonstration purposes
main = rule { false }
```

Then, install this as an `advisory` policy which issues a warning on failure:

```
$ nomad sentinel apply -level=advisory test-policy test.sentinel
Successfully wrote "test-policy" Sentinel policy!
```

Use `nomad init` to create a job file and attempt to submit it:

```
$ nomad init
Example job file written to example.nomad

$ nomad run example.nomad
Job Warnings:
1 warning(s):

* test-policy : Result: false (allowed failure based on level)

FALSE - test-policy:2:1 - Rule "main"


==> Monitoring evaluation "f43ac28d"
    Evaluation triggered by job "example"
    Evaluation within deployment: "11e01124"
    Allocation "2618f3b4" created: node "add8ce93", group "cache"
    Allocation "5c2674f2" created: node "add8ce93", group "cache"
    Allocation "9937811f" created: node "add8ce93", group "cache"
    Evaluation status changed: "pending" -> "complete"
==> Evaluation "f43ac28d" finished with status "complete"
```

We can see our policy failed, but the job was accepted because of an `advisory` enforcement level.

Next, let's change `test.sentinel` to only allow "exec" based drivers:

```
# Test policy only allows exec based tasks
main = rule { all_drivers_exec }

# all_drivers_exec checks that all the drivers in use are exec
all_drivers_exec = rule {
    all job.task_groups as tg {
        all tg.tasks as task {
            task.driver is "exec"
        }
    }
}
```

Then install the updated policy at a soft mandatory level:

```
$ nomad sentinel apply -level=soft-mandatory test-policy test.sentinel
Successfully wrote "test-policy" Sentinel policy!
```

With our new policy, attempt to submit the same job, which uses the "docker" driver:

```
$ nomad run example.nomad
Error submitting job: Unexpected response code: 500 (1 error(s) occurred:

* test-policy : Result: false

FALSE - test-policy:2:1 - Rule "main"
  FALSE - test-policy:6:5 - all job.task_groups as tg {
	all tg.tasks as task {
		task.driver is "exec"
	}
}

FALSE - test-policy:5:1 - Rule "all_drivers_exec"
)
```

Because our policy is failing, the job was rejected. Since this is a `soft-mandatory` policy,
submit with the `-policy-override` flag set:

```
$ nomad run -policy-override example.nomad
Job Warnings:
1 warning(s):

* test-policy : Result: false (allowed failure based on level)

FALSE - test-policy:2:1 - Rule "main"
  FALSE - test-policy:6:5 - all job.task_groups as tg {
	all tg.tasks as task {
		task.driver is "exec"
	}
}

FALSE - test-policy:5:1 - Rule "all_drivers_exec"


==> Monitoring evaluation "16195b50"
    Evaluation triggered by job "example"
    Evaluation within deployment: "11e01124"
    Evaluation status changed: "pending" -> "complete"
==> Evaluation "16195b50" finished with status "complete"
```

This time, the job was accepted but with a warning that our policy is failing but was overridden.

# Policy Specification

Sentinel policies are specified in the [Sentinel Language](#). The language is designed to be easy to read and write,
while being fast to evaluate. There is no limitation on how complex policies can be, but they are in the execution path so
care should be taken to avoid adversely impacting performance.

In each scope, there are different objects made available for introspection, such a job being submitted. Policies can
inspect these objects to apply fine-grained policies.

### Scope `submit-job`

The following objects are made available in the `submit-job` scope:

| Object | Description               |
| ------ | ------------------------- |
| `job`  | The job being submitted   |

See the [Sentinel Job Object](/guides/sentinel/job.html) for details on the fields that are available.