This is an automated email from the ASF dual-hosted git repository.
chia7712 pushed a commit to branch 3.9
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/3.9 by this push:
new fb112b235c9 KAFKA-19988 change example kafka-storage command in the
migration section (#21137)
fb112b235c9 is described below
commit fb112b235c94e86b87a6f160ff9861d18880d746
Author: Gergely Harmadas <[email protected]>
AuthorDate: Sat Dec 27 16:33:39 2025 +0100
KAFKA-19988 change example kafka-storage command in the migration section
(#21137)
When preparing for the migration, there is a small chance that the
retrieved cluster id from ZooKeeper contains a leading dash. Currently
the 3.9 documentation specifies the following during the step
"Provisioning the KRaft controller quorum":
```
# Save the previously retrieved cluster ID from ZooKeeper in a variable
called zk-cluster-id
$ bin/kafka-storage.sh format --standalone -t <zk-cluster-id> -c
config/kraft/controller.properties
```
However the above command will fail with a less fortunate cluster id
like `-Yh6XyBIQ9CeAlMwJ8f7Hg`, eg.:
```
bin/kafka-storage.sh format --standalone -t -Yh6XyBIQ9CeAlMwJ8f7Hg -c
config/server.properties
25/12/12 09:24:54 INFO utils.Log4jControllerRegistration$: [main]:
Registered `kafka:type=kafka.Log4jController` MBean
usage: kafka-storage format [-h] --config CONFIG --cluster-id CLUSTER_ID
[--add-scram ADD_SCRAM] [--ignore-formatted] [--release-version
RELEASE_VERSION] [--feature FEATURE] [--standalone |
--no-initial-controllers | --initial-controllers
INITIAL_CONTROLLERS]
kafka-storage: error: argument --cluster-id/-t: expected one argument
```
A similar problem came up with KRaft which was addressed in
[KAFKA-13741](https://issues.apache.org/jira/browse/KAFKA-13741). In our
case the cluster id is already specified, there is no way to change it.
I was able to come up with a simple solution by using the full name of
the argument like `--cluster-id=<zk-cluster-id>` instead of the
shorthand `-t <zk-cluster-id>`. Full example:
```
bin/kafka-storage.sh format --cluster-id=-Yh6XyBIQ9CeAlMwJ8f7Hg -c
config/kraft/controller.properties
```
I would propose to change the documentation based on my findings so we
will be able to cover also ZooKeeper based cluster ids with a leading
dash.
Reviewers: Chia-Ping Tsai <[email protected]>
---
docs/operations/kraft.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/operations/kraft.md b/docs/operations/kraft.md
index 4ce8474cb77..a63ce05d4ed 100644
--- a/docs/operations/kraft.md
+++ b/docs/operations/kraft.md
@@ -326,7 +326,7 @@ Follow these steps to format and start a new standalone
controller:
# Save the previously retrieved cluster ID from ZooKeeper in a variable
called zk-cluster-id
- $ bin/kafka-storage.sh format --standalone -t <zk-cluster-id> -c
config/kraft/controller.properties
+ $ bin/kafka-storage.sh format --standalone --cluster-id=<zk-cluster-id> -c
config/kraft/controller.properties
$ bin/kafka-server-start.sh config/kraft/controller.properties
Note: The migration can stall if the ZooKeeper Security Migration Tool was
previously executed (see
[KAFKA-19480](https://issues.apache.org/jira/browse/KAFKA-19480) for more
details). As a workaround, the malformed "/migration" node can be removed from
ZooKeeper by running `delete /migration` with the `zookeeper-shell.sh` CLI tool.
