You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by li...@apache.org on 2023/02/13 02:48:34 UTC
[pulsar-site] branch main updated: [feat][doc] add Use Cases, Features, Tools to Pulsar admin API (#403)
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 76936cd218d [feat][doc] add Use Cases, Features, Tools to Pulsar admin API (#403)
76936cd218d is described below
commit 76936cd218dbbc6ef9e9925bc645b5c49b14eb27
Author: Anonymitaet <50...@users.noreply.github.com>
AuthorDate: Mon Feb 13 10:48:30 2023 +0800
[feat][doc] add Use Cases, Features, Tools to Pulsar admin API (#403)
---
docs/admin-api-features.md | 30 ++++++++++++++++++
docs/admin-api-overview.md | 36 ++++------------------
docs/admin-api-tools.md | 34 ++++++++++++++++++++
docs/admin-api-use-cases.md | 28 +++++++++++++++++
docs/admin-get-started.md | 4 +--
sidebars.json | 3 ++
static/assets/admin-api-features.svg | 1 +
static/assets/admin-api-tools.svg | 1 +
static/assets/admin-api-use-cases.svg | 1 +
versioned_docs/version-2.11.x/admin-get-started.md | 4 +--
10 files changed, 108 insertions(+), 34 deletions(-)
diff --git a/docs/admin-api-features.md b/docs/admin-api-features.md
new file mode 100644
index 00000000000..be504d6dcd9
--- /dev/null
+++ b/docs/admin-api-features.md
@@ -0,0 +1,30 @@
+---
+id: admin-api-features
+title: Pulsar admin interfaces - Features
+sidebar_label: "Features"
+---
+
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
+
+Below are the most common tasks you may want to do. For the exhaustive lists of tasks and the method to perform these tasks, see [Tools](admin-api-tools.md).
+
+
+
+These administrative tasks are categorized based on Pulsar components.
+
+Category |Components|What do you want to do?
+|---|---|---
+Server|Broker|Operations on brokers.<br/><br/>For example, <br/>- Set dynamic configurations on brokers<br/> - Run health checks against brokers<br/> - Shutdown brokers<br/> - Get broker-level stats metrics
+Storage|Bookie|Operations on bookie placement policy. <br/><br/>For example, <br/> - Get or set bookie replacement policy
+Entities|- Topic <br/><br/> - Schema <br/><br/> - Namespace <br/><br/> - Tenant <br/><br/> - Cluster|Operations on topics, schemas, namespaces, tenants, or clusters.<br/><br/> For example, <br/> - Create, update or delete topics, tenants, namespaces, or clusters <br/> - Set isolation policies, configure offload thresholds, or set permissions for namespaces <br/> - Upload, extract, or delete schemas
+Stream processing|<br/><br/> - Function <br/><br/> - Connector <br/><br/> - Transaction <br/><br/> - Package | Operations on functions, function workers, or connectors. <br/> For example, <br/> - Create, update, and delete functions or connectors <br/> - Get stats of function workers, trigger rebalance of functions to workers <br/><br/> Operations on transactions. <br/> For example, <br/> - Get stats of transactions <br/> - Update the scale of transaction coordinators <br/><br/> Operatio [...]
+Others| - Proxy <br/><br/> - Resource groups <br/><br/> - Resource quotas | Operations on proxy stats. <br/> For example, <br/> - Get various monitoring metrics for proxy stats <br/><br/> Operations on resource groups.<br/>For example, <br/> - Create, update, and delete resource groups <br/><br/>Operations on resource quotas.<br/>For example, <br/> - Set resource quota for namespace bundles
+
+### Next steps
+
+- To perform administrative operations and check details of API references, see [Pulsar admin API - Tools](admin-api-tools.md).
+
+- To get up and running with Pulsar admin APIs quickly, see [Pulsar admin API - Get started](admin-get-started.md).
\ No newline at end of file
diff --git a/docs/admin-api-overview.md b/docs/admin-api-overview.md
index a9560ff2292..b668146a160 100644
--- a/docs/admin-api-overview.md
+++ b/docs/admin-api-overview.md
@@ -11,38 +11,14 @@ import TabItem from '@theme/TabItem';
Pulsar admin APIs enable you to administer clusters programmatically. For example, you can create, update, delete, and manage all the entities within Pulsar instances (such as clusters, namespaces, tenants, topics, schemas, connectors, functions, and so on), and set various policies for data, resources, and security.
-
+
-You can interact with the admin interface via:
+### Next steps
-- The `pulsar-admin` CLI tool, which is available in the `bin` folder of your Pulsar installation:
+- To learn usage scenarios, see [Pulsar admin API - Use cases](admin-api-use-cases.md).
- ```shell
- bin/pulsar-admin
- ```
+- To learn common administrative tasks, see [Pulsar admin API - Features](admin-api-features.md).
- :::tip
-
- For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more information, see [Pulsar admin doc](/tools/pulsar-admin/).
+- To perform administrative operations and check details of API references, see [Pulsar admin API - Tools](admin-api-tools.md).
- [Pulsar Shell](administration-pulsar-shell.md) extends `pulsar-admin` with an improved user experience for more flexibility and easier navigation between multiple clusters.
-
- :::
-
-- HTTP calls, which are made against the admin [REST API](reference-rest-api-overview.md) provided by Pulsar brokers. For some RESTful APIs, they might be redirected to the owner brokers for serving with [`307 Temporary Redirect`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307), hence the HTTP callers should handle `307 Temporary Redirect`. If you use `curl` commands, you should specify `-L` to handle redirections.
-
- :::tip
-
- For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see [REST API doc](reference-rest-api-overview.md).
-
- :::
-
-- A Java client interface.
-
- :::tip
-
- For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](https://pulsar.apache.org/api/admin/).
-
- :::
-
-> **The REST API is the admin interface**. Both the `pulsar-admin` CLI tool and the Java client use the REST API. If you implement your own admin interface client, you should use the REST API.
\ No newline at end of file
+- To get up and running with Pulsar admin APIs quickly, see [Pulsar admin API - Get started](admin-get-started.md).
\ No newline at end of file
diff --git a/docs/admin-api-tools.md b/docs/admin-api-tools.md
new file mode 100644
index 00000000000..8d4d97e36f8
--- /dev/null
+++ b/docs/admin-api-tools.md
@@ -0,0 +1,34 @@
+---
+id: admin-api-tools
+title: Pulsar admin interfaces - Tools
+sidebar_label: "Tools"
+---
+
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
+
+You can manage Pulsar entities through the Pulsar admin layer via one of the following tools:
+
+- Pulsar admin APIs
+
+ - [Java admin API](https://pulsar.apache.org/api/admin/): It’s a programmable interface written in Java.
+
+ - [REST API](https://pulsar.apache.org/admin-rest-api/?version=master): HTTP calls, which are made against the admin APIs provided by brokers. In addition, both the Java admin API and pulsar-admin CLI use the REST API.
+
+- [pulsar-admin CLI](https://pulsar.apache.org/reference/#/next/pulsar-admin/): It’s a command-line tool and is available in the bin folder of your Pulsar installation.
+
+
+
+Here are the explanations and comparisons of these tools.
+
+Category|Tools|When to use|Considerations
+|---|---|---|---
+Pulsar admin APIs|[Java admin API](https://pulsar.apache.org/api/admin/)| - If you want to implement your own admin interface client using Java and manage clusters. <br/><br/> - If you want to manage resources programmatically rather than relying on external tools inside of unit tests.<br/><br/> - If you want to use admin APIs in Java applications.| <br/><br/> - This method is only available in Java. <br/><br/> - It needs more development work if you want to use it to build applications.
+Pulsar admin APIs | [REST API](https://pulsar.apache.org/admin-rest-api/?version=master)|- If you want to implement your own admin interface client using other languages and manage clusters using scripts.| - This method is the most complicated. <br/><br/> - It needs more development work if you want to use it to build applications.
+Pulsar admin CLI| [pulsar-admin CLI](https://pulsar.apache.org/reference/#/next/pulsar-admin/) | - If you want to get started with Pulsar admin APIs with minimal effort (e.g., no need to prepare an extra environment). <br/><br/> - If you want to perform common administrative tasks.| - This method is the most easy-to-use. <br/><br/> - It’s challenging to use this method to build applications.<br/><br/> - It takes a little more time because JVM starts slowly.
+
+### Next steps
+
+- To get up and running with Pulsar admin APIs quickly, see [Pulsar admin API - Get started](admin-get-started.md).
\ No newline at end of file
diff --git a/docs/admin-api-use-cases.md b/docs/admin-api-use-cases.md
new file mode 100644
index 00000000000..ac9ed2c1572
--- /dev/null
+++ b/docs/admin-api-use-cases.md
@@ -0,0 +1,28 @@
+---
+id: admin-api-use-cases
+title: Pulsar admin interfaces - Use cases
+sidebar_label: "Use cases"
+---
+
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
+
+Pulsar admin APIs are one of the best productivity tools. You can perform various tasks with them, for example:
+
+- Administering Pulsar instances easily by creating, updating, or deleting objects with a single line of command, which increases management efficiency.
+
+- Monitoring Pulsar or troubleshooting issues by getting the status and information about Pulsar clusters, which reduces maintenance costs.
+
+- Facilitating the workflow of application development by implementing admin interface clients using your preferred languages (e.g., Go, Python, C++) based on REST APIs, which enhances developer experiences.
+
+
+
+### Next steps
+
+- To learn common administrative tasks, see [Pulsar admin API - Features](admin-api-features.md).
+
+- To perform administrative operations and check details of API references, see [Pulsar admin API - Tools](admin-api-tools.md).
+
+- To get up and running with Pulsar admin APIs quickly, see [Pulsar admin API - Get started](admin-get-started.md).
\ No newline at end of file
diff --git a/docs/admin-get-started.md b/docs/admin-get-started.md
index b0c0a8eee4e..c44139ae887 100644
--- a/docs/admin-get-started.md
+++ b/docs/admin-get-started.md
@@ -19,7 +19,7 @@ Each of the three admin interfaces (the `pulsar-admin` CLI tool, the [REST API](
values={[{"label":"pulsar-admin","value":"pulsar-admin"},{"label":"REST API","value":"REST API"},{"label":"Java","value":"Java"}]}>
<TabItem value="pulsar-admin">
-If you have enabled authentication, you need to provide an auth configuration to use the `pulsar-admin` tool. By default, the configuration for the `pulsar-admin` tool is in the [`conf/client.conf`](reference-configuration.md#client) file. The following are the available parameters:
+If you have enabled authentication, you need to provide an auth configuration to use the `pulsar-admin` tool. By default, the configuration for the `pulsar-admin` tool is in the [`conf/client.conf`](https://github.com/apache/pulsar/blob/master/conf/client.conf) file. The following are the available parameters:
|Name|Description|Default|
|----|-----------|-------|
@@ -34,7 +34,7 @@ If you have enabled authentication, you need to provide an auth configuration to
</TabItem>
<TabItem value="REST API">
-You can find details for the REST API exposed by Pulsar brokers in the [REST API doc](reference-rest-api-overview.md).
+You can find details for the REST API exposed by Pulsar brokers in the [REST API doc](https://pulsar.apache.org/admin-rest-api/?version=master).
If you want to test REST APIs in postman, you can use the REST API JSON files [here](https://pulsar.apache.org/swagger/master/).
diff --git a/sidebars.json b/sidebars.json
index 8abd37b56bc..faeedb8751b 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -333,6 +333,9 @@
"label": "Admin API",
"items": [
"admin-api-overview",
+ "admin-api-use-cases",
+ "admin-api-features",
+ "admin-api-tools",
"admin-api-get-started",
"admin-api-clusters",
"admin-api-tenants",
diff --git a/static/assets/admin-api-features.svg b/static/assets/admin-api-features.svg
new file mode 100644
index 00000000000..af485d8e13c
--- /dev/null
+++ b/static/assets/admin-api-features.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:lucid="lucid" width="878.15" height="811.33"><g transform="translate(-1465.5932274710149 -1213.6666666666667)" lucid:page-tab-id="0_0"><path d="M0 0h6299.2v6299.2H0z" fill="#fff"/><path d="M1485.6 1699a6 6 0 0 1 6-6h826.14a6 6 0 0 1 6 6v221.33a6 6 0 0 1-6 6H1491.6a6 6 0 0 1-6-6z" fill="#edf5ff"/><path d="M1502.1 1693h9.02m6 0h9.02m6 0h9.02m6 0h9.02m6 0h9.02m6 0h9.02m6 0h9.02m6 0h9.03m6 0h9.02m6 0h9m6 [...]
\ No newline at end of file
diff --git a/static/assets/admin-api-tools.svg b/static/assets/admin-api-tools.svg
new file mode 100644
index 00000000000..e43d24a9fe5
--- /dev/null
+++ b/static/assets/admin-api-tools.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:lucid="lucid" width="871.68" height="586.87"><g transform="translate(-1160.8245978592477 -896.5636510423033)" lucid:page-tab-id="0_0"><path d="M0 0h6299.2v6299.2H0z" fill="#fff"/><path d="M1296.2 1403.44h240v60h-240z" fill="none"/><use xlink:href="#a" transform="matrix(1,0,0,1,1296.195785166251,1403.4363489576963) translate(5.514702690972257 37.77007378472222)"/><use xlink:href="#b" transform="matrix [...]
\ No newline at end of file
diff --git a/static/assets/admin-api-use-cases.svg b/static/assets/admin-api-use-cases.svg
new file mode 100644
index 00000000000..834f6beb523
--- /dev/null
+++ b/static/assets/admin-api-use-cases.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:lucid="lucid" width="880" height="450.1"><g transform="translate(-1738 -1623.450476190476)" lucid:page-tab-id="0_0"><path d="M0 0h6299.2v6299.2H0z" fill="#fff"/><path d="M1758 1649.45a6 6 0 0 1 6-6h828a6 6 0 0 1 6 6v326.67a6 6 0 0 1-6 6h-828a6 6 0 0 1-6-6z" fill="#edf5ff"/><path d="M1774.54 1643.45h9.03m6.02 0h9.03m6.02 0h9.03m6.02 0h9.03m6.03 0h9.03m6 0h9.04m6.03 0h9.03m6.02 0h9.03m6.02 0h9.04m6.03 [...]
\ No newline at end of file
diff --git a/versioned_docs/version-2.11.x/admin-get-started.md b/versioned_docs/version-2.11.x/admin-get-started.md
index 0552b06045e..e8bad0ec193 100644
--- a/versioned_docs/version-2.11.x/admin-get-started.md
+++ b/versioned_docs/version-2.11.x/admin-get-started.md
@@ -19,7 +19,7 @@ Each of the three admin interfaces (the `pulsar-admin` CLI tool, the [REST API](
values={[{"label":"pulsar-admin","value":"pulsar-admin"},{"label":"REST API","value":"REST API"},{"label":"Java","value":"Java"}]}>
<TabItem value="pulsar-admin">
-If you have enabled authentication, you need to provide an auth configuration to use the `pulsar-admin` tool. By default, the configuration for the `pulsar-admin` tool is in the [`conf/client.conf`](reference-configuration.md#client) file. The following are the available parameters:
+If you have enabled authentication, you need to provide an auth configuration to use the `pulsar-admin` tool. By default, the configuration for the `pulsar-admin` tool is in the [`conf/client.conf`](https://github.com/apache/pulsar/blob/master/conf/client.conf) file. The following are the available parameters:
|Name|Description|Default|
|----|-----------|-------|
@@ -29,7 +29,7 @@ If you have enabled authentication, you need to provide an auth configuration to
|authParams|The authentication parameters for the cluster, as a comma-separated string.| |
|useTls|Whether or not TLS authentication will be enforced in the cluster.|false|
|tlsAllowInsecureConnection|Accept untrusted TLS certificate from client.|false|
-|tlsTrustCertsFilePath|Path for the trusted TLS certificate file.| |
+|tlsTrustCertsFilePath|Path for the trusted TLS certificate file.| |
</TabItem>
<TabItem value="REST API">