---
layout: docs
page_title: 'Commands: setup vault'
description: |
  Setup a Vault cluster for Nomad integration.
---

# Command: setup vault

This command sets up Vault for allowing Nomad workloads to authenticate
themselves using Workload Identity.

This command requires `acl:write` permissions for Vault and respects
`VAULT_TOKEN`, `VAULT_ADDR`, and other [Vault-related environment
variables][vaultenv].

The `-check` option can be used to verify if the Nomad cluster is ready to
migrate to use Workload Identities with Vault. This option requires
`operator:read` permission for Nomad.

Refer to [Migrating to Using Workload Identity with
Vault][nomad_acl_vault_wid_migrate] for more information.

<Warning>

This command is an experimental feature and may change its behavior in future
versions of Nomad.

</Warning>

## Usage

```plaintext
nomad setup vault [options]
```

## Setup Vault Options

- `-jwks-url`: URL of Nomad's JWKS endpoint contacted by Consul to verify JWT
  signatures. Defaults to `http://localhost:4646/.well-known/jwks.json`.

- `-jwks-ca-file`: Path to a CA certificate file that will be used to validate
  the JWKS URL if it uses TLS.

- `-destroy`: Removes all configuration components this command created from the
  Consul cluster.

- `-y`: Automatically answers `yes` to all the questions, making the setup
  non-interactive. Defaults to `false`.

- `-check`: Verify if the Nomad cluster is ready to migrate to Workload
  Identities.

### Setup Vault Options When Using `-check`:

- `-json`: Output migration status information in its JSON format.

- `-t`: Format and display migration status information using a Go template.

- `-verbose`: Display full information.

@include 'general_options_no_namespace.mdx'

## Examples

Below is an example of an interactive session with default options, interrupted
by answering `no` to one of the questions, demonstrating the capabilities of the
`-destroy` flag.

```shell-session
$ nomad setup vault

This command will walk you through configuring all the components required for
Nomad workloads to authenticate themselves against Vault ACL using their
respective workload identities.

First we need to connect to Vault.

[?] Is "http://127.0.0.1:8200" the correct address of your Vault cluster? [Y/n]

Since you're running Vault Enterprise, we will additionally create
a namespace "nomad-workloads" and create all configuration within that namespace.

[?] Create the namespace "nomad-workloads" in your Vault cluster? [Y/n]
[✔] Created namespace "nomad-workloads".

We will now enable the JWT credential backend and create a JWT auth method that
Nomad workloads will use.

This is the method configuration:

{
    "default_role": "nomad-workloads",
    "jwks_url": "http://localhost:4646/.well-known/jwks.json",
    "jwt_supported_algs": [
        "EdDSA",
        "RS256"
    ]
}
[?] Create JWT auth method in your Vault cluster? [Y/n]
[✔] Created JWT auth method "jwt-nomad".

We need to create a role that Nomad workloads will assume while authenticating,
and a policy associated with that role.


These are the rules for the policy "nomad-workloads" that we will create. It uses a templated
policy to allow Nomad tasks to access secrets in the path
"secrets/data/<job namespace>/<job name>":

path "secret/data/{{identity.entity.aliases.auth_jwt_1b8dcc32.metadata.nomad_namespace}}/{{identity.entity.aliases.auth_jwt_1b8dcc32.metadata.nomad_job_id}}/*" {
  capabilities = ["read"]
}

path "secret/data/{{identity.entity.aliases.auth_jwt_1b8dcc32.metadata.nomad_namespace}}/{{identity.entity.aliases.auth_jwt_1b8dcc32.metadata.nomad_job_id}}" {
  capabilities = ["read"]
}

path "secret/metadata/{{identity.entity.aliases.auth_jwt_1b8dcc32.metadata.nomad_namespace}}/*" {
  capabilities = ["list"]
}

path "secret/metadata/*" {
  capabilities = ["list"]
}

[?] Create the above policy in your Vault cluster? [Y/n]
[✔] Created policy "nomad-workloads".

We will now create an ACL role called "nomad-workloads" associated with the policy above.

{
    "bound_audiences": "vault.io",
    "claim_mappings": {
        "nomad_job_id": "nomad_job_id",
        "nomad_namespace": "nomad_namespace",
        "nomad_task": "nomad_task"
    },
    "role_type": "jwt",
    "token_period": "30m",
    "token_policies": [
        "nomad-workloads"
    ],
    "token_type": "service",
    "user_claim": "/nomad_job_id",
    "user_claim_json_pointer": true
}
[?] Create role in your Vault cluster? [Y/n] n

By answering "no" to any of these questions, you are risking an incorrect Vault
cluster configuration. Nomad workloads with Workload Identity will not be able
to authenticate unless you create missing configuration yourself.

[?] Remove everything this command creates? [Y/n]
The following items will be deleted:
  * Policy: "nomad-workloads"
  * JWT auth method: "jwt-nomad"
  * Namespace: "nomad-workloads"

[?] Remove all the items listed above? [Y/n]
[✔] Deleted policy "nomad-workloads".
[✔] Disabled JWT auth method "jwt-nomad".
[✔] Deleted namespace "nomad-workloads".

Vault cluster has not been configured for authenticating Nomad tasks and
services using workload identities.

Run the command again to finish the configuration process.
```

The `-check` option can use to verify if a cluster is ready to migrate to using
workload identities with Vault.

```
$ nomad setup vault -check

Jobs Without Workload Identity for Vault
The following jobs access Vault but are not configured for workload identity.

You should redeploy them before fully migrating to workload identities with
Vault to prevent unexpected errors if their tokens need to be recreated.

Refer to https://developer.hashicorp.com/nomad/s/vault-workload-identity-migration
for more information.

ID       Namespace  Type     Status
example  default    service  running

Outdated Nodes
The following nodes are running a version of Nomad that does not support using
workload identities with Vault.

You should upgrade them to Nomad 1.7 before fully migrating to workload
identities with Vault to prevent unexpected errors if they receive allocations
for jobs that use Vault.

Refer to https://developer.hashicorp.com/nomad/s/vault-workload-identity-migration
for more information.

ID        Name      Address        Version  Drain  Eligibility  Status
049f7683  client-1  192.168.0.186  1.6.4    false  eligible     ready

Vault Tokens
The following Vault ACL tokens were created by Nomad but will not be
automatically revoked after migrating to workload identities. They will expire
once their TTL reaches zero.

Accessor ID               Allocation ID  Node ID   Configured TTL
czh9MPcRXzAhxBL9XKyb3Kh1  f00893d4       049f7683  60
```

[vaultenv]: /vault/docs/commands#environment-variables
[nomad_acl_vault_wid_migrate]: /nomad/docs/integrations/vault/acl#migrating-to-using-workload-identity-with-vault