Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+190 −10
Open

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
54d5a35
Enhance the client node intro rel note with blog content
aimeeu Nov 24, 2025
478ee33
Apply Jeff's suggestions
aimeeu Nov 25, 2025
f012113
add how to use client intro tokens to connect-nodes page
aimeeu Nov 25, 2025
a97b115
remove nomad token section. Rewrite. Incorp feedback
aimeeu Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions content/nomad/v1.11.x/content/docs/architecture/cluster/node-identity.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,20 @@ description: Nomad's node identity feature uniquely identities each Nomad client

This page provides conceptual information about Nomad's node identity feature,
which uniquely identities each Nomad client node and provides an authentication
mechanism for nodes to make RPC calls to the Nomad servers. This feature does
not replace mTLS.
mechanism for nodes to make RPC calls to the Nomad servers.

The Nomad cluster gives every node a default identity once the cluster is able
to fully support the feature with a defined lifetime. This node identity is a
[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
Copy link
Member

@jrasell jrasell Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@aimeeu aimeeu Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

clusters. It does not replace mTLS but adds a second layer of security to
prevent an unauthorized client from joining a Nomad cluster. Using a client
introduction token gives you the added benefit of additional control over
misconfigured clients trying to join the cluster. You can specify node names,
node pools, and TTLs for the tokens you generate.

## Node identity claims

Alongside the standard JWT claims such as `exp` (expiration time), `iat` (issued
Expand Down
16 changes: 15 additions & 1 deletion content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,28 @@ We are pleased to announce the following Nomad updates.

Nomad's client node identity feature uniquely identities each Nomad client node
and provides an authentication mechanism for nodes to make RPC calls to the
Nomad servers. This feature does not replace mTLS.
Nomad servers.

Introduce Nomad clients to the cluster with JWT tokens. Configure Nomad servers
with introduction enforcement levels that dictate how clients join the cluster.
This approach results in logs and metrics to detail introduction violations.
Once registered, Nomad clients are now provided with an identity token, used for
RPC communication which is periodically renewed.

The client node introduction and identity feature is like multi-factor
authentication for your Nomad clusters. It does not replace mTLS but adds
a second layer of security to prevent an unauthorized client from joining a
Nomad cluster.

Each layer answers a distinct question.

- Networking: Can the client reach the server?
- mTLS: Does the client have valid certificates for the cluster?
- Client introduction token: Does the client have a valid token to join the
cluster?

Using a client introduction token gives you the added benefit of additional control over misconfigured clients trying to join the cluster. You can specify node names, node pools, and TTLs for the tokens you generate.

#### Relevant documentation

- [Client node identity concepts](/nomad/docs/architecture/cluster/node-identity)
Expand Down
Loading