docs(enterprise): fix contradictory single-compactor constraint in clustering docs by Copilot · Pull Request #7075 · influxdata/docs-v2

Copilot · 2026-04-08T19:39:37Z

Run only one compactor node per cluster

clustering.md showed architecture examples with multiple nodes in compact or all mode, contradicting multi-server.md's correct statement that only one compactor node is allowed per cluster. Running multiple compactors causes data corruption.

Don't use `all` mode in a multi-node cluster

Use --mode=all for single-node Enterprise deployments only. all mode is not compatible with multi-node clustering—some cluster features such as replication and catalog refresh aren't designed to work with all-mode nodes. In a multi-node cluster, use explicit modes (ingest, query, compact, process) and assign compact to exactly one node.

Changes

Explicit warnings added:

"Configure node modes" — new [!Warning] callout with heading "Don't use all mode in a multi-node cluster": all mode is for single-node Enterprise only; multi-node clusters must use explicit modes with compact assigned to exactly one node
"Configure compactor nodes" — same single-compactor constraint reinforced at the section level

Cluster architecture examples corrected:

Small (3 nodes): Node 1 changed from all → ingest,query,compact; Nodes 2–3 changed from all → ingest,query
Medium (6 nodes): "Nodes 5–6: Compactor + Process" (compact,process on both) → Node 5 compact, Node 6 process
Large (12+ nodes): "Nodes 9–10: Dedicated compactors" → Node 9 only; Node 10 absorbed into process group (now Nodes 10–12)

Troubleshooting / migration corrected:

"Compaction falling behind" solution: removed "Add compactor nodes"; specifies that increasing DataFusion threads applies to the Parquet-backed storage engine—the Performance Preview with PachaTree does not use DataFusion for compaction
"Migrate to specialized nodes" reframed as "From single-node to specialized cluster": all mode appears only in Phase 1 (single-node baseline); migration guidance now includes the requirement that the compact node must use the same --node-id as the all-mode node being replaced; pseudo-bash replaced with real influxdb3 serve commands across migration phases

- Add Warning callout in Configure node modes section: only one node per cluster can run in a mode that includes compaction (compact or all) - Add Warning callout in Configure compactor nodes section reinforcing the single-compactor-per-cluster rule - Fix Small cluster (3 nodes) example: changed nodes 2-3 from 'all' mode to 'ingest,query' since only one node can run compaction - Fix Medium cluster (6 nodes) example: split "Nodes 5-6: Compactor + Process" (both in compact,process) into Node 5 (compact) and Node 6 (process) with a note about the single-compactor rule - Fix Large cluster (12+ nodes) example: changed "Nodes 9-10: Dedicated compactors" to "Node 9: Dedicated compactor" and merged Node 10 into "Nodes 10-12: Process nodes" - Fix troubleshooting section: changed "Add compactor nodes or increase DataFusion threads" to "Increase DataFusion threads on your single compactor node" - Fix Migrate to specialized nodes section: updated Phase 1 from "all nodes: --mode=all" to a single-node baseline with a note warning against multi-node all-mode setups Agent-Logs-Url: https://github.com/influxdata/docs-v2/sessions/8fef041f-0506-4ec4-b334-beb5d6c5f03d Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>

jstirnaman · 2026-04-08T19:47:48Z

 - Increasing query times due to file fragmentation

