docs: Add node identity and introduction CLI, API, and config docs (#26516)

Co-authored-by: Aimee Ukasick <Aimee.Ukasick@ibm.com>

website/content/api-docs/acl/identities.mdx

@@ -0,0 +1,64 @@
+---
+layout: api
+page_title: ACL Identities - HTTP API
+description: |-
+  Use the `/acl/identity` endpoint to create client introduction identity tokens.
+---
+
+# ACL identities HTTP API
+
+Use the `/acl/identity` endpoint to create client introduction identity tokens.
+
+## Create client introduction identity
+
+This endpoint creates an ACL identity for use with client introduction.
+
+| Method | Path                                         | Produces           |
+|--------|----------------------------------------------|--------------------|
+| `POST` | `/v1/acl/identity/client-introduction-token` | `application/json` |
+
+The following table shows this endpoint's support for
+[blocking queries](/nomad/api-docs#blocking-queries) and
+[required ACLs](/nomad/api-docs#acls).
+
+| Blocking Queries | ACL Required |
+|------------------|--------------|
+| `NO`             | `node:write` |
+
+### Parameters
+
+- `NodeName` `(string: <optional>)` - The name of the node to which the introduction token is
+  scoped. If not specified, the value is left empty.
+
+- `NodePool` `(string: <optional>)` - The node pool to which the introduction token is scoped.
+  If not specified, the value is `default`.
+
+- `TTL` `(string: <optional>)` - The TTL to apply to the introduction token. If not specified, the
+  server configured default value is used.
+
+### Sample payload
+
+```json
+{
+  "NodeName": "node-338ef6e9",
+  "NodePool": "platform",
+  "TTL": "15m"
+}
+```
+
+### Sample request
+
+```shell-session
+$ curl \
+    --request POST \
+    --data @payload.json \
+    https://localhost:4646/v1/acl/identity/client-introduction-token
+```
+
+### Sample response
+
+```json
+{
+  "JWT":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlMGJhMmM3LWE5ODktNzI2Ni1kZDdlLWMyYzBkZmU3OTg4OSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJub21hZHByb2plY3QuaW8iLCJleHAiOjE3NTUwNzE2NDgsImlhdCI6MTc1NTA3MDc0OCwianRpIjoiYWVmMGE3NzUtNzQ0MS1jNjA2LTIyY2UtNGRhZGY4YzExYzlmIiwibmJmIjoxNzU1MDcwNzQ4LCJub21hZF9ub2RlX25hbWUiOiJub2RlLTMzOGVmNmU5Iiwibm9tYWRfbm9kZV9wb29sIjoicGxhdGZvcm0iLCJzdWIiOiJub2RlLWludHJvZHVjdGlvbjpnbG9iYWw6cGxhdGZvcm06bm9kZS0zMzhlZjZlOTpkZWZhdWx0In0.nCyqdlqStkjoX64p-AN0DA90eIbwVj9A-cYRtabEdTmqkocz-31YY9MlCKv0v6oU4AYHwUF-kBXG7LWYQgk2RKgWh-KttjfT1kJaS0k9jfiyVFxrLuz2F_KZO8kBzZFGS4bQw6nw0-6uR0tkkZvKVwrq6L3hyFUWpgB-gI2BidIZz7Y02RNtcpStjv0e-1DVyzFxInIuTnX-Z2fRAZz7w5e1nMtDFpnZgPM3nrjg2ZAKKiX9GiZT9IPip_KRsqdAN5TWkHlNQ7WmdzrIBZNe1IX15JWC7wSyCJn-n-FSSRc71X1P2ZYaOUzmJiGr-x7M95jDZD6CGDykfsD9pFQR_A"
+}
+```

website/content/commands/node/identity/index.mdx

@@ -0,0 +1,27 @@
+---
+layout: docs
+page_title: 'nomad node identity command reference'
+description: |
+  The `nomad node identity` commands allow for interaction with a specific node's identity.
+---
+
+# `nomad node identity` command reference
+
+Use the `node identity` command to interact with a specific node's identity.
+
+## Usage
+
+```plaintext
+nomad node identity <subcommand> [options]
+```
+
+Interact with a node's identity. All commands interact directly with a client and require setting
+the target node via its 36-character ID.
+
+Refer to the individual subcommand help for detailed usage information.
+
+Subcommands:
+
+ - [`renew`][renew] - Force a node to renew its identity
+
+[renew]: /nomad/commands/node/identity/renew

website/content/commands/node/identity/renew.mdx

@@ -0,0 +1,31 @@
+---
+layout: docs
+page_title: 'nomad node identity renew command reference'
+description: |
+  The `nomad node identity renew` command instructs a node to renew its identity.
+---
+
+# `nomad node identity renew` command reference
+
+Instruct a node to renew its identity at the next heartbeat. This command only applies to client
+agents.
+
+If ACLs are enabled, this command requires a token with the `node:write` capability.
+
+## Usage
+
+```plaintext
+nomad node identity renew [options] <node_id>
+```
+
+## Examples
+
+Instruct a specific node to renew its identity.
+
+```shell-session
+$ nomad node identity renew da86421c-7de9-85e4-2f50-3b2bf95102c1
+```
+
+## General options
+
+@include 'general_options.mdx'

website/content/commands/node/intro/create.mdx

@@ -0,0 +1,62 @@
+---
+layout: docs
+page_title: 'nomad node intro create command reference'
+description: |
+  The `nomad node intro create` command creates a new node introduction token.
+---
+
+# `nomad node intro create` command reference
+
+Use the `nomad node intro create` command to generates a new node introduction
+token. The Nomad cluster uses this token to authenticate a new Nomad client
+node. When possible, we recommend specifying the optional `-node-name` flag, so
+that the token is scoped to a specific node.
+
+If ACLs are enabled, this command requires a token with the `node:write` capability.
+
+## Usage
+
+```plaintext
+nomad node intro create [options]
+```
+
+## Options
+
+- `-node-name`: The name of the node to which the introduction token is scoped. If not
+  specified, the value is left empty.
+
+- `-node-pool`: The node pool to which the introduction token is scoped. If not specified, the
+  value `default` is used.
+
+- `-ttl`: The TTL to apply to the introduction token. If not specified, the server configured
+  default value is used.
+
+- `-json`: Output the response object in JSON format.
+
+- `-t`: Format and display the response object using a Go template.
+
+## Examples
+
+Create a node introduction token with a specific node name, node pool, and TTL.
+
+```shell-session
+$ nomad node intro create -node-name=node-338ef6e9 -node-pool=platform -ttl=15m
+
+Successfully generated client introduction token:
+
+eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlMGJhMmM3LWE5ODktNzI2Ni1kZDdlLWMyYzBkZmU3OTg4OSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJub21hZHByb2plY3QuaW8iLCJleHAiOjE3NTUwNzE2NDgsImlhdCI6MTc1NTA3MDc0OCwianRpIjoiYWVmMGE3NzUtNzQ0MS1jNjA2LTIyY2UtNGRhZGY4YzExYzlmIiwibmJmIjoxNzU1MDcwNzQ4LCJub21hZF9ub2RlX25hbWUiOiJub2RlLTMzOGVmNmU5Iiwibm9tYWRfbm9kZV9wb29sIjoicGxhdGZvcm0iLCJzdWIiOiJub2RlLWludHJvZHVjdGlvbjpnbG9iYWw6cGxhdGZvcm06bm9kZS0zMzhlZjZlOTpkZWZhdWx0In0.nCyqdlqStkjoX64p-AN0DA90eIbwVj9A-cYRtabEdTmqkocz-31YY9MlCKv0v6oU4AYHwUF-kBXG7LWYQgk2RKgWh-KttjfT1kJaS0k9jfiyVFxrLuz2F_KZO8kBzZFGS4bQw6nw0-6uR0tkkZvKVwrq6L3hyFUWpgB-gI2BidIZz7Y02RNtcpStjv0e-1DVyzFxInIuTnX-Z2fRAZz7w5e1nMtDFpnZgPM3nrjg2ZAKKiX9GiZT9IPip_KRsqdAN5TWkHlNQ7WmdzrIBZNe1IX15JWC7wSyCJn-n-FSSRc71X1P2ZYaOUzmJiGr-x7M95jDZD6CGDykfsD9pFQR_A
+```
+
+Create a node introduction token with a specific node name, node pool, and TTL with the output in
+JSON format.
+
+```shell-session
+$ nomad node intro create -node-name=node-338ef6e9 -node-pool=platform -ttl=15m -json
+{
+    "JWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlMGJhMmM3LWE5ODktNzI2Ni1kZDdlLWMyYzBkZmU3OTg4OSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJub21hZHByb2plY3QuaW8iLCJleHAiOjE3NTUwNzE3MzUsImlhdCI6MTc1NTA3MDgzNSwianRpIjoiZTYxYjhlYTUtZjkyYy05YmJmLWU0OWQtYmMxNTg2NDIyNjhhIiwibmJmIjoxNzU1MDcwODM1LCJub21hZF9ub2RlX25hbWUiOiJub2RlLTMzOGVmNmU5Iiwibm9tYWRfbm9kZV9wb29sIjoicGxhdGZvcm0iLCJzdWIiOiJub2RlLWludHJvZHVjdGlvbjpnbG9iYWw6cGxhdGZvcm06bm9kZS0zMzhlZjZlOTpkZWZhdWx0In0.Rij4lcI-vBT6C60oUmR_Qdx3LY6vYh-3OwLRjW-_cAZrl1OaoTUHwfinaUDZza4fY8UZo48ZXjcEw_9sHBYMnX9qByYbdtJUIsBCUn_VAIkMvZFLY4nR5zhB4XotQARqPNY0WENlEb0LhtQcIeFDPJOuDrDCrUk6QqKX5W-ZwFNLZe269LtQjlZDZT-AiNaJfhd8skNipdDW1XhusZucn3nIFQ-iQHqwb7zFB1vIxiNzJqPq_K2SYXIv41uEfWlcp9FTr_1XYQKfukzVg-GQq0nV74VVZSIh5TZLrEIB69GGoOy0t3CY7yDBfrqyKyw4B1fNPEz5o7G4VzoihmbGbA"
+}
+```
+
+## General options
+
+@include 'general_options.mdx'

website/content/commands/node/intro/index.mdx

@@ -0,0 +1,28 @@
+---
+layout: docs
+page_title: 'nomad node intro command reference'
+description: |
+  The `nomad node intro` commands allow for the creation of node introduction tokens.
+---
+
+# nomad node intro reference
+
+Use the `nomad node intro` command to manage node introduction tokens. The Nomad
+cluster uses these tokens to authenticate new Nomad clients.
+
+## Usage
+
+```plaintext
+nomad node intro <subcommand> [options]
+```
+
+This command groups subcommands for managing node introduction tokens. The Nomad
+cluster uses these tokens to authenticate new Nomad clients.
+
+Refer to the individual subcommand help for detailed usage information.
+
+Subcommands:
+
+ - [`create`][create] - Generate a new node introduction token
+
+[create]: /nomad/commands/node/intro/create

website/content/docs/configuration/server.mdx

@@ -116,6 +116,10 @@ server {
   deployment must be in the terminal state before it is eligible for garbage
   collection. This is specified using a label suffix like "30s" or "1h".
 
+- `client_introduction` <code>([ClientIntroduction](#client_introduction-parameters))</code> -
+  Configuration for how the Nomad server handles client introduction
+  requests.
+
 - `csi_volume_claim_gc_interval` `(string: "5m")` - Specifies the interval
   between CSI volume claim garbage collections.
 
@@ -324,6 +328,37 @@ server {
   section for more information on the format of the string. This field is
   deprecated in favor of the [server_join block][server-join].
 
+### `client_introduction` Parameters
+
+The `client_introduction` block controls how the Nomad server should generate
+introduction tokens for new clients and what enforcement to apply when new
+clients attempt to register with the server.
+
+- `enforcement` `(string: "warn")` - Specifics how the server handles new client
+  registration requests. The valid options are `none`, `warn`, and `strict`.
+
+  - `none`: The server does not enforce any client registration behaviour.
+  - `warn`: The server logs a warning message and emits a telemetry metric when
+    a client attempts to register without an introduction token. However, the
+    server does allow the registration to proceed.
+  - `strict`: The server rejects any client registration attempts that do not
+    include a valid introduction token. The server also logs a warning message
+    and emits a telemetry  metric.
+
+- `default_identity_ttl` `(string: "5m")` - The default TTL assigned to
+  generated client introduction tokens when the caller does not specify a TTL.
+  Specify this value with a label suffix like "30s" or "1h". Must be less
+  than `max_identity_ttl`.
+
+- `max_identity_ttl` `(string: "30m")` - The maximum TTL that can be requested
+  by a caller when generating client introduction tokens. Specify this value
+  with a label suffix like "30s" or "1h". Must be greater than
+  `default_identity_ttl`.
+
+Refer to the [Client introduction section][monitoring_nomad_client_introduction]
+of the Monitor Nomad guide for details on the client introduction metric that is
+emitted.
+
 ### `plan_rejection_tracker` Parameters
 
 The leader plan rejection tracker can be adjusted to prevent evaluations from
@@ -534,3 +569,4 @@ work.
 [Configure for multiple regions]: /nomad/docs/secure/acl/bootstrap#configure-for-multiple-regions
 [top_level_data_dir]: /nomad/docs/configuration#data_dir
 [JWKS URL]: /nomad/api-docs/operator/keyring#list-active-public-keys
+[monitoring_nomad_client_introduction]:/nomad/docs/monitor#client-introduction

website/content/docs/monitor/index.mdx

@@ -289,6 +289,17 @@ that membership is unstable.
 If these metrics increase, look at CPU load on the servers and network
 latency and packet loss for the [Serf] address.
 
+## Client introduction
+
+When you configure Nomad with [`client_introduction.enforcement`] set to either
+`warn` or `strict`, the server handling the client registration request
+increments the `nomad.client.introduction.enforcement` counter each time a new
+registration is made without an introduction token.
+
+Monitoring this metric can help identify clients that are not registering with
+an introduction token, which is important when migrating to a tougher
+enforcement level.
+
 [alerting-rules]: https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/
 [alertmanager]: https://prometheus.io/docs/alerting/alertmanager/
 [allocation-metrics]: /nomad/docs/reference/metrics#allocation-metrics
@@ -311,3 +322,4 @@ latency and packet loss for the [Serf] address.
 [Consensus Protocol (Raft)]: /nomad/docs/monitor#raft-consensus-protocol
 [Job Summary Metrics]: /nomad/docs/reference/metrics#job-summary-metrics
 [Scheduling]: /nomad/docs/concepts/scheduling/how-scheduling-works
+[`client_introduction.enforcement`]: /nomad/docs/configuration/server#client_introduction-parameters

website/data/api-docs-nav-data.json

@@ -36,6 +36,10 @@
         "title": "Binding Rules",
         "path": "acl/binding-rules"
       },
+      {
+        "title": "Identities",
+        "path": "acl/identities"
+      },
       {
         "title": "Login",
         "path": "acl/login"

website/data/commands-nav-data.json

@@ -468,6 +468,32 @@
         "title": "eligibility",
         "path": "node/eligibility"
       },
+      {
+        "title": "identity",
+        "routes": [
+          {
+            "title": "Overview",
+            "path": "node/identity"
+          },
+          {
+            "title": "renew",
+            "path": "node/identity/renew"
+          }
+        ]
+      },
+      {
+        "title": "intro",
+        "routes": [
+          {
+            "title": "Overview",
+            "path": "node/intro"
+          },
+          {
+            "title": "create",
+            "path": "node/intro/create"
+          }
+        ]
+      },
       {
         "title": "meta",
         "routes": [