[Doc]--Update docs for how to delete data from namespace + reorg the …

…admin API namespace doc (apache#8760)

Fixes https://github.com/streamnative/pulsar/issues/1639



### Motivation
To specify how soon after message acknowledgement can we expect the message to be deleted - is it immediate or is there some asynchronous cleanup process.



### Modifications

1: Add "delete data from namespaces" for master release. Once the PR is approved, will sync update to previous releases.
2: Reorg the Admin API for namespace doc as some section titles are missed.

site2/docs/admin-api-namespaces.md

@@ -14,7 +14,7 @@ Namespaces can be managed via:
 
 ## Namespaces resources
 
-### Create
+### Create namespaces
 
 You can create new namespaces under a given [tenant](reference-terminology.md#tenant).
 
@@ -83,7 +83,7 @@ admin.namespaces().getPolicies(namespace);
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-### List namespaces within a tenant
+### List namespaces
 
 You can list all namespaces within a given Pulsar [tenant](reference-terminology.md#tenant).
 
@@ -109,7 +109,7 @@ admin.namespaces().getNamespaces(tenant);
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-### Delete
+### Delete namespaces
 
 You can delete existing namespaces from a tenant.
 
@@ -133,6 +133,8 @@ admin.namespaces().deleteNamespace(namespace);
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
+### Configure replication clusters
+
 #### Set replication cluster
 
 It sets replication clusters for a namespace, so Pulsar can internally replicate publish message from one colo to another colo.
@@ -186,6 +188,8 @@ admin.namespaces().getNamespaceReplicationClusters(namespace)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
+### Configure backlog quota policies
+
 #### Set backlog quota policies
 
 Backlog quota helps the broker to restrict bandwidth/storage of a namespace once it reaches a certain threshold limit. Admin can set the limit and take corresponding action after the limit is reached.
@@ -283,6 +287,8 @@ admin.namespaces().removeBacklogQuota(namespace, backlogQuotaType)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
+### Configure persistence policies
+
 #### Set persistence policies
 
 Persistence policies allow to configure persistency-level for all topic messages under a given namespace.
@@ -352,7 +358,9 @@ admin.namespaces().getPersistence(namespace)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-#### Unload namespace bundle
+### Configure namespace bundles
+
+#### Unload namespace bundles
 
 The namespace bundle is a virtual group of topics which belong to the same namespace. If the broker gets overloaded with the number of bundles, this command can help unload a bundle from that broker, so it can be served by some other less-loaded brokers. The namespace bundle ID ranges from 0x00000000 to 0xffffffff.
 
@@ -380,15 +388,16 @@ admin.namespaces().unloadNamespaceBundle(namespace, bundle)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-#### Set message-ttl
+#### Split namespace bundles
 
-It configures message’s time to live (in seconds) duration.
+Each namespace bundle can contain multiple topics and each bundle can be served by only one broker. 
+If a single bundle is creating an excessive load on a broker, an admin splits the bundle using this command permitting one or more of the new bundles to be unloaded thus spreading the load across the brokers.
 
 <!--DOCUSAURUS_CODE_TABS-->
 <!--pulsar-admin-->
 
 ```
-$ pulsar-admin namespaces set-message-ttl --messageTTL 100 test-tenant/ns1
+$ pulsar-admin namespaces split-bundle --bundle 0x00000000_0xffffffff test-tenant/ns1
 ```
 
 ```
@@ -398,53 +407,55 @@ N/A
 <!--REST API-->
 
 ```
-{@inject: endpoint|POST|/admin/v2/namespaces/{tenant}/{namespace}/messageTTL|operation/setNamespaceMessageTTL}
+{@inject: endpoint|PUT|/admin/v2/namespaces/{tenant}/{namespace}/{bundle}/split|operation/splitNamespaceBundle}
 ```
 
 <!--Java-->
 
 ```java
-admin.namespaces().setNamespaceMessageTTL(namespace, messageTTL)
+admin.namespaces().splitNamespaceBundle(namespace, bundle)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-#### Get message-ttl
+### Configure message TTL
 
-It gives a message ttl of configured namespace.
+#### Set message-ttl
+
+It configures message’s time to live (in seconds) duration.
 
 <!--DOCUSAURUS_CODE_TABS-->
 <!--pulsar-admin-->
 
 ```
-$ pulsar-admin namespaces get-message-ttl test-tenant/ns1
+$ pulsar-admin namespaces set-message-ttl --messageTTL 100 test-tenant/ns1
 ```
 
 ```
-100
+N/A
 ```
 
 <!--REST API-->
 
 ```
-{@inject: endpoint|GET|/admin/v2/namespaces/{tenant}/{namespace}/messageTTL|operation/getNamespaceMessageTTL}
+{@inject: endpoint|POST|/admin/v2/namespaces/{tenant}/{namespace}/messageTTL|operation/setNamespaceMessageTTL}
 ```
 
 <!--Java-->
 
 ```java
-admin.namespaces().getNamespaceMessageTTL(namespace)
+admin.namespaces().setNamespaceMessageTTL(namespace, messageTTL)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-#### Remove message-ttl
+#### Get message-ttl
 
-Remove a message TTL of the configured namespace.
+It gives a message ttl of configured namespace.
 
 <!--DOCUSAURUS_CODE_TABS-->
 <!--pulsar-admin-->
 
 ```
-$ pulsar-admin namespaces remove-message-ttl test-tenant/ns1
+$ pulsar-admin namespaces get-message-ttl test-tenant/ns1
 ```
 
 ```
@@ -454,46 +465,48 @@ $ pulsar-admin namespaces remove-message-ttl test-tenant/ns1
 <!--REST API-->
 
 ```
-{@inject: endpoint|DELETE|/admin/v2/namespaces/{tenant}/{namespace}/messageTTL|operation/removeNamespaceMessageTTL}
+{@inject: endpoint|GET|/admin/v2/namespaces/{tenant}/{namespace}/messageTTL|operation/getNamespaceMessageTTL}
 ```
 
 <!--Java-->
 
 ```java
-admin.namespaces().removeNamespaceMessageTTL(namespace)
+admin.namespaces().getNamespaceMessageTTL(namespace)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-#### Split bundle
+#### Remove message-ttl
 
-Each namespace bundle can contain multiple topics and each bundle can be served by only one broker. 
-If a single bundle is creating an excessive load on a broker, an admin splits the bundle using this command permitting one or more of the new bundles to be unloaded thus spreading the load across the brokers.
+Remove a message TTL of the configured namespace.
 
 <!--DOCUSAURUS_CODE_TABS-->
 <!--pulsar-admin-->
 
 ```
-$ pulsar-admin namespaces split-bundle --bundle 0x00000000_0xffffffff test-tenant/ns1
+$ pulsar-admin namespaces remove-message-ttl test-tenant/ns1
 ```
 
 ```
-N/A
+100
 ```
 
 <!--REST API-->
 
 ```
-{@inject: endpoint|PUT|/admin/v2/namespaces/{tenant}/{namespace}/{bundle}/split|operation/splitNamespaceBundle}
+{@inject: endpoint|DELETE|/admin/v2/namespaces/{tenant}/{namespace}/messageTTL|operation/removeNamespaceMessageTTL}
 ```
 
 <!--Java-->
 
 ```java
-admin.namespaces().splitNamespaceBundle(namespace, bundle)
+admin.namespaces().removeNamespaceMessageTTL(namespace)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-#### Clear backlog
+
+### Clear backlog
+
+#### Clear namespace backlog
 
 It clears all message backlog for all the topics that belong to a specific namespace. You can also clear backlog for a specific subscription as well.
 
@@ -549,6 +562,8 @@ admin.namespaces().clearNamespaceBundleBacklogForSubscription(namespace, bundle,
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
+### Configure retention
+
 #### Set retention
 
 Each namespace contains multiple topics and the retention size (storage size) of each topic should not exceed a specific threshold or it should be stored for a certain period. This command helps configure the retention size and time of topics in a given namespace.
@@ -608,7 +623,9 @@ admin.namespaces().getRetention(namespace)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-#### Set dispatch throttling
+### Configure dispatch throttling for topics
+
+#### Set dispatch throttling for topics
 
 It sets message dispatch rate for all the topics under a given namespace. 
 The dispatch rate can be restricted by the number of messages per X seconds (`msg-dispatch-rate`) or by the number of message-bytes per X second (`byte-dispatch-rate`).
@@ -645,7 +662,7 @@ admin.namespaces().setDispatchRate(namespace, new DispatchRate(1000, 1048576, 1)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-#### Get configured message-rate
+#### Get configured message-rate for topics
 
 It shows configured message-rate for the namespace (topics under this namespace can dispatch this many messages per second)
 
@@ -677,6 +694,8 @@ admin.namespaces().getDispatchRate(namespace)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
+### Configure dispatch throttling for subscription
+
 #### Set dispatch throttling for subscription
 
 It sets message dispatch rate for all the subscription of topics under a given namespace.
@@ -707,7 +726,7 @@ admin.namespaces().setSubscriptionDispatchRate(namespace, new DispatchRate(1000,
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-#### Get configured message-rate
+#### Get configured message-rate for subscription
 
 It shows configured message-rate for the namespace (topics under this namespace can dispatch this many messages per second)
 
@@ -739,6 +758,8 @@ admin.namespaces().getSubscriptionDispatchRate(namespace)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
+### Configure dispatch throttling for replicator
+
 #### Set dispatch throttling for replicator
 
 It sets message dispatch rate for all the replicator between replication clusters under a given namespace.
@@ -769,7 +790,7 @@ admin.namespaces().setReplicatorDispatchRate(namespace, new DispatchRate(1000, 1
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-#### Get configured message-rate
+#### Get configured message-rate for replicator
 
 It shows configured message-rate for the namespace (topics under this namespace can dispatch this many messages per second)
 
@@ -801,6 +822,8 @@ admin.namespaces().getReplicatorDispatchRate(namespace)
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
+### Configure deduplication snapshot interval
+
 #### Get deduplication snapshot interval
 
 It shows configured `deduplicationSnapshotInterval` for a namespace (Each topic under the namespace will take a deduplication snapshot according to this interval)
@@ -884,7 +907,7 @@ admin.namespaces().removeDeduplicationSnapshotInterval(namespace)
 
 Coming soon.
 
-### Unloading from a broker
+### Unload namespaces from a broker
 
 You can unload a namespace, or a [namespace bundle](reference-terminology.md#namespace-bundle), from the Pulsar [broker](reference-terminology.md#broker) that is currently responsible for it.
 

site2/docs/cookbooks-retention-expiry.md

@@ -335,4 +335,14 @@ $ pulsar-admin namespaces remove-message-ttl my-tenant/my-ns
 
 ```java
 admin.namespaces().removeNamespaceMessageTTL(namespace)
-```
+```
+## Delete messages from namespaces
+
+If you do not have any retention period and that you never have much of a backlog, the upper limit for retaining messages, which are acknowledged, equals to the Pulsar segment rollover period + entry log rollover period + (garbage collection interval * garbage collection ratios).
+
+- **Segment rollover period**: basically, the segment rollover period is how often a new segment is created. Once a new segment is created, the old segment will be deleted. By default, this happens either when you have written 50,000 entries (messages) or have waited 240 minutes. You can tune this in your broker.
+
+- **Entry log rollover period**: multiple ledgers in BookKeeper are interleaved into an [entry log](https://bookkeeper.apache.org/docs/4.11.1/getting-started/concepts/#entry-logs). In order for a ledger that has been deleted, the entry log must all be rolled over.
+The entry log rollover period is configurable, but is purely based on the entry log size. For details, see [here](https://bookkeeper.apache.org/docs/4.11.1/reference/config/#entry-log-settings). Once the entry log is rolled over, the entry log can be garbage collected.
+
+- **Garbage collection interval**: because entry logs have interleaved ledgers, to free up space, the entry logs need to be rewritten. The garbage collection interval is how often BookKeeper performs garbage collection. which is related to minor compaction and major compaction of entry logs. For details, see [here](https://bookkeeper.apache.org/docs/4.11.1/reference/config/#entry-log-compaction-settings).