Nomad Docs: Enhance client intro release note & add usage guide #1384

aimeeu · 2025-11-24T22:21:50Z

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:

ASAP: Bug fixes, broken content, imminent releases
3 days: Small changes, easy reviews
1 week: Default expectation
Best effort: No urgency

Pull request:

Verify that the PR is set to merge into the correct base branch
Verify that all status checks passed
Verify that the preview environment deployed successfully
Add additional reviewers if they are not part of assigned groups

Content:

I added redirects for any moved or removed pages
I followed the Education style guide
I looked at the local or Vercel build to make sure the content rendered correctly

Reviewer checklist

This PR is set to merge into the correct base branch.
The content does not contain technical inaccuracies.
The content follows the Education content and style guides.
I have verified and tested changes to instructions for end users.

github-actions · 2025-11-24T22:24:14Z

Vercel Previews Deployed

Name	Status	Preview	Updated (UTC)
Dev Portal	✅ Ready (Inspect)	Visit Preview	Thu Dec 4 18:20:07 UTC 2025
Unified Docs API	✅ Ready (Inspect)	Visit Preview	Thu Dec 4 18:15:15 UTC 2025

github-actions · 2025-11-24T22:47:03Z

Broken Link Checker

No broken links found! 🎉

boruszak

I left suggestions and my reasoning. Otherwise LGTM!

content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx

jrasell · 2025-11-25T08:07:19Z

content/nomad/v1.11.x/content/docs/architecture/cluster/node-identity.mdx

 [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


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.

@jrasell I created a new section in the connect nodes into a cluster page. "Use client node introduction tokens" based 100% on Benjamin Lynkins blog but cut down to bare bones. Anthony is planning a longer tutorial on how to use client introduction.

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

boruszak

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.

boruszak · 2025-11-26T20:36:04Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+
+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).   


Suggested change

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

boruszak · 2025-11-26T20:37:51Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+   }
+   ```
+
+1. Create the policy.


Suggested change

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.

boruszak · 2025-11-26T20:41:00Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+
+### Create an ACL role
+
+This example creates an ACL role called `client-introduction`.


Suggested change

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.

boruszak · 2025-11-26T20:42:33Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+-policy="client-introduction"
+```
+
+Output is similar to the this:


Suggested change

Output is similar to the this:

The output describes the ACL role, including its attached policies and the Raft index at its creation.

