From df06c64fb5efa03b8f65c1e424c169d27af18884 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 5 Nov 2025 00:09:14 -0500 Subject: [PATCH] New Enterprise CLI commands: `show nodes` and `stop` (#6510) * Closes #6509 New Ent 3 CLI Commands 1. influxdb3 stop - Parent command for node lifecycle management 2. influxdb3 stop node - Stop a node in the Enterprise cluster and free up licensed cores 3. influxdb3 show nodes - Display information about nodes in the cluster Files Created Shared Content Files (only used by Ent3 for now): - content/shared/influxdb3-cli/stop/_index.md - Stop command overview - content/shared/influxdb3-cli/stop/node.md - Stop node command details with examples - content/shared/influxdb3-cli/show/nodes.md - Show nodes command details with examples Enterprise-Specific Frontmatter Files: - content/influxdb3/enterprise/reference/cli/influxdb3/stop/_index.md - content/influxdb3/enterprise/reference/cli/influxdb3/stop/node.md - content/influxdb3/enterprise/reference/cli/influxdb3/show/nodes.md Updated Files: - Added stop command to the main influxdb3 CLI reference - Added nodes subcommand to the show command reference * Apply suggestion from @jstirnaman * Apply suggestion from @jstirnaman --- .../reference/cli/influxdb3/_index.md | 3 +- .../reference/cli/influxdb3/show/nodes.md | 18 +++ .../reference/cli/influxdb3/stop/_index.md | 15 +++ .../reference/cli/influxdb3/stop/node.md | 18 +++ content/shared/influxdb3-cli/show/_index.md | 18 +-- content/shared/influxdb3-cli/show/nodes.md | 122 ++++++++++++++++++ content/shared/influxdb3-cli/stop/_index.md | 23 ++++ content/shared/influxdb3-cli/stop/node.md | 116 +++++++++++++++++ 8 files changed, 323 insertions(+), 10 deletions(-) create mode 100644 content/influxdb3/enterprise/reference/cli/influxdb3/show/nodes.md create mode 100644 content/influxdb3/enterprise/reference/cli/influxdb3/stop/_index.md create mode 100644 content/influxdb3/enterprise/reference/cli/influxdb3/stop/node.md create mode 100644 content/shared/influxdb3-cli/show/nodes.md create mode 100644 content/shared/influxdb3-cli/stop/_index.md create mode 100644 content/shared/influxdb3-cli/stop/node.md diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/_index.md b/content/influxdb3/enterprise/reference/cli/influxdb3/_index.md index 3a5558a03..0ea63527f 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/_index.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/_index.md @@ -31,6 +31,7 @@ influxdb3 [GLOBAL-OPTIONS] [COMMAND] | [query](/influxdb3/enterprise/reference/cli/influxdb3/query/) | Query {{% product-name %}} | | [serve](/influxdb3/enterprise/reference/cli/influxdb3/serve/) | Run the {{% product-name %}} server | | [show](/influxdb3/enterprise/reference/cli/influxdb3/show/) | List resources | +| [stop](/influxdb3/enterprise/reference/cli/influxdb3/stop/) | Mark nodes as stopped | | [test](/influxdb3/enterprise/reference/cli/influxdb3/test/) | Test plugins | | [update](/influxdb3/enterprise/reference/cli/influxdb3/update/) | Update resources | | [write](/influxdb3/enterprise/reference/cli/influxdb3/write/) | Write to {{% product-name %}} | @@ -85,7 +86,7 @@ In the examples below, replace the following: {{% code-placeholders "my-host-01|my-cluster-01" %}} -### Quick-start influxdb3 server +### Quick-start influxdb3 server diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/show/nodes.md b/content/influxdb3/enterprise/reference/cli/influxdb3/show/nodes.md new file mode 100644 index 000000000..bb35f7f03 --- /dev/null +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/show/nodes.md @@ -0,0 +1,18 @@ +--- +title: influxdb3 show nodes +description: > + The `influxdb3 show nodes` command displays information about nodes in your InfluxDB 3 Enterprise cluster. +menu: + influxdb3_enterprise: + parent: influxdb3 show + name: influxdb3 show nodes +weight: 301 +related: + - /influxdb3/enterprise/reference/cli/influxdb3/stop/node/ + - /influxdb3/enterprise/reference/cli/influxdb3/serve/ +source: /shared/influxdb3-cli/show/nodes.md +--- + + diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/stop/_index.md b/content/influxdb3/enterprise/reference/cli/influxdb3/stop/_index.md new file mode 100644 index 000000000..2b28a3b0e --- /dev/null +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/stop/_index.md @@ -0,0 +1,15 @@ +--- +title: influxdb3 stop +description: > + The `influxdb3 stop` command marks nodes as stopped in the catalog for your InfluxDB 3 Enterprise cluster. +menu: + influxdb3_enterprise: + parent: influxdb3 + name: influxdb3 stop +weight: 302 +source: /shared/influxdb3-cli/stop/_index.md +--- + + diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/stop/node.md b/content/influxdb3/enterprise/reference/cli/influxdb3/stop/node.md new file mode 100644 index 000000000..95f82f749 --- /dev/null +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/stop/node.md @@ -0,0 +1,18 @@ +--- +title: influxdb3 stop node +description: > + The `influxdb3 stop node` command marks a node as stopped in the catalog and frees up its licensed cores for other nodes. +menu: + influxdb3_enterprise: + parent: influxdb3 stop + name: influxdb3 stop node +weight: 301 +related: + - /influxdb3/enterprise/reference/cli/influxdb3/show/nodes/ + - /influxdb3/enterprise/reference/cli/influxdb3/serve/ +source: /shared/influxdb3-cli/stop/node.md +--- + + diff --git a/content/shared/influxdb3-cli/show/_index.md b/content/shared/influxdb3-cli/show/_index.md index b8c93fd7e..a72195110 100644 --- a/content/shared/influxdb3-cli/show/_index.md +++ b/content/shared/influxdb3-cli/show/_index.md @@ -1,4 +1,3 @@ - The `influxdb3 show` command lists resources in your {{< product-name >}} server. ## Usage @@ -11,14 +10,15 @@ influxdb3 show ## Subcommands -| Subcommand | Description | -| :---------------------------------------------------------------------- | :--------------------------------------------- | -| [databases](/influxdb3/version/reference/cli/influxdb3/show/databases/) | List database | -{{% show-in "enterprise" %}}| [license](/influxdb3/version/reference/cli/influxdb3/show/license/) | Display license information |{{% /show-in %}} -| [plugins](/influxdb3/version/reference/cli/influxdb3/show/plugins/) | List loaded plugins | -| [system](/influxdb3/version/reference/cli/influxdb3/show/system/) | Display system table data | -| [tokens](/influxdb3/version/reference/cli/influxdb3/show/tokens/) | List authentication tokens | -| help | Print command help or the help of a subcommand | +| Subcommand | Description | | | +| :---------------------------------------------------------------------- | :------------------------------------------------------------------ | --------------------------- | ---------------- | +| [databases](/influxdb3/version/reference/cli/influxdb3/show/databases/) | List database | | | +| {{% show-in "enterprise" %}} | [license](/influxdb3/version/reference/cli/influxdb3/show/license/) | Display license information | {{% /show-in %}} | +| {{% show-in "enterprise" %}} | [nodes](/influxdb3/version/reference/cli/influxdb3/show/nodes/) | Display node information | {{% /show-in %}} | +| [plugins](/influxdb3/version/reference/cli/influxdb3/show/plugins/) | List loaded plugins | | | +| [system](/influxdb3/version/reference/cli/influxdb3/show/system/) | Display system table data | | | +| [tokens](/influxdb3/version/reference/cli/influxdb3/show/tokens/) | List authentication tokens | | | +| help | Print command help or the help of a subcommand | | | ## Options diff --git a/content/shared/influxdb3-cli/show/nodes.md b/content/shared/influxdb3-cli/show/nodes.md new file mode 100644 index 000000000..4e641d2f8 --- /dev/null +++ b/content/shared/influxdb3-cli/show/nodes.md @@ -0,0 +1,122 @@ +The `influxdb3 show nodes` command displays information about nodes in your {{< product-name >}} cluster, including their state, mode, and resource usage. + +## Usage + + + +```bash +influxdb3 show nodes [OPTIONS] +``` + +## Options + +| Option | | Description | +| :----- | :--------- | :--------------------------------------------------------------------------------------- | +| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | +| | `--format` | Output format: `pretty` (default), `json`, or `csv` | +| | `--token` | Authentication token | +| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | +| `-h` | `--help` | Print help information | + +### Option environment variables + +You can use the following environment variables to set command options: + +| Environment Variable | Option | +| :--------------------- | :-------- | +| `INFLUXDB3_HOST_URL` | `--host` | +| `INFLUXDB3_AUTH_TOKEN` | `--token` | + +## Output + +The command displays the following information for each node: + +- **node\_id**: The unique identifier for the node +- **node\_catalog\_id**: The internal catalog identifier +- **instance\_id**: The unique instance identifier +- **mode**: The node's operating modes (ingest, query, process, compact) +- **core\_count**: Number of CPU cores allocated to the node +- **state**: Current node state (`running` or `stopped`) +- **updated\_at**: Timestamp of the last update +- **cli\_params**: Command-line parameters used to start the node + +## Examples + +- [List all nodes in pretty format](#list-all-nodes-in-pretty-format) +- [List nodes in JSON format](#list-nodes-in-json-format) +- [List nodes on a remote server](#list-nodes-on-a-remote-server) + +### List all nodes in pretty format + + + +```bash +influxdb3 show nodes +``` + + + +``` ++----------+-----------------+--------------------------------------+--------+------------+---------+---------------------------+ +| node_id | node_catalog_id | instance_id | mode | core_count | state | updated_at | ++----------+-----------------+--------------------------------------+--------+------------+---------+---------------------------+ +| node-1 | 0 | e38944e4-1204-4bb4-92f3-71138894d674 | ingest | 1 | running | 2025-09-04T10:15:57.126 | +| node-2 | 1 | f5418c97-eb6d-47b5-8176-efc0ad7b882e | ingest | 1 | stopped | 2025-09-04T10:16:57.503 | ++----------+-----------------+--------------------------------------+--------+------------+---------+---------------------------+ +``` + +### List nodes in JSON format + + + +```bash +influxdb3 show nodes --format json +``` + +The output is similar to the following: + + + +```json +[ + { + "node_id": "node-1", + "node_catalog_id": 0, + "instance_id": "e38944e4-1204-4bb4-92f3-71138894d674", + "mode": [ + "ingest" + ], + "core_count": 1, + "state": "running", + "updated_at": "2025-09-04T10:15:57.126", + "cli_params": "{\"http-bind\":\"127.0.0.1:8181\",\"node-id\":\"node-1\",\"data-dir\":\"/path/to/data\",\"object-store\":\"file\",\"mode\":\"ingest\"}" + }, + { + "node_id": "node-2", + "node_catalog_id": 1, + "instance_id": "f5418c97-eb6d-47b5-8176-efc0ad7b882e", + "mode": [ + "ingest" + ], + "core_count": 1, + "state": "stopped", + "updated_at": "2025-09-04T10:16:57.503", + "cli_params": "{\"http-bind\":\"127.0.0.1:8182\",\"node-id\":\"node-2\",\"data-dir\":\"/path/to/data\",\"object-store\":\"file\",\"mode\":\"ingest\"}" + } +] +``` + +### List nodes on a remote server + + + +```bash { placeholders="AUTH_TOKEN|INFLUXDB_HOST" } +influxdb3 show nodes \ + --host INFLUXDB_HOST \ + --token AUTH_TOKEN +``` + +Replace the following: + +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: Authentication token with sufficient privileges +- {{% code-placeholder-key %}}`INFLUXDB_HOST`{{% /code-placeholder-key %}}: Host URL of the running {{< product-name >}} server diff --git a/content/shared/influxdb3-cli/stop/_index.md b/content/shared/influxdb3-cli/stop/_index.md new file mode 100644 index 000000000..1d69dac43 --- /dev/null +++ b/content/shared/influxdb3-cli/stop/_index.md @@ -0,0 +1,23 @@ +The `influxdb3 stop` command marks nodes as stopped in the catalog for your {{< product-name >}} cluster. + +## Usage + + + +```bash +influxdb3 stop +``` + +## Subcommands + +| Subcommand | Description | +| :------------------------------------------------------------ | :--------------------------------------------- | +| [node](/influxdb3/version/reference/cli/influxdb3/stop/node/) | Mark a node as stopped | +| help | Print command help or the help of a subcommand | + +## Options + +| Option | | Description | +| :----- | :----------- | :------------------------------ | +| `-h` | `--help` | Print help information | +| | `--help-all` | Print detailed help information | diff --git a/content/shared/influxdb3-cli/stop/node.md b/content/shared/influxdb3-cli/stop/node.md new file mode 100644 index 000000000..e470d3730 --- /dev/null +++ b/content/shared/influxdb3-cli/stop/node.md @@ -0,0 +1,116 @@ +The `influxdb3 stop node` command marks a node as stopped in the catalog, freeing up the licensed cores it was using for other nodes. + +> [!Important] +> This command is designed for cleaning up the catalog **after** you have already stopped the physical instance. +> It does not shut down the running process - you must stop the instance first (for example, using `kill` or stopping the container). + +## Usage + + + +```bash { placeholders="NODE_ID" } +influxdb3 stop node [OPTIONS] --node-id +``` + +## Options + +| Option | | Description | +| :----- | :---------- | :--------------------------------------------------------------------------------------- | +| | `--node-id` | *({{< req >}})* The node ID to stop | +| | `--force` | Skip confirmation prompt | +| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | +| | `--token` | Authentication token | +| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | +| `-h` | `--help` | Print help information | + +### Option environment variables + +You can use the following environment variables to set command options: + +| Environment Variable | Option | +| :--------------------- | :-------- | +| `INFLUXDB3_HOST_URL` | `--host` | +| `INFLUXDB3_AUTH_TOKEN` | `--token` | + +## Use case + +Use this command when you have forcefully stopped a node instance (for example, using `kill -9` or stopping a container) and need to update the catalog to reflect the change. +This frees up the licensed cores from the stopped node so other nodes can use them. + +## Behavior + +When you run this command: + +1. The command marks the specified node as `stopped` in the catalog +2. Licensed cores from the stopped node are freed for reuse by other nodes +3. Other nodes in the cluster see the update after their catalog sync interval (default 10 seconds) +4. The command requires authentication if the server has auth enabled + +> [!Warning] +> **Stop the instance first** +> +> This command only updates catalog metadata. +> Always stop the physical instance **before** running this command. +> If the instance is still running, it may cause inconsistencies in the cluster. + +## Examples + +- [Clean up catalog after killing a node](#clean-up-catalog-after-killing-a-node) +- [Clean up catalog without confirmation](#clean-up-catalog-without-confirmation) +- [Clean up catalog on a remote server](#clean-up-catalog-on-a-remote-server) + +In the examples below, replace the following: + +- {{% code-placeholder-key %}}`NODE_ID`{{% /code-placeholder-key %}}: + The node identifier for the stopped instance +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + Authentication token with sufficient privileges +- {{% code-placeholder-key %}}`INFLUXDB_HOST`{{% /code-placeholder-key %}}: + Host URL of the running {{< product-name >}} server + +### Clean up catalog after killing a node + +This example shows the typical workflow: first stop the instance, then clean up the catalog. + + + +```bash { placeholders="NODE_ID|PID" } +# First, stop the physical instance (for example, using kill) +kill -9 + +# Then, clean up the catalog +influxdb3 stop node --node-id NODE_ID +``` + +The command prompts for confirmation. + +### Clean up catalog without confirmation + + + +```bash { placeholders="NODE_ID" } +influxdb3 stop node --node-id NODE_ID --force +``` + +### Clean up catalog on a remote server + + + +```bash { placeholders="AUTH_TOKEN|INFLUXDB_HOST|NODE_ID" } +influxdb3 stop node \ + --host INFLUXDB_HOST \ + --node-id NODE_ID \ + --token AUTH_TOKEN +``` + +## Verify node status + +After stopping a node, verify its status using the [`influxdb3 show nodes`](/influxdb3/version/reference/cli/influxdb3/show/nodes/) command: + + + +```bash +influxdb3 show nodes +``` + +The stopped node appears with `state: "stopped"` in the output.