From 4473b6662764b2b3d9c7294f3d9cdb1278ab22e8 Mon Sep 17 00:00:00 2001 From: Benedikt Labrenz Date: Wed, 11 Nov 2026 17:08:39 +0100 Subject: [PATCH 1/3] fix described defaults for partitions and replication factor --- docs/modules/kafka/pages/usage-guide/topics.adoc | 4 ++-- extra/crds.yaml | 7 ++++--- rust/shared/src/crd/topic.rs | 7 ++++--- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/modules/kafka/pages/usage-guide/topics.adoc b/docs/modules/kafka/pages/usage-guide/topics.adoc index 64493345..408036d0 100644 --- a/docs/modules/kafka/pages/usage-guide/topics.adoc +++ b/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 <>. <6> What happens to the topic when the KafkaTopic is deleted, see <>. diff --git a/extra/crds.yaml b/extra/crds.yaml index d8c56add..e7d5c719 100644 --- a/extra/crds.yaml +++ b/extra/crds.yaml @@ -2339,8 +2339,8 @@ 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 @@ -2348,7 +2348,8 @@ spec: 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 diff --git a/rust/shared/src/crd/topic.rs b/rust/shared/src/crd/topic.rs index 28c22bc5..d601067c 100644 --- a/rust/shared/src/crd/topic.rs +++ b/rust/shared/src/crd/topic.rs @@ -117,14 +117,15 @@ pub mod versioned { }]))] pub topic_name: Option, - /// 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, /// 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, From cd7a308c45cd33cac9b1318b50a893457d0813f9 Mon Sep 17 00:00:00 2001 From: Benedikt Labrenz Date: Wed, 11 Nov 2026 17:11:11 +0100 Subject: [PATCH 2/3] document problems with creating topics in not fully initialized cluster --- docs/modules/kafka/pages/usage-guide/topics.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/modules/kafka/pages/usage-guide/topics.adoc b/docs/modules/kafka/pages/usage-guide/topics.adoc index 408036d0..17bb3bcd 100644 --- a/docs/modules/kafka/pages/usage-guide/topics.adoc +++ b/docs/modules/kafka/pages/usage-guide/topics.adoc @@ -64,6 +64,10 @@ 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 reaches a broker, also while the KafkaCluster is still starting. +Kafka assigns the partitions to the brokers that are registered at that time, and the agent never reassigns partitions. +Partitions of a topic created before all brokers were running 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 From 6fd1815f6a58ebee20603aacf3edfe7f0c137c97 Mon Sep 17 00:00:00 2001 From: Benedikt Richter Date: Thu, 12 Nov 2026 10:01:15 +0100 Subject: [PATCH 3/3] Apply batched suggestions from code review Co-authored-by: Sebastian Bernauer --- docs/modules/kafka/pages/usage-guide/topics.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/modules/kafka/pages/usage-guide/topics.adoc b/docs/modules/kafka/pages/usage-guide/topics.adoc index 17bb3bcd..acad28ea 100644 --- a/docs/modules/kafka/pages/usage-guide/topics.adoc +++ b/docs/modules/kafka/pages/usage-guide/topics.adoc @@ -64,9 +64,11 @@ 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 reaches a broker, also while the KafkaCluster is still starting. +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. -Partitions of a topic created before all brokers were running 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}^]. +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