nomad/website/content/docs/job-specification/vault.mdx

---
layout: docs
page_title: vault block in the 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 in the job specification

<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.

## 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.

- `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.

## 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/job-declare/task-driver/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/secure/vault/acl#nomad-workload-identities
[legacy Vault authentication workflow]: /nomad/docs/v1.8.x/integrations/vault/acl