github.com/smintz/nomad@v0.8.3/website/source/docs/job-specification/vault.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "vault Stanza - Job Specification" 4 sidebar_current: "docs-job-specification-vault" 5 description: |- 6 The "vault" stanza allows the task to specify that it requires a token from a 7 HashiCorp Vault server. Nomad will automatically retrieve a Vault token for 8 the task and handle token renewal for the task. 9 --- 10 11 # `vault` Stanza 12 13 <table class="table table-bordered table-striped"> 14 <tr> 15 <th width="120">Placement</th> 16 <td> 17 <code>job -> **vault**</code> 18 <br> 19 <code>job -> group -> **vault**</code> 20 <br> 21 <code>job -> group -> task -> **vault**</code> 22 </td> 23 </tr> 24 </table> 25 26 The `vault` stanza allows a task to specify that it requires a token from a 27 [HashiCorp Vault][vault] server. Nomad will automatically retrieve a Vault token 28 for the task and handle token renewal for the task. If specified at the `group` 29 level, the configuration will apply to all tasks within the group. If specified 30 at the `job` level, the configuration will apply to all tasks within the job. If 31 multiple `vault` stanzas are specified, they are merged with the `task` stanza 32 taking the highest precedence, then the `group`, then the `job`. 33 34 ```hcl 35 job "docs" { 36 group "example" { 37 task "server" { 38 vault { 39 policies = ["cdn", "frontend"] 40 41 change_mode = "signal" 42 change_signal = "SIGUSR1" 43 } 44 } 45 } 46 } 47 ``` 48 49 The Nomad client will make the Vault token available to the task by writing it 50 to the secret directory at `secret/vault_token` and by injecting a VAULT_TOKEN 51 environment variable. 52 53 If Nomad is unable to renew the Vault token (perhaps due to a Vault outage or 54 network error), the client will attempt to retrieve a new Vault token. If successful, the 55 contents of the secrets file are updated on disk, and action will be taken 56 according to the value set in the `change_mode` parameter. 57 58 If a `vault` stanza is specified, the [`template`][template] stanza can interact 59 with Vault as well. 60 61 ## `vault` Parameters 62 63 - `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take 64 if the Vault token changes. The possible values are: 65 66 - `"noop"` - take no action (continue running the task) 67 - `"restart"` - restart the task 68 - `"signal"` - send a configurable signal to the task 69 70 - `change_signal` `(string: "")` - Specifies the signal to send to the task as a 71 string like `"SIGUSR1"` or `"SIGINT"`. This option is required if the 72 `change_mode` is `signal`. 73 74 - `env` `(bool: true)` - Specifies if the `VAULT_TOKEN` environment variable 75 should be set when starting the task. 76 77 - `policies` `(array<string>: [])` - Specifies the set of Vault policies that 78 the task requires. The Nomad client will generate a Vault token that is 79 limited to those policies. 80 81 ## `vault` Examples 82 83 The following examples only show the `vault` stanzas. Remember that the 84 `vault` stanza is only valid in the placements listed above. 85 86 ### Retrieve Token 87 88 This example tells the Nomad client to retrieve a Vault token. The token is 89 available to the task via the canonical environment variable `VAULT_TOKEN` and 90 written to disk at `secrets/vault_token`. The resulting token will have the 91 "frontend" Vault policy attached. 92 93 ```hcl 94 vault { 95 policies = ["frontend"] 96 } 97 ``` 98 99 ### Signal Task 100 101 This example shows signaling the task instead of restarting it. 102 103 ```hcl 104 vault { 105 policies = ["frontend"] 106 107 change_mode = "signal" 108 change_signal = "SIGINT" 109 } 110 ``` 111 112 [restart]: /docs/job-specification/restart.html "Nomad restart Job Specification" 113 [template]: /docs/job-specification/template.html "Nomad template Job Specification" 114 [vault]: https://www.vaultproject.io/ "Vault by HashiCorp"