From fd2319fdd0d784d6d51026a33522aee446454f2f Mon Sep 17 00:00:00 2001
From: HuanliMeng <48120384+Huanli-Meng@users.noreply.github.com>
Date: Tue, 15 Sep 2020 10:48:27 +0800
Subject: [PATCH] [Doc]--Update Pulsar Admin CLI doc to support to
 set/get/remove persistence polices, message TTL, and backlog quota on topic
 level (#7852)

Motivation
In PRs, #7738, #7646, #7817, persistence polices, message TTL, and backlog quota policies are supported on topic level. The PR for code modification is updated and merged. but the doc is not updated accordingly.

This PR is used to support to set/get/remove persistence polices, message TTL, and backlog quota on topic level.

Modifications
Update the Pulsar Admin CLI doc to support to set/get/remove persistence polices, message TTL, and backlog quota on topic level.

* Update backlog-quota policies on topic level

* update contents

* update contents
---
 site2/docs/concepts-multi-tenancy.md | 15 +++++
 site2/docs/reference-pulsar-admin.md | 95 ++++++++++++++++++++++++++++
 2 files changed, 110 insertions(+)

diff --git a/site2/docs/concepts-multi-tenancy.md b/site2/docs/concepts-multi-tenancy.md
index b26799cff422e..06d724ceb6741 100644
--- a/site2/docs/concepts-multi-tenancy.md
+++ b/site2/docs/concepts-multi-tenancy.md
@@ -37,3 +37,18 @@ persistent://tenant/app1/topic-2
 
 persistent://tenant/app1/topic-3
 ```
+
+### Namespace change events and topic-level policies
+
+Pulsar is a multi-tenant event streaming system. Administrators can manage the tenants and namespaces by setting policies at different levels. However, the policies, such as retention policy and storage quota policy, are only available at a namespace level. In many use cases, users need to set a policy at the topic level. The namespace change events approach is proposed for supporting topic-level policies in an efficient way. In this approach, Pulsar is used as an event log to store namespace change events (such as topic policy changes). This approach has a few benefits:
+
+- Avoid using ZooKeeper and introduce more loads to ZooKeeper.
+- Use Pulsar as an event log for propagating the policy cache. It can scale efficiently.
+- Use Pulsar SQL to query the namespace changes and audit the system.
+
+Each namespace has a system topic `__change_events`. This system topic is used for storing change events for a given namespace. The following figure illustrates how to use namespace change events to implement a topic-level policy.
+
+1. Pulsar Admin clients communicate with the Admin Restful API to update topic level policies.
+2. Any broker that receives the Admin HTTP request publishes a topic policy change event to the corresponding `__change_events` topic of the namespace.
+3. Each broker that owns a namespace bundle(s) subscribes to the `__change_events` topic to receive change events of the namespace. It then applies the change events to the policy cache.
+4. Once the policy cache is updated, the broker sends the response back to the Pulsar Admin clients.
diff --git a/site2/docs/reference-pulsar-admin.md b/site2/docs/reference-pulsar-admin.md
index 9c583d5daae78..be4d946d3e872 100644
--- a/site2/docs/reference-pulsar-admin.md
+++ b/site2/docs/reference-pulsar-admin.md
@@ -1787,6 +1787,15 @@ Subcommands
 * `reset-cursor`
 * `get-message-by-id`
 * `last-message-id`
+* `get-backlog-quotas`
+* `set-backlog-quota`
+* `remove-backlog-quota`
+* `get-persistence`
+* `set-persistence`
+* `remove-persistence`
+* `get-message-ttl`
+* `set-message-ttl`
+* `remove-message-ttl`
 * `get-deduplication`
 * `set-deduplication`
 * `remove-deduplication`
@@ -2205,6 +2214,21 @@ Options
 |`-l`, `--ledgerId`|The ledger id |0|
 |`-e`, `--entryId`|The entry id |0|
 
+### `get-backlog-quotas`
+Get the backlog quota policies for a topic.
+
+Usage
+```bash
+$ pulsar-admin topics get-backlog-quotas tenant/namespace/topic
+```
+
+### `set-backlog-quota`
+Set a backlog quota policy for a topic.
+
+Usage
+```bash
+$ pulsar-admin topics set-backlog-quota tenant/namespace/topic options
+=======
 ### `get-deduplication`
 Get a deduplication policy for a topic.
 
@@ -2223,6 +2247,77 @@ $ pulsar-admin topics set-deduplication tenant/namespace/topic
 
 Options
 |Flag|Description|Default|
+|----|---|---|
+|`-l`, `--limit`|Size limit (eg: 10M, 16G)", required = true)||
+|`-p`, `--policy`|Retention policy to enforce when the limit is reached. The valid options are: `producer_request_hold`, `producer_exception` or `consumer_backlog_eviction`|
+
+### `remove-backlog-quota`
+Remove a backlog quota policy from a topic.
+
+Usage
+```bash
+$ pulsar-admin topics remove-backlog-quota tenant/namespace/topic
+```
+
+### `get-persistence`
+Get the persistence policies for a topic.
+
+Usage
+```bash
+$ pulsar-admin topics get-persistence tenant/namespace/topic
+```
+
+### `set-persistence`
+Set the persistence policies for a topic.
+
+Usage
+```bash
+$ pulsar-admin topics set-persistence tenant/namespace/topic options
+```
+
+Options
+|Flag|Description|Default|
+|----|---|---|
+|`-e`, `--bookkeeper-ensemble`|Number of bookies to use for a topic|0|
+|`-w`, `--bookkeeper-write-quorum`|How many writes to make of each entry|0|
+|`-a`, `--bookkeeper-ack-quorum`|Number of acks (garanteed copies) to wait for each entry|0|
+|`-r`, `--ml-mark-delete-max-rate`|Throttling rate of mark-delete operation (0 means no throttle)||
+
+### `remove-persistence`
+Remove the persistence policy for a topic.
+
+Usage
+```bash
+$ pulsar-admin topics remove-persistence tenant/namespace/topic
+```
+### `get-message-ttl`
+Get the message TTL for a topic.
+
+Usage
+```bash
+$ pulsar-admin topics get-message-ttl tenant/namespace/topic
+```
+
+### `set-message-ttl`
+Set the message TTL for a topic.
+
+Usage
+```bash
+$ pulsar-admin topics set-message-ttl tenant/namespace/topic options
+```
+
+Options
+|Flag|Description|Default|
+|----|---|---|
+|`-ttl`, `--messageTTL`|Message TTL for a topic in second, allowed range from 1 to `Integer.MAX_VALUE` |0|
+
+### `remove-message-ttl`
+Remove the message TTL for a topic.
+
+Usage
+```bash
+$ pulsar-admin topics remove-message-ttl tenant/namespace/topic
+=======
 |---|---|---|
 |`--enable`, `-e`|Enable message deduplication on the specified topic.|false|
 |`--disable`, `-d`|Disable message deduplication on the specified topic.|false|