github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/other-specifications/acl-policy.mdx (about) 1 --- 2 layout: docs 3 page_title: ACL Policy Specification 4 description: Learn about Nomad's ACL policy specification. 5 --- 6 7 # ACL Policy Specification 8 9 The [Secure Nomad with Access Control] guide includes step-by-step instructions 10 for bootstrapping Nomad's Access Control List (ACL) system, authoring policies, 11 and granting policies. This document is a detailed reference of the expected 12 policy structure and available options. 13 14 ACL policies are written using [HashiCorp Configuration Language 15 (HCL)][hcl]. The HCL interpreter can also parse JSON to facilitate 16 machine-generated configuration. A detailed syntax specification for HCL can be 17 found at [HCL Native Syntax Specification][hcl_syntax_spec]. 18 19 All content of an ACL policy is case-sensitive. 20 21 An ACL policy contains one or more **rules**. Each rule block contains a 22 combination of `policy` and `capabilities` fields. The specific values permitted 23 are described for each rule definition below. An example structure of an ACL 24 policy is as follows: 25 26 ```hcl 27 # this is a namespace rule for the "foo" namespace 28 namespace "foo" { 29 policy = "write" # this is a policy field 30 capabilities = ["alloc-exec"] # this is a capabilities list 31 32 # this block controls access to variables in this namespace 33 variables { 34 path "project/*" { 35 capabilities = ["read", "write"] 36 } 37 } 38 } 39 40 # this is a namespace rule, with a wildcard label 41 namespace "*" { 42 policy = "read" 43 } 44 45 node { 46 policy = "read" 47 } 48 49 agent { 50 policy = "read" 51 } 52 53 operator { 54 policy = "read" 55 } 56 57 quota { 58 policy = "read" 59 } 60 61 # this is a host_volume rule, with a wildcard label 62 host_volume "*" { 63 policy = "read" 64 } 65 66 plugin { 67 policy = "write" 68 } 69 ``` 70 71 ## Namespace Rules 72 73 Namespace rules are defined with a `namespace` block. An ACL policy can include 74 zero, one, or more namespace rules. 75 76 Namespace rules control access to APIs in Nomad that are namespaced: 77 [Jobs][api_jobs], [Allocations][api_allocations], 78 [Deployments][api_deployments], [Evaluations][api_evaluations], 79 [Recommendations][api_recommendations], [Scaling 80 Policies][api_scaling_policies], [Services][api_services], and [CSI 81 Volumes][api_volumes]. Namespace rules also filter items related to the above 82 APIs from the [Event Stream][api_events] and [Search][api_search] APIs. 83 84 Each namespace rule is labeled with the namespace name it applies to. If no 85 namespace label is specified, the rule will apply to the "default" 86 namespace. You may use wildcard globs (`"*"`) in the namespace label, to apply a 87 rule to multiple namespaces. 88 89 Only one namespace rule can apply. When an action is checked against the ACL 90 Policy, the namespace rule is selected by first checking for an _exact match_, 91 before falling back to a glob-based lookup. When looking up the namespace by 92 glob, the matching rule with the greatest number of matched characters will be 93 chosen. 94 95 For example the following policy will evaluate to deny for `production-web`, 96 because it is 9 characters different from the `"*-web"` rule, but 13 characters 97 different from the `"*"` rule. 98 99 ```hcl 100 namespace "*-web" { 101 policy = "deny" 102 } 103 104 namespace "*" { 105 policy = "write" 106 } 107 ``` 108 109 Each namespace rule can include a coarse-grained `policy` field, a fine-grained 110 `capabilities` field, a `variables` block, or all three. 111 112 The `policy` field for namespace rules can have one of the following values: 113 - `read`: allow the resource to be read but not modified 114 - `write`: allow the resource to be read and modified 115 - `deny`: do not allow the resource to be read or modified. Deny takes 116 precedence when multiple policies are associated with a token. 117 118 In addition to the coarse-grained `policy`, you can provide a fine-grained list 119 of `capabilities`. This includes: 120 121 - `deny` - When multiple policies are associated with a token, deny will take 122 precedence and prevent any capabilities. 123 - `list-jobs` - Allows listing the jobs and seeing coarse grain status. 124 - `parse-job` - Allows parsing a job from HCL to JSON. 125 - `read-job` - Allows inspecting a job and seeing fine grain status. 126 - `submit-job` - Allows jobs to be submitted, updated, or stopped. 127 - `dispatch-job` - Allows jobs to be dispatched 128 - `read-logs` - Allows the logs associated with a job to be viewed. 129 - `read-fs` - Allows the filesystem of allocations associated to be viewed. 130 - `alloc-exec` - Allows an operator to connect and run commands in running 131 allocations. 132 - `alloc-node-exec` - Allows an operator to connect and run commands in 133 allocations running without filesystem isolation, for example, raw_exec jobs. 134 - `alloc-lifecycle` - Allows an operator to stop individual allocations 135 manually. 136 - `csi-register-plugin` - Allows jobs to be submitted that register themselves 137 as CSI plugins. 138 - `csi-write-volume` - Allows CSI volumes to be registered or deregistered. 139 - `csi-read-volume` - Allows inspecting a CSI volume and seeing fine grain 140 status. 141 - `csi-list-volume` - Allows listing CSI volumes and seeing coarse grain status. 142 - `csi-mount-volume` - Allows jobs to be submitted that claim a CSI volume. 143 - `list-scaling-policies` - Allows listing scaling policies. 144 - `read-scaling-policy` - Allows inspecting a scaling policy. 145 - `read-job-scaling` - Allows inspecting the current scaling of a job. 146 - `scale-job`: Allows scaling a job up or down. 147 - `sentinel-override` - Allows soft mandatory policies to be overridden. 148 149 The coarse-grained policy permissions are shorthand for the following fine- 150 grained namespace capabilities: 151 152 <!-- markdownlint-disable --> 153 154 | Policy | Capabilities | 155 | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 156 | `deny` | deny | 157 | `read` | list-jobs<br />parse-job<br />read-job<br />csi-list-volume<br />csi-read-volume<br />list-scaling-policies<br />read-scaling-policy<br />read-job-scaling | 158 | `write` | list-jobs<br />parse-job<br />read-job<br />submit-job<br />dispatch-job<br />read-logs<br />read-fs<br />alloc-exec<br />alloc-lifecycle<br />csi-write-volume<br />csi-mount-volume<br />list-scaling-policies<br />read-scaling-policy<br />read-job-scaling<br />scale-job | 159 | `scale` | list-scaling-policies<br />read-scaling-policy<br />read-job-scaling<br />scale-job | 160 161 <!-- markdownlint-enable --> 162 163 If you provide both a `policy` and `capabilities` list, the capabilities are 164 merged. For example, the policy below adds the `submit-job` capability to the `read` 165 policy disposition, which provides the `list-job` and `read-job` capabilities: 166 167 ```hcl 168 # Allow reading jobs and submitting jobs, without allowing access 169 # to view log output or inspect the filesystem 170 namespace "default" { 171 policy = "read" 172 capabilities = ["submit-job"] 173 } 174 ``` 175 176 A similar policy could also be expressed as: 177 178 ```hcl 179 # Allow reading jobs and submitting jobs, without allowing access 180 # to view log output or inspect the filesystem 181 namespace "default" { 182 capabilities = ["submit-job","list-jobs","read-job"] 183 } 184 ``` 185 186 ### Variables 187 188 The `variables` block in the `namespace` rule controls access to 189 [Variables][]. The variables block is optional, but you can specify only one 190 variables block per namespace rule. 191 192 A `variables` block includes one or more `path` blocks. Each `path` block is 193 labeled with the path it applies to. You may use wildcard globs (`"*"`) in the 194 path label, to apply the block to multiple paths in the namespace. 195 196 Each path has a list of `capabilities`. The available capabilities for Variables 197 are as follows: 198 199 | Capability | Notes | 200 |------------|-----------------------------------------------------------------------------------------------------------------------| 201 | write | Create or update Variables at this path. Includes the "list" capability but not the "read" or "destroy" capabilities. | 202 | read | Read the decrypted contents of Variables at this path. Also includes the "list" capability | 203 | list | List the metadata but not contents of Variables at this path. | 204 | destroy | Delete Variables at this path. | 205 | deny | No permissions at this path. Deny takes precedence over other capabilities. | 206 207 For example, the policy below allows full access to variables at all paths in 208 the "dev" namespace that are prefixed with "project/", but only read access to 209 paths prefixed with "system/". Note that the glob can match an empty string but 210 all other characters are strictly matched. This policy grants read access to 211 paths prefixed with "system/" but not a path named "system" (without a trailing 212 slash). This policy does not grant any other coarse-grained policy or 213 fine-grained capabilities. 214 215 ```hcl 216 namespace "dev" { 217 218 variables { 219 220 # full access to secrets in all "project" paths 221 path "project/*" { 222 capabilities = ["write", "read", "destroy", "list"] 223 } 224 225 # read/list access within a "system/" path belonging to administrators 226 path "system/*" { 227 capabilities = ["read"] 228 } 229 } 230 } 231 ``` 232 233 ## Node rules 234 235 The `node` rule controls access to the [Node API][api_node] such as listing 236 nodes or triggering a node drain. The node rule is optional, but you can specify 237 only one node rule per ACL Policy. 238 239 ```hcl 240 node { 241 policy = "read" 242 } 243 ``` 244 245 The `policy` field for the node rule can have one of the following values: 246 - `read`: allow the resource to be read but not modified 247 - `write`: allow the resource to be read and modified 248 - `deny`: do not allow the resource to be read or modified. Deny takes 249 precedence when multiple policies are associated with a token. 250 251 ## Agent rules 252 253 The `agent` rule controls access to the [Agent API][api_agent] such as join and 254 leave. The agent rule is optional, but you can specify only one agent rule per 255 ACL Policy. 256 257 ```hcl 258 agent { 259 policy = "read" 260 } 261 ``` 262 263 The `policy` field for the agent rule can have one of the following values: 264 - `read`: allow the resource to be read but not modified 265 - `write`: allow the resource to be read and modified 266 - `deny`: do not allow the resource to be read or modified. Deny takes 267 precedence when multiple policies are associated with a token. 268 269 ## Operator rules 270 271 The `operator` rule controls access to the [Operator API][api_operator] such 272 raft or scheduler configuration. The operator rule is optional, but you can 273 specify only one operator rule per ACL Policy. 274 275 ```hcl 276 operator { 277 policy = "read" 278 } 279 ``` 280 281 The `policy` field for the operator rule can have one of the following values: 282 - `read`: allow the resource to be read but not modified 283 - `write`: allow the resource to be read and modified 284 - `deny`: do not allow the resource to be read or modified. Deny takes 285 precedence when multiple policies are associated with a token. 286 287 In the example above, the token could be used to query the operator endpoints 288 for diagnostic purposes but not make any changes. 289 290 ## Quota rules 291 292 The `quota` rule controls access to the [Quota API][api_quota] such as quota 293 creation and deletion. The quota rule is optional, but you can specify only one 294 quota rule per ACL Policy. 295 296 ```hcl 297 quota { 298 policy = "read" 299 } 300 ``` 301 302 The `policy` field for the quota rule can have one of the following values: 303 - `read`: allow the resource to be read but not modified 304 - `write`: allow the resource to be read and modified 305 - `deny`: do not allow the resource to be read or modified. Deny takes 306 precedence when multiple policies are associated with a token. 307 308 ## Host Volume rules 309 310 The `host_volume` rule controls access to mounting and accessing [host 311 volumes][host_volumes]. An ACL Policy can include zero, one, or more host volume 312 rules. 313 314 ```hcl 315 host_volume "*" { 316 policy = "write" 317 } 318 319 host_volume "prod-*" { 320 policy = "deny" 321 } 322 323 host_volume "prod-ca-certificates" { 324 policy = "read" 325 } 326 ``` 327 328 Host volume rules are labeled with the volume names that they apply to. As with 329 namespaces, you may use wildcards to reuse the same configuration across a set 330 of volumes. 331 332 The `policy` field for host volume rules can have one of the following values: 333 - `read`: allow the resource to be read but not modified 334 - `write`: allow the resource to be read and modified 335 - `deny`: do not allow the resource to be read or modified. Deny takes 336 precedence when multiple policies are associated with a token. 337 338 In addition to the coarse grained policy, host volume rules can include a list 339 of fine-grained `capabilities`. These include: 340 341 - `deny` - Do not allow a user to mount a volume in any way. 342 - `mount-readonly` - Only allow the user to mount the volume as `readonly` 343 - `mount-readwrite` - Allow the user to mount the volume as `readonly` or 344 `readwrite` if the `host_volume` configuration allows it. 345 346 The coarse-grained policy permissions are shorthand for the fine grained 347 capabilities: 348 349 <!-- markdownlint-disable --> 350 351 | Policy | Capabilities | 352 |---------|-------------------------------------| 353 | `deny` | deny | 354 | `read` | mount-readonly | 355 | `write` | mount-readonly<br />mount-readwrite | 356 357 <!-- markdownlint-enable --> 358 359 When both the policy short hand and a capabilities list are provided, the 360 capabilities are merged. 361 362 ~> **Note:** Host Volume policies are applied when attempting to _use_ a volume. 363 Regardless of this configuration, users with access to the Node API will be able 364 to list available volumes using the `nomad node status` command or API call. . 365 366 ## Plugin rules 367 368 The `plugin` rule controls access to [CSI plugins][api_plugins], such as listing 369 plugins or getting plugin status. The plugin rule is optional, but you can 370 specify only one plugin rule per ACL policy. 371 372 ```hcl 373 plugin { 374 policy = "read" 375 } 376 ``` 377 378 The `policy` field for the plugin rule can have one of the following values: 379 - `read`: allow the resource to be read but not modified 380 - `list`: allow the resource to be listed, but not inspected in detail 381 - `write`: allow the resource to be read and modified 382 - `deny`: do not allow the resource to be read or modified. Deny takes 383 precedence when multiple policies are associated with a token. 384 385 386 [Secure Nomad with Access Control]: https://learn.hashicorp.com/collections/nomad/access-control 387 [hcl]: https://github.com/hashicorp/hcl 388 [hcl_syntax_spec]: https://github.com/hashicorp/hcl/blob/main/hclsyntax/spec.md 389 [api_jobs]: /api-docs/jobs 390 [api_allocations]: /api-docs/allocations 391 [api_deployments]: /api-docs/deployments 392 [api_evaluations]: /api-docs/evaluations 393 [api_recommendations]: /api-docs/recommendations 394 [api_scaling_policies]: /api-docs/scaling-policies 395 [api_services]: /api-docs/services 396 [api_volumes]: /api-docs/volumes 397 [api_events]: /api-docs/events 398 [api_search]: /api-docs/search 399 [api_agent]: /api-docs/agent/ 400 [api_node]: /api-docs/nodes/ 401 [api_operator]: /api-docs/operator/ 402 [api_quota]: /api-docs/quotas/ 403 [host_volumes]: /docs/configuration/client#host_volume-stanza 404 [api_plugins]: /api-docs/plugins/ 405 [Variables]: /docs/concepts/variables