[feature][doc] Add docs for system topic and update for topic policy

site2/docs/concepts-messaging.md

@@ -857,6 +857,38 @@ Producer<byte[]> producer = client.newProducer()
 
 ```
 
+## System topic
+
+System topic is a predefined topic for internal use within Pulsar. It can be either persistent or non-persistent topic.
+
+System topics serve to implement certain features and eliminate dependencies on third-party components, such as transactions, heartbeat detections, topic-level policies, and resource group services. System topics empower the implementation of these features to be simplified, dependent, and flexible. Take heartbeat detections for example, you can leverage the system topic for healthcheck to internally enable producer/reader to procude/consume messages under the heartbeat namespace, which can detect whether the current service is still alive.
+
+There are diverse system topics depending on namespaces. The following table outlines the available system topics for each specific namespace.
+
+| Namespace | TopicName | Domain | Count | Usage |
+|-----------|-----------|--------|-------|-------|
+| pulsar/system | `transaction_coordinator_assign_${id}` | Persistent | Default 16 | Transaction coordinator |
+| pulsar/system | `_transaction_log${tc_id}` | Persistent | Default 16 | Transaction log |
+| pulsar/system | `resource-usage` | Non-persistent | Default 4 | Resource group service |
+| host/port | `heartbeat` | Persistent | 1 | Heartbeat detection |
+| User-defined-ns | [`__change_events`](concepts-multi-tenancy.md#namespace-change-events-and-topic-level-policies) | Persistent | Default 4 | Topic events |
+| User-defined-ns | `__transaction_buffer_snapshot` | Persistent | One per namespace | Transaction buffer snapshots |
+| User-defined-ns | `${topicName}__transaction_pending_ack` | Persistent | One per every topic subscription acknowledged with transactions | Acknowledgements with transactions |
+
+:::note
+
+* You cannot create any system topics. To list system topics, you can add the option `--include-system-topic` when you get the topic list by using [Pulsar admin API](/tools/pulsar-admin).
+
+* Since Pulsar version 2.11.0, system topics are enabled by default.
+  In earlier versions, you need to change the following configurations in the `conf/broker.conf` or `conf/standalone.conf` file to enable system topics.
+
+  ```conf
+  systemTopicEnabled=true
+  topicLevelPoliciesEnabled=true
+  ```
+
+:::
+
 ## Message redelivery
 
 Apache Pulsar supports graceful failure handling and ensures critical data is not lost. Software will always have unexpected conditions and at times messages may not be delivered successfully. Therefore, it is important to have a built-in mechanism that handles failure, particularly in asynchronous messaging as highlighted in the following examples.

site2/docs/concepts-multi-tenancy.md

@@ -45,14 +45,16 @@ 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.
+- Avoid using ZooKeeper and introducing 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.
+Each namespace has a [system topic](concepts-messaging.md#system-topic) named `__change_events`. This system topic stores change events for a given namespace. The following figure illustrates how to leverage it to update topic-level policies.
+
+![Leverage the system topic to update topic-level policies](/assets/system-topic-for-topic-level-policies.svg)
 
-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.
+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 system topic (`__change_events`) of the namespace.
+3. Each broker that owns a namespace bundle(s) subscribes to the system topic (`__change_events`) to receive the change events of the namespace.
+4. Each broker applies the change events to its policy cache.
+5. Once the policy cache is updated, the broker sends the response back to the Pulsar Admin clients.

site2/website/versioned_docs/version-2.10.0/concepts-messaging.md

@@ -854,6 +854,38 @@ Producer<byte[]> producer = client.newProducer()
 
 ```
 
