fix: Topic creation docs

docs/modules/kafka/pages/usage-guide/topics.adoc

@@ -36,8 +36,8 @@ spec:
 ----
 <1> The KafkaCluster in the same namespace that manages the topic. It cannot be changed.
 <2> The name of the topic in Kafka. Defaults to `metadata.name`. It cannot be changed.
-<3> The number of partitions. Defaults to the broker setting `num.partitions` when the topic is created.
-<4> The number of replicas of each partition. Defaults to the broker setting `default.replication.factor` when the topic is created.
+<3> The number of partitions. Defaults to `num.partitions` of the KRaft controllers when the topic is created.
+<4> The number of replicas of each partition. Defaults to `default.replication.factor` of the KRaft controllers when the topic is created.
 <5> The configs of the topic, see <<configs>>.
 <6> What happens to the topic when the KafkaTopic is deleted, see <<deletion>>.
 
@@ -64,6 +64,12 @@ Use `kafka-reassign-partitions.sh` or Cruise Control for this.
 
 An unsupported change is reported in the `Synced` condition, and all other changes are still applied.
 
+The agent creates a topic as soon as it is able to reach a broker.
+This could be while the KafkaCluster is still starting and only a subset of the brokers being online.
+Kafka assigns the partitions to the brokers that are registered at that time, and the agent never reassigns partitions.
+We recommend to delay creating KafkaTopics until the KafkaCluster is ready.
+However, if for some reason the topic was created earlier (with only a subset of brokers), partitions of a topic can be spread with `kafka-reassign-partitions.sh` as described in the https://kafka.apache.org/44/operations/basic-kafka-operations/#expanding-your-cluster[Kafka documentation{external-link-icon}^].
+
 [[configs]]
 === Configs
 

extra/crds.yaml

@@ -2339,16 +2339,17 @@ spec:
                 type: string
               partitions:
                 description: |-
-                  Number of partitions. Can only be increased. Defaults to the broker setting
-                  `num.partitions` when the topic is created.
+                  Number of partitions. Can only be increased. Defaults to `num.partitions` of the KRaft
+                  controllers when the topic is created.
                 format: int32
                 minimum: 1.0
                 nullable: true
                 type: integer
               replicationFactor:
                 description: |-
                   Number of replicas of each partition. Changes are not applied to existing topics.
-                  Defaults to the broker setting `default.replication.factor` when the topic is created.
+                  Defaults to `default.replication.factor` of the KRaft controllers when the topic is
+                  created.
                 format: int16
                 maximum: 32767.0
                 minimum: 1.0

rust/shared/src/crd/topic.rs

@@ -117,14 +117,15 @@ pub mod versioned {
         }]))]
         pub topic_name: Option<TopicName>,
 
-        /// Number of partitions. Can only be increased. Defaults to the broker setting
-        /// `num.partitions` when the topic is created.
+        /// Number of partitions. Can only be increased. Defaults to `num.partitions` of the KRaft
+        /// controllers when the topic is created.
         #[serde(default, skip_serializing_if = "Option::is_none")]
         #[schemars(range(min = 1))]
         pub partitions: Option<i32>,
 
         /// Number of replicas of each partition. Changes are not applied to existing topics.
-        /// Defaults to the broker setting `default.replication.factor` when the topic is created.
+        /// Defaults to `default.replication.factor` of the KRaft controllers when the topic is
+        /// created.
         #[serde(default, skip_serializing_if = "Option::is_none")]
         #[schemars(range(min = 1))]
         pub replication_factor: Option<i16>,