Nomad Docs: Enhance client intro release note & add usage guide #1384
Conversation
Vercel Previews Deployed
|
Broken Link CheckerNo broken links found! 🎉 |
boruszak
left a comment
boruszak
left a comment
There was a problem hiding this comment.
I left suggestions and my reasoning. Otherwise LGTM!
content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx
Outdated
Show resolved
Hide resolved
content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx
Outdated
Show resolved
Hide resolved
content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx
Outdated
Show resolved
Hide resolved
| [JSON Web Token (JWT)][] that has been signed by the leader's keyring and is | ||
| generated as part of the node's registration and heartbeat process. | ||
|
|
||
| The node identity feature is like multi-factor authentication for your Nomad |
There was a problem hiding this comment.
Do we want to call out that this is node introduction rather than identity? I see two different features and node identity does not act like MFA, it's node introduction that does.
If we wanted to expand the context, mTLS guards at the region level and stops misconfigured clients joining the wrong region or agents running in the wrong mode.
Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
aimeeu
changed the title
boruszak
left a comment
boruszak
left a comment
There was a problem hiding this comment.
See my comments about the overall workflow. I started just leaving suggestions, but after reading through the steps several times I'm not quite able to parse what is actually happening and why the ACL token is required.
|
|
||
| Follow these steps to use client node introduction tokens: | ||
|
|
||
| 1. [Create an ACL policy in which the node has write permissions](#create-an-acl-policy). |
There was a problem hiding this comment.
| 1. [Create an ACL policy in which the node has write permissions](#create-an-acl-policy). | |
| 1. [Create an ACL policy for a node with write permissions](#create-an-acl-policy). |
Simplifying this
| } | ||
| ``` | ||
|
|
||
| 1. Create the policy. |
There was a problem hiding this comment.
| 1. Create the policy. | |
| 1. Add the policy to the Nomad cluster. |
To avoid repetition with the step before this one and clarify what is happening.
|
|
||
| ### Create an ACL role | ||
|
|
||
| This example creates an ACL role called `client-introduction`. |
There was a problem hiding this comment.
| This example creates an ACL role called `client-introduction`. | |
| Create an ACL role, and attach the policy you created to the role. | |
| This example creates an ACL role with the name `client-introduction` that uses the policy `client-introduction`. |
- Instructions to begin the section, then the example.
- Trying to point out both CLI flags because the example uses the same name but that isn't a requirement.
| -policy="client-introduction" | ||
| ``` | ||
|
|
||
| Output is similar to the this: |
There was a problem hiding this comment.
| Output is similar to the this: | |
| The output describes the ACL role, including its attached policies and the Raft index at its creation. |
| [`-client-intro-token` parameter](/nomad/commands/agent#client-intro-token) of | ||
| the `nomad agent` command. Alternately, you may place the `intro_token.jwt` file | ||
| in the client's state directory, which is by default [the | ||
| `<data_dir>/client_state_dir>` |
There was a problem hiding this comment.
Missing and/or extra bracket?
| You may optionally specify node names, node pools, and TTLs when you generate | ||
| client introduction tokens. | ||
|
|
||
| Follow these steps to use client node introduction tokens: |
There was a problem hiding this comment.
| Follow these steps to use client node introduction tokens: | |
| The workflow for client introduction tokens uses two tokens: an _ACL token_ and a _client introduction token_. The ACL token allows the node to create a client introduction token, which you apply to the Nomad client when you start it. |
I'm trying to summarize the overall workflow, but finding it a bit convoluted.
|
|
||
| ```shell-session | ||
| Accessor ID = 8c22a7c0-44f5-044d-ef84-bfa06118faf4 | ||
| Secret ID = d99d678d-426c-330e-74f3-de53a868e2f9 |
There was a problem hiding this comment.
Highlighting the value of the client-intro-token-1 ACL token, which all instructions up to this point have led to creating.
| ```shell-session | ||
| curl \ | ||
| --request POST \ | ||
| --header "X-Nomad-Token: d99d678d-426c-330e-74f3-de53a868e2f9" \ |
There was a problem hiding this comment.
Here's the client-intro-token-1 ACL token value. So now I have a few questions.
- Should the CLI instructions have included a step to use the ACL token as well?
- Are you supposed to create a separate ACL token for each node, and that's why it's
token-1? - Or should you be creating a separate intro token for each client, using the one shared ACL token?
But now I'm confused about the workflow. You create an ACL token so that a client node has permission to contact a server and change policies (which covers creating client introduction tokens). Then the node uses the client introduction token it creates to join the cluster it already has a valid ACL token from? Why the dedicated client token, then, when there's already an ACL token being used?
3 participants
Description
Enhance the client node intro and identity release note with content from Benjamin Lykins' blog. This builds on the previous PR that added the bit about not replacing mTLS.
Links
Jira: CE-1084 CE-1088
Contributor checklists
Review urgency:
Pull request:
Content:
Reviewer checklist