open-nomad/website/content/docs/job-specification/vault.mdx
Ashlee M Boyer 57f8ebfa26
docs: Migrate link formats (#15779)
* Adding check-legacy-links-format workflow

* Adding test-link-rewrites workflow

* chore: updates link checker workflow hash

* Migrating links to new format

Co-authored-by: Kendall Strautman <kendallstrautman@gmail.com>
2023-01-25 09:31:14 -08:00

133 lines
4.1 KiB
Plaintext

---
layout: docs
page_title: vault Stanza - Job Specification
description: |-
The "vault" stanza allows the task to specify that it requires a token from a
HashiCorp Vault server. Nomad will automatically retrieve a Vault token for
the task and handle token renewal for the task.
---
# `vault` Stanza
<Placement
groups={[
['job', 'vault'],
['job', 'group', 'vault'],
['job', 'group', 'task', 'vault'],
]}
/>
The `vault` stanza allows a task to specify that it requires a token from a
[HashiCorp Vault][vault] server. Nomad will automatically retrieve a Vault token
for the task and handle token renewal for the task. If specified at the `group`
level, the configuration will apply to all tasks within the group. If specified
at the `job` level, the configuration will apply to all tasks within the job. If
multiple `vault` stanzas are specified, they are merged with the `task` stanza
taking the highest precedence, then the `group`, then the `job`.
```hcl
job "docs" {
group "example" {
task "server" {
vault {
policies = ["cdn", "frontend"]
change_mode = "signal"
change_signal = "SIGUSR1"
}
}
}
}
```
The Nomad client will make the Vault token available to the task by writing it
to the secret directory at `secrets/vault_token` and by injecting a `VAULT_TOKEN`
environment variable. If the Nomad cluster is [configured](/nomad/docs/configuration/vault#namespace)
to use [Vault Namespaces](/vault/docs/enterprise/namespaces),
a `VAULT_NAMESPACE` environment variable will be injected whenever `VAULT_TOKEN` is set.
If Nomad is unable to renew the Vault token (perhaps due to a Vault outage or
network error), the client will attempt to retrieve a new Vault token. If successful, the
contents of the secrets file are updated on disk, and action will be taken
according to the value set in the `change_mode` parameter.
If a `vault` stanza is specified, the [`template`][template] stanza can interact
with Vault as well.
## `vault` Parameters
- `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take
if the Vault token changes. The possible values are:
- `"noop"` - take no action (continue running the task)
- `"restart"` - restart the task
- `"signal"` - send a configurable signal to the task
- `change_signal` `(string: "")` - Specifies the signal to send to the task as a
string like `"SIGUSR1"` or `"SIGINT"`. This option is required if the
`change_mode` is `signal`.
- `env` `(bool: true)` - Specifies if the `VAULT_TOKEN` and `VAULT_NAMESPACE`
environment variables should be set when starting the task.
- `namespace` `(string: "")` <EnterpriseAlert inline/> - Specifies the Vault Namespace
to use for the task. The Nomad client will retrieve a Vault token that is scoped to
this particular namespace.
- `policies` `(array<string>: [])` - Specifies the set of Vault policies that
the task requires. The Nomad client will retrieve a Vault token that is
limited to those policies.
## `vault` Examples
The following examples only show the `vault` stanzas. Remember that the
`vault` stanza is only valid in the placements listed above.
### Retrieve Token
This example tells the Nomad client to retrieve a Vault token. The token is
available to the task via the canonical environment variable `VAULT_TOKEN` and
written to disk at `secrets/vault_token`. The resulting token will have the
"frontend" Vault policy attached.
```hcl
vault {
policies = ["frontend"]
}
```
### Signal Task
This example shows signaling the task instead of restarting it.
```hcl
vault {
policies = ["frontend"]
change_mode = "signal"
change_signal = "SIGINT"
}
```
### Vault Namespace
This example shows specifying a particular Vault namespace for a given task.
<EnterpriseAlert />
```hcl
vault {
policies = ["frontend"]
namespace = "engineering/frontend"
change_mode = "signal"
change_signal = "SIGINT"
}
```
[restart]: /nomad/docs/job-specification/restart "Nomad restart Job Specification"
[template]: /nomad/docs/job-specification/template "Nomad template Job Specification"
[vault]: https://www.vaultproject.io/ "Vault by HashiCorp"