1--- 2layout: "docs" 3page_title: "vault Stanza - Job Specification" 4sidebar_current: "docs-job-specification-vault" 5description: |- 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 26The `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 28for the task and handle token renewal for the task. If specified at the `group` 29level, the configuration will apply to all tasks within the group. If specified 30at the `job` level, the configuration will apply to all tasks within the job. If 31multiple `vault` stanzas are specified, they are merged with the `task` stanza 32taking the highest precedence, then the `group`, then the `job`. 33 34```hcl 35job "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 49The Nomad client will make the Vault token available to the task by writing it 50to the secret directory at `secrets/vault_token` and by injecting a `VAULT_TOKEN` 51environment variable. If the Nomad cluster is [configured](/docs/configuration/vault.html#namespace) 52to use [Vault Namespaces](https://www.vaultproject.io/docs/enterprise/namespaces/index.html), 53a `VAULT_NAMESPACE` environment variable will be injected whenever `VAULT_TOKEN` is. 54 55If Nomad is unable to renew the Vault token (perhaps due to a Vault outage or 56network error), the client will attempt to retrieve a new Vault token. If successful, the 57contents of the secrets file are updated on disk, and action will be taken 58according to the value set in the `change_mode` parameter. 59 60If a `vault` stanza is specified, the [`template`][template] stanza can interact 61with Vault as well. 62 63## `vault` Parameters 64 65- `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take 66 if the Vault token changes. The possible values are: 67 68 - `"noop"` - take no action (continue running the task) 69 - `"restart"` - restart the task 70 - `"signal"` - send a configurable signal to the task 71 72- `change_signal` `(string: "")` - Specifies the signal to send to the task as a 73 string like `"SIGUSR1"` or `"SIGINT"`. This option is required if the 74 `change_mode` is `signal`. 75 76- `env` `(bool: true)` - Specifies if the `VAULT_TOKEN` and `VAULT_NAMESPACE` 77 environment variables should be set when starting the task. 78 79- `policies` `(array<string>: [])` - Specifies the set of Vault policies that 80 the task requires. The Nomad client will retrieve a Vault token that is 81 limited to those policies. 82 83## `vault` Examples 84 85The following examples only show the `vault` stanzas. Remember that the 86`vault` stanza is only valid in the placements listed above. 87 88### Retrieve Token 89 90This example tells the Nomad client to retrieve a Vault token. The token is 91available to the task via the canonical environment variable `VAULT_TOKEN` and 92written to disk at `secrets/vault_token`. The resulting token will have the 93"frontend" Vault policy attached. 94 95```hcl 96vault { 97 policies = ["frontend"] 98} 99``` 100 101### Signal Task 102 103This example shows signaling the task instead of restarting it. 104 105```hcl 106vault { 107 policies = ["frontend"] 108 109 change_mode = "signal" 110 change_signal = "SIGINT" 111} 112``` 113 114[restart]: /docs/job-specification/restart.html "Nomad restart Job Specification" 115[template]: /docs/job-specification/template.html "Nomad template Job Specification" 116[vault]: https://www.vaultproject.io/ "Vault by HashiCorp" 117