boruszak · 2025-11-26T20:44:57Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+[`-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>`


Missing and/or extra bracket?

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

boruszak · 2025-11-26T20:56:34Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+
+```shell-session
+Accessor ID  = 8c22a7c0-44f5-044d-ef84-bfa06118faf4
+Secret ID    = d99d678d-426c-330e-74f3-de53a868e2f9


Highlighting the value of the client-intro-token-1 ACL token, which all instructions up to this point have led to creating.

boruszak · 2025-11-26T21:06:08Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+```shell-session
+curl \
+    --request POST \
+    --header "X-Nomad-Token: d99d678d-426c-330e-74f3-de53a868e2f9" \


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?

jrasell · 2025-12-01T15:06:06Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+You may optionally specify node names, node pools, and TTLs when you generate
+client introduction tokens.


Is it worth stating our stance being that we should specify node names and node pool when creating an identity token to tightly scope and provide more security?

boruszak

Much more clear to me this time, with the existing ACL token issue taken care of.

My big suggestion is to be more explicit about the change from working on the server node to working on the client node, which gets buried in the term "Nomad agent."

boruszak · 2025-12-03T21:30:02Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+You may restrict which clients join your cluster with a client
+introduction token. The client node introduction feature is like multi-factor
+authentication for your Nomad clusters. It does not replace mTLS but adds an
+additional layer of security to prevent an unauthorized or misconfigured client
+from joining a Nomad cluster. Although you do not need to configure mTLS to use
+client node introduction tokens, we do recommend securing your cluster with mTLS.


Suggested change

You may restrict which clients join your cluster with a client

introduction token. The client node introduction feature is like multi-factor

authentication for your Nomad clusters. It does not replace mTLS but adds an

additional layer of security to prevent an unauthorized or misconfigured client

from joining a Nomad cluster. Although you do not need to configure mTLS to use

client node introduction tokens, we do recommend securing your cluster with mTLS.

Use client introduction tokens to restrict which clients join your cluster.

The client node introduction feature is like multi-factor authentication

for your Nomad clusters. **It does not replace mTLS**, but instead adds an

additional layer of security that prevents an unauthorized or misconfigured client

from joining a Nomad cluster.

Moving the last sentence to the next line. Changes to the first sentence simplify the sentence and main idea. Bold is optional. I believe it fits the style guidelines about emphasis for differentiation but not semantic emphasis.

boruszak · 2025-12-03T21:33:41Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+from joining a Nomad cluster. Although you do not need to configure mTLS to use
+client node introduction tokens, we do recommend securing your cluster with mTLS.
+
+Each security layer answers a distinct question:


Suggested change

Each security layer answers a distinct question:

You do not need to configure mTLS before you use client node introduction tokens. However, we do recommend securing your cluster with mTLS, even if you use a client introduction because each security layer answers a distinct question:

I'm not a fan of the rhetorical questions, but if you keep them flesh out the setup to provide context.

boruszak · 2025-12-03T21:37:38Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+When you generate a client introduction token, you may specify the following
+optional parameters:


Suggested change

When you generate a client introduction token, you may specify the following

optional parameters:

Optionally, you can specify additional parameters for your client introduction token to further secure their cluster access:

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

boruszak · 2025-12-03T21:41:29Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+
+- You have [bootstrapped the ACL system](/nomad/docs/secure/acl/bootstrap).
+- You have a management token.
+- You have configured the CLI to use the management token.


Suggested change

- You have configured the CLI to use the management token.

- You set the value of the management to `$NOMAD_TOKEN` to use the CLI.

More actionable/direct by stating the env. variable.

boruszak · 2025-12-03T21:48:56Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+1. [Configure the Nomad agent to use client introduction](#configure-the-nomad-agent).
+1. [Start the Nomad agent](#start-the-nomad-agent).


Suggested change

1. [Configure the Nomad agent to use client introduction](#configure-the-nomad-agent).

1. [Start the Nomad agent](#start-the-nomad-agent).

1. [Update the Nomad server's configuration to use client introduction tokens](#update-the-nomad-server).

1. [Start the Nomad agent on the client node](#start-the-nomad-agent).

You've mentioned previously the terminology blur around "Nomad server" and "Nomad agent." I suggest differentiating with the phrasing here because it's the only part of these instructions where there's lingering ambiguity around a sudden change. All of the previous steps interact with the Nomad server, and then you start the agent on the client node with the token attached.

You aren't starting the agent on the client node. The agent in question is the server.

boruszak · 2025-12-03T21:49:31Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+ "eyJhbGciOiJSUzI1NiIsImtpZCI6IjljZDgy..."
+```
+
+### Configure the Nomad agent


Suggested change

### Configure the Nomad agent

### Update the Nomad server's configuration

boruszak · 2025-12-03T21:51:11Z

content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx

+
+</CodeBlockConfig>
+
+There is no additional client configuration.


Suggested change

There is no additional client configuration.

This example also sets default and max TTLs for the client introduction token.

No additional configuration is required on the client node.

To be more explicit about the other parameters in the example.

Enhance the client node intro rel note with blog content

54d5a35

aimeeu requested review from a team as code owners November 24, 2025 22:21

aimeeu added the Nomad label Nov 24, 2025

boruszak approved these changes Nov 24, 2025

View reviewed changes

jrasell reviewed Nov 25, 2025

View reviewed changes

aimeeu and others added 2 commits November 25, 2025 11:18

Apply Jeff's suggestions

478ee33

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

add how to use client intro tokens to connect-nodes page

f012113

aimeeu changed the title ~~Nomad Docs: Enhance client intro release note~~ Nomad Docs: Enhance client intro release note & add usage guide Nov 25, 2025

boruszak requested changes Nov 26, 2025

View reviewed changes

jrasell reviewed Dec 1, 2025

View reviewed changes

aimeeu added the Runtime label Dec 1, 2025

remove nomad token section. Rewrite. Incorp feedback

a97b115

boruszak approved these changes Dec 3, 2025

View reviewed changes

address feedback; fix typo in release notes

052837e

aimeeu merged commit c0506ff into main Dec 4, 2025
15 checks passed

aimeeu deleted the aimeeu-ce1084-client branch December 4, 2025 18:43


		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).

	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).

	1. Create the policy.
	1. Add the policy to the Nomad cluster.


		### Create an ACL role

		This example creates an ACL role called `client-introduction`.

-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`.

	Output is similar to the this:
	The output describes the ACL role, including its attached policies and the Raft index at its creation.

		You may optionally specify node names, node pools, and TTLs when you generate
		client introduction tokens.

	Each security layer answers a distinct question:
	You do not need to configure mTLS before you use client node introduction tokens. However, we do recommend securing your cluster with mTLS, even if you use a client introduction because each security layer answers a distinct question:

		When you generate a client introduction token, you may specify the following
		optional parameters:

	When you generate a client introduction token, you may specify the following
	optional parameters:
	Optionally, you can specify additional parameters for your client introduction token to further secure their cluster access:

	- You have configured the CLI to use the management token.
	- You set the value of the management to `$NOMAD_TOKEN` to use the CLI.

		1. [Configure the Nomad agent to use client introduction](#configure-the-nomad-agent).
		1. [Start the Nomad agent](#start-the-nomad-agent).

	### Configure the Nomad agent
	### Update the Nomad server's configuration


		</CodeBlockConfig>

		There is no additional client configuration.

-There is no additional client configuration.
+This example also sets default and max TTLs for the client introduction token.
+No additional configuration is required on the client node.

Nomad Docs: Enhance client intro release note & add usage guide #1384

Nomad Docs: Enhance client intro release note & add usage guide #1384

Conversation

aimeeu commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Links

Contributor checklists

Reviewer checklist

Uh oh!

github-actions bot commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vercel Previews Deployed

Uh oh!

github-actions bot commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Broken Link Checker

Uh oh!

boruszak left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

boruszak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

boruszak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aimeeu commented Nov 24, 2025 •

edited

Loading

github-actions bot commented Nov 24, 2025 •

edited

Loading

github-actions bot commented Nov 24, 2025 •

edited

Loading