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|