mirror of
https://github.com/kemko/nomad.git
synced 2026-01-01 16:05:42 +03:00
e1e80f383e
The new `nomad setup vault -check` commmand can be used to retrieve information about the changes required before a cluster is migrated from the deprecated legacy authentication flow with Vault to use only workload identities.
211 lines
6.6 KiB
Plaintext
211 lines
6.6 KiB
Plaintext
---
|
|
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`.
|
|
|
|
- `-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
|