From 5ef735f89e518105d4498e9bf00503a2c313b407 Mon Sep 17 00:00:00 2001 From: vbotbuildovich <62446873+vbotbuildovich@users.noreply.github.com> Date: Fri, 3 Apr 2026 17:46:33 +0000 Subject: [PATCH 01/11] auto-docs: Update property docs for v26.1.2 --- antora.yml | 4 +-- ...-property-changes-v26.1.1-to-v26.1.2.json} | 6 ++-- ....json => redpanda-properties-v26.1.2.json} | 35 ++++++++++--------- .../properties/cluster-properties.adoc | 24 +++---------- .../partials/properties/topic-properties.adoc | 10 ++---- 5 files changed, 31 insertions(+), 48 deletions(-) rename docs-data/{redpanda-property-changes-v26.1.1-to-v26.1.1-rc5.json => redpanda-property-changes-v26.1.1-to-v26.1.2.json} (81%) rename modules/reference/attachments/{redpanda-properties-v26.1.1-rc5.json => redpanda-properties-v26.1.2.json} (99%) diff --git a/antora.yml b/antora.yml index 2d617a50c6..a7d65438d4 100644 --- a/antora.yml +++ b/antora.yml @@ -17,8 +17,8 @@ asciidoc: # Fallback versions # We try to fetch the latest versions from GitHub at build time # -- - full-version: 26.1.1 - latest-redpanda-tag: 'v26.1.1' + full-version: 26.1.2 + latest-redpanda-tag: 'v26.1.2' latest-console-tag: 'v3.3.1' latest-release-commit: '35a825c9c1880ebeedf4c18bb8c6cceaa63566c1' latest-operator-version: 'v2.3.8-24.3.6' diff --git a/docs-data/redpanda-property-changes-v26.1.1-to-v26.1.1-rc5.json b/docs-data/redpanda-property-changes-v26.1.1-to-v26.1.2.json similarity index 81% rename from docs-data/redpanda-property-changes-v26.1.1-to-v26.1.1-rc5.json rename to docs-data/redpanda-property-changes-v26.1.1-to-v26.1.2.json index 0f0d4b108b..35219831fe 100644 --- a/docs-data/redpanda-property-changes-v26.1.1-to-v26.1.1-rc5.json +++ b/docs-data/redpanda-property-changes-v26.1.1-to-v26.1.2.json @@ -1,8 +1,8 @@ { "comparison": { "oldVersion": "v26.1.1", - "newVersion": "v26.1.1-rc5", - "timestamp": "2026-03-31T14:37:03.774Z" + "newVersion": "v26.1.2", + "timestamp": "2026-04-03T17:46:32.769Z" }, "summary": { "newProperties": 0, @@ -10,6 +10,7 @@ "changedDescriptions": 0, "changedTypes": 0, "deprecatedProperties": 0, + "removedDeprecatedProperties": 0, "removedProperties": 0, "emptyDescriptions": 2 }, @@ -19,6 +20,7 @@ "changedDescriptions": [], "changedTypes": [], "deprecatedProperties": [], + "removedDeprecatedProperties": [], "removedProperties": [], "emptyDescriptions": [ { diff --git a/modules/reference/attachments/redpanda-properties-v26.1.1-rc5.json b/modules/reference/attachments/redpanda-properties-v26.1.2.json similarity index 99% rename from modules/reference/attachments/redpanda-properties-v26.1.1-rc5.json rename to modules/reference/attachments/redpanda-properties-v26.1.2.json index f72db52b73..6f3de7fece 100644 --- a/modules/reference/attachments/redpanda-properties-v26.1.1-rc5.json +++ b/modules/reference/attachments/redpanda-properties-v26.1.2.json @@ -240,10 +240,12 @@ "defined_in": "model/metadata.h", "enum": [ "calibrated", - "random" + "random", + "greedy" ], "enum_string_mappings": { "calibrated": "calibrated", + "greedy": "greedy", "random": "random" }, "type": "enum" @@ -577,7 +579,7 @@ "cloud_supported": false, "config_scope": "broker", "default": "/usr/share/redpanda/proxy-api-doc", - "defined_in": "src/v/pandaproxy/rest/configuration.cc", + "defined_in": "src/v/pandaproxy/schema_registry/configuration.cc", "description": "Path to the API specifications directory. This directory contains API documentation for both the HTTP Proxy API and Schema Registry API.", "is_deprecated": false, "is_enterprise": false, @@ -3388,7 +3390,7 @@ "needs_restart": true, "nullable": false, "related_topics": [ - "xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics]" + "self-managed-only: xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics]" ], "type": "boolean", "visibility": "user" @@ -5496,7 +5498,7 @@ "config_scope": "cluster", "default": "unset", "defined_in": "src/v/config/configuration.cc", - "description": "Set the default storage mode for new topics. This value applies to any topic created without an explicit <> setting (that is, when the topic's `redpanda.storage.mode` is `unset`).\n\nAccepted values:\n\n* `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration.\n* `local`: Store data only on local disks, with no object storage involvement.\n* `tiered`: Store data on local disks and replicate it to object storage using xref:manage:tiered-storage.adoc[Tiered Storage]. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using xref:manage:tiered-storage.adoc#cloud-topics[cloud topics].", + "description": "Set the default storage mode for new topics. This value applies to any topic created without an explicit <> setting (that is, when the topic's `redpanda.storage.mode` is `unset`).\n\nAccepted values:\n\n* `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration.\n* `local`: Store data only on local disks, with no object storage involvement.\n* `tiered`: Store data on local disks and replicate it to object storage using Tiered Storage. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using Cloud Topics.", "enum": [ "local", "tiered", @@ -5510,8 +5512,8 @@ "needs_restart": false, "nullable": false, "related_topics": [ - "xref:manage:tiered-storage.adoc[Tiered Storage]", - "xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics]" + "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]", + "self-managed-only: xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics]" ], "type": "string", "version": "v26.1.1", @@ -7577,14 +7579,14 @@ "config_scope": "cluster", "default": null, "defined_in": "src/v/config/configuration.cc", - "description": "Initial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica set.", + "description": "Initial local retention size target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica set.", "is_deprecated": false, "is_enterprise": false, "name": "initial_retention_local_target_bytes_default", "needs_restart": false, "nullable": true, "related_topics": [ - "xref:manage:tiered-storage.adoc[Tiered Storage]" + "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]" ], "type": "integer", "visibility": "user" @@ -7598,7 +7600,7 @@ "config_scope": "cluster", "default": null, "defined_in": "src/v/config/configuration.cc", - "description": "Initial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica is set.", + "description": "Initial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", "is_deprecated": false, "is_enterprise": false, "maximum": 17592186044415, @@ -7607,7 +7609,7 @@ "needs_restart": false, "nullable": true, "related_topics": [ - "xref:manage:tiered-storage.adoc[Tiered Storage]" + "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]" ], "type": "integer", "visibility": "user" @@ -8701,7 +8703,8 @@ "description": "Mode of the leader balancer optimization strategy. `calibrated` uses a heuristic that balances leaders based on replica counts per shard. `random` randomly moves leaders to reduce load on heavily-loaded shards. Legacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", "enum": [ "calibrated", - "random" + "random", + "greedy" ], "example": "`model::leader_balancer_mode_to_string( model::leader_balancer_mode::calibrated)`", "is_deprecated": false, @@ -11254,8 +11257,8 @@ "is_topic_property": true, "name": "redpanda.cloud_topic.enabled", "related_topics": [ - "xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics]", - "xref:manage:tiered-storage.adoc[Tiered Storage]" + "self-managed-only: xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics]", + "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]" ], "type": "string", "visibility": "user" @@ -11620,7 +11623,7 @@ "corresponding_cluster_property": "default_redpanda_storage_mode", "default": "unset", "defined_in": "src/v/kafka/protocol/topic_properties.h", - "description": "The storage mode for a topic. Determines how topic data is stored and whether it is eligible for upload to object storage.\n\nAccepted values:\n\n* `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings.\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables xref:manage:tiered-storage.adoc[Tiered Storage] for the topic.\n* `cloud`: Topic data is stored in object storage using the glossterm:Cloud Topic[,Cloud Topics] architecture. Local storage is used only as a write buffer.\n* `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`.\n\nThis property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics.", + "description": "The storage mode for a topic. Determines how topic data is stored and whether it is eligible for upload to object storage.\n\nAccepted values:\n\n* `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings.\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables Tiered Storage for the topic.\n* `cloud`: Topic data is stored in object storage using the Cloud Topics architecture. Local storage is used only as a write buffer.\n* `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`.\n\nThis property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics.", "enum": [ "local", "tiered", @@ -11633,8 +11636,8 @@ "name": "redpanda.storage.mode", "needs_restart": false, "related_topics": [ - "xref:manage:tiered-storage.adoc[Tiered Storage]", - "xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics]" + "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]", + "self-managed-only: xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics]" ], "type": "string", "version": "v26.1.1" diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index f1fee64386..5dd718502c 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -4935,14 +4935,8 @@ Accepted values: * `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration. * `local`: Store data only on local disks, with no object storage involvement. -ifndef::env-cloud[] -* `tiered`: Store data on local disks and replicate it to object storage using xref:manage:tiered-storage.adoc[Tiered Storage]. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`. -* `cloud`: Store data primarily in object storage using xref:manage:tiered-storage.adoc#cloud-topics[cloud topics]. -endif::[] -ifdef::env-cloud[] * `tiered`: Store data on local disks and replicate it to object storage using Tiered Storage. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`. * `cloud`: Store data primarily in object storage using Cloud Topics. -endif::[] [cols="1s,2a"] |=== @@ -4990,9 +4984,9 @@ endif::[] | `tiered` +ifndef::env-cloud[] | Related topics | -ifndef::env-cloud[] * xref:manage:tiered-storage.adoc[Tiered Storage] * xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics] @@ -9172,12 +9166,7 @@ endif::[] === initial_retention_local_target_bytes_default -ifndef::env-cloud[] -Initial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica set. -endif::[] -ifdef::env-cloud[] Initial local retention size target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica set. -endif::[] [cols="1s,2a"] |=== @@ -9223,12 +9212,7 @@ endif::[] === initial_retention_local_target_ms_default -ifndef::env-cloud[] -Initial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica is set. -endif::[] -ifdef::env-cloud[] -Initial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica is set. -endif::[] +Initial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set. [cols="1s,2a"] |=== @@ -11517,10 +11501,10 @@ Mode of the leader balancer optimization strategy. `calibrated` uses a heuristic | Accepted values | ifndef::env-cloud[] -`calibrated`, `random` +`calibrated`, `random`, `greedy` endif::[] ifdef::env-cloud[] -`calibrated`, `random` +`calibrated`, `random`, `greedy` endif::[] diff --git a/modules/reference/partials/properties/topic-properties.adoc b/modules/reference/partials/properties/topic-properties.adoc index 2f599a9cb3..29bf1bcbee 100644 --- a/modules/reference/partials/properties/topic-properties.adoc +++ b/modules/reference/partials/properties/topic-properties.adoc @@ -977,9 +977,9 @@ ifndef::env-cloud[] | Yes endif::[] +ifndef::env-cloud[] | Related topics | -ifndef::env-cloud[] * xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics] * xref:manage:tiered-storage.adoc[Tiered Storage] @@ -1567,14 +1567,8 @@ The storage mode for a topic. Determines how topic data is stored and whether it Accepted values: * `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings. -ifndef::env-cloud[] -* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables xref:manage:tiered-storage.adoc[Tiered Storage] for the topic. -* `cloud`: Topic data is stored in object storage using the glossterm:Cloud Topic[,Cloud Topics] architecture. Local storage is used only as a write buffer. -endif::[] -ifdef::env-cloud[] * `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables Tiered Storage for the topic. * `cloud`: Topic data is stored in object storage using the Cloud Topics architecture. Local storage is used only as a write buffer. -endif::[] * `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`. This property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics. @@ -1616,9 +1610,9 @@ ifndef::env-cloud[] | Yes endif::[] +ifndef::env-cloud[] | Related topics | -ifndef::env-cloud[] * xref:manage:tiered-storage.adoc[Tiered Storage] * xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics] From 2aad44910f63de13aec276966a04f24513406d0f Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 7 Apr 2026 09:15:15 +0100 Subject: [PATCH 02/11] docs: Add leader_balancer_mode greedy option and restore xrefs - Add override for leader_balancer_mode documenting the new greedy strategy which distributes leadership evenly per topic - Restore xrefs to Tiered Storage and Cloud Topics pages in storage mode property descriptions (default_redpanda_storage_mode, redpanda.storage.mode, initial_retention_local_target_*_default) --- docs-data/property-overrides.json | 12 ++++++++---- .../redpanda-properties-v26.1.2.json | 12 ++++++------ .../properties/cluster-properties.adoc | 18 +++++++++++++----- .../partials/properties/topic-properties.adoc | 4 ++-- 4 files changed, 29 insertions(+), 17 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index a13c840587..8cfc202556 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -775,7 +775,7 @@ "config_scope": "cluster" }, "default_redpanda_storage_mode": { - "description": "Set the default storage mode for new topics. This value applies to any topic created without an explicit <> setting (that is, when the topic's `redpanda.storage.mode` is `unset`).\n\nAccepted values:\n\n* `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration.\n* `local`: Store data only on local disks, with no object storage involvement.\n* `tiered`: Store data on local disks and replicate it to object storage using Tiered Storage. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using Cloud Topics.", + "description": "Set the default storage mode for new topics. This value applies to any topic created without an explicit <> setting (that is, when the topic's `redpanda.storage.mode` is `unset`).\n\nAccepted values:\n\n* `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration.\n* `local`: Store data only on local disks, with no object storage involvement.\n* `tiered`: Store data on local disks and replicate it to object storage using xref:manage:tiered-storage.adoc[Tiered Storage]. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics].", "related_topics": [ "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]", "self-managed-only: xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics]" @@ -1092,14 +1092,14 @@ "config_scope": "topic" }, "initial_retention_local_target_bytes_default": { - "description": "Initial local retention size target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica set.", + "description": "Initial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", "related_topics": [ "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]" ], "config_scope": "cluster" }, "initial_retention_local_target_ms_default": { - "description": "Initial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", + "description": "Initial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", "related_topics": [ "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]" ], @@ -1296,6 +1296,10 @@ "description": "Leadership rebalancing idle timeout.\n\n*Unit*: milliseconds", "config_scope": "cluster" }, + "leader_balancer_mode": { + "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated`: Balances leaders based on replica counts per shard using a calibrated heuristic.\n* `random`: Randomly moves leaders to reduce load on heavily-loaded shards.\n* `greedy`: A topic-aware strategy that distributes each topic's leadership evenly across all brokers. Pre-calculates the target distribution for consistent, reproducible results across runs. Useful for benchmarking or production environments where predictable leader distribution matters.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", + "config_scope": "cluster" + }, "leader_balancer_mute_timeout": { "description": "The length of time that a glossterm:Raft[] group is muted after a leadership rebalance operation. Any group that has been moved, regardless of whether the move succeeded or failed, undergoes a cooling-off period. This prevents Raft groups from repeatedly experiencing leadership rebalance operations in a short time frame, which can lead to instability in the cluster.\n\nThe leader balancer maintains a list of muted groups and reevaluates muted status at the start of each balancing iteration. Muted groups still contribute to overall cluster balance calculations although they can't themselves be moved until the mute period is over.", "config_scope": "cluster" @@ -1795,7 +1799,7 @@ "config_scope": "topic" }, "redpanda.storage.mode": { - "description": "The storage mode for a topic. Determines how topic data is stored and whether it is eligible for upload to object storage.\n\nAccepted values:\n\n* `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings.\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables Tiered Storage for the topic.\n* `cloud`: Topic data is stored in object storage using the Cloud Topics architecture. Local storage is used only as a write buffer.\n* `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`.\n\nThis property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics.", + "description": "The storage mode for a topic. Determines how topic data is stored and whether it is eligible for upload to object storage.\n\nAccepted values:\n\n* `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings.\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables xref:manage:tiered-storage.adoc[Tiered Storage] for the topic.\n* `cloud`: Topic data is stored in object storage using the xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics] architecture. Local storage is used only as a write buffer.\n* `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`.\n\nThis property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics.", "related_topics": [ "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]", "self-managed-only: xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics]" diff --git a/modules/reference/attachments/redpanda-properties-v26.1.2.json b/modules/reference/attachments/redpanda-properties-v26.1.2.json index 6f3de7fece..054d9e10b2 100644 --- a/modules/reference/attachments/redpanda-properties-v26.1.2.json +++ b/modules/reference/attachments/redpanda-properties-v26.1.2.json @@ -579,7 +579,7 @@ "cloud_supported": false, "config_scope": "broker", "default": "/usr/share/redpanda/proxy-api-doc", - "defined_in": "src/v/pandaproxy/schema_registry/configuration.cc", + "defined_in": "src/v/pandaproxy/rest/configuration.cc", "description": "Path to the API specifications directory. This directory contains API documentation for both the HTTP Proxy API and Schema Registry API.", "is_deprecated": false, "is_enterprise": false, @@ -5498,7 +5498,7 @@ "config_scope": "cluster", "default": "unset", "defined_in": "src/v/config/configuration.cc", - "description": "Set the default storage mode for new topics. This value applies to any topic created without an explicit <> setting (that is, when the topic's `redpanda.storage.mode` is `unset`).\n\nAccepted values:\n\n* `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration.\n* `local`: Store data only on local disks, with no object storage involvement.\n* `tiered`: Store data on local disks and replicate it to object storage using Tiered Storage. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using Cloud Topics.", + "description": "Set the default storage mode for new topics. This value applies to any topic created without an explicit <> setting (that is, when the topic's `redpanda.storage.mode` is `unset`).\n\nAccepted values:\n\n* `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration.\n* `local`: Store data only on local disks, with no object storage involvement.\n* `tiered`: Store data on local disks and replicate it to object storage using xref:manage:tiered-storage.adoc[Tiered Storage]. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics].", "enum": [ "local", "tiered", @@ -7579,7 +7579,7 @@ "config_scope": "cluster", "default": null, "defined_in": "src/v/config/configuration.cc", - "description": "Initial local retention size target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica set.", + "description": "Initial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", "is_deprecated": false, "is_enterprise": false, "name": "initial_retention_local_target_bytes_default", @@ -7600,7 +7600,7 @@ "config_scope": "cluster", "default": null, "defined_in": "src/v/config/configuration.cc", - "description": "Initial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", + "description": "Initial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", "is_deprecated": false, "is_enterprise": false, "maximum": 17592186044415, @@ -8700,7 +8700,7 @@ "config_scope": "cluster", "default": "calibrated", "defined_in": "src/v/config/configuration.cc", - "description": "Mode of the leader balancer optimization strategy. `calibrated` uses a heuristic that balances leaders based on replica counts per shard. `random` randomly moves leaders to reduce load on heavily-loaded shards. Legacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", + "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated`: Balances leaders based on replica counts per shard using a calibrated heuristic.\n* `random`: Randomly moves leaders to reduce load on heavily-loaded shards.\n* `greedy`: A topic-aware strategy that distributes each topic's leadership evenly across all brokers. Pre-calculates the target distribution for consistent, reproducible results across runs. Useful for benchmarking or production environments where predictable leader distribution matters.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", "enum": [ "calibrated", "random", @@ -11623,7 +11623,7 @@ "corresponding_cluster_property": "default_redpanda_storage_mode", "default": "unset", "defined_in": "src/v/kafka/protocol/topic_properties.h", - "description": "The storage mode for a topic. Determines how topic data is stored and whether it is eligible for upload to object storage.\n\nAccepted values:\n\n* `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings.\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables Tiered Storage for the topic.\n* `cloud`: Topic data is stored in object storage using the Cloud Topics architecture. Local storage is used only as a write buffer.\n* `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`.\n\nThis property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics.", + "description": "The storage mode for a topic. Determines how topic data is stored and whether it is eligible for upload to object storage.\n\nAccepted values:\n\n* `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings.\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables xref:manage:tiered-storage.adoc[Tiered Storage] for the topic.\n* `cloud`: Topic data is stored in object storage using the xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics] architecture. Local storage is used only as a write buffer.\n* `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`.\n\nThis property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics.", "enum": [ "local", "tiered", diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index 5dd718502c..73ea247274 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -4935,8 +4935,8 @@ Accepted values: * `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration. * `local`: Store data only on local disks, with no object storage involvement. -* `tiered`: Store data on local disks and replicate it to object storage using Tiered Storage. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`. -* `cloud`: Store data primarily in object storage using Cloud Topics. +* `tiered`: Store data on local disks and replicate it to object storage using xref:manage:tiered-storage.adoc[Tiered Storage]. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`. +* `cloud`: Store data primarily in object storage using xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics]. [cols="1s,2a"] |=== @@ -9166,7 +9166,7 @@ endif::[] === initial_retention_local_target_bytes_default -Initial local retention size target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica set. +Initial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set. [cols="1s,2a"] |=== @@ -9212,7 +9212,7 @@ endif::[] === initial_retention_local_target_ms_default -Initial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set. +Initial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set. [cols="1s,2a"] |=== @@ -11489,7 +11489,15 @@ endif::[] === leader_balancer_mode -Mode of the leader balancer optimization strategy. `calibrated` uses a heuristic that balances leaders based on replica counts per shard. `random` randomly moves leaders to reduce load on heavily-loaded shards. Legacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`. +Mode of the leader balancer optimization strategy. + +Accepted values: + +* `calibrated`: Balances leaders based on replica counts per shard using a calibrated heuristic. +* `random`: Randomly moves leaders to reduce load on heavily-loaded shards. +* `greedy`: A topic-aware strategy that distributes each topic's leadership evenly across all brokers. Pre-calculates the target distribution for consistent, reproducible results across runs. Useful for benchmarking or production environments where predictable leader distribution matters. + +Legacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`. [cols="1s,2a"] |=== diff --git a/modules/reference/partials/properties/topic-properties.adoc b/modules/reference/partials/properties/topic-properties.adoc index 29bf1bcbee..39f136929d 100644 --- a/modules/reference/partials/properties/topic-properties.adoc +++ b/modules/reference/partials/properties/topic-properties.adoc @@ -1567,8 +1567,8 @@ The storage mode for a topic. Determines how topic data is stored and whether it Accepted values: * `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings. -* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables Tiered Storage for the topic. -* `cloud`: Topic data is stored in object storage using the Cloud Topics architecture. Local storage is used only as a write buffer. +* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables xref:manage:tiered-storage.adoc[Tiered Storage] for the topic. +* `cloud`: Topic data is stored in object storage using the xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics] architecture. Local storage is used only as a write buffer. * `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`. This property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics. From 821838d4e6d1584978d69d2950e6884aa8cf922d Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 7 Apr 2026 09:33:32 +0100 Subject: [PATCH 03/11] docs: Add leader_balancer_mode greedy option and preserve conditional xrefs - Add override for leader_balancer_mode documenting the new greedy strategy - Embed AsciiDoc conditionals in storage mode property descriptions to preserve xrefs for self-managed and plain text for cloud docs --- docs-data/property-overrides.json | 10 +++++----- .../attachments/redpanda-properties-v26.1.2.json | 8 ++++---- .../partials/properties/cluster-properties.adoc | 16 ++++++++++++++++ .../partials/properties/topic-properties.adoc | 6 ++++++ 4 files changed, 31 insertions(+), 9 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index 8cfc202556..aed4c0ffcf 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -775,7 +775,7 @@ "config_scope": "cluster" }, "default_redpanda_storage_mode": { - "description": "Set the default storage mode for new topics. This value applies to any topic created without an explicit <> setting (that is, when the topic's `redpanda.storage.mode` is `unset`).\n\nAccepted values:\n\n* `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration.\n* `local`: Store data only on local disks, with no object storage involvement.\n* `tiered`: Store data on local disks and replicate it to object storage using xref:manage:tiered-storage.adoc[Tiered Storage]. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics].", + "description": "Set the default storage mode for new topics. This value applies to any topic created without an explicit <> setting (that is, when the topic's `redpanda.storage.mode` is `unset`).\n\nAccepted values:\n\n* `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration.\n* `local`: Store data only on local disks, with no object storage involvement.\nifndef::env-cloud[]\n* `tiered`: Store data on local disks and replicate it to object storage using xref:manage:tiered-storage.adoc[Tiered Storage]. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics].\nendif::[]\nifdef::env-cloud[]\n* `tiered`: Store data on local disks and replicate it to object storage using Tiered Storage. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using Cloud Topics.\nendif::[]", "related_topics": [ "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]", "self-managed-only: xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics]" @@ -1092,14 +1092,14 @@ "config_scope": "topic" }, "initial_retention_local_target_bytes_default": { - "description": "Initial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", + "description": "ifndef::env-cloud[]\nInitial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.\nendif::[]\nifdef::env-cloud[]\nInitial local retention size target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.\nendif::[]", "related_topics": [ "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]" ], "config_scope": "cluster" }, "initial_retention_local_target_ms_default": { - "description": "Initial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", + "description": "ifndef::env-cloud[]\nInitial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.\nendif::[]\nifdef::env-cloud[]\nInitial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.\nendif::[]", "related_topics": [ "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]" ], @@ -1799,7 +1799,7 @@ "config_scope": "topic" }, "redpanda.storage.mode": { - "description": "The storage mode for a topic. Determines how topic data is stored and whether it is eligible for upload to object storage.\n\nAccepted values:\n\n* `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings.\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables xref:manage:tiered-storage.adoc[Tiered Storage] for the topic.\n* `cloud`: Topic data is stored in object storage using the xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics] architecture. Local storage is used only as a write buffer.\n* `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`.\n\nThis property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics.", + "description": "The storage mode for a topic. Determines how topic data is stored and whether it is eligible for upload to object storage.\n\nAccepted values:\n\n* `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings.\nifndef::env-cloud[]\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables xref:manage:tiered-storage.adoc[Tiered Storage] for the topic.\n* `cloud`: Topic data is stored in object storage using the xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics] architecture. Local storage is used only as a write buffer.\nendif::[]\nifdef::env-cloud[]\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables Tiered Storage for the topic.\n* `cloud`: Topic data is stored in object storage using the Cloud Topics architecture. Local storage is used only as a write buffer.\nendif::[]\n* `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`.\n\nThis property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics.", "related_topics": [ "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]", "self-managed-only: xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics]" @@ -2265,4 +2265,4 @@ "description": "The default write caching mode to apply to user topics. Write caching acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to be written to disk. With `acks=all`, this provides lower latency while still ensuring that a majority of brokers acknowledge the write. \n\nFsyncs follow <> and <>, whichever is reached first.\n\nThe `write_caching_default` cluster property can be overridden with the xref:reference:properties/topic-properties.adoc#writecaching[`write.caching`] topic property." } } -} +} \ No newline at end of file diff --git a/modules/reference/attachments/redpanda-properties-v26.1.2.json b/modules/reference/attachments/redpanda-properties-v26.1.2.json index 054d9e10b2..a6dc6ce627 100644 --- a/modules/reference/attachments/redpanda-properties-v26.1.2.json +++ b/modules/reference/attachments/redpanda-properties-v26.1.2.json @@ -5498,7 +5498,7 @@ "config_scope": "cluster", "default": "unset", "defined_in": "src/v/config/configuration.cc", - "description": "Set the default storage mode for new topics. This value applies to any topic created without an explicit <> setting (that is, when the topic's `redpanda.storage.mode` is `unset`).\n\nAccepted values:\n\n* `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration.\n* `local`: Store data only on local disks, with no object storage involvement.\n* `tiered`: Store data on local disks and replicate it to object storage using xref:manage:tiered-storage.adoc[Tiered Storage]. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics].", + "description": "Set the default storage mode for new topics. This value applies to any topic created without an explicit <> setting (that is, when the topic's `redpanda.storage.mode` is `unset`).\n\nAccepted values:\n\n* `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration.\n* `local`: Store data only on local disks, with no object storage involvement.\nifndef::env-cloud[]\n* `tiered`: Store data on local disks and replicate it to object storage using xref:manage:tiered-storage.adoc[Tiered Storage]. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics].\nendif::[]\nifdef::env-cloud[]\n* `tiered`: Store data on local disks and replicate it to object storage using Tiered Storage. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`.\n* `cloud`: Store data primarily in object storage using Cloud Topics.\nendif::[]", "enum": [ "local", "tiered", @@ -7579,7 +7579,7 @@ "config_scope": "cluster", "default": null, "defined_in": "src/v/config/configuration.cc", - "description": "Initial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", + "description": "ifndef::env-cloud[]\nInitial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.\nendif::[]\nifdef::env-cloud[]\nInitial local retention size target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.\nendif::[]", "is_deprecated": false, "is_enterprise": false, "name": "initial_retention_local_target_bytes_default", @@ -7600,7 +7600,7 @@ "config_scope": "cluster", "default": null, "defined_in": "src/v/config/configuration.cc", - "description": "Initial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", + "description": "ifndef::env-cloud[]\nInitial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.\nendif::[]\nifdef::env-cloud[]\nInitial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.\nendif::[]", "is_deprecated": false, "is_enterprise": false, "maximum": 17592186044415, @@ -11623,7 +11623,7 @@ "corresponding_cluster_property": "default_redpanda_storage_mode", "default": "unset", "defined_in": "src/v/kafka/protocol/topic_properties.h", - "description": "The storage mode for a topic. Determines how topic data is stored and whether it is eligible for upload to object storage.\n\nAccepted values:\n\n* `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings.\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables xref:manage:tiered-storage.adoc[Tiered Storage] for the topic.\n* `cloud`: Topic data is stored in object storage using the xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics] architecture. Local storage is used only as a write buffer.\n* `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`.\n\nThis property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics.", + "description": "The storage mode for a topic. Determines how topic data is stored and whether it is eligible for upload to object storage.\n\nAccepted values:\n\n* `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings.\nifndef::env-cloud[]\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables xref:manage:tiered-storage.adoc[Tiered Storage] for the topic.\n* `cloud`: Topic data is stored in object storage using the xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics] architecture. Local storage is used only as a write buffer.\nendif::[]\nifdef::env-cloud[]\n* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables Tiered Storage for the topic.\n* `cloud`: Topic data is stored in object storage using the Cloud Topics architecture. Local storage is used only as a write buffer.\nendif::[]\n* `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`.\n\nThis property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics.", "enum": [ "local", "tiered", diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index 73ea247274..ffbe2c0f03 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -4935,8 +4935,14 @@ Accepted values: * `unset`: Defer to the legacy <> and <> topic properties for Tiered Storage configuration. * `local`: Store data only on local disks, with no object storage involvement. +ifndef::env-cloud[] * `tiered`: Store data on local disks and replicate it to object storage using xref:manage:tiered-storage.adoc[Tiered Storage]. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`. * `cloud`: Store data primarily in object storage using xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics]. +endif::[] +ifdef::env-cloud[] +* `tiered`: Store data on local disks and replicate it to object storage using Tiered Storage. Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`. +* `cloud`: Store data primarily in object storage using Cloud Topics. +endif::[] [cols="1s,2a"] |=== @@ -9166,7 +9172,12 @@ endif::[] === initial_retention_local_target_bytes_default +ifndef::env-cloud[] Initial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set. +endif::[] +ifdef::env-cloud[] +Initial local retention size target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set. +endif::[] [cols="1s,2a"] |=== @@ -9212,7 +9223,12 @@ endif::[] === initial_retention_local_target_ms_default +ifndef::env-cloud[] Initial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set. +endif::[] +ifdef::env-cloud[] +Initial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set. +endif::[] [cols="1s,2a"] |=== diff --git a/modules/reference/partials/properties/topic-properties.adoc b/modules/reference/partials/properties/topic-properties.adoc index 39f136929d..9143ceb281 100644 --- a/modules/reference/partials/properties/topic-properties.adoc +++ b/modules/reference/partials/properties/topic-properties.adoc @@ -1567,8 +1567,14 @@ The storage mode for a topic. Determines how topic data is stored and whether it Accepted values: * `local`: Topic data is stored only on the broker's local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings. +ifndef::env-cloud[] * `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables xref:manage:tiered-storage.adoc[Tiered Storage] for the topic. * `cloud`: Topic data is stored in object storage using the xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics] architecture. Local storage is used only as a write buffer. +endif::[] +ifdef::env-cloud[] +* `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables Tiered Storage for the topic. +* `cloud`: Topic data is stored in object storage using the Cloud Topics architecture. Local storage is used only as a write buffer. +endif::[] * `unset`: Specifies that the topic's storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`. This property overrides the cluster-wide config_ref:default_redpanda_storage_mode,true,properties/cluster-properties[] setting for individual topics. From ebb21418da7886522c442d972885a4d0fd1bd3c5 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 7 Apr 2026 10:01:46 +0100 Subject: [PATCH 04/11] docs: Improve leader_balancer_mode guidance Update description to help users choose between calibrated, random, and greedy modes with clearer guidance on when to use each option. --- docs-data/property-overrides.json | 2 +- .../attachments/redpanda-properties-v26.1.2.json | 2 +- .../reference/partials/properties/cluster-properties.adoc | 8 +++----- 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index aed4c0ffcf..9cafc12545 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -1297,7 +1297,7 @@ "config_scope": "cluster" }, "leader_balancer_mode": { - "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated`: Balances leaders based on replica counts per shard using a calibrated heuristic.\n* `random`: Randomly moves leaders to reduce load on heavily-loaded shards.\n* `greedy`: A topic-aware strategy that distributes each topic's leadership evenly across all brokers. Pre-calculates the target distribution for consistent, reproducible results across runs. Useful for benchmarking or production environments where predictable leader distribution matters.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", + "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility.\n* `greedy`: A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", "config_scope": "cluster" }, "leader_balancer_mute_timeout": { diff --git a/modules/reference/attachments/redpanda-properties-v26.1.2.json b/modules/reference/attachments/redpanda-properties-v26.1.2.json index a6dc6ce627..8dfd00e9ce 100644 --- a/modules/reference/attachments/redpanda-properties-v26.1.2.json +++ b/modules/reference/attachments/redpanda-properties-v26.1.2.json @@ -8700,7 +8700,7 @@ "config_scope": "cluster", "default": "calibrated", "defined_in": "src/v/config/configuration.cc", - "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated`: Balances leaders based on replica counts per shard using a calibrated heuristic.\n* `random`: Randomly moves leaders to reduce load on heavily-loaded shards.\n* `greedy`: A topic-aware strategy that distributes each topic's leadership evenly across all brokers. Pre-calculates the target distribution for consistent, reproducible results across runs. Useful for benchmarking or production environments where predictable leader distribution matters.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", + "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility.\n* `greedy`: A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", "enum": [ "calibrated", "random", diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index ffbe2c0f03..f854bffed2 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -8015,7 +8015,6 @@ endif::[] // end::redpanda-cloud[] -// tag::redpanda-cloud[] === iceberg_rest_catalog_aws_credentials_source *Accepted values*: `aws_instance_metadata`, `azure_aks_oidc_federation`, `azure_vm_instance_metadata`, `config_file`, `gcp_instance_metadata`, `sts`. @@ -8076,7 +8075,6 @@ endif::[] |=== -// end::redpanda-cloud[] // tag::redpanda-cloud[] === iceberg_rest_catalog_aws_region @@ -11509,9 +11507,9 @@ Mode of the leader balancer optimization strategy. Accepted values: -* `calibrated`: Balances leaders based on replica counts per shard using a calibrated heuristic. -* `random`: Randomly moves leaders to reduce load on heavily-loaded shards. -* `greedy`: A topic-aware strategy that distributes each topic's leadership evenly across all brokers. Pre-calculates the target distribution for consistent, reproducible results across runs. Useful for benchmarking or production environments where predictable leader distribution matters. +* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads. +* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility. +* `greedy`: A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state. Legacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`. From ca043baabd669d1f47f0c644cdd7f1a501612bf6 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 7 Apr 2026 13:02:54 +0100 Subject: [PATCH 05/11] docs: Add greedy leader balancer to release notes and version note - Add release notes section for greedy leader balancer mode - Add (v26.1.2+) version note to greedy option in config reference --- docs-data/property-overrides.json | 2 +- modules/get-started/pages/release-notes/redpanda.adoc | 11 +++++++++++ .../attachments/redpanda-properties-v26.1.2.json | 2 +- .../partials/properties/cluster-properties.adoc | 2 +- 4 files changed, 14 insertions(+), 3 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index 9cafc12545..d410169bc0 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -1297,7 +1297,7 @@ "config_scope": "cluster" }, "leader_balancer_mode": { - "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility.\n* `greedy`: A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", + "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility.\n* `greedy` (v26.1.2+): A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", "config_scope": "cluster" }, "leader_balancer_mute_timeout": { diff --git a/modules/get-started/pages/release-notes/redpanda.adoc b/modules/get-started/pages/release-notes/redpanda.adoc index f0cd9a2f78..3871020ded 100644 --- a/modules/get-started/pages/release-notes/redpanda.adoc +++ b/modules/get-started/pages/release-notes/redpanda.adoc @@ -63,6 +63,17 @@ To create cross-region Remote Read Replica topics, configure dynamic upstreams t See xref:manage:tiered-storage.adoc#remote-read-replicas[Remote Read Replicas] for setup instructions and configuration details. +== Greedy leader balancer mode + +Redpanda {page-component-version} introduces a new `greedy` mode for the xref:reference:properties/cluster-properties.adoc#leader_balancer_mode[`leader_balancer_mode`] property. This topic-aware strategy pre-calculates the entire target leader distribution before making moves, ensuring each topic is independently balanced across all brokers. + +Unlike the default `calibrated` mode (which adaptively samples and prioritizes high-impact moves), `greedy` mode produces deterministic, reproducible results given the same input state. This makes it ideal for: + +* **Benchmarking**: Eliminates noise from non-deterministic leader placement across test runs +* **Predictable environments**: When you need consistent leader distribution after cluster operations + +Note that `greedy` mode may move more leaders than other modes to reach its target state, as it optimizes for the final distribution rather than minimizing the number of moves. + == Automatic broker decommissioning When continuous partition balancing is enabled, Redpanda can automatically decommission brokers that remain unavailable for a configured duration. The xref:reference:properties/cluster-properties.adoc#partition_autobalancing_node_autodecommission_timeout_sec[`partition_autobalancing_node_autodecommission_timeout_sec`] property triggers permanent broker removal, unlike xref:reference:properties/cluster-properties.adoc#partition_autobalancing_node_availability_timeout_sec[`partition_autobalancing_node_availability_timeout_sec`] which only moves partitions temporarily. diff --git a/modules/reference/attachments/redpanda-properties-v26.1.2.json b/modules/reference/attachments/redpanda-properties-v26.1.2.json index 8dfd00e9ce..3b94809ddb 100644 --- a/modules/reference/attachments/redpanda-properties-v26.1.2.json +++ b/modules/reference/attachments/redpanda-properties-v26.1.2.json @@ -8700,7 +8700,7 @@ "config_scope": "cluster", "default": "calibrated", "defined_in": "src/v/config/configuration.cc", - "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility.\n* `greedy`: A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", + "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility.\n* `greedy` (v26.1.2+): A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", "enum": [ "calibrated", "random", diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index f854bffed2..c8e599384e 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -11509,7 +11509,7 @@ Accepted values: * `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads. * `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility. -* `greedy`: A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state. +* `greedy` (v26.1.2+): A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state. Legacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`. From 32bf3533019dc79ac2ae2cc75a29bef814c4bc85 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 7 Apr 2026 13:04:30 +0100 Subject: [PATCH 06/11] docs: Add leadership balancing modes section to cluster-balancing.adoc Document the leader_balancer_mode options (calibrated, random, greedy) in the cluster balancing guide. --- .../cluster-maintenance/cluster-balancing.adoc | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc b/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc index 27d9daaed1..d5fa8e75c7 100644 --- a/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc +++ b/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc @@ -48,6 +48,24 @@ By default, Redpanda enables topic-aware leadership balancing with the xref:refe NOTE: In addition to the periodic heartbeat, leadership balancing can also occur when a xref:upgrade:rolling-upgrade.adoc#impact-of-broker-restarts[broker restarts] or when the controller leader changes (such as when a controller partition changes leader). The _controller leader_ manages the entire cluster. For example, when decommissioning a broker, the controller leader creates a reallocation plan for all partition replicas allocated to that broker. The _partition leader_ then handles the reconfiguration for its Raft group. +=== Leadership balancing modes + +The xref:reference:properties/cluster-properties.adoc#leader_balancer_mode[`leader_balancer_mode`] property controls the optimization strategy used for leadership balancing: + +[cols="1,3"] +|=== +| Mode | Description + +| `calibrated` (default) +| An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads. + +| `random` +| Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility. + +| `greedy` (v26.1.2+) +| A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state. +|=== + === Manually change leadership Despite an even distribution of leaders, sometimes the write pattern is not even across topics, and a set of traffic-heavy partitions could land on one broker and cause a latency spike. For information about metrics to monitor, see xref:manage:monitoring.adoc#partition-health[Partition health]. From ac4d8a15e5a94530ef62ddfa5ba824fa0e9fd9e5 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 7 Apr 2026 13:07:32 +0100 Subject: [PATCH 07/11] docs: Add greedy mode to benchmark guide and refine random description - Add section to benchmark.adoc recommending greedy mode for consistent results - Update random mode description: "fallback" instead of "legacy compatibility" - Regenerate property docs with updated descriptions --- docs-data/property-overrides.json | 2 +- modules/develop/pages/benchmark.adoc | 11 +++++++++++ .../pages/cluster-maintenance/cluster-balancing.adoc | 2 +- .../attachments/redpanda-properties-v26.1.2.json | 2 +- .../partials/properties/cluster-properties.adoc | 2 +- 5 files changed, 15 insertions(+), 4 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index d410169bc0..6b1c7e5fb9 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -1297,7 +1297,7 @@ "config_scope": "cluster" }, "leader_balancer_mode": { - "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility.\n* `greedy` (v26.1.2+): A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", + "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior.\n* `greedy` (v26.1.2+): A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", "config_scope": "cluster" }, "leader_balancer_mute_timeout": { diff --git a/modules/develop/pages/benchmark.adoc b/modules/develop/pages/benchmark.adoc index eefee70a73..8e8e8a434f 100644 --- a/modules/develop/pages/benchmark.adoc +++ b/modules/develop/pages/benchmark.adoc @@ -177,6 +177,17 @@ NOTE: Beginning with Ansible 2.14, references to `args: warn` within Ansible tas Connect to the benchmark's client and run the benchmark with a custom workload. +=== Ensure consistent leader distribution + +For reproducible benchmark results, configure Redpanda to use the `greedy` leader balancer mode. Unlike the default `calibrated` mode, `greedy` mode pre-calculates the target leader distribution and produces deterministic results across runs, eliminating noise from non-deterministic leader placement. + +[,bash] +---- +rpk cluster config set leader_balancer_mode greedy +---- + +See xref:manage:cluster-maintenance/cluster-balancing.adoc#leadership-balancing-modes[Leadership balancing modes] for details. + . Connect with SSH to the benchmark client, with its IP address retrieved from the `client_ssh_host` output of Terraform. + [,bash] diff --git a/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc b/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc index d5fa8e75c7..5d90412cf9 100644 --- a/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc +++ b/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc @@ -60,7 +60,7 @@ The xref:reference:properties/cluster-properties.adoc#leader_balancer_mode[`lead | An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads. | `random` -| Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility. +| Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior. | `greedy` (v26.1.2+) | A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state. diff --git a/modules/reference/attachments/redpanda-properties-v26.1.2.json b/modules/reference/attachments/redpanda-properties-v26.1.2.json index 3b94809ddb..3c4c5f03fd 100644 --- a/modules/reference/attachments/redpanda-properties-v26.1.2.json +++ b/modules/reference/attachments/redpanda-properties-v26.1.2.json @@ -8700,7 +8700,7 @@ "config_scope": "cluster", "default": "calibrated", "defined_in": "src/v/config/configuration.cc", - "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility.\n* `greedy` (v26.1.2+): A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", + "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior.\n* `greedy` (v26.1.2+): A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", "enum": [ "calibrated", "random", diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index c8e599384e..c33e1e4793 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -11508,7 +11508,7 @@ Mode of the leader balancer optimization strategy. Accepted values: * `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads. -* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility. +* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior. * `greedy` (v26.1.2+): A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state. Legacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`. From 3ece1249f019af060625b732b0970d9ae89e8690 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Tue, 7 Apr 2026 13:08:57 +0100 Subject: [PATCH 08/11] Apply suggestions from code review Co-authored-by: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> --- modules/get-started/pages/release-notes/redpanda.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/modules/get-started/pages/release-notes/redpanda.adoc b/modules/get-started/pages/release-notes/redpanda.adoc index 3871020ded..4abcbf7024 100644 --- a/modules/get-started/pages/release-notes/redpanda.adoc +++ b/modules/get-started/pages/release-notes/redpanda.adoc @@ -65,14 +65,13 @@ See xref:manage:tiered-storage.adoc#remote-read-replicas[Remote Read Replicas] f == Greedy leader balancer mode -Redpanda {page-component-version} introduces a new `greedy` mode for the xref:reference:properties/cluster-properties.adoc#leader_balancer_mode[`leader_balancer_mode`] property. This topic-aware strategy pre-calculates the entire target leader distribution before making moves, ensuring each topic is independently balanced across all brokers. +Version 26.1.2 introduces a new `greedy` mode for the xref:reference:properties/cluster-properties.adoc#leader_balancer_mode[`leader_balancer_mode`] property. This topic-aware strategy pre-calculates the entire target leader distribution before making moves, ensuring each topic is independently balanced across all brokers. Unlike the default `calibrated` mode (which adaptively samples and prioritizes high-impact moves), `greedy` mode produces deterministic, reproducible results given the same input state. This makes it ideal for: * **Benchmarking**: Eliminates noise from non-deterministic leader placement across test runs * **Predictable environments**: When you need consistent leader distribution after cluster operations -Note that `greedy` mode may move more leaders than other modes to reach its target state, as it optimizes for the final distribution rather than minimizing the number of moves. == Automatic broker decommissioning From 8a974b426e2dba74bc7202964e12c6c512e7c6c7 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 7 Apr 2026 13:29:28 +0100 Subject: [PATCH 09/11] docs: Move greedy tip to after cluster setup in benchmark guide --- modules/develop/pages/benchmark.adoc | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/modules/develop/pages/benchmark.adoc b/modules/develop/pages/benchmark.adoc index 8e8e8a434f..5b82bb1e65 100644 --- a/modules/develop/pages/benchmark.adoc +++ b/modules/develop/pages/benchmark.adoc @@ -173,21 +173,12 @@ ansible-playbook deploy.yaml --private-key= + NOTE: Beginning with Ansible 2.14, references to `args: warn` within Ansible tasks cause a fatal error and halt the execution of the playbook. You may find instances of this in the components installed by `ansible-galaxy`, particularly in the `cloudalchemy.grafana` task in `dashboards.yml`. To resolve this issue, removing the `warn` line in from the yml file. +TIP: For reproducible benchmark results, configure the cluster to use the `greedy` xref:manage:cluster-maintenance/cluster-balancing.adoc#leadership-balancing-modes[leader balancer mode]: `rpk cluster config set leader_balancer_mode greedy`. This eliminates noise from non-deterministic leader placement across runs. + == Run benchmark Connect to the benchmark's client and run the benchmark with a custom workload. -=== Ensure consistent leader distribution - -For reproducible benchmark results, configure Redpanda to use the `greedy` leader balancer mode. Unlike the default `calibrated` mode, `greedy` mode pre-calculates the target leader distribution and produces deterministic results across runs, eliminating noise from non-deterministic leader placement. - -[,bash] ----- -rpk cluster config set leader_balancer_mode greedy ----- - -See xref:manage:cluster-maintenance/cluster-balancing.adoc#leadership-balancing-modes[Leadership balancing modes] for details. - . Connect with SSH to the benchmark client, with its IP address retrieved from the `client_ssh_host` output of Terraform. + [,bash] From 216f2b74921ed45ab9cfd0c17f2b5c8a21491e7a Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 7 Apr 2026 13:48:56 +0100 Subject: [PATCH 10/11] docs: Exclude greedy leader balancer mode from public docs - Remove greedy from leader_balancer_mode description (internal use only) - Remove greedy section from release notes - Remove leadership balancing modes table from cluster-balancing.adoc - Remove greedy TIP from benchmark.adoc - Add _comment field explaining exclusion Note: The accepted_values override doesn't affect the metadata table row. The property automation needs updating to support excluding enum values from the generated table. --- docs-data/property-overrides.json | 4 +++- modules/develop/pages/benchmark.adoc | 2 -- .../pages/release-notes/redpanda.adoc | 10 ---------- .../cluster-maintenance/cluster-balancing.adoc | 18 ------------------ .../redpanda-properties-v26.1.2.json | 2 +- .../properties/cluster-properties.adoc | 1 - 6 files changed, 4 insertions(+), 33 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index 6b1c7e5fb9..ff2493fc8d 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -1297,7 +1297,9 @@ "config_scope": "cluster" }, "leader_balancer_mode": { - "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior.\n* `greedy` (v26.1.2+): A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", + "_comment": "greedy mode excluded from docs - internal use only (added in v26.1.2)", + "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", + "accepted_values": ["calibrated", "random"], "config_scope": "cluster" }, "leader_balancer_mute_timeout": { diff --git a/modules/develop/pages/benchmark.adoc b/modules/develop/pages/benchmark.adoc index 5b82bb1e65..eefee70a73 100644 --- a/modules/develop/pages/benchmark.adoc +++ b/modules/develop/pages/benchmark.adoc @@ -173,8 +173,6 @@ ansible-playbook deploy.yaml --private-key= + NOTE: Beginning with Ansible 2.14, references to `args: warn` within Ansible tasks cause a fatal error and halt the execution of the playbook. You may find instances of this in the components installed by `ansible-galaxy`, particularly in the `cloudalchemy.grafana` task in `dashboards.yml`. To resolve this issue, removing the `warn` line in from the yml file. -TIP: For reproducible benchmark results, configure the cluster to use the `greedy` xref:manage:cluster-maintenance/cluster-balancing.adoc#leadership-balancing-modes[leader balancer mode]: `rpk cluster config set leader_balancer_mode greedy`. This eliminates noise from non-deterministic leader placement across runs. - == Run benchmark Connect to the benchmark's client and run the benchmark with a custom workload. diff --git a/modules/get-started/pages/release-notes/redpanda.adoc b/modules/get-started/pages/release-notes/redpanda.adoc index 4abcbf7024..f0cd9a2f78 100644 --- a/modules/get-started/pages/release-notes/redpanda.adoc +++ b/modules/get-started/pages/release-notes/redpanda.adoc @@ -63,16 +63,6 @@ To create cross-region Remote Read Replica topics, configure dynamic upstreams t See xref:manage:tiered-storage.adoc#remote-read-replicas[Remote Read Replicas] for setup instructions and configuration details. -== Greedy leader balancer mode - -Version 26.1.2 introduces a new `greedy` mode for the xref:reference:properties/cluster-properties.adoc#leader_balancer_mode[`leader_balancer_mode`] property. This topic-aware strategy pre-calculates the entire target leader distribution before making moves, ensuring each topic is independently balanced across all brokers. - -Unlike the default `calibrated` mode (which adaptively samples and prioritizes high-impact moves), `greedy` mode produces deterministic, reproducible results given the same input state. This makes it ideal for: - -* **Benchmarking**: Eliminates noise from non-deterministic leader placement across test runs -* **Predictable environments**: When you need consistent leader distribution after cluster operations - - == Automatic broker decommissioning When continuous partition balancing is enabled, Redpanda can automatically decommission brokers that remain unavailable for a configured duration. The xref:reference:properties/cluster-properties.adoc#partition_autobalancing_node_autodecommission_timeout_sec[`partition_autobalancing_node_autodecommission_timeout_sec`] property triggers permanent broker removal, unlike xref:reference:properties/cluster-properties.adoc#partition_autobalancing_node_availability_timeout_sec[`partition_autobalancing_node_availability_timeout_sec`] which only moves partitions temporarily. diff --git a/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc b/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc index 5d90412cf9..27d9daaed1 100644 --- a/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc +++ b/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc @@ -48,24 +48,6 @@ By default, Redpanda enables topic-aware leadership balancing with the xref:refe NOTE: In addition to the periodic heartbeat, leadership balancing can also occur when a xref:upgrade:rolling-upgrade.adoc#impact-of-broker-restarts[broker restarts] or when the controller leader changes (such as when a controller partition changes leader). The _controller leader_ manages the entire cluster. For example, when decommissioning a broker, the controller leader creates a reallocation plan for all partition replicas allocated to that broker. The _partition leader_ then handles the reconfiguration for its Raft group. -=== Leadership balancing modes - -The xref:reference:properties/cluster-properties.adoc#leader_balancer_mode[`leader_balancer_mode`] property controls the optimization strategy used for leadership balancing: - -[cols="1,3"] -|=== -| Mode | Description - -| `calibrated` (default) -| An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads. - -| `random` -| Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior. - -| `greedy` (v26.1.2+) -| A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state. -|=== - === Manually change leadership Despite an even distribution of leaders, sometimes the write pattern is not even across topics, and a set of traffic-heavy partitions could land on one broker and cause a latency spike. For information about metrics to monitor, see xref:manage:monitoring.adoc#partition-health[Partition health]. diff --git a/modules/reference/attachments/redpanda-properties-v26.1.2.json b/modules/reference/attachments/redpanda-properties-v26.1.2.json index 3c4c5f03fd..a0a43f57ac 100644 --- a/modules/reference/attachments/redpanda-properties-v26.1.2.json +++ b/modules/reference/attachments/redpanda-properties-v26.1.2.json @@ -8700,7 +8700,7 @@ "config_scope": "cluster", "default": "calibrated", "defined_in": "src/v/config/configuration.cc", - "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior.\n* `greedy` (v26.1.2+): A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", + "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", "enum": [ "calibrated", "random", diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index c33e1e4793..eb689ef821 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -11509,7 +11509,6 @@ Accepted values: * `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads. * `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior. -* `greedy` (v26.1.2+): A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state. Legacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`. From e2103a56c9e7358ad96111d8c81052b94a8a554d Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 7 Apr 2026 18:21:36 +0100 Subject: [PATCH 11/11] docs: Regenerate property docs with accepted_values fix Regenerated with updated tooling that respects accepted_values override. leader_balancer_mode now shows only calibrated and random options (greedy excluded per internal-only status). --- .../attachments/redpanda-properties-v26.1.2.json | 8 ++++++-- .../partials/properties/cluster-properties.adoc | 4 ++-- .../partials/properties/topic-properties.adoc | 10 +++++++++- 3 files changed, 17 insertions(+), 5 deletions(-) diff --git a/modules/reference/attachments/redpanda-properties-v26.1.2.json b/modules/reference/attachments/redpanda-properties-v26.1.2.json index a0a43f57ac..76ea8f7035 100644 --- a/modules/reference/attachments/redpanda-properties-v26.1.2.json +++ b/modules/reference/attachments/redpanda-properties-v26.1.2.json @@ -8703,8 +8703,7 @@ "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.", "enum": [ "calibrated", - "random", - "greedy" + "random" ], "example": "`model::leader_balancer_mode_to_string( model::leader_balancer_mode::calibrated)`", "is_deprecated": false, @@ -11426,6 +11425,11 @@ "default": "TopicNameStrategy", "defined_in": "src/v/kafka/server/handlers/topics/types.h", "description": "The subject name strategy for keys when `redpanda.key.schema.id.validation` is enabled. This determines how the topic and schema are mapped to a subject name in the Schema Registry.", + "enum": [ + "TopicNameStrategy", + "RecordNameStrategy", + "TopicRecordNameStrategy" + ], "is_deprecated": false, "is_enterprise": false, "is_topic_property": true, diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index eb689ef821..02dbd9e589 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -11522,10 +11522,10 @@ Legacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as | Accepted values | ifndef::env-cloud[] -`calibrated`, `random`, `greedy` +`calibrated`, `random` endif::[] ifdef::env-cloud[] -`calibrated`, `random`, `greedy` +`calibrated`, `random` endif::[] diff --git a/modules/reference/partials/properties/topic-properties.adoc b/modules/reference/partials/properties/topic-properties.adoc index 9143ceb281..80491397af 100644 --- a/modules/reference/partials/properties/topic-properties.adoc +++ b/modules/reference/partials/properties/topic-properties.adoc @@ -1241,8 +1241,16 @@ The subject name strategy for keys when `redpanda.key.schema.id.validation` is e | Property | Value | Type -| `string` +| `string` (enum) +| Accepted Values +| +ifndef::env-cloud[] +`TopicNameStrategy`, `RecordNameStrategy`, `TopicRecordNameStrategy` +endif::[] +ifdef::env-cloud[] +`TopicNameStrategy`, `RecordNameStrategy`, `TopicRecordNameStrategy` +endif::[] | Default