This is an automated email from the ASF dual-hosted git repository.
showuon pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/trunk by this push:
new 42b408703a0 MINOR: Fixed documentation on formatting new brokers
(#21981)
42b408703a0 is described below
commit 42b408703a00bb8f6f7e4892c0253e4b9fb0df07
Author: Paolo Patierno <[email protected]>
AuthorDate: Wed May 6 09:45:50 2026 +0200
MINOR: Fixed documentation on formatting new brokers (#21981)
The current documentation states that when formatting a new broker we
should use the `--no-initial-controllers` flag while looking at the code
it doesn't seem to be necessary.
I tried doing that without such a flag. The formatting works and the
broker starts up without issue. If we think about that, at storage
format time, what the tool gets is the broker config properties file and
it can't detected if we are going to use this broker for a new cluster
or an existing cluster, so I don't understand why the documentation
mentions the usage of the flag for new brokers (which is understandable
for the controller instead). Even today, with static quorum, we format
brokers without such a flag.
Even looking at the source of `StorageTool`, when the
`--no-initial-controllers` flag is missing, the check is done only
against controller. For the broker it doesn't care at all. See
https://github.com/apache/kafka/blob/trunk/core/src/main/scala/kafka/tools/StorageTool.scala#L162
This PR tries to fix the documentation and making it clearer.
Reviewers: Luke Chen <[email protected]>
---------
Signed-off-by: Paolo Patierno <[email protected]>
---
docs/operations/kraft.md | 12 ++++++++++--
1 file changed, 10 insertions(+), 2 deletions(-)
diff --git a/docs/operations/kraft.md b/docs/operations/kraft.md
index b46647505b7..86c51231cf2 100644
--- a/docs/operations/kraft.md
+++ b/docs/operations/kraft.md
@@ -142,9 +142,17 @@ bin/kafka-storage.sh format --cluster-id ${CLUSTER_ID} \
This command is similar to the standalone version but the snapshot at
00000000000000000000-0000000000.checkpoint will instead contain a VotersRecord
that includes information for all of the controllers specified in
--initial-controllers. It is important that the value of this flag is the same
in all of the controllers with the same cluster id. In the replica description
0@controller-0:1234:3Db5QLSqSZieL3rJBUUegA, 0 is the replica id,
3Db5QLSqSZieL3rJBUUegA is the replica directory id, co [...]
-### Formatting Brokers and New Controllers
+### Formatting New Brokers
-When provisioning new broker and controller nodes that we want to add to an
existing Kafka cluster, use the `kafka-storage.sh format` command with the
--no-initial-controllers flag.
+When provisioning new broker nodes that we want to add to an existing Kafka
cluster, use the `kafka-storage.sh format` command with no additional flags.
+
+```bash
+$ bin/kafka-storage.sh format --cluster-id <CLUSTER_ID> --config
config/server.properties
+```
+
+### Formatting New Controllers
+
+When provisioning new controller nodes that we want to add to an existing
Kafka cluster, use the `kafka-storage.sh format` command with the
--no-initial-controllers flag.
```bash
$ bin/kafka-storage.sh format --cluster-id <CLUSTER_ID> --config
config/server.properties --no-initial-controllers