+
+## System topic
+
+System topic is a predefined topic for internal use within Pulsar. It can be either persistent or non-persistent topic.
+
+System topics serve to implement certain features and eliminate dependencies on third-party components, such as transactions, heartbeat detections, topic-level policies, and resource group services. System topics empower the implementation of these features to be simplified, dependent, and flexible. Take heartbeat detections for example, you can leverage the system topic for healthcheck to internally enable producer/reader to procude/consume messages under the heartbeat namespace, which can detect whether the current service is still alive.
+
+There are diverse system topics depending on namespaces. The following table outlines the available system topics for each specific namespace.
+
+| Namespace | TopicName | Domain | Count | Usage |
+|-----------|-----------|--------|-------|-------|
+| pulsar/system | `transaction_coordinator_assign_${id}` | Persistent | Default 16 | Transaction coordinator |
+| pulsar/system | `_transaction_log${tc_id}` | Persistent | Default 16 | Transaction log |
+| pulsar/system | `resource-usage` | Non-persistent | Default 4 | Resource group service |
+| host/port | `heartbeat` | Persistent | 1 | Heartbeat detection |
+| User-defined-ns | [`__change_events`](concepts-multi-tenancy.md#namespace-change-events-and-topic-level-policies) | Persistent | Default 4 | Topic events |
+| User-defined-ns | `__transaction_buffer_snapshot` | Persistent | One per namespace | Transaction buffer snapshots |
+| User-defined-ns | `${topicName}__transaction_pending_ack` | Persistent | One per every topic subscription acknowledged with transactions | Acknowledgements with transactions |
+
+:::note
+
+* You cannot create any system topics.
+* By default, system topics are disabled. To enable system topics, you need to change the following configurations in the `conf/broker.conf` or `conf/standalone.conf` file.
+
+  ```conf
+  systemTopicEnabled=true
+  topicLevelPoliciesEnabled=true
+  ```
+
+:::
+
+
 ## Message redelivery
 
 Apache Pulsar supports graceful failure handling and ensures critical data is not lost. Software will always have unexpected conditions and at times messages may not be delivered successfully. Therefore, it is important to have a built-in mechanism that handles failure, particularly in asynchronous messaging as highlighted in the following examples.

site2/website/versioned_docs/version-2.10.0/concepts-multi-tenancy.md

@@ -46,14 +46,22 @@ 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.
+- Avoid using ZooKeeper and introducing 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.
+Each namespace has a [system topic](concepts-messaging.md#system-topic) named `__change_events`. This system topic stores change events for a given namespace. The following figure illustrates how to leverage it to update topic-level policies.
+
+![Leverage the system topic to update topic-level policies](/assets/system-topic-for-topic-level-policies.svg)
+
+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 system topic (`__change_events`) of the namespace.
+3. Each broker that owns a namespace bundle(s) subscribes to the system topic (`__change_events`) to receive the change events of the namespace.
+4. Each broker applies the change events to its policy cache.
+5. Once the policy cache is updated, the broker sends the response back to the Pulsar Admin clients.
+
+:::note
+
+By default, the system topic is disabled. To enable topic-level policy (`topicLevelPoliciesEnabled`=`true`), you need to enable the system topic by setting `systemtopicenabled` to `true` in the `conf/broker.conf` or `conf/standalone.conf` file.
 
-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.
+:::

site2/website/versioned_docs/version-2.8.0/concepts-messaging.md

@@ -581,6 +581,38 @@ Producer<byte[]> producer = client.newProducer()
 
 ```
 
+
+## System topic
+
+System topic is a predefined topic for internal use within Pulsar. It can be either persistent or non-persistent topic.
+
+System topics serve to implement certain features and eliminate dependencies on third-party components, such as transactions, heartbeat detections, topic-level policies, and resource group services. System topics empower the implementation of these features to be simplified, dependent, and flexible. Take heartbeat detections for example, you can leverage the system topic for healthcheck to internally enable producer/reader to procude/consume messages under the heartbeat namespace, which can detect whether the current service is still alive.
+
+There are diverse system topics depending on namespaces. The following table outlines the available system topics for each specific namespace.
+
+| Namespace | TopicName | Domain | Count | Usage |
+|-----------|-----------|--------|-------|-------|
+| pulsar/system | `transaction_coordinator_assign_${id}` | Persistent | Default 16 | Transaction coordinator |
+| pulsar/system | `_transaction_log${tc_id}` | Persistent | Default 16 | Transaction log |
+| pulsar/system | `resource-usage` | Non-persistent | Default 4 | Resource group service |
+| host/port | `heartbeat` | Persistent | 1 | Heartbeat detection |
+| User-defined-ns | [`__change_events`](concepts-multi-tenancy.md#namespace-change-events-and-topic-level-policies) | Persistent | Default 4 | Topic events |
+| User-defined-ns | `__transaction_buffer_snapshot` | Persistent | One per namespace | Transaction buffer snapshots |
+| User-defined-ns | `${topicName}__transaction_pending_ack` | Persistent | One per every topic subscription acknowledged with transactions | Acknowledgements with transactions |
+
+:::note
+
+* You cannot create any system topics.
+* By default, system topics are disabled. To enable system topics, you need to change the following configurations in the `conf/broker.conf` or `conf/standalone.conf` file.
+
+  ```conf
+  systemTopicEnabled=true
+  topicLevelPoliciesEnabled=true
+  ```
+
+:::
+
+
 ## Message retention and expiry
 
 By default, Pulsar message brokers:

site2/website/versioned_docs/version-2.8.0/concepts-multi-tenancy.md

@@ -46,14 +46,22 @@ 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.
+- Avoid using ZooKeeper and introducing 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.
+Each namespace has a [system topic](concepts-messaging.md#system-topic) named `__change_events`. This system topic stores change events for a given namespace. The following figure illustrates how to leverage it to update topic-level policies.
+
+![Leverage the system topic to update topic-level policies](/assets/system-topic-for-topic-level-policies.svg)
+
+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 system topic (`__change_events`) of the namespace.
+3. Each broker that owns a namespace bundle(s) subscribes to the system topic (`__change_events`) to receive the change events of the namespace.
+4. Each broker applies the change events to its policy cache.
+5. Once the policy cache is updated, the broker sends the response back to the Pulsar Admin clients.
+
+:::note
+
+By default, the system topic is disabled. To enable topic-level policy (`topicLevelPoliciesEnabled`=`true`), you need to enable the system topic by setting `systemtopicenabled` to `true` in the `conf/broker.conf` or `conf/standalone.conf` file.
 
-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.
+:::

site2/website/versioned_docs/version-2.8.1/concepts-messaging.md

@@ -581,6 +581,38 @@ Producer<byte[]> producer = client.newProducer()
 
 ```
 
+
+## System topic
+
+System topic is a predefined topic for internal use within Pulsar. It can be either persistent or non-persistent topic.
+
+System topics serve to implement certain features and eliminate dependencies on third-party components, such as transactions, heartbeat detections, topic-level policies, and resource group services. System topics empower the implementation of these features to be simplified, dependent, and flexible. Take heartbeat detections for example, you can leverage the system topic for healthcheck to internally enable producer/reader to procude/consume messages under the heartbeat namespace, which can detect whether the current service is still alive.
+
+There are diverse system topics depending on namespaces. The following table outlines the available system topics for each specific namespace.
+
+| Namespace | TopicName | Domain | Count | Usage |
+|-----------|-----------|--------|-------|-------|
+| pulsar/system | `transaction_coordinator_assign_${id}` | Persistent | Default 16 | Transaction coordinator |
+| pulsar/system | `_transaction_log${tc_id}` | Persistent | Default 16 | Transaction log |
+| pulsar/system | `resource-usage` | Non-persistent | Default 4 | Resource group service |
+| host/port | `heartbeat` | Persistent | 1 | Heartbeat detection |
+| User-defined-ns | [`__change_events`](concepts-multi-tenancy.md#namespace-change-events-and-topic-level-policies) | Persistent | Default 4 | Topic events |
+| User-defined-ns | `__transaction_buffer_snapshot` | Persistent | One per namespace | Transaction buffer snapshots |
+| User-defined-ns | `${topicName}__transaction_pending_ack` | Persistent | One per every topic subscription acknowledged with transactions | Acknowledgements with transactions |
+
+:::note
+
+* You cannot create any system topics.
+* By default, system topics are disabled. To enable system topics, you need to change the following configurations in the `conf/broker.conf` or `conf/standalone.conf` file.
+
+  ```conf
+  systemTopicEnabled=true
+  topicLevelPoliciesEnabled=true
+  ```
+
+:::
+
+
 ## Message retention and expiry
 
 By default, Pulsar message brokers: