docs(DOC-732): document partition_autobalancing_node_autodecommission_time (#1607)

Co-authored-by: Claude Sonnet 4.6 <[email protected]>
Co-authored-by: JakeSCahill <[email protected]>
Co-authored-by: Jake Cahill <[email protected]>

Author: 3 people

modules/manage/pages/cluster-maintenance/continuous-data-balancing.adoc

@@ -2,49 +2,73 @@
 :description: Continuous Data Balancing simplifies operations with self-healing clusters that dynamically balance partitions.
 :page-aliases: cluster-administration:continuous-data-balancing.adoc
 :page-categories: Management
+:page-topic-type: how-to
+:personas: infrastructure_operator
+:learning-objective-1: Enable Continuous Data Balancing on a Redpanda cluster
+:learning-objective-2: Check data balancing status using rpk
+:learning-objective-3: Cancel partition balancing moves for a specific node
 
 [NOTE]
 ====
 include::shared:partial$enterprise-license.adoc[]
 ====
 
-Continuous Data Balancing continuously monitors your node and rack availability and disk usage. This enables self-healing clusters that dynamically balance partitions, ensuring smooth operations and optimal cluster performance.
+Continuous Data Balancing continuously monitors your node and rack availability and disk usage, dynamically balancing partitions to maintain smooth operations and optimal cluster performance.
 
-It also maintains the configured replication level, even after infrastructure failure. Node availability has the highest priority in data balancing. After a rack (with all nodes belonging to it) becomes unavailable, Redpanda moves partition replicas to the remaining nodes. This violates the rack awareness constraint. But after this rack (or a new one) becomes available, Redpanda repairs the rack awareness constraint by moving excess replicas from racks that have more than one replica to the newly-available rack.
+Continuous Data Balancing also maintains the configured replication level, even after infrastructure failure. Node availability has the highest priority in data balancing. After a rack (with all nodes belonging to it) becomes unavailable, Redpanda moves partition replicas to the remaining nodes. This violates the rack awareness constraint. After the rack (or a replacement rack) becomes available, Redpanda repairs the constraint by moving excess replicas from racks that have more than one replica to the newly-available rack.
+
+After reading this page, you will be able to:
+
+* [ ] {learning-objective-1}
+* [ ] {learning-objective-2}
+* [ ] {learning-objective-3}
 
 == Set Continuous Data Balancing properties
 
-To enable Continuous Data Balancing, set the `partition_autobalancing_mode` property to `continuous`. You can then customize properties for monitoring your node availability and disk usage.
+To enable Continuous Data Balancing, set the `partition_autobalancing_mode` property to `continuous`. Customize the following properties to monitor node availability and disk usage.
 
 |===
 | Property | Description
 
 | `partition_autobalancing_node_availability_timeout_sec`
 | When a node is unreachable for the specified amount of time, Redpanda acts as if the node had been decommissioned: rebalancing begins, re-creating all of its replicas on other nodes in the cluster. +
  +
-*Note:* The node remains part of the cluster, and it can rejoin when it comes back online. A node that was actually decommissioned is removed from the cluster. +
+The node remains part of the cluster and can rejoin when it comes back online. A node that was actually decommissioned is removed from the cluster. +
  +
 Default is 900 seconds (15 minutes).
 
+[[partition_autobalancing_node_autodecommission_timeout_sec]]
+| `partition_autobalancing_node_autodecommission_timeout_sec`
+| When a node is unavailable for this timeout duration, Redpanda automatically and permanently decommissions the node. This property only applies when `partition_autobalancing_mode` is set to `continuous`. Unlike `partition_autobalancing_node_availability_timeout_sec`, which moves partitions while keeping the node in the cluster, this property removes the node from the cluster entirely. A decommissioned node cannot rejoin the cluster. +
+ +
+Only one node is decommissioned at a time. If a decommission is already in progress, automatic decommission does not trigger until it completes. If the decommission stalls (for example, because the node holds the only replica of a partition), manual intervention is required. See xref:manage:cluster-maintenance/nodewise-partition-recovery.adoc[]. +
+ +
+By default, this property is null and automatic decommission is disabled.
+
 | `partition_autobalancing_max_disk_usage_percent`
 | When a node fills up to this disk usage percentage, Redpanda starts moving replicas off the node to other nodes with disk utilization below the percentage. +
  +
 Default is 80%.
 |===
 
-For information about other modes with `partition_autobalancing_mode`, see xref:./cluster-balancing.adoc[Cluster Balancing].
+For the other `partition_autobalancing_mode` options, see xref:manage:cluster-maintenance/cluster-balancing.adoc[Cluster balancing].
+
+== Use data balancing commands
 
-== Use Data Balancing commands
+Use the following `rpk` commands to monitor and control data balancing.
 
 === Check data balancing status
 
 To see the status, run:
 
-`rpk cluster partitions balancer-status`
+[,bash]
+----
+rpk cluster partitions balancer-status
+----
 
 This shows the time since the last data balancing, the number of replica movements in progress, the nodes that are unavailable, and the nodes that are over the disk space threshold (default = 80%).
 
-It also returns a data balancing status: `off`, `ready`, `starting`, `in-progress`, or `stalled`. If the command reports a `stalled` status, check the following:
+It also returns a data balancing status: `off`, `ready`, `starting`, `in-progress`, or `stalled`. If the command reports a `stalled` status, verify:
 
 * Are there enough healthy nodes? For example, in a three node cluster, no movements are possible for partitions with three replicas.
 * Does the cluster have sufficient space? Partitions are not moved if all nodes in the cluster are utilizing more than their disk space threshold.
@@ -55,10 +79,16 @@ It also returns a data balancing status: `off`, `ready`, `starting`, `in-progres
 
 To cancel the current partition balancing moves, run:
 
-`rpk cluster partitions movement-cancel`
+[,bash]
+----
+rpk cluster partitions movement-cancel
+----
 
-To cancel the partition moves in a specific node, add `--node`. For example:
+To cancel partition moves on a specific node, use the `--node` flag. For example:
 
-`rpk cluster partitions movement-cancel --node 1`
+[,bash]
+----
+rpk cluster partitions movement-cancel --node 1
+----
 
-NOTE: If continuous balancing hasn't been turned off, and if the system is still unbalanced, then it schedules another partition balancing. To stop all balancing, first set `partition_autobalancing_mode` to `off`. Then cancel current data balancing moves.
+NOTE: If continuous balancing is still enabled and the cluster remains unbalanced, Redpanda schedules another partition balancing round. To stop all balancing, first set `partition_autobalancing_mode` to `off`, then cancel the current data balancing moves.

modules/manage/pages/cluster-maintenance/decommission-brokers.adoc

@@ -10,6 +10,16 @@ When you decommission a broker, its partition replicas are reallocated across th
 
 CAUTION: When a broker is decommissioned, it cannot rejoin the cluster. If a broker with the same ID tries to rejoin the cluster, it is rejected.
 
+== Decommissioning methods
+
+There are two ways to decommission brokers in Redpanda:
+
+* Manual decommissioning (described in this guide): Use `rpk` commands to explicitly decommission a broker when you need full control over the timing and selection of brokers to remove.
+
+* Automatic decommissioning: When xref:manage:cluster-maintenance/continuous-data-balancing.adoc[Continuous Data Balancing] is enabled, you can configure the xref:manage:cluster-maintenance/continuous-data-balancing.adoc#partition_autobalancing_node_autodecommission_timeout_sec[partition_autobalancing_node_autodecommission_timeout_sec] property to automatically decommission brokers that remain unavailable for a specified duration.
+
+Both methods permanently remove the broker from the cluster. Decommissioned brokers cannot rejoin.
+
 == What happens when a broker is decommissioned?
 
 When a broker is decommissioned, the controller leader creates a reallocation plan for all partition replicas that are allocated to that broker. By default, this reallocation is done in batches of 50 to avoid overwhelming the remaining brokers with Raft recovery. See xref:reference:tunable-properties.adoc#partition_autobalancing_concurrent_moves[`partition_autobalancing_concurrent_moves`].

modules/manage/pages/kubernetes/k-decommission-brokers.adoc

@@ -15,6 +15,16 @@ You may want to decommission a broker in the following situations:
 
 NOTE: When a broker is decommissioned, it cannot rejoin the cluster. If a broker with the same ID tries to rejoin the cluster, it is rejected.
 
+== Decommissioning methods
+
+There are two ways to decommission brokers in Redpanda:
+
+* Manual decommissioning (described in this guide): Use `rpk` commands or Kubernetes automation to explicitly decommission a broker when you need full control over the timing and selection of brokers to remove.
+
+* Automatic decommissioning: When xref:manage:cluster-maintenance/continuous-data-balancing.adoc[Continuous Data Balancing] is enabled, you can configure the xref:manage:cluster-maintenance/continuous-data-balancing.adoc#partition_autobalancing_node_autodecommission_timeout_sec[partition_autobalancing_node_autodecommission_timeout_sec] property to automatically decommission brokers that remain unavailable for a specified duration.
+
+Both methods permanently remove the broker from the cluster. Decommissioned brokers cannot rejoin.
+
 == Prerequisites
 
 You must have the following: