KAFKA-9863: update the deprecated --zookeeper option in the documentation into --bootstrap-server by showuon · Pull Request #8482 · apache/kafka

showuon · 2020-04-14T11:28:19Z

Since V2.2.0, the -zookeeper option turned into deprecated because Kafka can directly connect to brokers with --bootstrap-server (KIP-377). But in the official documentation, there are many example commands use --zookeeper instead of --bootstrap-server. Follow the command in the documentation, you'll get this warning, which is not good.

Warning: --zookeeper is deprecated and will be removed in a future version of Kafka.
Use --bootstrap-server instead to specify a broker to connect to.

Update configuration.html, ops.html, security.html files

Mainly update 2 commands:

before: bin/kafka-configs.sh --zookeeper localhost:2181 ...
after: bin/kafka-configs.sh --bootstrap-server localhost:9092 ...
before: bin/kafka-reassign-partitions.sh --zookeeper localhost:2181 ...
after: bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 ...

JIRA: https://issues.apache.org/jira/browse/KAFKA-9863

Committer Checklist (excluded from commit message)

Verify design and implementation
Verify test coverage and CI build status
Verify documentation (including upgrade notes)

…bootstrap-server

showuon · 2020-04-14T11:41:15Z

@joestein @rajinisivaram @hachikuji , could you help review this PR? Thank you very much.

rondagostino

Thanks for the PR! This is an excellent change. There is one other occurrences that should also be fixed. From git grep -n -- --zookeeper *.html:

docs/ops.html:97: > bin/kafka-preferred-replica-election.sh --zookeeper zk_host:port/chroot

rondagostino · 2020-04-14T14:03:03Z


  <pre class="brush: bash;">
-  &gt; bin/kafka-configs.sh --zookeeper localhost:2181 --entity-type brokers --entity-name 0 --alter --add-config
+  &gt; bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-name 0 --alter --add-config


This specific change should not be made because the paragraph above is referring specifically to configuration "before starting brokers for bootstrapping". However, since it is talking about storing sensitive information, it is likely that this would be a TLS-enabled Zookeeper quorum. So I would suggest:

Suggested change

> bin/kafka-configs.sh --zookeeper localhost:2181 --entity-type brokers --entity-name 0 --alter --add-config

> bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-name 0 --alter --add-config

> bin/kafka-configs.sh --zookeeper localhost:2182 --zk-tls-config-file zk_tls_config.properties --entity-type brokers --entity-name 0 --alter --add-config

Updated. Thanks.

rondagostino · 2020-04-14T14:32:32Z

        <p>Create SCRAM credentials for user <i>alice</i> with password <i>alice-secret</i>:
        <pre class="brush: bash;">
-    > bin/kafka-configs.sh --zookeeper localhost:2181 --alter --add-config 'SCRAM-SHA-256=[iterations=8192,password=alice-secret],SCRAM-SHA-512=[password=alice-secret]' --entity-type users --entity-name alice
+    > bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'SCRAM-SHA-256=[iterations=8192,password=alice-secret],SCRAM-SHA-512=[password=alice-secret]' --entity-type users --entity-name alice


Same thing here and the examples below: this is about bootstrapping credentials.

Suggested change

> bin/kafka-configs.sh --zookeeper localhost:2181 --alter --add-config 'SCRAM-SHA-256=[iterations=8192,password=alice-secret],SCRAM-SHA-512=[password=alice-secret]' --entity-type users --entity-name alice

> bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'SCRAM-SHA-256=[iterations=8192,password=alice-secret],SCRAM-SHA-512=[password=alice-secret]' --entity-type users --entity-name alice

> bin/kafka-configs.sh --zookeeper localhost:2182 --zk-tls-config-file zk_tls_config.properties --alter --add-config 'SCRAM-SHA-256=[iterations=8192,password=alice-secret],SCRAM-SHA-512=[password=alice-secret]' --entity-type users --entity-name alice

Updated. Thanks.

rondagostino · 2020-04-14T14:33:14Z

        <p>The following examples also require a user <i>admin</i> for inter-broker communication which can be created using:
        <pre class="brush: bash;">
-    > bin/kafka-configs.sh --zookeeper localhost:2181 --alter --add-config 'SCRAM-SHA-256=[password=admin-secret],SCRAM-SHA-512=[password=admin-secret]' --entity-type users --entity-name admin
+    > bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'SCRAM-SHA-256=[password=admin-secret],SCRAM-SHA-512=[password=admin-secret]' --entity-type users --entity-name admin


And here...

rondagostino · 2020-04-14T14:33:50Z

        <p>Existing credentials may be listed using the <i>--describe</i> option:
        <pre class="brush: bash;">
