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 @jstirnamanpull/6394/head^2
Jason Stirnaman
GitHub
parent
089190dc60
commit
df06c64fb5
|
|
@ -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
|
||||
|
||||
<!--pytest.mark.skip-->
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
<!--
|
||||
//SOURCE - content/shared/influxdb3-cli/show/nodes.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
|
||||
---
|
||||
|
||||
<!--
|
||||
//SOURCE - content/shared/influxdb3-cli/stop/_index.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
|
||||
---
|
||||
|
||||
<!--
|
||||
//SOURCE - content/shared/influxdb3-cli/stop/node.md
|
||||
-->
|
||||
|
|
@ -1,4 +1,3 @@
|
|||
|
||||
The `influxdb3 show` command lists resources in your {{< product-name >}} server.
|
||||
|
||||
## Usage
|
||||
|
|
@ -11,14 +10,15 @@ influxdb3 show <SUBCOMMAND>
|
|||
|
||||
## 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
<!--pytest.mark.skip-->
|
||||
|
||||
```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
|
||||
|
||||
<!--pytest.mark.skip-->
|
||||
|
||||
```bash
|
||||
influxdb3 show nodes
|
||||
```
|
||||
|
||||
<!--pytest-codeblocks:expected-output-->
|
||||
|
||||
```
|
||||
+----------+-----------------+--------------------------------------+--------+------------+---------+---------------------------+
|
||||
| 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
|
||||
|
||||
<!--pytest.mark.skip-->
|
||||
|
||||
```bash
|
||||
influxdb3 show nodes --format json
|
||||
```
|
||||
|
||||
The output is similar to the following:
|
||||
|
||||
<!--pytest-codeblocks:expected-output-->
|
||||
|
||||
```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
|
||||
|
||||
<!--pytest.mark.skip-->
|
||||
|
||||
```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
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
The `influxdb3 stop` command marks nodes as stopped in the catalog for your {{< product-name >}} cluster.
|
||||
|
||||
## Usage
|
||||
|
||||
<!--pytest.mark.skip-->
|
||||
|
||||
```bash
|
||||
influxdb3 stop <SUBCOMMAND>
|
||||
```
|
||||
|
||||
## 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 |
|
||||
|
|
@ -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
|
||||
|
||||
<!--pytest.mark.skip-->
|
||||
|
||||
```bash { placeholders="NODE_ID" }
|
||||
influxdb3 stop node [OPTIONS] --node-id <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.
|
||||
|
||||
<!--pytest.mark.skip-->
|
||||
|
||||
```bash { placeholders="NODE_ID|PID" }
|
||||
# First, stop the physical instance (for example, using kill)
|
||||
kill -9 <PID>
|
||||
|
||||
# Then, clean up the catalog
|
||||
influxdb3 stop node --node-id NODE_ID
|
||||
```
|
||||
|
||||
The command prompts for confirmation.
|
||||
|
||||
### Clean up catalog without confirmation
|
||||
|
||||
<!--pytest.mark.skip-->
|
||||
|
||||
```bash { placeholders="NODE_ID" }
|
||||
influxdb3 stop node --node-id NODE_ID --force
|
||||
```
|
||||
|
||||
### Clean up catalog on a remote server
|
||||
|
||||
<!--pytest.mark.skip-->
|
||||
|
||||
```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:
|
||||
|
||||
<!--pytest.mark.skip-->
|
||||
|
||||
```bash
|
||||
influxdb3 show nodes
|
||||
```
|
||||
|
||||
The stopped node appears with `state: "stopped"` in the output.
|
||||
Loading…
Reference in New Issue