github.com/smintz/nomad@v0.8.3/website/source/guides/sentinel-policy.html.markdown (about) 1 --- 2 layout: "guides" 3 page_title: "Sentinel Policies" 4 sidebar_current: "guides-sentinel" 5 description: |- 6 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. 7 --- 8 9 # Sentinel Policies 10 11 [Nomad Enterprise](https://www.hashicorp.com/products/nomad/) integrates with [HashiCorp Sentinel](https://docs.hashicorp.com/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). 12 13 ~> **Enterprise Only!** This functionality only exists in Nomad Enterprise. 14 This is not present in the open source version of Nomad. 15 16 # Sentinel Overview 17 18 Sentinel integrates with the ACL system, and provides the ability to do fine grained policy enforcement. Users must have appropriate permissions to perform an action, and then are subject to any applicable Sentinel policies: 19 20 ![Sentinel Overview](/assets/images/sentinel.jpg) 21 22 * **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. 23 24 * **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. 25 26 * **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. 27 28 ### Sentinel Policies 29 30 Each Sentinel policy has a unique name, an optional description, applicable scope, enforcement level, and a Sentinel rule definition. 31 If multiple policies are installed for the same scope, all of them are enforced and must pass. 32 33 Sentinel policies _cannot_ be used unless the ACL system is enabled. 34 35 ### Policy Scope 36 37 Sentinel policies specify an applicable scope, which limits when the policy is enforced. This allows policies to govern various aspects of the system. 38 39 The following table summarizes the scopes that are available for Sentinel policies: 40 41 | Scope | Description | 42 | ---------- | ----------------------------------------------------- | 43 | submit-job | Applies to any jobs (new or updated) being registered | 44 45 46 ### Enforcement Level 47 48 Sentinel policies specify an enforcement level which changes how a policy is enforced. This allows for more flexibility in policy enforcement. 49 50 The following table summarizes the enforcement levels that are available: 51 52 | Enforcement Level | Description | 53 | ----------------- | ---------------------------------------------------------------------- | 54 | advisory | Issues a warning when a policy fails | 55 | soft-mandatory | Prevents operation when a policy fails, issues a warning if overridden | 56 | hard-mandatory | Prevents operation when a policy fails | 57 58 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. 59 60 ## Multi-Region Configuration 61 62 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. 63 64 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 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. 65 66 ## Configuring Sentinel Policies 67 68 Sentinel policies are tied to the ACL system, which is not enabled by default. 69 See the [ACL guide](/guides/acl.html) for details on how to configure ACLs. 70 71 ## Example: Installing Sentinel Policies 72 73 This example shows how to install a Sentinel policy. It assumes that ACLs have already 74 been bootstrapped (see the [ACL guide](/guides/acl.html)), and that a `NOMAD_TOKEN` environment variable 75 is set to a management token. 76 77 First, create a Sentinel policy, named `test.sentinel`: 78 79 ``` 80 # Test policy always fails for demonstration purposes 81 main = rule { false } 82 ``` 83 84 Then, install this as an `advisory` policy which issues a warning on failure: 85 86 ``` 87 $ nomad sentinel apply -level=advisory test-policy test.sentinel 88 Successfully wrote "test-policy" Sentinel policy! 89 ``` 90 91 Use `nomad job init` to create a job file and attempt to submit it: 92 93 ``` 94 $ nomad job init 95 Example job file written to example.nomad 96 97 $ nomad job run example.nomad 98 Job Warnings: 99 1 warning(s): 100 101 * test-policy : Result: false (allowed failure based on level) 102 103 FALSE - test-policy:2:1 - Rule "main" 104 105 106 ==> Monitoring evaluation "f43ac28d" 107 Evaluation triggered by job "example" 108 Evaluation within deployment: "11e01124" 109 Allocation "2618f3b4" created: node "add8ce93", group "cache" 110 Allocation "5c2674f2" created: node "add8ce93", group "cache" 111 Allocation "9937811f" created: node "add8ce93", group "cache" 112 Evaluation status changed: "pending" -> "complete" 113 ==> Evaluation "f43ac28d" finished with status "complete" 114 ``` 115 116 We can see our policy failed, but the job was accepted because of an `advisory` enforcement level. 117 118 Next, let's change `test.sentinel` to only allow "exec" based drivers: 119 120 ``` 121 # Test policy only allows exec based tasks 122 main = rule { all_drivers_exec } 123 124 # all_drivers_exec checks that all the drivers in use are exec 125 all_drivers_exec = rule { 126 all job.task_groups as tg { 127 all tg.tasks as task { 128 task.driver is "exec" 129 } 130 } 131 } 132 ``` 133 134 Then install the updated policy at a soft mandatory level: 135 136 ``` 137 $ nomad sentinel apply -level=soft-mandatory test-policy test.sentinel 138 Successfully wrote "test-policy" Sentinel policy! 139 ``` 140 141 With our new policy, attempt to submit the same job, which uses the "docker" driver: 142 143 ``` 144 $ nomad run example.nomad 145 Error submitting job: Unexpected response code: 500 (1 error(s) occurred: 146 147 * test-policy : Result: false 148 149 FALSE - test-policy:2:1 - Rule "main" 150 FALSE - test-policy:6:5 - all job.task_groups as tg { 151 all tg.tasks as task { 152 task.driver is "exec" 153 } 154 } 155 156 FALSE - test-policy:5:1 - Rule "all_drivers_exec" 157 ) 158 ``` 159 160 Because our policy is failing, the job was rejected. Since this is a `soft-mandatory` policy, 161 submit with the `-policy-override` flag set: 162 163 ``` 164 $ nomad job run -policy-override example.nomad 165 Job Warnings: 166 1 warning(s): 167 168 * test-policy : Result: false (allowed failure based on level) 169 170 FALSE - test-policy:2:1 - Rule "main" 171 FALSE - test-policy:6:5 - all job.task_groups as tg { 172 all tg.tasks as task { 173 task.driver is "exec" 174 } 175 } 176 177 FALSE - test-policy:5:1 - Rule "all_drivers_exec" 178 179 180 ==> Monitoring evaluation "16195b50" 181 Evaluation triggered by job "example" 182 Evaluation within deployment: "11e01124" 183 Evaluation status changed: "pending" -> "complete" 184 ==> Evaluation "16195b50" finished with status "complete" 185 ``` 186 187 This time, the job was accepted but with a warning that our policy is failing but was overridden. 188 189 # Policy Specification 190 191 Sentinel policies are specified in the [Sentinel 192 Language](https://docs.hashicorp.com/sentinel/). The language is designed to be 193 easy to read and write, while being fast to evaluate. There is no limitation on 194 how complex policies can be, but they are in the execution path so care should 195 be taken to avoid adversely impacting performance. 196 197 In each scope, there are different objects made available for introspection, such a job being submitted. Policies can 198 inspect these objects to apply fine-grained policies. 199 200 ### Scope `submit-job` 201 202 The following objects are made available in the `submit-job` scope: 203 204 | Object | Description | 205 | ------ | ------------------------- | 206 | `job` | The job being submitted | 207 208 See the [Sentinel Job Object](/guides/sentinel/job.html) for details on the fields that are available. 209