diff --git a/website/content/api-docs/acl/identities.mdx b/website/content/api-docs/acl/identities.mdx new file mode 100644 index 000000000..05652a3cc --- /dev/null +++ b/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: )` - The name of the node to which the introduction token is + scoped. If not specified, the value is left empty. + +- `NodePool` `(string: )` - The node pool to which the introduction token is scoped. + If not specified, the value is `default`. + +- `TTL` `(string: )` - 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" +} +``` diff --git a/website/content/commands/node/identity/index.mdx b/website/content/commands/node/identity/index.mdx new file mode 100644 index 000000000..de975e2b6 --- /dev/null +++ b/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 [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 diff --git a/website/content/commands/node/identity/renew.mdx b/website/content/commands/node/identity/renew.mdx new file mode 100644 index 000000000..c4b4fcd6d --- /dev/null +++ b/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] +``` + +## 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' diff --git a/website/content/commands/node/intro/create.mdx b/website/content/commands/node/intro/create.mdx new file mode 100644 index 000000000..91a22aa61 --- /dev/null +++ b/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' diff --git a/website/content/commands/node/intro/index.mdx b/website/content/commands/node/intro/index.mdx new file mode 100644 index 000000000..7ddf97931 --- /dev/null +++ b/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 [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 diff --git a/website/content/docs/configuration/server.mdx b/website/content/docs/configuration/server.mdx index 7cc6526dc..e9bdc1e6c 100644 --- a/website/content/docs/configuration/server.mdx +++ b/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` ([ClientIntroduction](#client_introduction-parameters)) - + 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 diff --git a/website/content/docs/monitor/index.mdx b/website/content/docs/monitor/index.mdx index 5e2352103..f9ae7bd57 100644 --- a/website/content/docs/monitor/index.mdx +++ b/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 diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index 5b78b65f4..4219b07eb 100644 --- a/website/data/api-docs-nav-data.json +++ b/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" diff --git a/website/data/commands-nav-data.json b/website/data/commands-nav-data.json index 2b56721ed..d0c37d599 100644 --- a/website/data/commands-nav-data.json +++ b/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": [