(kafka) branch trunk updated: KAFKA-18945 Enhance the docs for Admin APIs (#19315)

[chia7712]

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 <brandb...@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 <chia7...@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;