You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kafka.apache.org by ch...@apache.org on 2025/03/31 05:49:12 UTC
(kafka) branch trunk updated: KAFKA-18945 Enhance the docs for Admin APIs (#19315)
This is an automated email from the ASF dual-hosted git repository.
chia7712 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 c095faa5783 KAFKA-18945 Enhance the docs for Admin APIs (#19315)
c095faa5783 is described below
commit c095faa5783b3b2f37f0be590eca7a3ab9aabc99
Author: Kuan-Po Tseng <br...@gmail.com>
AuthorDate: Mon Mar 31 13:49:04 2025 +0800
KAFKA-18945 Enhance the docs for Admin APIs (#19315)
Enhance the documentation for Admin#describeCluster and
Admin#describeConfigs to clarify their behavior when using
bootstrap.controllers and bootstrap.servers.
Reviewers: Chia-Ping Tsai <ch...@gmail.com>
---
clients/src/main/java/org/apache/kafka/clients/admin/Admin.java | 6 ++++++
.../java/org/apache/kafka/clients/admin/DescribeClusterResult.java | 6 ++++--
2 files changed, 10 insertions(+), 2 deletions(-)
diff --git a/clients/src/main/java/org/apache/kafka/clients/admin/Admin.java b/clients/src/main/java/org/apache/kafka/clients/admin/Admin.java
index 9b537f79305..aa30650c6a5 100644
--- a/clients/src/main/java/org/apache/kafka/clients/admin/Admin.java
+++ b/clients/src/main/java/org/apache/kafka/clients/admin/Admin.java
@@ -345,6 +345,9 @@ public interface Admin extends AutoCloseable {
/**
* Get information about the nodes in the cluster.
+ * <p>
+ * To obtain broker cluster information, you must configure {@link AdminClientConfig#BOOTSTRAP_SERVERS_CONFIG}.
+ * To obtain controller cluster information, you must configure {@link AdminClientConfig#BOOTSTRAP_CONTROLLERS_CONFIG}.
*
* @param options The options to use when getting information about the cluster.
* @return The DescribeClusterResult.
@@ -473,6 +476,9 @@ public interface Admin extends AutoCloseable {
* <li>{@link ConfigResource.Type#CLIENT_METRICS}: will return empty configs</li>
* </ul>
* <p>
+ * Note that you cannot describe broker configs or broker logger using {@link AdminClientConfig#BOOTSTRAP_CONTROLLERS_CONFIG},
+ * and you cannot describe controller configs or controller logger using {@link AdminClientConfig#BOOTSTRAP_SERVERS_CONFIG}.
+ * <p>
* This operation is supported by brokers with version 0.11.0.0 or higher.
*
* @param resources See relevant type {@link ConfigResource.Type}
diff --git a/clients/src/main/java/org/apache/kafka/clients/admin/DescribeClusterResult.java b/clients/src/main/java/org/apache/kafka/clients/admin/DescribeClusterResult.java
index 3113608a007..3a4c40cad08 100644
--- a/clients/src/main/java/org/apache/kafka/clients/admin/DescribeClusterResult.java
+++ b/clients/src/main/java/org/apache/kafka/clients/admin/DescribeClusterResult.java
@@ -51,8 +51,10 @@ public class DescribeClusterResult {
}
/**
- * Returns a future which yields the current controller id.
- * Note that this may yield null, if the controller ID is not yet known.
+ * Returns a future which yields the current controller node.
+ * <p>
+ * When using {@link AdminClientConfig#BOOTSTRAP_SERVERS_CONFIG}, the controller refer to a random broker.
+ * When using {@link AdminClientConfig#BOOTSTRAP_CONTROLLERS_CONFIG}, it refers to the current voter leader.
*/
public KafkaFuture<Node> controller() {
return controller;