From 79c521e570a2afade3c5268a84a01e726638e7ec Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Wed, 12 Apr 2023 15:29:33 -0700 Subject: [PATCH] docs: add node meta command docs (#16828) * docs: add node meta command docs Fixes #16758 * it helps if you actually add the files to git * fix typos and examples vs usage --- command/node_meta_apply.go | 6 +- website/content/docs/commands/node/index.mdx | 3 + .../content/docs/commands/node/meta/apply.mdx | 41 ++++++++++++ .../content/docs/commands/node/meta/index.mdx | 29 +++++++++ .../content/docs/commands/node/meta/read.mdx | 62 +++++++++++++++++++ website/data/docs-nav-data.json | 17 +++++ 6 files changed, 155 insertions(+), 3 deletions(-) create mode 100644 website/content/docs/commands/node/meta/apply.mdx create mode 100644 website/content/docs/commands/node/meta/index.mdx create mode 100644 website/content/docs/commands/node/meta/read.mdx diff --git a/command/node_meta_apply.go b/command/node_meta_apply.go index e295ccb7d..e2163d178 100644 --- a/command/node_meta_apply.go +++ b/command/node_meta_apply.go @@ -37,10 +37,10 @@ Node Meta Apply Options: the request will be used by default. -unset key1,...,keyN - Unset the command separated list of keys. + Unset the comma separated list of keys. - Example: - $ nomad node meta apply -unset testing,tempvar ready=1 role=preinit-db + Example: + $ nomad node meta apply -unset testing,tempvar ready=1 role=preinit-db ` return strings.TrimSpace(helpText) } diff --git a/website/content/docs/commands/node/index.mdx b/website/content/docs/commands/node/index.mdx index b315f5fb7..289d1a027 100644 --- a/website/content/docs/commands/node/index.mdx +++ b/website/content/docs/commands/node/index.mdx @@ -23,9 +23,12 @@ subcommands are available: - [`node eligibility`][eligibility] - Toggle scheduling eligibility on a given node +- [`node meta`][meta] - Interact with node metadata + - [`node status`][status] - Display status information about nodes [config]: /nomad/docs/commands/node/config 'View or modify client configuration details' [drain]: /nomad/docs/commands/node/drain 'Set drain mode on a given node' [eligibility]: /nomad/docs/commands/node/eligibility 'Toggle scheduling eligibility on a given node' +[meta]: /nomad/docs/commands/node/meta 'Interact with node metadata' [status]: /nomad/docs/commands/node/status 'Display status information about nodes' diff --git a/website/content/docs/commands/node/meta/apply.mdx b/website/content/docs/commands/node/meta/apply.mdx new file mode 100644 index 000000000..5b6723033 --- /dev/null +++ b/website/content/docs/commands/node/meta/apply.mdx @@ -0,0 +1,41 @@ +--- +layout: docs +page_title: 'Commands: node meta apply' +description: | + The node meta apply command updates node metadata. +--- + +# Command: node meta apply + +Modify a node's metadata. This command only applies to client agents, and can +be used to update the scheduling metadata the node registers. + +~> Changes are batched and may take up to 10 seconds to propagate to the + servers and affect scheduling. + +This command uses the [`/v1/client/metadata` HTTP API][api]. + +## Usage + +```plaintext +nomad node meta apply [-node-id ...] [-unset ...] key1=value1 ... kN=vN +``` + +## General Options + +@include 'general_options.mdx' + +## Node Meta Apply Options + +- `-node-id` - Updates metadata on the specified node. If not specified the + node receiving the request will be used by default. + +- `-unset` - Unset the comma separated list of keys. + +## Examples + +```shell-session +$ nomad node meta apply -unset testing,tempvar ready=1 role=preinit-db +``` + +[api]: /nomad/api-docs/client#update-node-metadata diff --git a/website/content/docs/commands/node/meta/index.mdx b/website/content/docs/commands/node/meta/index.mdx new file mode 100644 index 000000000..2b65048e5 --- /dev/null +++ b/website/content/docs/commands/node/meta/index.mdx @@ -0,0 +1,29 @@ +--- +layout: docs +page_title: 'Commands: node meta' +description: | + The node meta commands are used to read and update node metadata. +--- + +# Command: node meta + +The `meta` command is used to read and update node metadata. This metadata is +available for [interpolation using the `${meta.}` syntax in jobs][interp]. + +## Usage + +Usage: `nomad node meta [options]` + +The `apply` subcommand allows for dynamically updating node metadata. The +`read` subcommand allows reading all of the metadata set on the client. All +commands interact directly with a client and allow setting a custom target with +the `-node-id` option. + +Please see the individual subcommand help for detailed usage information: + + - [`apply`][apply] - Modify node metadata + - [`read`][read] - Read node metadata + +[interp]: /nomad/docs/runtime/interpolation#node-attributes +[apply]: /nomad/docs/commands/node/meta/apply +[read]: /nomad/docs/commands/node/meta/read diff --git a/website/content/docs/commands/node/meta/read.mdx b/website/content/docs/commands/node/meta/read.mdx new file mode 100644 index 000000000..8564cf7e5 --- /dev/null +++ b/website/content/docs/commands/node/meta/read.mdx @@ -0,0 +1,62 @@ +--- +layout: docs +page_title: 'Commands: node meta read' +description: | + The node meta read command reads node metadata. +--- + +# Command: node meta read + +Read a node's metadata. This command only works on client agents. The node +status command can be used to retrieve node metadata from any agent. + +Changes via the "node meta apply" subcommand are batched and may take up to +10 seconds to propagate to the servers and affect scheduling. This command +will always return the most recent node metadata while the "node status" +command can be used to view the metadata that is currently being used for +scheduling. + +This command uses the [`/v1/client/metadata` HTTP API][api]. + +## Usage + +```plaintext +nomad node meta read [-json] [-node-id ...] +``` + +## General Options + +@include 'general_options.mdx' + +## Node Meta Read Options + +- `-node-id` - Reads metadata on the specified node. If not specified the + node receiving the request will be used by default. + +- `-json` - Output the node metadata in its JSON format. + +- `-t` : Format and display node using a Go template. + +## Example + +```shell-session +$ nomad node meta read -node-id 3b58b0a6 + +All Meta +connect.gateway_image = envoyproxy/envoy:v${NOMAD_envoy_version} +connect.log_level = info +connect.proxy_concurrency = 1 +connect.sidecar_image = envoyproxy/envoy:v${NOMAD_envoy_version} +example = a + +Dynamic Meta +example = a + +Static Meta +connect.gateway_image = envoyproxy/envoy:v${NOMAD_envoy_version} +connect.log_level = info +connect.proxy_concurrency = 1 +connect.sidecar_image = envoyproxy/envoy:v${NOMAD_envoy_version} +``` + +[api]: /nomad/api-docs/client#read-node-metadata diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 3490ff209..3db88c626 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -649,6 +649,23 @@ "title": "eligibility", "path": "commands/node/eligibility" }, + { + "title": "meta", + "routes": [ + { + "title": "Overview", + "path": "commands/node/meta" + }, + { + "title": "apply", + "path": "commands/node/meta/apply" + }, + { + "title": "read", + "path": "commands/node/meta/read" + } + ] + }, { "title": "status", "path": "commands/node/status"