ab7eb5de6e
Move some common Vault API data struct decoding out of the Vault client so it can be reused in other situations. Make Vault job validation its own function so it's easier to expand it. Rename the `Job.VaultPolicies` method to just `Job.Vault` since it returns the full Vault block, not just their policies. Set `ChangeMode` on `Vault.Canonicalize`. Add some missing tests. Allows specifying an entity alias that will be used by Nomad when deriving the task Vault token. An entity alias assigns an indentity to a token, allowing better control and management of Vault clients since all tokens with the same indentity alias will now be considered the same client. This helps track Nomad activity in Vault's audit logs and better control over Vault billing. Add support for a new Nomad server configuration to define a default entity alias to be used when deriving Vault tokens. This default value will be used if the task doesn't have an entity alias defined.
150 lines
4.7 KiB
Plaintext
150 lines
4.7 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](/docs/configuration/vault#namespace)
|
|
to use [Vault Namespaces](https://www.vaultproject.io/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.
|
|
|
|
- `entity_alias` `(string: "")` - Specifies the entity alias to use when creating
|
|
Vault tokens for the task. This allows multiple tokens to be created as a single
|
|
[Vault client][vault_client].
|
|
|
|
- `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"
|
|
}
|
|
```
|
|
|
|
### Entity Alias
|
|
|
|
This example shows a task that will receive a token created with a specified
|
|
entity alias. If [`allow_unauthenticated`] is set to `true`, the token used to
|
|
register this job must be allowed to use the `frontend` entity alias.
|
|
|
|
```hcl
|
|
vault {
|
|
policies = ["frontend"]
|
|
entity_alias = "frontend"
|
|
}
|
|
```
|
|
|
|
### 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"
|
|
}
|
|
```
|
|
|
|
[`allow_unauthenticated`]: /docs/configuration/vault#allow_unauthenticated
|
|
[restart]: /docs/job-specification/restart 'Nomad restart Job Specification'
|
|
[template]: /docs/job-specification/template 'Nomad template Job Specification'
|
|
[vault]: https://www.vaultproject.io/ 'Vault by HashiCorp'
|
|
[vault_client]: https://www.vaultproject.io/docs/concepts/client-count
|