nomad/website/content/docs/configuration/vault.mdx

---
layout: docs
page_title: vault Block in Agent Configuration
description: |-
  Configure Nomad server and client integration with HashiCorp Vault in the `vault` block of a Nomad agent configuration. Configure cluster name and the role for creating tokens. For Nomad clients, configure Vault's address, namespace, and certificate or TLS authentication. Specify the JWT authentication path. For Nomad servers, configure the server's default workload identity, which includes workload identity recipients, workload TTL, and key-value pairs for additional identity claims.

---

# `vault` Block in Agent Configuration

<Placement groups={['vault']} />

This page provides reference information for configuring Nomad server and client
integration with [HashiCorp Vault][vault] in the `vault` block of a Nomad agent
configuration. Configure cluster name and the role for creating tokens. For
Nomad clients, configure Vault's address, namespace, and certificate or TLS
authentication. Specify the JWT authentication path. For Nomad
servers, configure the server's default workload identity, which includes
workload identity recipients, workload TTL, and key-value pairs for additional
identity claims.

When configured, job tasks can use [workload identities][workload_id] to receive
Vault ACL tokens automatically.

Refer to the [Nomad and Vault Integration][nomad-vault] page for more
information about the Vault integration.

```hcl
vault {
  enabled = true

  default_identity {
    aud = ["vault.io"]
    ttl = "1h"

    extra_claims {
      unique_id = "${job.region}:${job.namespace}:${job.id}"
    }
  }
}
```

In Nomad Enterprise, you may specify multiple `vault` blocks to configure access
to multiple Vault clusters. Each Vault cluster must have a different value for
the [`name`](#name) field.

## `vault` Parameters

Some parameters are expected to be specified in the configuration file of Nomad
agents running as clients, servers, or in all agents. Parameters are safely
ignored if placed in a configuration file where they are not expected to be
defined.

### Parameters for Nomad Clients and Servers

These parameters should be defined in the configuration file of all Nomad
agents.

- `name` `(string: "default")` <EnterpriseAlert inline/> - Specifies a name for
  the cluster so it can be referred to by job submitters in the job
  specification's [`vault.cluster`][] field. In Nomad Community Edition, only
  the `"default"` cluster will be used, so this field should be omitted.

- `enabled` `(bool: false)` - Specifies if the Vault integration should be
  activated.

### Parameters for Nomad Clients

These parameters should only be defined in the configuration file of Nomad
agents with [`client.enabled`] set to `true`.

- `namespace` `(string: "")` - Specifies the [Vault namespace](/vault/docs/enterprise/namespaces)
  used by the Vault integration. If non-empty, this namespace will be used on
  all Vault API calls.

- `address` - `(string: "https://vault.service.consul:8200")` - Specifies the
  address to the Vault server. This must include the protocol, host/ip, and port
  given in the format `protocol://host:port`. If your Vault installation is
  behind a load balancer, this should be the address of the load balancer.

- `jwt_auth_backend_path` - `(string: "jwt-nomad")` - Specifies the mount
  [path][vault_auth_enable_path] of the JWT authentication method to be used to
  login with workload identity JWTs.

- `ca_file` `(string: "")` - Specifies an optional path to the CA
  certificate used for Vault communication. If unspecified, this will fallback
  to the default system CA bundle, which varies by OS and version.

- `ca_path` `(string: "")` - Specifies an optional path to a folder
  containing CA certificates to be used for Vault communication. If unspecified,
  this will fallback to the default system CA bundle, which varies by OS and
  version.

- `cert_file` `(string: "")` - Specifies the path to the certificate used for
  Vault communication. This must be set if
  [tls_require_and_verify_client_cert](/vault/docs/configuration/listener/tcp#tls_require_and_verify_client_cert)
  is enabled in Vault.

- `create_from_role` `(string: "")` - Specifies the role to create tokens
  from. This field defines the role used to derive task tokens when the job does
  not define a value for [`vault.role`][jobspec_vault_role]. If empty, the
  default Vault cluster role is used.

- `key_file` `(string: "")` - Specifies the path to the private key used for
  Vault communication. If this is set then you need to also set
  `cert_file`. This must be set if
  [tls_require_and_verify_client_cert](/vault/docs/configuration/listener/tcp#tls_require_and_verify_client_cert)
  is enabled in Vault.

- `tls_server_name` `(string: "")` - Specifies an optional string used to set
  the SNI host when connecting to Vault via TLS.

- `tls_skip_verify` `(bool: false)` - Specifies if SSL peer validation should be
  enforced.

  !> It is **strongly discouraged** to disable SSL verification. Instead, you
  should install a custom CA bundle and validate against it. Disabling SSL
  verification can allow an attacker to easily compromise your cluster.

### Parameters for Nomad Servers

These parameters should only be defined in the configuration file of Nomad
agents with [`server.enabled`] set to `true`.

- `default_identity` <code>([Identity](#default_identity-parameters): nil)</code> -
  Specifies the default workload identity configuration to use when a task with
  a `vault` block does not specify an [`identity`][jobspec_identity] block
  named `vault_<name>`, where `<name>` matches the value of this `vault` block
  [`name`](#name) parameter. Setting a default identity causes the value of
  `allow_unauthenticated` to be ignored.

### `default_identity` Parameters

- `aud` `(array<string>: [])` - List of valid recipients for this workload
  identity. This value must match the [`bound_audiences`][vault_bound_aud]
  configuration in the Vault JWT auth method. It is recommended to provide one,
  and only one, audience to minimize where the identity may be used.

- `env` `(bool: false)` - If true the workload identity will be available in
  the task's `NOMAD_TOKEN_vault` environment variable.

- `file` `(bool: false)` - If true the workload identity will be available in
  the task's filesystem via the path `secrets/nomad_vault.jwt`. If the
  [`task.user`][taskuser] parameter is set, the token file will only be
  readable by that user. Otherwise the file is readable by everyone but is
  protected by parent directory permissions.

- `ttl` `(string: "")` - Specifies for how long the workload identity should be
  considered as valid before expiring.

- `extra_claims` `(map[string]string: optional)` - A set of key-value pairs that
  will be provided as extra identity claims for workloads. You can use the keys
  as [user claims in Vault role configurations][vault-jwt-user-claim]. The
  values are interpolated. For example, if you include the extra claim
  `unique_id = "${job.region}:${job.namespace}:${job.id}"`, you could set the
  user claim field to `/extra_claims/unique_id` to map that identifier to an
  entity alias. The available attributes for interpolation are:

  - `${job.region}` - The region where the job is running.
  - `${job.namespace}` - The job's namespace.
  - `${job.id}` - The job's ID.
  - `${job.node_pool}` - The node pool where the allocation is running.
  - `${group.name}` - The task group name of the task using Vault.
  - `${alloc.id}` - The allocation's ID.
  - `${task.name}` - The name of the task using Vault.
  - `${node.id}` - The ID of the node where the allocation is running.
  - `${node.datacenter}` - The datacenter of the node where the allocation is running.
  - `${node.pool}` - The node pool of the node where the allocation is running.
  - `${node.class` - The class of the node where the allocation is running.
  - `${vault.cluster}` - The Vault cluster name.
  - `${vault.namespace}` - The Vault namespace.
  - `${vault.role}` - The Vault role.

## `vault` Examples

The following examples only show the `vault` blocks. Remember that the
`vault` block is only valid in the placements listed above.

### Nomad Server

This example shows a Vault configuration for a Nomad server using the workload
identity authentication flow.

```hcl
server {
  enabled = true
  # ...
}

vault {
  enabled = true

  # Provide a default workload identity configuration so jobs don't need to
  # specify one.
  default_identity {
    aud  = ["vault.io"]
    env  = false
    file = true
    ttl  = "1h"
  }
}
```

### Nomad Client

This example shows a Vault configuration for a Nomad client.

```hcl
client {
  enabled = true
  # ...
}

vault {
  enabled   = true
  address   = "https://vault.service.consul:8200"
  ca_path   = "/etc/certs/ca"
  cert_file = "/var/certs/vault.crt"
  key_file  = "/var/certs/vault.key"
}
```

## `vault` Configuration Reloads

The Vault configuration can be reloaded on servers. This can be useful if a new
token needs to be given to the servers without having to restart them. A reload
can be accomplished by sending the process a `SIGHUP` signal.

[`client.enabled`]: /nomad/docs/configuration/client#enabled
[`server.enabled`]: /nomad/docs/configuration/server#enabled
[`vault.cluster`]: /nomad/docs/job-specification/vault#cluster
[jobspec_vault_role]: /nomad/docs/job-specification/vault#role
[jobspec_identity]: /nomad/docs/job-specification/identity
[nomad-vault]: /nomad/docs/secure/vault 'Nomad Vault Integration'
[taskuser]: /nomad/docs/job-specification/task#user "Nomad task Block"
[vault]: https://www.vaultproject.io/ 'Vault by HashiCorp'
[vault_bound_aud]: /vault/api-docs/auth/jwt#bound_audiences
[vault_auth_enable_path]: /vault/docs/commands/auth/enable#path
[workload_id]: /nomad/docs/concepts/workload-identity
[vault-jwt-user-claim]: /vault/api-docs/auth/jwt#user_claim