mirror of
https://github.com/kemko/nomad.git
synced 2026-01-06 18:35:44 +03:00
cdaf45d990
The documentation is referring to a `file` attribute that does not exist on the `vault` block. This PR changes those references to mention the `disable_file` attribute instead.
230 lines
8.3 KiB
Plaintext
230 lines
8.3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: vault Block - Job Specification
|
|
description: |-
|
|
The "vault" block 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` Block
|
|
|
|
<Placement
|
|
groups={[
|
|
['job', 'vault'],
|
|
['job', 'group', 'vault'],
|
|
['job', 'group', 'task', 'vault'],
|
|
]}
|
|
/>
|
|
|
|
The `vault` block 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` blocks are specified, they are merged with the `task` block
|
|
taking the highest precedence, then the `group`, then the `job`.
|
|
|
|
```hcl
|
|
job "docs" {
|
|
group "example" {
|
|
task "server" {
|
|
vault {
|
|
cluster = "default"
|
|
role = "prod"
|
|
|
|
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.
|
|
This behavior can be altered using the `env` and `disable_file` parameters.
|
|
|
|
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` block is specified, the [`template`][template] block can interact
|
|
with Vault as well.
|
|
|
|
## `vault` Parameters
|
|
|
|
- `allow_token_expiration` `(bool: false)` - Specifies that Nomad clients should
|
|
not attempt to renew a task's Vault token, allowing it to expire. This should
|
|
only be used when a secret is requested from Vault once at the start of a task
|
|
or in a short-lived prestart task. Long-running tasks should never set
|
|
`allow_token_expiration=true` if they obtain Vault secrets via `template`
|
|
blocks, as the Vault token will expire and the template runner will continue
|
|
to make failing requests to Vault until its [`vault_retry`][] attempts are
|
|
exhausted, at which point the task will fail.
|
|
|
|
When Nomad has been configured to use [Workload Identity with Vault][], Nomad
|
|
clients will automatically detect when tokens cannot be refreshed (for
|
|
example, when the Vault auth method is configured to issue batch tokens). In
|
|
this case, the `allow_token_expiration` option will be implicitly set to
|
|
`true` by the client. The [legacy Vault authentication workflow][] cannot
|
|
automatically detect this.
|
|
|
|
- `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`.
|
|
|
|
- `cluster` `(string: "default")` <EnterpriseAlert inline/> - Specifies the
|
|
Vault cluster to use. The Nomad client will retrieve a Vault token from the
|
|
cluster configured in the agent configuration with the same
|
|
[`vault.name`][]. In Nomad Community Edition, this field is ignored.
|
|
|
|
- `env` `(bool: true)` - Specifies if the `VAULT_TOKEN` and `VAULT_NAMESPACE`
|
|
environment variables should be set when starting the task.
|
|
|
|
- `disable_file` `(bool: false)` - Specifies if the Vault token should be
|
|
written to `secrets/vault_token`.
|
|
<Warning>
|
|
While the <code>secrets</code> path is not shared with tasks that
|
|
use <a href="/nomad/docs/concepts/filesystem#image-isolation">
|
|
<code>image</code>
|
|
</a> filesystem isolation, it is still accessible by tasks using <a href="/nomad/docs/concepts/filesystem#chroot-isolation">
|
|
<code>chroot</code>
|
|
</a> or <a href="/nomad/docs/concepts/filesystem#none-isolation"><code>none</code>
|
|
</a> isolation.
|
|
</Warning>
|
|
|
|
- `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. This field may only be used with the legacy Vault
|
|
authentication workflow and not with JWT and workload identity. It is
|
|
deprecated in favor of the `role` field and will be removed in Nomad 1.10.
|
|
|
|
- `role` `(string: "")` - Specifies the Vault role used when retrieving a token
|
|
from Vault using JWT and workload identity. If not specified the client's
|
|
[`create_from_role`][] value is used.
|
|
|
|
## `vault` Examples
|
|
|
|
The following examples only show the `vault` blocks. Remember that the
|
|
`vault` block 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
|
|
Vault policies from the "prod" role attached.
|
|
|
|
```hcl
|
|
vault {
|
|
role = "prod"
|
|
}
|
|
```
|
|
|
|
### Signal Task
|
|
|
|
This example shows signaling the task instead of restarting it.
|
|
|
|
```hcl
|
|
vault {
|
|
role = "prod"
|
|
|
|
change_mode = "signal"
|
|
change_signal = "SIGINT"
|
|
}
|
|
```
|
|
|
|
### Private Token and Change Modes
|
|
|
|
This example retrieves a Vault token that is not shared with the task when using
|
|
a driver that provides `image` isolation like [Docker][docker].
|
|
|
|
This allows Nomad to use a powerful Vault token that interacts with the task's
|
|
[`template`][template] stanzas to issue all kinds of secrets (e.g., database
|
|
secrets, other vault tokens, etc.), without sharing that issuing power with
|
|
the task itself:
|
|
|
|
```hcl
|
|
vault {
|
|
role = "prod"
|
|
change_mode = "noop"
|
|
env = false
|
|
disable_file = true
|
|
}
|
|
|
|
template {
|
|
data = <<-EOH
|
|
{{with secret "auth/token/create/nomad-job" "policies=examplepolicy"}}{{.Auth.ClientToken}}{{ end }}
|
|
EOH
|
|
|
|
destination = "${NOMAD_SECRETS_DIR}/examplepolicy.token"
|
|
change_mode = "noop"
|
|
perms = "600"
|
|
}
|
|
|
|
template {
|
|
data = <<-EOH
|
|
{{ with secret "pki_int/issue/nomad-task"
|
|
"common_name=example.service.consul" "ttl=72h"
|
|
"alt_names=localhost" "ip_sans=127.0.0.1"}}
|
|
{{ .Data.certificate }}
|
|
{{ .Data.private_key }}
|
|
{{ end }}
|
|
EOH
|
|
|
|
destination = "${NOMAD_SECRETS_DIR}/client.crt"
|
|
change_mode = "restart"
|
|
perms = "600"
|
|
}
|
|
```
|
|
|
|
The example above uses `change_mode = "noop"` in the `template` stanza for
|
|
`examplepolicy.token`, which means that the task's workload is responsible for
|
|
detecting and handling changes to that file. In contrast, the `template` stanza
|
|
for `client.crt` is configured so that Nomad will restart the task whenever
|
|
the certificate is reissued, as indicated by `change_mode = "restart"`
|
|
(which is the default value for `change_mode`).
|
|
|
|
|
|
### Vault Namespace
|
|
|
|
This example shows specifying a particular Vault namespace for a given task.
|
|
|
|
<EnterpriseAlert />
|
|
|
|
```hcl
|
|
vault {
|
|
role = "prod"
|
|
namespace = "engineering/frontend"
|
|
|
|
change_mode = "signal"
|
|
change_signal = "SIGINT"
|
|
}
|
|
```
|
|
|
|
[`create_from_role`]: /nomad/docs/configuration/vault#create_from_role
|
|
[docker]: /nomad/docs/drivers/docker "Docker Driver"
|
|
[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"
|
|
[`vault.name`]: /nomad/docs/configuration/vault#name
|
|
[`vault_retry`]: /nomad/docs/configuration/client#vault_retry
|
|
[Workload Identity with Vault]: /nomad/docs/integrations/vault/acl#nomad-workload-identities
|
|
[legacy Vault authentication workflow]: /nomad/docs/integrations/vault/acl#authentication-without-workload-identity-legacy
|