This is an automated email from the ASF dual-hosted git repository.
liuyu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new eec5b2aae75 [improve][doc] Optimize Admin API > Features > Brokers
(#493)
eec5b2aae75 is described below
commit eec5b2aae7543e745b9cdda74494a777b999c0d2
Author: Anonymitaet <[email protected]>
AuthorDate: Wed Mar 29 15:10:05 2023 +0800
[improve][doc] Optimize Admin API > Features > Brokers (#493)
---
docs/admin-api-brokers.md | 147 +++++++++++++++++++-----------------------
docs/reference-terminology.md | 11 +++-
sidebars.json | 10 +--
3 files changed, 78 insertions(+), 90 deletions(-)
diff --git a/docs/admin-api-brokers.md b/docs/admin-api-brokers.md
index d1edf968764..d5612fc93b6 100644
--- a/docs/admin-api-brokers.md
+++ b/docs/admin-api-brokers.md
@@ -9,37 +9,19 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
````
-
:::tip
- This page only shows **some frequently used operations**.
-
- - For the latest and complete information about `Pulsar admin`, including
commands, flags, descriptions, and more information, see [Pulsar admin
docs](pathname:///reference/#/@pulsar:version_reference@/pulsar-admin/).
-
- - For the latest and complete information about `REST API`, including
parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
-
- - For the latest and complete information about `Java admin API`, including
classes, methods, descriptions, and more, see [Java admin API doc](/api/admin/).
+This page only shows **some frequently used operations**. For the latest and
complete information, see the **reference docs** below.
:::
-Pulsar brokers consist of two components:
-
-1. An HTTP server exposing a {@inject: rest:REST:/} interface administration
and [topic](reference-terminology.md#topic) lookup.
-2. A dispatcher that handles all Pulsar
[message](reference-terminology.md#message) transfers.
-
-[Brokers](reference-terminology.md#broker) can be managed via:
-
-* The `brokers` command of the
[`pulsar-admin`](pathname:///reference/#/@pulsar:version_reference@/pulsar-admin/)
tool
-* The `/admin/v2/brokers` endpoint of the admin {@inject: rest:REST:/} API
-* The `brokers` method of the `PulsarAdmin` object in the [Java
API](client-libraries-java.md)
+Category|Method|If you want to manage brokers...
+|---|---|---
+[Pulsar CLI](reference-cli-tools.md)
|[pulsar-admin](pathname:///reference/#/@pulsar:version_origin@/pulsar-admin/),
which lists all commands, flags, descriptions, and more.| See the `broker`
command
+[Pulsar admin APIs](admin-api-overview.md)| {@inject: rest:REST API:/}, which
lists all parameters, responses, samples, and more.|See the `/admin/v2/brokers`
endpoint
+[Pulsar admin APIs](admin-api-overview.md)|[Java admin API](/api/admin/),
which lists all classes, methods, descriptions, and more.|See the `brokers`
method of the `PulsarAdmin` object
-In addition to being configurable when you start them up, brokers can also be
[dynamically configured](#dynamic-broker-configuration).
-
-For a full listing of broker-specific configuration parameters, see the
[Configuration](reference-configuration.md#broker) page.
-
-## Brokers resources
-
-### List active brokers
+## List active broker
Fetch all available active brokers that are serving traffic with cluster name.
@@ -76,9 +58,9 @@ admin.brokers().getActiveBrokers(clusterName)
</Tabs>
````
-### Get the information of the leader broker
+## List namespace owned by broker
-Fetch the information of the leader broker, for example, the service url.
+You can list all namespaces which are owned and served by a given broker.
````mdx-code-block
<Tabs groupId="api-choice"
@@ -87,39 +69,53 @@ Fetch the information of the leader broker, for example,
the service url.
<TabItem value="pulsar-admin">
```shell
-pulsar-admin brokers leader-broker
+pulsar-admin brokers namespaces use \
+ --url localhost:8080
```
Example output:
-```json
-{
- "serviceUrl" : "http://localhost:8080";
-}
+```
+public/default/0x00000000_0x40000000 [broker_assignment=shared
is_controlled=false is_active=true]
+public/default/0xc0000000_0xffffffff [broker_assignment=shared
is_controlled=false is_active=true]
+public/functions/0x40000000_0x80000000 [broker_assignment=shared
is_controlled=false is_active=true]
+public/functions/0x00000000_0x40000000 [broker_assignment=shared
is_controlled=false is_active=true]
+pulsar/standalone/localhost:8080/0x00000000_0xffffffff
[broker_assignment=shared is_controlled=false is_active=true]
+pulsar/localhost:8080/0x00000000_0xffffffff [broker_assignment=shared
is_controlled=false is_active=true]
+public/functions/0x80000000_0xc0000000 [broker_assignment=shared
is_controlled=false is_active=true]
+public/default/0x80000000_0xc0000000 [broker_assignment=shared
is_controlled=false is_active=true]
```
</TabItem>
<TabItem value="REST API">
-{@inject:
endpoint|GET|/admin/v2/brokers/leaderBroker|operation/getLeaderBroker?version=@pulsar:version_number@}
+{@inject:
endpoint|GET|/admin/v2/brokers/:cluster/:broker/ownedNamespaces|operation/getOwnedNamespaes?version=@pulsar:version_number@}
</TabItem>
<TabItem value="Java">
```java
-admin.brokers().getLeaderBroker()
+admin.brokers().getOwnedNamespaces(cluster,brokerUrl);
```
-For the detail of the code above, see
[here](https://github.com/apache/pulsar/blob/master/pulsar-client-admin/src/main/java/org/apache/pulsar/client/admin/internal/BrokersImpl.java#L80)
-
</TabItem>
</Tabs>
````
-#### list of namespaces owned by a given broker
+## Update broker conf
-It finds all namespaces which are owned and served by a given broker.
+You can update broker configurations using one of the following ways:
+
+- Supply
[configurations](pathname:///reference/#/@pulsar:version_origin@/config/reference-configuration-broker)
when starting up brokers.
+
+- [Update configurations dynamically](#update-broker-conf-dynamically) **when
running brokers**.
+
+ Since all broker configurations in Pulsar are stored in ZooKeeper,
configuration values can also be dynamically updated when brokers are running.
When you update broker configurations dynamically, ZooKeeper will notify the
broker of the change and then the broker will override any existing
configuration values.
+
+### List updatable broker conf
+
+Fetch a list of all potentially updatable configuration parameters.
````mdx-code-block
<Tabs groupId="api-choice"
@@ -128,33 +124,32 @@ It finds all namespaces which are owned and served by a
given broker.
<TabItem value="pulsar-admin">
```shell
-pulsar-admin brokers namespaces use \
- --url localhost:8080
+pulsar-admin brokers list-dynamic-config
```
Example output:
```
-public/default/0x00000000_0x40000000 [broker_assignment=shared
is_controlled=false is_active=true]
-public/default/0xc0000000_0xffffffff [broker_assignment=shared
is_controlled=false is_active=true]
-public/functions/0x40000000_0x80000000 [broker_assignment=shared
is_controlled=false is_active=true]
-public/functions/0x00000000_0x40000000 [broker_assignment=shared
is_controlled=false is_active=true]
-pulsar/standalone/localhost:8080/0x00000000_0xffffffff
[broker_assignment=shared is_controlled=false is_active=true]
-pulsar/localhost:8080/0x00000000_0xffffffff [broker_assignment=shared
is_controlled=false is_active=true]
-public/functions/0x80000000_0xc0000000 [broker_assignment=shared
is_controlled=false is_active=true]
-public/default/0x80000000_0xc0000000 [broker_assignment=shared
is_controlled=false is_active=true]
+forceDeleteNamespaceAllowed
+loadBalancerMemoryResourceWeight
+allowAutoTopicCreation
+brokerDeleteInactivePartitionedTopicMetadataEnabled
+managedLedgerInactiveLedgerRolloverTimeSeconds
+loadBalancerNamespaceBundleMaxMsgRate
+resourceUsageTransportPublishIntervalInSecs
+# omit...
```
</TabItem>
<TabItem value="REST API">
-{@inject:
endpoint|GET|/admin/v2/brokers/:cluster/:broker/ownedNamespaces|operation/getOwnedNamespaes?version=@pulsar:version_number@}
+{@inject:
endpoint|GET|/admin/v2/brokers/configuration|operation/getDynamicConfigurationName?version=@pulsar:version_number@}
</TabItem>
<TabItem value="Java">
```java
-admin.brokers().getOwnedNamespaces(cluster,brokerUrl);
+admin.brokers().getDynamicConfigurationNames();
```
</TabItem>
@@ -162,16 +157,7 @@ admin.brokers().getOwnedNamespaces(cluster,brokerUrl);
</Tabs>
````
-### Dynamic broker configuration
-
-One way to configure a Pulsar [broker](reference-terminology.md#broker) is to
supply a [configuration](reference-configuration.md#broker) when the broker is
[started up](reference-cli-tools.md).
-
-But since all broker configuration in Pulsar is stored in ZooKeeper,
configuration values can also be dynamically updated *while the broker is
running*. When you update broker configuration dynamically, ZooKeeper will
notify the broker of the change and the broker will then override any existing
configuration values.
-
-* The `brokers` command for the
[`pulsar-admin`](pathname:///reference/#/@pulsar:version_reference@/pulsar-admin/)
tool has a variety of subcommands that enable you to manipulate a broker's
configuration dynamically, enabling you to [update config
values](#update-dynamic-configuration) and more.
-* In the Pulsar admin {@inject: rest:REST:/} API, dynamic configuration is
managed through the `/admin/v2/brokers/configuration` endpoint.
-
-### Update dynamic configuration
+### Update broker conf dynamically
````mdx-code-block
<Tabs groupId="api-choice"
@@ -202,9 +188,9 @@ admin.brokers().updateDynamicConfiguration(configName,
configValue);
</Tabs>
````
-### List updated values
+### List updated broker conf
-Fetch a list of all potentially updatable configuration parameters.
+Fetch a list of all parameters that have been dynamically updated.
````mdx-code-block
<Tabs groupId="api-choice"
@@ -213,32 +199,24 @@ Fetch a list of all potentially updatable configuration
parameters.
<TabItem value="pulsar-admin">
```shell
-pulsar-admin brokers list-dynamic-config
+pulsar-admin brokers get-all-dynamic-config
```
-
Example output:
```
-forceDeleteNamespaceAllowed
-loadBalancerMemoryResourceWeight
-allowAutoTopicCreation
-brokerDeleteInactivePartitionedTopicMetadataEnabled
-managedLedgerInactiveLedgerRolloverTimeSeconds
-loadBalancerNamespaceBundleMaxMsgRate
-resourceUsageTransportPublishIntervalInSecs
-# omit...
+brokerShutdownTimeoutMs 100
```
</TabItem>
<TabItem value="REST API">
-{@inject:
endpoint|GET|/admin/v2/brokers/configuration|operation/getDynamicConfigurationName?version=@pulsar:version_number@}
+{@inject:
endpoint|GET|/admin/v2/brokers/configuration/values|operation/getAllDynamicConfigurations?version=@pulsar:version_number@}
</TabItem>
<TabItem value="Java">
```java
-admin.brokers().getDynamicConfigurationNames();
+admin.brokers().getAllDynamicConfigurations();
```
</TabItem>
@@ -246,9 +224,9 @@ admin.brokers().getDynamicConfigurationNames();
</Tabs>
````
-### List all
+## Get info of leader broker
-Fetch a list of all parameters that have been dynamically updated.
+Fetch the information of the leader broker, for example, the service URL.
````mdx-code-block
<Tabs groupId="api-choice"
@@ -257,27 +235,32 @@ Fetch a list of all parameters that have been dynamically
updated.
<TabItem value="pulsar-admin">
```shell
-pulsar-admin brokers get-all-dynamic-config
+pulsar-admin brokers leader-broker
```
+
Example output:
-```
-brokerShutdownTimeoutMs 100
+```json
+{
+ "serviceUrl" : "http://localhost:8080";
+}
```
</TabItem>
<TabItem value="REST API">
-{@inject:
endpoint|GET|/admin/v2/brokers/configuration/values|operation/getAllDynamicConfigurations?version=@pulsar:version_number@}
+{@inject:
endpoint|GET|/admin/v2/brokers/leaderBroker|operation/getLeaderBroker?version=@pulsar:version_number@}
</TabItem>
<TabItem value="Java">
```java
-admin.brokers().getAllDynamicConfigurations();
+admin.brokers().getLeaderBroker()
```
+For the detail of the code above, see
[here](https://github.com/apache/pulsar/blob/master/pulsar-client-admin/src/main/java/org/apache/pulsar/client/admin/internal/BrokersImpl.java#L80)
+
</TabItem>
</Tabs>
-````
+````
\ No newline at end of file
diff --git a/docs/reference-terminology.md b/docs/reference-terminology.md
index 077ec934e43..54b954025d3 100644
--- a/docs/reference-terminology.md
+++ b/docs/reference-terminology.md
@@ -153,9 +153,14 @@ with all the [brokers](#broker) in a [cluster](#cluster).
### Broker
-A stateless component of Pulsar [clusters](#cluster) that runs two other
components: an HTTP server
-exposing a REST interface for administration and topic lookup and a
[dispatcher](#dispatcher) that
-handles all message transfers. Pulsar clusters typically consist of multiple
brokers.
+A broker is a stateless component of Pulsar [clusters](#cluster). It consists
of two components:
+
+
+- An HTTP server exposing a REST interface for administration and topic lookup.
+
+- A [dispatcher](#dispatcher) that handles all message transfers.
+
+Pulsar clusters typically consist of multiple brokers.
### Dispatcher
diff --git a/sidebars.json b/sidebars.json
index afd3568c3bb..540537e4389 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -448,15 +448,15 @@
"id": "admin-api-features"
},
"items": [
- "admin-api-clusters",
- "admin-api-tenants",
"admin-api-brokers",
- "admin-api-namespaces",
- "admin-api-permissions",
- "admin-api-topics",
+ "admin-api-clusters",
"admin-api-functions",
+ "admin-api-namespaces",
"admin-api-packages",
+ "admin-api-permissions",
"admin-api-schemas",
+ "admin-api-tenants",
+ "admin-api-topics",
"admin-api-transactions"
]
},
