From 54d5a35185a7fb925041576af0a83a6b968a198a Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Mon, 24 Nov 2025 16:19:20 -0600 Subject: [PATCH 1/5] Enhance the client node intro rel note with blog content --- .../docs/architecture/cluster/node-identity.mdx | 10 ++++++++-- .../content/docs/release-notes/nomad/v1-11-x.mdx | 16 +++++++++++++++- 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/content/nomad/v1.11.x/content/docs/architecture/cluster/node-identity.mdx b/content/nomad/v1.11.x/content/docs/architecture/cluster/node-identity.mdx index 8e8b8492e6..ad34e5f471 100644 --- a/content/nomad/v1.11.x/content/docs/architecture/cluster/node-identity.mdx +++ b/content/nomad/v1.11.x/content/docs/architecture/cluster/node-identity.mdx @@ -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 +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 diff --git a/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx b/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx index 7149aef85f..405f82f8e8 100644 --- a/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx +++ b/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx @@ -15,7 +15,7 @@ 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. @@ -23,6 +23,20 @@ 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) From 478ee3320c23b0898360bff69b72ce4a577b9474 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Tue, 25 Nov 2025 11:18:41 -0600 Subject: [PATCH 2/5] Apply Jeff's suggestions Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- .../content/docs/release-notes/nomad/v1-11-x.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx b/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx index 405f82f8e8..409c1819e6 100644 --- a/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx +++ b/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx @@ -23,10 +23,10 @@ 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. +The client node introduction and identity feature functions as multi-factor +authentication for your Nomad clusters. It does not replace mTLS. Instead, +it adds a second layer of security to prevent an unauthorized client from +joining a Nomad cluster. Each layer answers a distinct question. @@ -35,7 +35,7 @@ Each layer answers a distinct question. - 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. +Using a client introduction token gives you additional control over misconfigured clients trying to join the Nomad cluster because you can specify node names, node pools, and TTLs for the tokens you generate. #### Relevant documentation From f012113cb76166286b5595bfe50aafa21da75035 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Tue, 25 Nov 2025 13:32:29 -0600 Subject: [PATCH 3/5] add how to use client intro tokens to connect-nodes page --- .../architecture/cluster/node-identity.mdx | 9 +- .../docs/deploy/clusters/connect-nodes.mdx | 226 +++++++++++++++++- .../docs/release-notes/nomad/v1-11-x.mdx | 19 +- 3 files changed, 230 insertions(+), 24 deletions(-) diff --git a/content/nomad/v1.11.x/content/docs/architecture/cluster/node-identity.mdx b/content/nomad/v1.11.x/content/docs/architecture/cluster/node-identity.mdx index ad34e5f471..cfcdedfd56 100644 --- a/content/nomad/v1.11.x/content/docs/architecture/cluster/node-identity.mdx +++ b/content/nomad/v1.11.x/content/docs/architecture/cluster/node-identity.mdx @@ -15,13 +15,6 @@ 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 -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 @@ -54,7 +47,7 @@ lifetime check is bypassed. A node's identity is stored within its local database, which is persisted within the configured [`data_dir`][client_cfg_state_dir]. To view the stored identity, -along with other state resouces, run the +along with other state resources, run the [`operator client-state` command][cli_operattor_client_state]. [JSON Web Token (JWT)]: https://datatracker.ietf.org/doc/html/rfc7519 diff --git a/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx b/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx index 5d1f406ae8..70ca55063b 100644 --- a/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx +++ b/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx @@ -11,13 +11,16 @@ description: |- In order to create a Nomad cluster out of individual nodes, you need to introduce them to one another. There are several ways to perform this: -- Manually +- Manual bootstrap - Cloud Auto-Join - Consul -This tutorial describes each method and provides configuration snippets, which +This guide describes each method and provides configuration snippets, which you can use as starting points for your own configuration. +You may also use client node introduction tokens to restrict which clients join +your cluster. + ## Manual clustering Manually bootstrapping a Nomad cluster does not rely on additional tooling, but @@ -82,9 +85,9 @@ the client. This means only one server must be specified because, after initial contact, the full set of servers in the client's region are shared with the client. -## Join nodes using cloud auto-join +## Use cloud auto-join -As of Nomad 0.8.4, [`retry_join`] accepts a unified interface using the +The [`retry_join`] parameter accepts a unified interface using the [go-discover] library for doing automatic cluster joining using cloud metadata. To use retry-join with a supported cloud provider, specify the configuration on the command line or configuration file as a `key=value key=value ...` string. @@ -214,6 +217,221 @@ consul { Refer to the [`consul` stanza] documentation for the complete set of configuration options. + +## Use client node introduction tokens + +You may restrict which clients join your cluster by configuring client +introduction tokens. The client node introduction 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 or misconfigured client from +joining a Nomad cluster. + +Each layer answers a distinct question: + +- mTLS: Does the client have valid certificates for the cluster? +- Client introduction token: Does the client have a valid token to join the +cluster? + +You do not need to configure mTLS to use client node introduction tokens, but we +do recommend securing your cluster with mTLS. + +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: + +1. [Create an ACL policy in which the node has write permissions](#create-an-acl-policy). +1. [Create an ACL role from the policy](#create-an-acl-role). +1. [Generate a Nomad token](#generate-a-nomad-token). +1. [Generate a client introduction token](#generate-a-client-introduction-token). +1. [Configure the Nomad agent to use client introduction](#configure-the-nomad-agent). +1. [Start the Nomad agent](#start-the-nomad-agent). +1. [Monitor client join failures](#monitor-client-join-failures). + +### Create an ACL policy + +This example creates the `node:write` policy required to generate tokens. + +1. Create a policy file called `client-introduction.hcl`. + + ```hcl + node { + policy = "write" + } + ``` + +1. Create the policy. + + ```shell-session + nomad acl policy apply client-introduction client-introduction.hcl + ``` + +### Create an ACL role + +This example creates an ACL role called `client-introduction`. + +```shell-session +nomad acl role create --tls-skip-verify -name="client-introduction" \ +-policy="client-introduction" +``` + +Output is similar to the this: + +```shell-session +ID = cf0b4a43-b00f-cc30-b656-b34d66151b04 +Name = client-introduction +Description = +Policies = client-introduction +Create Index = 117 +Modify Index = 117 +``` + +### Generate a Nomad token + +Generate an ACL token from the `client-introduction` role. Nomad uses this +token to request client introduction tokens. In a production environment, we +recommend that you use Vault to generate and manage these tokens. + +```shell-session +nomad acl token create -name="client-intro-token-1" \ +-role-name="client-introduction" -type=client -ttl=8h +``` + +Output is similar to this: + +```shell-session +Accessor ID = 8c22a7c0-44f5-044d-ef84-bfa06118faf4 +Secret ID = d99d678d-426c-330e-74f3-de53a868e2f9 +Name = client-intro-token-1 +Type = client +Global = false +Create Time = 2025-11-18 21:01:44.62075624 +0000 UTC +Expiry Time = 2025-11-19 05:01:44.62075624 +0000 UTC +Create Index = 128 +Modify Index = 128 +Policies = [] + +Roles +ID Name +cf0b4a43-b00f-cc30-b656-b34d66151b04 client-introduction +``` + +### Generate a client introduction token + +The following snippets generate a basic token. + + + + +Use the [`nomad node intro create` command](/nomad/commands/node/intro/create) to generate the client introduction token. + +```shell-session +nomad node intro create > intro_token.jwt +``` + +The `intro-token.jwt` contents are similar to this. + +```shell-session + "eyJhbGciOiJSUzI1NiIsImtpZCI6IjljZDgy..." +``` + + + + +Use the [client introduction identity +endpoint](/nomad/api-docs/acl/identities#create-client-introduction-identity) to +generate the client introduction token. This example sends an empty JSON object, +but you may use a JSON payload file to specify parameters such as `NodeName`, +`NodePool`, and `TTL`. + +```shell-session +curl \ + --request POST \ + --header "X-Nomad-Token: d99d678d-426c-330e-74f3-de53a868e2f9" \ + --data {} \ + https://localhost:4646/v1/acl/identity/client-introduction-token \ + >> intro_token.jwt +``` + +The response includes the JWT. + +```shell-session +{ + "JWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjljZDgy..." +} +``` + + + + +### Configure the Nomad agent + +Configure the Nomad agent's `server.client_introduction` block. This example +sets the `enforcement` parameter to `strict`, which means the agent rejects any +client without without a valid token. Refer to the [`server.client_introduction` +block +documentation](/nomad/docs/configuration/server#client_introduction-parameters) +for additional enforcement options. + + + +```hcl +data_dir = "/opt/nomad/" +acl { + enabled = true +} +server { + enabled = true + bootstrap_expect = 1 + client_introduction { + enforcement = "strict" # Default = "warn" + default_identity_ttl = "5m" # Default = "5m" + max_identity_ttl = "30m" # Default = "30m" + } +} +tls { + http = true + rpc = true + ca_file = "/opt/nomad/tls/nomad-agent-ca.pem" + cert_file = "/opt/nomad/tls/global-server-nomad.pem" + key_file = "/opt/nomad/tls/global-server-nomad-key.pem" +} +``` + + + +There is no additional client configuration. + +### Start the Nomad agent + +We recommend setting the JWT token in an environment variable called +`NOMAD_CLIENT_INTRO_TOKEN`. The next option is to set it in the +[`-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 +`/client_state_dir>` +directory](/nomad/docs/configuration/client#state_dir). + +This example starts the agent with the JWT token set in the +`-client-intro-token` parameter. + +```shell-session +nomad agent -config /etc/nomad.d/nomad.hcl \ +-client-intro-token "eyJhbGciOiJSUzI1NiIsImtpZCI6IjljZDgy..." +``` + +### Monitor client join failures + +You have the following options to determine when client registration fails: + +- Check the agent logs for `[ERROR] nomad.client: node registration without + introduction token` messages. +- Monitor the [`nomad.client.introduction.enforcement` + counter](/nomad/docs/monitor#client-introduction), which increments when a + client tries to join without a valid client introduction token. + + + [`consul` stanza]: /nomad/docs/configuration/consul [`node config` command]: /nomad/commands/node/config [`retry_join`]: /nomad/docs/configuration/server_join#retry_join diff --git a/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx b/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx index 409c1819e6..583beeccff 100644 --- a/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx +++ b/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx @@ -24,24 +24,19 @@ 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 functions as multi-factor -authentication for your Nomad clusters. It does not replace mTLS. Instead, -it 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? +authentication for your Nomad clusters. It does not replace mTLS. Instead, it +adds a second layer of security to prevent an unauthorized client from joining a +Nomad cluster. Using a client introduction token gives you additional control over misconfigured clients trying to join the Nomad cluster because 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) -- [Client identity node pool TTL configuration option](/nomad/docs/other-specifications/node-pool#node_identity_ttl) -- [Client Introduction server configuration options](/nomad/docs/configuration/server#client_introduction-parameters) +- [Client identity node pool TTL configuration + option](/nomad/docs/other-specifications/node-pool#node_identity_ttl) +- [Use client node introduction tokens to connect clients to your Nomad agent](/nomad/docs/deploy/clusters/connect-nodes#use-client-node-introduction-tokens) +- [Client introduction server configuration options](/nomad/docs/configuration/server#client_introduction-parameters) - [Client introduction monitoring detail](/nomad/docs/monitor#client-introduction) - [Client introduction agent CLI token flag](/nomad/commands/agent#client-intro-token) From a97b1151a1ccc5544e4e1eb30b6f6b22fda58f13 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Tue, 2 Dec 2025 14:53:49 -0600 Subject: [PATCH 4/5] remove nomad token section. Rewrite. Incorp feedback --- .../docs/deploy/clusters/connect-nodes.mdx | 138 ++++++------------ 1 file changed, 46 insertions(+), 92 deletions(-) diff --git a/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx b/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx index 70ca55063b..dc684b4c1c 100644 --- a/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx +++ b/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx @@ -220,34 +220,44 @@ options. ## Use client node introduction tokens -You may restrict which clients join your cluster by configuring client -introduction tokens. The client node introduction 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 or misconfigured client from -joining a Nomad cluster. +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. -Each layer answers a distinct question: +Each security layer answers a distinct question: - mTLS: Does the client have valid certificates for the cluster? - Client introduction token: Does the client have a valid token to join the cluster? -You do not need to configure mTLS to use client node introduction tokens, but we -do recommend securing your cluster with mTLS. +When you generate a client introduction token, you may specify the following +optional parameters: + +- Node pool: The node pool that clients with this token may join. This + token is not valid with any other node pool. +- Node name: The token is scoped to the node with this name. No other node may + use this token to join the cluster. +- TTL: Token expiration. The token is not valid after expiration. -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: -1. [Create an ACL policy in which the node has write permissions](#create-an-acl-policy). +1. [Create an ACL node policy](#create-an-acl-policy). 1. [Create an ACL role from the policy](#create-an-acl-role). -1. [Generate a Nomad token](#generate-a-nomad-token). 1. [Generate a client introduction token](#generate-a-client-introduction-token). 1. [Configure the Nomad agent to use client introduction](#configure-the-nomad-agent). 1. [Start the Nomad agent](#start-the-nomad-agent). 1. [Monitor client join failures](#monitor-client-join-failures). +### Prerequisites + +- 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. + ### Create an ACL policy This example creates the `node:write` policy required to generate tokens. @@ -260,7 +270,7 @@ This example creates the `node:write` policy required to generate tokens. } ``` -1. Create the policy. +1. Add the policy to the cluster. ```shell-session nomad acl policy apply client-introduction client-introduction.hcl @@ -268,14 +278,15 @@ This example creates the `node:write` policy required to generate tokens. ### Create an ACL role -This example creates an ACL role called `client-introduction`. +Create an ACL role with the `client-introduction` policy. ```shell-session nomad acl role create --tls-skip-verify -name="client-introduction" \ -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. ```shell-session ID = cf0b4a43-b00f-cc30-b656-b34d66151b04 @@ -286,89 +297,29 @@ Create Index = 117 Modify Index = 117 ``` -### Generate a Nomad token - -Generate an ACL token from the `client-introduction` role. Nomad uses this -token to request client introduction tokens. In a production environment, we -recommend that you use Vault to generate and manage these tokens. - -```shell-session -nomad acl token create -name="client-intro-token-1" \ --role-name="client-introduction" -type=client -ttl=8h -``` - -Output is similar to this: - -```shell-session -Accessor ID = 8c22a7c0-44f5-044d-ef84-bfa06118faf4 -Secret ID = d99d678d-426c-330e-74f3-de53a868e2f9 -Name = client-intro-token-1 -Type = client -Global = false -Create Time = 2025-11-18 21:01:44.62075624 +0000 UTC -Expiry Time = 2025-11-19 05:01:44.62075624 +0000 UTC -Create Index = 128 -Modify Index = 128 -Policies = [] - -Roles -ID Name -cf0b4a43-b00f-cc30-b656-b34d66151b04 client-introduction -``` - ### Generate a client introduction token -The following snippets generate a basic token. - - - +Use the [`nomad node intro create` command](/nomad/commands/node/intro/create) +to generate the client introduction token, which is a JSON Web Token (JWT). -Use the [`nomad node intro create` command](/nomad/commands/node/intro/create) to generate the client introduction token. +This example scopes the token to a node pool named `staging` and writes the +result to a file called `intro_token.jwt`. ```shell-session -nomad node intro create > intro_token.jwt +nomad node intro create -node-pool=staging > intro_token.jwt ``` -The `intro-token.jwt` contents are similar to this. +The `intro-token.jwt` file contains the JWT. ```shell-session "eyJhbGciOiJSUzI1NiIsImtpZCI6IjljZDgy..." ``` - - - -Use the [client introduction identity -endpoint](/nomad/api-docs/acl/identities#create-client-introduction-identity) to -generate the client introduction token. This example sends an empty JSON object, -but you may use a JSON payload file to specify parameters such as `NodeName`, -`NodePool`, and `TTL`. - -```shell-session -curl \ - --request POST \ - --header "X-Nomad-Token: d99d678d-426c-330e-74f3-de53a868e2f9" \ - --data {} \ - https://localhost:4646/v1/acl/identity/client-introduction-token \ - >> intro_token.jwt -``` - -The response includes the JWT. - -```shell-session -{ - "JWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjljZDgy..." -} -``` - - - - ### Configure the Nomad agent Configure the Nomad agent's `server.client_introduction` block. This example sets the `enforcement` parameter to `strict`, which means the agent rejects any -client without without a valid token. Refer to the [`server.client_introduction` +client without a valid token. Refer to the [`server.client_introduction` block documentation](/nomad/docs/configuration/server#client_introduction-parameters) for additional enforcement options. @@ -385,8 +336,8 @@ server { bootstrap_expect = 1 client_introduction { enforcement = "strict" # Default = "warn" - default_identity_ttl = "5m" # Default = "5m" - max_identity_ttl = "30m" # Default = "30m" + default_identity_ttl = "15m" # Default = "5m" + max_identity_ttl = "60m" # Default = "30m" } } tls { @@ -404,15 +355,18 @@ There is no additional client configuration. ### Start the Nomad agent -We recommend setting the JWT token in an environment variable called -`NOMAD_CLIENT_INTRO_TOKEN`. The next option is to set it in the -[`-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 -`/client_state_dir>` -directory](/nomad/docs/configuration/client#state_dir). +You have the following options for passing the client introduction token to the +Nomad agent: + +- Set the token as the value of a `NOMAD_CLIENT_INTRO_TOKEN` environment + variable. +- Use the [`-client-intro-token` + parameter](/nomad/commands/agent#client-intro-token) of the `nomad agent` + command. +- Place the `intro_token.jwt` file in the client's state directory, which is by + default [the `/client_state_dir>` directory](/nomad/docs/configuration/client#state_dir). -This example starts the agent with the JWT token set in the +This example starts the agent with the client introduction token passed in the `-client-intro-token` parameter. ```shell-session From 052837ecd3dd1080a3e0641267ca94757f291c1e Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Thu, 4 Dec 2025 11:53:59 -0600 Subject: [PATCH 5/5] address feedback; fix typo in release notes --- .../docs/deploy/clusters/connect-nodes.mdx | 53 ++++++++----------- .../docs/release-notes/nomad/v1-11-x.mdx | 4 +- 2 files changed, 25 insertions(+), 32 deletions(-) diff --git a/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx b/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx index dc684b4c1c..d5b73e5ee3 100644 --- a/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx +++ b/content/nomad/v1.11.x/content/docs/deploy/clusters/connect-nodes.mdx @@ -220,21 +220,14 @@ options. ## Use client node introduction tokens -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. - -Each security layer answers a distinct question: - -- mTLS: Does the client have valid certificates for the cluster? -- Client introduction token: Does the client have a valid token to join the -cluster? +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. When you generate a client introduction token, you may specify the following -optional parameters: +optional parameters to further secure cluster access: - Node pool: The node pool that clients with this token may join. This token is not valid with any other node pool. @@ -242,21 +235,22 @@ optional parameters: use this token to join the cluster. - TTL: Token expiration. The token is not valid after expiration. +### Create a client introduction token Follow these steps to use client node introduction tokens: 1. [Create an ACL node policy](#create-an-acl-policy). 1. [Create an ACL role from the policy](#create-an-acl-role). 1. [Generate a client introduction token](#generate-a-client-introduction-token). -1. [Configure the Nomad agent to use client introduction](#configure-the-nomad-agent). -1. [Start the Nomad agent](#start-the-nomad-agent). +1. [Update your Nomad server configuration to use client introduction](#update-your-nomad-server-configuration). +1. [Start the Nomad server](#start-the-nomad-server). 1. [Monitor client join failures](#monitor-client-join-failures). ### Prerequisites -- 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. +You bootstrapped the ACL system and configured the CLI to use your management +token. Refer to the [Bootstrap the ACL system +guide](/nomad/docs/secure/acl/bootstrap) for instructions. ### Create an ACL policy @@ -315,12 +309,11 @@ The `intro-token.jwt` file contains the JWT. "eyJhbGciOiJSUzI1NiIsImtpZCI6IjljZDgy..." ``` -### Configure the Nomad agent +### Update your Nomad server configuration -Configure the Nomad agent's `server.client_introduction` block. This example -sets the `enforcement` parameter to `strict`, which means the agent rejects any -client without a valid token. Refer to the [`server.client_introduction` -block +Configure your Nomad server's `server.client_introduction` block. This example +sets strict enforcement, which means the server rejects any client without a +valid token. Refer to the [`server.client_introduction` block documentation](/nomad/docs/configuration/server#client_introduction-parameters) for additional enforcement options. @@ -336,8 +329,8 @@ server { bootstrap_expect = 1 client_introduction { enforcement = "strict" # Default = "warn" - default_identity_ttl = "15m" # Default = "5m" - max_identity_ttl = "60m" # Default = "30m" + default_identity_ttl = "5m" # Default = "5m" + max_identity_ttl = "30m" # Default = "30m" } } tls { @@ -351,12 +344,12 @@ tls { -There is no additional client configuration. +No additional configuration is required on the client node. -### Start the Nomad agent +### Start the Nomad server You have the following options for passing the client introduction token to the -Nomad agent: +Nomad server: - Set the token as the value of a `NOMAD_CLIENT_INTRO_TOKEN` environment variable. @@ -366,7 +359,7 @@ Nomad agent: - Place the `intro_token.jwt` file in the client's state directory, which is by default [the `/client_state_dir>` directory](/nomad/docs/configuration/client#state_dir). -This example starts the agent with the client introduction token passed in the +This example starts the server with the client introduction token passed in the `-client-intro-token` parameter. ```shell-session @@ -378,7 +371,7 @@ nomad agent -config /etc/nomad.d/nomad.hcl \ You have the following options to determine when client registration fails: -- Check the agent logs for `[ERROR] nomad.client: node registration without +- Check the server logs for `[ERROR] nomad.client: node registration without introduction token` messages. - Monitor the [`nomad.client.introduction.enforcement` counter](/nomad/docs/monitor#client-introduction), which increments when a diff --git a/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx b/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx index 583beeccff..7dae3524b5 100644 --- a/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx +++ b/content/nomad/v1.11.x/content/docs/release-notes/nomad/v1-11-x.mdx @@ -13,7 +13,7 @@ We are pleased to announce the following Nomad updates. ### Client node introduction and identity -Nomad's client node identity feature uniquely identities each Nomad client node +Nomad's client node identity feature uniquely identifies each Nomad client node and provides an authentication mechanism for nodes to make RPC calls to the Nomad servers. @@ -35,7 +35,7 @@ Using a client introduction token gives you additional control over misconfigure - [Client node identity concepts](/nomad/docs/architecture/cluster/node-identity) - [Client identity node pool TTL configuration option](/nomad/docs/other-specifications/node-pool#node_identity_ttl) -- [Use client node introduction tokens to connect clients to your Nomad agent](/nomad/docs/deploy/clusters/connect-nodes#use-client-node-introduction-tokens) +- [Use client node introduction tokens to connect clients to your Nomad server](/nomad/docs/deploy/clusters/connect-nodes#use-client-node-introduction-tokens) - [Client introduction server configuration options](/nomad/docs/configuration/server#client_introduction-parameters) - [Client introduction monitoring detail](/nomad/docs/monitor#client-introduction) - [Client introduction agent CLI token flag](/nomad/commands/agent#client-intro-token)