mirror of
https://github.com/kemko/nomad.git
synced 2026-01-01 16:05:42 +03:00
f9dd120d29
When setting up auth methods for Consul and Vault in production environments, we can typically assume that the CA certificate for the JWKS endpoint will be in the host certificate store (as part of the usual configuration management cluster admins needs to do). But for quick demos with `-dev` agents, this won't be the case. Add a `-jwks-ca-file` parameter to the setup commands so that we can use this tool to quickly setup WI with `-dev` agents running TLS.
214 lines
6.7 KiB
Plaintext
214 lines
6.7 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`.
|
|
|
|
- `-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
|