DOC-834 Warn users to never assign broker IDs (#910)

Co-authored-by: Joyce Fee <[email protected]>
(cherry picked from commit 281c1ab)

Author: 2 people

modules/deploy/pages/deployment-option/self-hosted/manual/production/production-deployment.adoc

@@ -212,13 +212,20 @@ IMPORTANT: Redpanda expects its storage to be persistent, and it's an error
 to erase a broker's drive and restart it. However, in some environments (like when migrating to a different Node pool on Kubernetes), truly persistent storage is unavailable,
 and brokers may find their data volumes erased. For such environments, Redpanda recommends setting `empty_seed_starts_cluster` to false and designating a set of seed servers such that they couldn't lose their storage simultaneously.
 
-=== Configure broker IDs
+=== Do not configure broker IDs
 
-Redpanda automatically generates unique IDs for each new broker. This means that you don't need to include IDs in configuration files or worry about policies on `node_id` re-use.
+Redpanda automatically generates unique broker IDs for each new broker and assigns it to the xref:reference:properties/broker-properties.adoc[`node_id`] field in the broker configuration. This ensures safe and consistent cluster operations without requiring manual configuration.
 
-If you choose to assign broker IDs, make sure to use a fresh `node_id` each time you add a broker to the cluster.
+.Do not set `node_id` manually.
+[WARNING]
+====
+Redpanda assigns unique IDs automatically to prevent issues such as:
+
+- Brokers with empty disks rejoining the cluster.
+- Conflicts during recovery or scaling.
 
-CAUTION: Never reuse broker IDs, even for brokers that have been decommissioned and restarted empty. Doing so can result in an inconsistent state.
+Manually setting or reusing `node_id` values, even for decommissioned brokers, can cause cluster inconsistencies and operational failures.
+====
 
 include::deploy:partial$self-test.adoc[leveloffset=+1]
 

modules/manage/pages/cluster-maintenance/node-property-configuration.adoc

@@ -16,7 +16,7 @@ The default `redpanda.yaml` file groups broker properties into categories:
 
 The `redpanda.yaml` file rarely needs to be edited after the system is installed, but you can choose to change broker configuration property values.
 
-CAUTION: The one broker configuration property you cannot change is the unique broker identifier: `node_id`. After a broker joins the cluster, do not change the `node_id`. You can altogether omit `node_id` from `redpanda.yaml` and have Redpanda assign it automatically. For more information, see xref:deploy:deployment-option/self-hosted/manual/production/production-deployment.adoc#configure-broker-ids[Configure broker IDs].
+NOTE: The broker configuration property xref:reference:properties/broker-properties.adoc[`node_id`] is immutable. To ensure safe operations, omit the `node_id` field from `redpanda.yaml` and allow Redpanda to assign it automatically. For more information, see xref:deploy:deployment-option/self-hosted/manual/production/production-deployment.adoc#do-not-configure-broker-ids[Do not configure broker IDs].
 
 To change a broker property setting:
 

modules/reference/pages/properties/broker-properties.adoc

@@ -201,7 +201,18 @@ Threshold for log messages that contain a larger memory allocation than specifie
 
 A number that uniquely identifies the broker within the cluster. If `null` (the default value), Redpanda automatically assigns an ID. If set, it must be non-negative value.
 
-CAUTION: The `node_id` property must not be changed after a broker joins the cluster.
+.Do not set `node_id` manually.
+[WARNING]
+====
+Redpanda assigns unique IDs automatically to prevent issues such as:
+
+- Brokers with empty disks rejoining the cluster.
+- Conflicts during recovery or scaling.
+
+Manually setting or reusing `node_id` values, even for decommissioned brokers, can cause cluster inconsistencies and operational failures.
+====
+
+Broker IDs are immutable. After a broker joins the cluster, its `node_id` *cannot* be changed.
 
 
 *Accepted values:* [`0`, `4294967295`]