KAFKA-19988: change example kafka-storage command in the migration section

[harmadasg]

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. 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 chia7712@gmail.com

[harmadasg]

Currently ops.html is out of sync between kafka 3.9 and kafka-site. What I gathered is the following:

• kafka#19158 was opened to kafka 3.9 but the author was advised to instead open it directly to kafka-site since the 3.9 docs was already published
• kafka-site#667 was merged
• The newly added section was accidentally overridden in kafka-site#687 during the 3.9.1 release since it was not part of ops.html in kafka
• kafka-site#695 was merged in order to revert some 3.9 doc changes that were unexpectedly overwritten including the section about the kafka-storage tool command

All in all the section about the kafka-storage tool command is still missing from ops.html in kafka. I included in my PR since I have to modify it anyway and this way there is no chance for an accidental removal from kafka-site.

[chia7712]

@harmadasg would you mind fixing the conflicts?

[harmadasg]

@chia7712 oh I see in the meantime the markdown docs change was also applied to 3.9. fixed the conflicts