mirror of
https://github.com/kemko/nomad.git
synced 2026-01-06 02:15:43 +03:00
dae496e427
* Enhance front matter description for search * acl section * alloc section * config section * deployment section * eval section * job section * license section * namespace section * node section * node pool section * operator section * plugin section * quota section * recommendation section * scaling section * sentinel section * server section * service section * setup section * system section * tls section * var section * volume section * change reference to command reference * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --------- Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
152 lines
4.9 KiB
Plaintext
152 lines
4.9 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: 'nomad setup consul command reference'
|
|
description: |
|
|
The `nomad setup consul` command configures a Consul cluster to allow Nomad workloads to authenticate themselves with workload identity.
|
|
---
|
|
|
|
# `nomad setup consul` command reference
|
|
|
|
The `nomad setup consul` command configures a Consul cluster to allow Nomad workloads to authenticate themselves with workload identity.
|
|
|
|
This command requires `acl:write` permissions for Consul and respects
|
|
`CONSUL_HTTP_TOKEN`, `CONSUL_HTTP_ADDR`, and other [Consul-related environment
|
|
variables][consulenv].
|
|
|
|
## Usage
|
|
|
|
```plaintext
|
|
nomad setup consul [options]
|
|
```
|
|
|
|
## 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`.
|
|
|
|
## 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 consul
|
|
|
|
This command will walk you through configuring all the components required for
|
|
Nomad workloads to authenticate themselves against Consul ACL using their
|
|
respective workload identities.
|
|
|
|
First we need to connect to Consul.
|
|
|
|
[?] Is "127.0.0.1:8500" the correct address of your Consul cluster? [Y/n]
|
|
|
|
Since you're running Consul Enterprise, we will additionally create
|
|
a namespace "nomad-workloads" and bind the auth methods to that namespace.
|
|
|
|
[?] Create the namespace "nomad-workloads" in your Consul cluster? [Y/n]
|
|
[✔] Created namespace "nomad-workloads".
|
|
|
|
Nomad needs a JWT auth method for Consul services and tasks. The method for
|
|
services will be called "nomad-workloads".
|
|
|
|
This is the "nomad-workloads" method configuration:
|
|
|
|
{
|
|
"Name": "nomad-workloads",
|
|
"Type": "jwt",
|
|
"DisplayName": "nomad-workloads",
|
|
"Description": "Login method for Nomad workloads using workload identities",
|
|
"TokenLocality": "local",
|
|
"Config": {
|
|
"BoundAudiences": [
|
|
"consul.io"
|
|
],
|
|
"ClaimMappings": {
|
|
"consul_namespace": "consul_namespace",
|
|
"nomad_job_id": "nomad_job_id",
|
|
"nomad_namespace": "nomad_namespace",
|
|
"nomad_service": "nomad_service",
|
|
"nomad_task": "nomad_task"
|
|
},
|
|
"JWKSURL": "http://localhost:4646/.well-known/jwks.json",
|
|
"JWTSupportedAlgs": [
|
|
"RS256"
|
|
]
|
|
},
|
|
"CreateIndex": 0,
|
|
"ModifyIndex": 0,
|
|
"NamespaceRules": [
|
|
{
|
|
"BindNamespace": "${value.consul_namespace}"
|
|
}
|
|
]
|
|
}
|
|
[?] Create "nomad-workloads" auth method in your Consul cluster? [Y/n]
|
|
[✔] Created auth method "nomad-workloads".
|
|
|
|
Consul uses binding rules to map claims between Nomad's JWTs to Consul service
|
|
identities and ACL roles, so we need to create a two binding rules for the auth
|
|
method we created above: one for services, and one for tasks.
|
|
|
|
This is the binding rule for services:
|
|
|
|
{
|
|
"ID": "",
|
|
"Description": "Binding rule for Nomad services authenticated using a workload identity",
|
|
"AuthMethod": "nomad-workloads",
|
|
"Selector": "\"nomad_service\" in value",
|
|
"BindType": "service",
|
|
"BindName": "${value.nomad_service}",
|
|
"CreateIndex": 0,
|
|
"ModifyIndex": 0
|
|
}
|
|
[?] Create this binding rule in your Consul cluster? [Y/n]
|
|
[✔] Created binding rule for auth method "nomad-workloads".
|
|
|
|
This is the binding rule for tasks:
|
|
|
|
{
|
|
"ID": "",
|
|
"Description": "Binding rule for Nomad tasks authenticated using a workload identity",
|
|
"AuthMethod": "nomad-workloads",
|
|
"Selector": "\"nomad_service\" not in value",
|
|
"BindType": "role",
|
|
"BindName": "nomad-${value.nomad_namespace}-tasks",
|
|
"CreateIndex": 0,
|
|
"ModifyIndex": 0
|
|
}
|
|
[?] Create this binding rule in your Consul cluster? [Y/n] n
|
|
|
|
By answering "no" to any of these questions, you are risking an incorrect Consul
|
|
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:
|
|
* Auth method: nomad-workloads
|
|
* Binding rules: 4d80108a-6d77-36e1-71b1-d20a9acf8b17
|
|
* Namespace: nomad-workloads
|
|
|
|
[?] Remove all the items listed above? [Y/n]
|
|
[✔] Deleted binding rule "4d80108a-6d77-36e1-71b1-d20a9acf8b17".
|
|
[✔] Deleted auth method "nomad-workloads".
|
|
[✔] Deleted namespace "nomad-workloads".
|
|
|
|
Consul cluster has not been configured for authenticating Nomad tasks and
|
|
services using workload identitiies.
|
|
|
|
Run the command again to finish the configuration process.
|
|
```
|
|
|
|
[consulenv]: /consul/commands#environment-variables
|