Caveat about adding partitions to existing topics (#891)

Co-authored-by: Paulo Borges <[email protected]>

Author: Feediver1

modules/develop/pages/config-topics.adoc

@@ -73,6 +73,8 @@ rpk topic add-partitions [TOPICS...] --num [#]
 
 Note that `--num <#>` is the number of partitions to _add_, not the total number of partitions.
 
+include::develop:partial$balance-existing-topic-redistribution.adoc[]
+
 ifndef::env-cloud[]
 === Change the replication factor
 

modules/develop/partials/balance-existing-topic-redistribution.adoc

@@ -0,0 +1 @@
+NOTE: If a topic already has messages and you add partitions, the existing messages won’t be redistributed to the new partitions.  If you require messages to be redistributed, then you must create a new topic with the new partition count, then stream the messages from the old topic to the new topic so they are appropriately distributed according to the new partition hashing.

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

@@ -3,7 +3,7 @@
 :page-aliases: cluster-administration:cluster-balancing.adoc
 :page-categories: Management
 
-Cluster balancing is crucial for optimal performance. Unbalanced clusters can saturate resources on one or more brokers, impacting  throughput and latency. Furthermore, a cluster with replicas on a down broker risks availability loss if more brokers fail, and a cluster that keeps losing brokers without healing eventually risks data loss. Redpanda provides various topic-aware tools to balance clusters for best performance. 
+Cluster balancing is crucial for optimal performance. Unbalanced clusters can saturate resources on one or more brokers, impacting  throughput and latency. Furthermore, a cluster with replicas on a down broker risks availability loss if more brokers fail, and a cluster that keeps losing brokers without healing eventually risks data loss. Redpanda provides various topic-aware tools to balance clusters for best performance.
 
 [.no-clip]
 |===
@@ -12,32 +12,33 @@ Cluster balancing is crucial for optimal performance. Unbalanced clusters can sa
 | <<Partition leadership balancing>>
 |
 This balancer transfers the leadership of a broker's partitions to other replicas to avoid topic leadership hotspots on one or a few specific brokers in your cluster. 
-+
+
 The partition leader regularly sends heartbeats to its followers. If a follower does not receive a heartbeat within a timeout, it triggers a new leader election. Redpanda also provides leadership balancing when brokers are added or decommissioned.
 
 | <<Partition replica balancing>>
 |
 This balancer moves partition replicas to avoid topic replica hotspots on one or a few specific brokers in your cluster.
-+
+
 Redpanda prioritizes balancing a topic's partition replica count evenly across all brokers while it's balancing the cluster's overall partition count. Because different topics in a cluster can have vastly different load profiles, this better distributes the workload evenly across brokers.
-+
+
 Redpanda provides partition replica balancing when brokers are added or decommissioned.
 
 | <<Intra-broker partition balancing>>
 
 |
 This balancer moves partition replicas across CPU cores in an individual broker. Redpanda maintains balanced partition replica assignments between cores to avoid topic hotspots on one or a few specific cores within a broker.
-+
+
 Continuous Intra-Broker Partition Balancing (`core_balancing_continuous`) requires an xref:get-started:licenses.adoc#redpanda-enterprise-edition[enterprise license].
 
 | xref:manage:cluster-maintenance/continuous-data-balancing.adoc[Continuous Data Balancing]
 
 |
-This balancer monitors broker and rack availability, as well as disk usage, to avoid topic hotspots when moving data off brokers with fuller disks. Continuous Data Balancing enables self-healing clusters that dynamically balance partitions. It also ensures adherence to rack-aware replica placement policy and self-heals after rack (or availability zone) failure or replacement. This balancer does not keep the relative fullness of each broker within a defined range, it just prevents hitting the fullness threshold of each individual broker. 
-+
+This balancer monitors broker and rack availability, as well as disk usage, to avoid topic hotspots when moving data off brokers with fuller disks. Continuous Data Balancing enables self-healing clusters that dynamically balance partitions. It also ensures adherence to rack-aware replica placement policy and self-heals after rack (or availability zone) failure or replacement. This balancer does not keep the relative fullness of each broker within a defined range, it just prevents hitting the fullness threshold of each individual broker.
+
 Continuous Data Balancing requires an xref:get-started:licenses.adoc#redpanda-enterprise-edition[enterprise license].
 |===
 
+include::develop:partial$balance-existing-topic-redistribution.adoc[]
 
 == Partition leadership balancing