vault Block

The vault block configures Nomad's integration with HashiCorp's Vault. When configured, tasks can use workload identities to receive Vault ACL tokens automatically.

Alternatively, Nomad servers may be configured with a high-privileged Vault token that is used to derive fine-grained tokens for tasks. Refer to Token-based Authentication for configuration details. This workflow is deprecated and will be removed in a future version of Nomad. Using using workload identities is strongly recommended as it is easier to manage and more secure.

Refer to the Nomad and Vault Integration page for more information about the Vault integration.

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

The placement also depends on the authentication strategy used. This section describes the parameter organization for workload identity authentication. Refer to the Token-based Authentication section if using Vault tokens directly.

Parameters for Nomad Clients and Servers

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

• name (string: "default") EnterpriseEnterprise - 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.

• create_from_role (string: "") - Specifies the role to create tokens from.

  When using workload identities this field defines the role used to derive task tokens when the job does not define a value for vault.role. If empty, the default Vault cluster role is used.

  For token-based authentication, the Nomad servers derive tokens using this role. The token given to Nomad does not have to be created from this role but must have update capability on auth/token/create/<create_from_role> path in Vault. If this value is unset and the token is created from a role, the value is defaulted to the role the token is from.

  Note: This used to be a server-only field, but it is client-only when using workload identities. It should be set in both while transitioning from token-based authentication to workload identities.

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 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 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 is enabled in Vault.

• 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 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 (Identity: nil) - Specifies the default workload identity configuration to use when a task with a vault block does not specify an identity block named vault_<name>, where <name> matches the value of this vault block name parameter. Setting a default identity causes the value of allow_unauthenticated to be ignored.

Deprecated Parameters

These parameters are used by the deprecated token-based authentication flow and will be removed in a future release.

• allow_unauthenticated (bool: true) - Specifies if users submitting jobs to the Nomad server should be required to provide their own Vault token, proving they have access to the policies listed in the job. This option should be disabled in an untrusted environment.

• task_token_ttl (string: "72h") - Specifies the TTL of created tokens when using a root token. This is specified using a label suffix like "30s" or "1h".

• token (string: "") - Specifies the parent Vault token to use to derive child tokens for jobs requesting tokens. Only required on Nomad servers. Nomad client agents use the allocation's token when contacting Vault. Visit the Vault Integration Guide to see how to generate an appropriate token in Vault.

  It is strongly discouraged to place the token as a configuration parameter like this, since the token could be checked into source control accidentally. Users should set the VAULT_TOKEN environment variable when starting the agent instead.

default_identity Parameters

• aud (array<string>: []) - List of valid recipients for this workload identity. This value must match the bound_audiences 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 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. 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.

Token-based Authentication

When using token-based authentication the vault block parameters should be defined as below.

Parameters for Nomad Clients and Servers

• address
• ca_file
• ca_path
• cert_file
• enabled
• key_file
• name
• namespace
• tls_server_name
• tls_skip_verify

Parameters for Nomad Servers

• allow_unauthenticated
• create_from_role
• token
• task_token_ttl

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.

server {
  enabled = true
  # ...
}

vault {
  enabled = true

  # Only needed in servers when transioning from the token-based flow to
  # workload identities.
  create_from_role = "nomad-cluster"

  # 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"
  }
}

This example shows a Vault configuration for a Nomad server using the deprecated token-based authentication flow.

server {
  enabled = true
  # ...
}

vault {
  enabled   = true
  ca_path   = "/etc/certs/ca"
  cert_file = "/var/certs/vault.crt"
  key_file  = "/var/certs/vault.key"

  # Address to communicate with Vault. The below is the default address if
  # unspecified.
  address = "https://vault.service.consul:8200"

  # Embedding the token in the configuration is discouraged. Instead users
  # should set the VAULT_TOKEN environment variable when starting the Nomad
  # agent
  token = "debecfdc-9ed7-ea22-c6ee-948f22cdd474"

  # Setting the create_from_role option causes Nomad to create tokens for tasks
  # via the provided role. This allows the role to manage what policies are
  # allowed and disallowed for use by tasks.
  create_from_role = "nomad-cluster"
}

Nomad Client

This example shows a Vault configuration for a Nomad client.

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.