HashiConf 2024 Now streaming live from Boston! Attend for free
Nomad
Nomad Home

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.

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 for more information.

Warning

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

Usage

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.

  • -address=<addr>: The address of the Nomad server. Overrides the NOMAD_ADDR environment variable if set. Defaults to http://127.0.0.1:4646.

  • -region=<region>: The region of the Nomad server to forward commands to. Overrides the NOMAD_REGION environment variable if set. Defaults to the Agent's local region.

  • -no-color: Disables colored command output. Alternatively, NOMAD_CLI_NO_COLOR may be set. This option takes precedence over -force-color.

  • -force-color: Forces colored command output. This can be used in cases where the usual terminal detection fails. Alternatively, NOMAD_CLI_FORCE_COLOR may be set. This option has no effect if -no-color is also used.

  • -ca-cert=<path>: Path to a PEM encoded CA cert file to use to verify the Nomad server SSL certificate. Overrides the NOMAD_CACERT environment variable if set.

  • -ca-path=<path>: Path to a directory of PEM encoded CA cert files to verify the Nomad server SSL certificate. If both -ca-cert and -ca-path are specified, -ca-cert is used. Overrides the NOMAD_CAPATH environment variable if set.

  • -client-cert=<path>: Path to a PEM encoded client certificate for TLS authentication to the Nomad server. Must also specify -client-key. Overrides the NOMAD_CLIENT_CERT environment variable if set.

  • -client-key=<path>: Path to an unencrypted PEM encoded private key matching the client certificate from -client-cert. Overrides the NOMAD_CLIENT_KEY environment variable if set.

  • -tls-server-name=<value>: The server name to use as the SNI host when connecting via TLS. Overrides the NOMAD_TLS_SERVER_NAME environment variable if set.

  • -tls-skip-verify: Do not verify TLS certificate. This is highly not recommended. Verification will also be skipped if NOMAD_SKIP_VERIFY is set.

  • -token: The SecretID of an ACL token to use to authenticate API requests with. Overrides the NOMAD_TOKEN environment variable if set.

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.

$ 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
Edit this page on GitHub