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