-**Solution:** Add compactor nodes or increase DataFusion threads (see [Compactor node issues](#compactor-node-issues))
+**Solution:** Increase DataFusion threads on your single compactor node (see [Compactor node issues](#compactor-node-issues))


@philjb @peterbarnett03 Can you verify this?

for parquet backend yes, which uses datafusion for compaction (pacha doesn't use DF for compaction).

for parquet backend yes, which uses datafusion for compaction (pacha doesn't use DF for compaction).

@copilot Specify that this solution is for the Parquet-backed storage engine. The Performance Preview (with PachaTree) doesn't use DataFusion for compaction.

Updated in d1f15bf. The solution now specifies it applies to the default Parquet-backed storage engine and notes that PachaTree (Performance Preview) doesn't use DataFusion for compaction.

github-actions · 2026-04-08T19:52:20Z

PR Preview Action v1.4.8
🚀 Deployed preview to https://influxdata.github.io/docs-v2/pr-preview/pr-7075/
on branch `gh-pages` at 2026-04-15 22:15 UTC

github-actions · 2026-04-08T19:52:21Z

📦 PR Preview — Preview Bot

Status	Details
Result	✅ DEPLOYED
Preview	View preview
Pages	1 page(s) deployed
Build time	56s
Last updated	2026-04-15 22:15:09 UTC

Pages included in this preview

/influxdb3/enterprise/admin/clustering/

_{Preview auto-deploys on push. Will be cleaned up when PR closes.}

github-actions · 2026-04-09T16:39:36Z

Vale Style Check Results

Metric	Count
Errors	0
Warnings	0
Suggestions	0

✅ Check passed

philjb · 2026-04-10T22:15:22Z

+> [!Warning]
+> Only **one** node per cluster can run in a mode that includes compaction (`compact` or `all`).
+> Running multiple compactors causes data corruption.
+> In a cluster, assign `all` mode to at most one node, and ensure no other node uses the `compact` mode.


I'm not sure all mode is compatible with clustering at all. I think "all" nodes act alone, but i haven't tried it.

Why would i run an "All" node with a separate "ingest" node for example. It's an odd configuration. If it is possible, i don't think i would recommended it.

Updated the issue and PR description with the latest advice.

Updated in d1f15bf to reflect that all mode is for single-node Enterprise deployments only. Changes include:

Warning callout now says: avoid all in multi-node clusters (replication and catalog refresh aren't designed for all-mode nodes); use explicit modes with compact assigned to exactly one node

Small cluster (3 nodes) example: Node 1 changed from mode: all to mode: ingest,query,compact

"Migrate to specialized nodes" section reframed as "single-node to specialized cluster" migration, showing all only in the single-node Phase 1

- Update 'all' mode description to single-node Enterprise only throughout - Replace 'all' mode in Small cluster (3 nodes) example with explicit ingest,query,compact modes - Update warning callout: all mode is for single-node only; multi-node clusters should use explicit modes with compact assigned to one node - Update 'Migrate to specialized nodes' to clarify single-node → cluster migration path without using all mode in multi-node context - Specify that DataFusion thread tuning for compaction applies to the default Parquet-backed storage engine, not PachaTree (Performance Preview) Agent-Logs-Url: https://github.com/influxdata/docs-v2/sessions/da0e0cbe-bbfc-42d3-8821-0a025ed3ef50 Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>

philjb · 2026-04-15T16:19:25Z

-> In a baseline multi-node setup, additional nodes should use `ingest,query` instead of `all`
-> to avoid running multiple compactors.
+> `all` mode is intended for single-node Enterprise deployments.
+> When scaling to a multi-node cluster, replace `all` with explicit modes and assign `compact` to exactly one node.


it needs to be more than this; when upgrading from an All to multinode, the "new" compact node must have the same node-id as the all node being replaced.

Incorporated in 689cacc. The migration example now shows the compact node in Phase 2 using --node-id=node0 — the same node-id as the all-mode node being replaced — with a comment making this requirement explicit.

jstirnaman · 2026-04-15T18:01:34Z

 - `process`: Data processing and transformations

+> [!Warning]
+> Use `all` mode for **single-node** Enterprise deployments only.


Suggested change

> Use `all` mode for **single-node** Enterprise deployments only.

> #### Don't use all mode in a multi-node cluster

>

> Use `all` mode for **single-node** Enterprise deployments only.

Applied in 689cacc. The warning now has a heading "Don't use all mode in a multi-node cluster" and the opening line matches your suggestion.

jstirnaman · 2026-04-15T18:02:07Z


+> [!Warning]
+> Use `all` mode for **single-node** Enterprise deployments only.
+> Avoid using `all` mode in a multi-node cluster—some cluster features such as replication and catalog refresh aren't designed to work with `all`-mode nodes.


Suggested change

> Avoid using `all` mode in a multi-node cluster—some cluster features such as replication and catalog refresh aren't designed to work with `all`-mode nodes.

> Some cluster features such as replication and catalog refresh aren't designed to work with `all`-mode nodes.

Applied in 689cacc.

jstirnaman · 2026-04-15T18:04:30Z

 - Increasing query times due to file fragmentation

-**Solution:** Add compactor nodes or increase DataFusion threads (see [Compactor node issues](#compactor-node-issues))
+**Solution:** For nodes using the default Parquet-backed storage engine, increase DataFusion threads on your single compactor node (see [Compactor node issues](#compactor-node-issues)).


Suggested change

**Solution:** For nodes using the default Parquet-backed storage engine, increase DataFusion threads on your single compactor node (see [Compactor node issues](#compactor-node-issues)).

**Solution:** For nodes using the Parquet-backed storage engine, increase DataFusion threads on your single compactor node (see [Compactor node issues](#compactor-node-issues)).

Applied in 689cacc — "default" removed.

jstirnaman · 2026-04-15T18:11:34Z

+### From single-node to specialized cluster
+
+> [!Note]
+> `all` mode is intended for single-node Enterprise deployments.


Suggested change

> `all` mode is intended for single-node Enterprise deployments.

> `all` mode is only for single-node Enterprise deployments.

Applied in 689cacc.

jstirnaman · 2026-04-15T18:18:49Z

+
+> [!Note]
+> `all` mode is intended for single-node Enterprise deployments.
+> When scaling to a multi-node cluster, replace `all` with explicit modes and assign `compact` to exactly one node.


Suggested change

> When scaling to a multi-node cluster, replace `all` with explicit modes and assign `compact` to exactly one node.

When scaling a single `all` node cluster to a multi-node cluster:

- Replace the `all` node with nodes that have explicit, specialized modes

- Assign `compact` mode to exactly one node that uses the same node-id as the `all` node being replaced

Applied in 689cacc. The scaling guidance is now outside the callout as bullet points, incorporating the same-node-id requirement from @philjb's comment.

jstirnaman · 2026-04-15T18:24:43Z

+> `all` mode is intended for single-node Enterprise deployments.
+> When scaling to a multi-node cluster, replace `all` with explicit modes and assign `compact` to exactly one node.

 ```bash


@copilot Fix the notation/syntax in this "bash" example so that it represents real code. Observe the following for all examples scaling from all mode to a multi-node cluster:

Replace the all node with nodes that have explicit, specialized modes

Assign compact mode to exactly one node that uses the same node-id as the all node being replaced

Fixed in 689cacc. The pseudo-bash is replaced with real influxdb3 serve commands. Phase 2 now explicitly shows the compact node reusing --node-id=node0 (same as the replaced all-mode node), per @philjb's requirement.

- Warning callout: add heading 'Don't use all mode in a multi-node cluster'; reword opening lines per review suggestions - Compaction troubleshooting: remove 'default' qualifier before 'Parquet-backed storage engine' - Migration section: rewrite note to say 'is only for'; move scaling guidance outside the callout as bullet points; replace pseudo-bash with real influxdb3 serve commands; incorporate same-node-id requirement for compact node when replacing an all-mode node Agent-Logs-Url: https://github.com/influxdata/docs-v2/sessions/50bbe0a2-e066-4da0-8e00-afe917dba91b Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>

Initial plan

5e47919

Copilot AI assigned Copilot and jstirnaman Apr 8, 2026

Copilot started work on behalf of jstirnaman April 8, 2026 19:41 View session

Copilot AI linked an issue Apr 8, 2026 that may be closed by this pull request

Don't run multiple "all" nodes in a cluster #7074

Open

Copilot AI changed the title ~~[WIP] Fix issue with running multiple 'all' nodes in cluster~~ docs(enterprise): fix contradictory single-compactor constraint in clustering docs Apr 8, 2026

Copilot finished work on behalf of jstirnaman April 8, 2026 19:45

Copilot AI requested a review from jstirnaman April 8, 2026 19:45

jstirnaman approved these changes Apr 8, 2026

View reviewed changes

jstirnaman marked this pull request as ready for review April 8, 2026 19:50

jstirnaman requested a review from a team as a code owner April 8, 2026 19:50

jstirnaman requested review from sanderson and removed request for a team April 8, 2026 19:50

jstirnaman requested review from peterbarnett03 and philjb and removed request for sanderson April 8, 2026 19:52

Merge branch 'master' into copilot/fix-multiple-all-nodes-cluster-issue

b7b04d4

github-actions bot added the product:v3-monolith InfluxDB 3 Core and Enterprise (single-node / clusterable) label Apr 9, 2026

jstirnaman removed the request for review from philjb April 9, 2026 16:41

Merge branch 'master' into copilot/fix-multiple-all-nodes-cluster-issue

792af02

philjb reviewed Apr 10, 2026

View reviewed changes

jstirnaman added 2 commits April 14, 2026 07:31

Merge branch 'master' into copilot/fix-multiple-all-nodes-cluster-issue

a0c6d2e

Merge branch 'master' into copilot/fix-multiple-all-nodes-cluster-issue

1e92766

Copilot started work on behalf of jstirnaman April 15, 2026 15:44 View session

Copilot finished work on behalf of jstirnaman April 15, 2026 15:50

Copilot AI requested a review from jstirnaman April 15, 2026 15:50

philjb reviewed Apr 15, 2026

View reviewed changes

Comment thread content/influxdb3/enterprise/admin/clustering.md Outdated

philjb reviewed Apr 15, 2026

View reviewed changes

jstirnaman requested changes Apr 15, 2026

View reviewed changes

Copilot started work on behalf of jstirnaman April 15, 2026 22:05 View session

jstirnaman and others added 2 commits April 15, 2026 17:05

Merge branch 'master' into copilot/fix-multiple-all-nodes-cluster-issue

86c7ba8

Copilot finished work on behalf of jstirnaman April 15, 2026 22:10

Copilot AI requested a review from jstirnaman April 15, 2026 22:10

	> Avoid using `all` mode in a multi-node cluster—some cluster features such as replication and catalog refresh aren't designed to work with `all`-mode nodes.
	> Some cluster features such as replication and catalog refresh aren't designed to work with `all`-mode nodes.

	Solution: For nodes using the default Parquet-backed storage engine, increase DataFusion threads on your single compactor node (see [Compactor node issues](#compactor-node-issues)).
	Solution: For nodes using the Parquet-backed storage engine, increase DataFusion threads on your single compactor node (see [Compactor node issues](#compactor-node-issues)).

	> `all` mode is intended for single-node Enterprise deployments.
	> `all` mode is only for single-node Enterprise deployments.

-> When scaling to a multi-node cluster, replace `all` with explicit modes and assign `compact` to exactly one node.
+When scaling a single `all` node cluster to a multi-node cluster:
+- Replace the `all` node with nodes that have explicit, specialized modes
+- Assign `compact` mode to exactly one node that uses the same node-id as the `all` node being replaced

Conversation

Copilot AI commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Run only one compactor node per cluster

Don't use all mode in a multi-node cluster

Changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 PR Preview — Preview Bot

Uh oh!

github-actions bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Style Check Results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Apr 8, 2026 •

edited

Loading

Don't use `all` mode in a multi-node cluster

github-actions bot commented Apr 8, 2026 •

edited

Loading

github-actions bot commented Apr 8, 2026 •

edited

Loading

github-actions bot commented Apr 9, 2026 •

edited

Loading