-    > bin/kafka-configs.sh --zookeeper localhost:2181 --describe --entity-type users --entity-name alice
+    > bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type users --entity-name alice


And here...

Updated. Thanks.

rondagostino · 2020-04-14T14:33:59Z

        <p>Credentials may be deleted for one or more SCRAM mechanisms using the <i>--delete</i> option:
        <pre class="brush: bash;">
-    > bin/kafka-configs.sh --zookeeper localhost:2181 --alter --delete-config 'SCRAM-SHA-512' --entity-type users --entity-name alice
+    > bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --delete-config 'SCRAM-SHA-512' --entity-type users --entity-name alice


...and here.

Updated. Thanks.

1. keep --zookeeper argument in the places that is talking about configure zk before broker up 2. use --zookeeper --zk-tls-config-file when doing some security related action, ex: update password

showuon · 2020-04-15T08:37:16Z

Hi @rondagostino , thanks for the comments.

What I've updated in bcc8155:

Yes, I missed the place in docs/ops.html:97: > bin/kafka-preferred-replica-election.sh --zookeeper zk_host:port/chroot, I updated it to > bin/kafka-preferred-replica-election.sh --bootstrap-server broker_host:port now.
Keep using --zookeeper in the place that talking about configuration before broker up.
Use secure port 2182 instead of 2181, and add --zk-tls-config-file to configure the tls connection with zookeeper when doing security-related actions.

BTW, enable the Kafka client to use TLS connection with zookeeper is a really good KIP. Thank you very much.

rondagostino

BTW, enable the Kafka client to use TLS connection with zookeeper is a really good KIP. Thank you very much.

You're welcome , @showuon -- thank you for these fixes. LGTM.

showuon · 2020-04-17T07:34:06Z

@cmccabe , could you please help review this PR?
This is a small and straightforward change to update the documentation only. And it's related to the PR that you also reviewed before #8056 , and #3848

Thank you very much.

showuon · 2020-04-22T03:36:50Z

@junrao @omkreddy , could you please help review this PR? This is a small and straightforward change to update the documentation only, but I think it's important to users. Thank you very much.

cmccabe · 2020-04-22T20:40:36Z

LGTM. Thanks, @showuon , @rondagostino

gerardq · 2020-06-30T08:20:40Z

Hi, don't know if this is the correct place but here is my issue: kafka-configs --zookeeper ... ---entity-type users can be used to manage SCRAM users stored in zookeeper. So it still needs to connect to zookeeper, not bootstrap server. Will this be supported in future releases? Whenever I run the command (using cp 5.5.0) I am getting the warning '--zookeeper is deprecated and will be removed in a future version of Kafka'. When trying the command via bootstrap-server it fails saying 'Invalid entity type users, the entity type must be one of topics,brokers,broker-loggers with the --bootstrap-server argument'.

cmccabe · 2020-06-30T17:29:51Z

@gerardq : https://cwiki.apache.org/confluence/display/KAFKA/KIP-506%3A+Allow+setting+SCRAM+password+via+Admin+interface will address this in the future.

update the deprecated --zookeeper option in the documentation into --…

392c640

…bootstrap-server

showuon changed the title ~~update the deprecated --zookeeper option in the documentation into --bootstrap-server~~ KAFKA-9863: update the deprecated --zookeeper option in the documentation into --bootstrap-server Apr 14, 2020

rondagostino reviewed Apr 14, 2020

View reviewed changes

address reviewer's comments

bcc8155

1. keep --zookeeper argument in the places that is talking about configure zk before broker up 2. use --zookeeper --zk-tls-config-file when doing some security related action, ex: update password

rondagostino reviewed Apr 15, 2020

View reviewed changes

cmccabe merged commit a91b067 into apache:trunk Apr 22, 2020

showuon deleted the KAFKA-9863 branch April 23, 2020 01:44

	> bin/kafka-configs.sh --zookeeper localhost:2181 --entity-type brokers --entity-name 0 --alter --add-config
	> bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-name 0 --alter --add-config
	> bin/kafka-configs.sh --zookeeper localhost:2182 --zk-tls-config-file zk_tls_config.properties --entity-type brokers --entity-name 0 --alter --add-config

Conversation

showuon commented Apr 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Committer Checklist (excluded from commit message)

Uh oh!

showuon commented Apr 14, 2020

Uh oh!

rondagostino left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

showuon commented Apr 15, 2020

Uh oh!

rondagostino left a comment

Choose a reason for hiding this comment

Uh oh!

showuon commented Apr 17, 2020

Uh oh!

showuon commented Apr 22, 2020

Uh oh!

cmccabe commented Apr 22, 2020

Uh oh!

gerardq commented Jun 30, 2020

Uh oh!

cmccabe commented Jun 30, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

showuon commented Apr 14, 2020 •

edited

Loading