This is an automated email from the ASF dual-hosted git repository.
zhaijia pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new 96258f8 [Issue 5924] [Doc]--Update geo-replication doc. (#7227)
96258f8 is described below
commit 96258f818cd9cf14777cad1d9ee6993cfc2b6860
Author: HuanliMeng <[email protected]>
AuthorDate: Tue Jun 16 10:23:23 2020 +0800
[Issue 5924] [Doc]--Update geo-replication doc. (#7227)
Fixes #5924
### Motivation
Since PIP-33, we can configure a subscription to be replicated. hence it
supports both local subscription and replicated subscription.
These updates are based on updates for the master, which have been approved
and merged.
The following releases are updated: releases 2.5.2--2.4.0
### Modifications
For releases 2.5.2--2.5.0:
Update the administration > geo-replication: remove the remove the original
note, which emphasize supporting local subscription only.
For releases 2.4.2--2.4.0:
Update the administration > geo-replication: remove the remove the original
note, which emphasize supporting local subscription only.
Update the administration > geo-replication: add the replicated
subscriptions and its sub sections, which are available for releases 2.5.0 and
later releases.
---
.../administration-geo.md | 61 ++++++++++-----------
.../administration-geo.md | 63 +++++++++++----------
.../administration-geo.md | 64 +++++++++++-----------
.../version-2.5.0/administration-geo.md | 3 +-
.../administration-geo.md | 5 +-
.../administration-geo.md | 5 +-
6 files changed, 97 insertions(+), 104 deletions(-)
diff --git a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
b/site2/website/versioned_docs/version-2.4.0/administration-geo.md
similarity index 60%
copy from site2/website/versioned_docs/version-2.5.0/administration-geo.md
copy to site2/website/versioned_docs/version-2.4.0/administration-geo.md
index e467141..8fd7d80 100644
--- a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
+++ b/site2/website/versioned_docs/version-2.4.0/administration-geo.md
@@ -1,5 +1,5 @@
---
-id: version-2.5.0-administration-geo
+id: version-2.4.0-administration-geo
title: Pulsar geo-replication
sidebar_label: Geo-replication
original_id: administration-geo
@@ -7,51 +7,50 @@ original_id: administration-geo
*Geo-replication* is the replication of persistently stored message data
across multiple clusters of a Pulsar instance.
-## How geo-replication works
+## How it works
The diagram below illustrates the process of geo-replication across Pulsar
clusters:
-In this diagram, whenever **P1**, **P2**, and **P3** producers publish
messages to the **T1** topic on **Cluster-A**, **Cluster-B**, and **Cluster-C**
clusters respectively, those messages are instantly replicated across clusters.
Once the messages are replicated, **C1** and **C2** consumers can consume those
messages from their respective clusters.
+In this diagram, whenever **P1**, **P2**, and **P3** producers publish
messages to the **T1** topic on **Cluster-A**, **Cluster-B**, and **Cluster-C**
clusters respectively, those messages are instantly replicated across clusters.
Once replicated, **C1** and **C2** consumers can consume those messages from
their respective clusters.
-Without geo-replication, **C1** and **C2** consumers are not able to consume
messages that **P3** producer publishes.
+Without geo-replication, **C1** and **C2** consumers are not able to consume
messages published by **P3** producer.
## Geo-replication and Pulsar properties
-You must enable geo-replication on a per-tenant basis in Pulsar. You can
enable geo-replication between clusters only when a tenant is created that
allows access to both clusters.
+Geo-replication must be enabled on a per-tenant basis in Pulsar.
Geo-replication can be enabled between clusters only when a tenant has been
created that allows access to both clusters.
-Although geo-replication must be enabled between two clusters, actually
geo-replication is managed at the namespace level. You must complete the
following tasks to enable geo-replication for a namespace:
+Although geo-replication must be enabled between two clusters, it's actually
managed at the namespace level. You must complete the following tasks to enable
geo-replication for a namespace:
-* [Enable geo-replication namespaces](#enable-geo-replication-namespaces)
+* [Enable geo-replication namespaces](#enabling-geo-replication-namespaces)
* Configure that namespace to replicate across two or more provisioned clusters
-Any message published on *any* topic in that namespace is replicated to all
clusters in the specified set.
+Any message published on *any* topic in that namespace will be replicated to
all clusters in the specified set.
## Local persistence and forwarding
-When messages are produced on a Pulsar topic, messages are first persisted in
the local cluster, and then forwarded asynchronously to the remote clusters.
+When messages are produced on a Pulsar topic, they are first persisted in the
local cluster, and then forwarded asynchronously to the remote clusters.
-In normal cases, when connectivity issues are none, messages are replicated
immediately, at the same time as they are dispatched to local consumers.
Typically, the network [round-trip
time](https://en.wikipedia.org/wiki/Round-trip_delay_time) (RTT) between the
remote regions defines end-to-end delivery latency.
+In normal cases, when there are no connectivity issues, messages are
replicated immediately, at the same time as they are dispatched to local
consumers. Typically, end-to-end delivery latency is defined by the network
[round-trip time](https://en.wikipedia.org/wiki/Round-trip_delay_time) (RTT)
between the remote regions.
Applications can create producers and consumers in any of the clusters, even
when the remote clusters are not reachable (like during a network partition).
-> #### Subscriptions are local to a cluster
-> While producers and consumers can publish to and consume from any cluster in
a Pulsar instance, subscriptions are local to the clusters in which the
subscriptions are created and cannot be transferred between clusters. If you do
need to transfer a subscription, you need to create a new subscription in the
desired cluster.
+Producers and consumers can publish messages to and consume messages from any
cluster in a Pulsar instance. However, subscriptions cannot only be local to
the cluster where the subscriptions are created but also can be transferred
between clusters after replicated subscription is enabled. Once replicated
subscription is enabled, you can keep subscription state in synchronization.
Therefore, a topic can be asynchronously replicated across multiple
geographical regions. In case of failover [...]
-In the aforementioned example, the **T1** topic is replicated among three
clusters, **Cluster-A**, **Cluster-B**, and **Cluster-C**.
+In the aforementioned example, the **T1** topic is being replicated among
three clusters, **Cluster-A**, **Cluster-B**, and **Cluster-C**.
-All messages produced in any of the three clusters are delivered to all
subscriptions in other clusters. In this case, **C1** and **C2** consumers
receive all messages that **P1**, **P2**, and **P3** producers publish.
Ordering is still guaranteed on a per-producer basis.
+All messages produced in any of the three clusters are delivered to all
subscriptions in other clusters. In this case, **C1** and **C2** consumers will
receive all messages published by **P1**, **P2**, and **P3** producers.
Ordering is still guaranteed on a per-producer basis.
-## Configure replication
+## Configuring replication
As stated in [Geo-replication and Pulsar
properties](#geo-replication-and-pulsar-properties) section, geo-replication in
Pulsar is managed at the [tenant](reference-terminology.md#tenant) level.
-### Grant permissions to properties
+### Granting permissions to properties
-To replicate to a cluster, the tenant needs permission to use that cluster.
You can grant permission to the tenant when you create the tenant or grant
later.
+To replicate to a cluster, the tenant needs permission to use that cluster.
You can grant permission to the tenant when you create it or grant later.
-Specify all the intended clusters when you create a tenant:
+Specify all the intended clusters when creating a tenant:
```shell
$ bin/pulsar-admin tenants create my-tenant \
@@ -61,7 +60,7 @@ $ bin/pulsar-admin tenants create my-tenant \
To update permissions of an existing tenant, use `update` instead of `create`.
-### Enable geo-replication namespaces
+### Enabling geo-replication namespaces
You can create a namespace with the following command sample.
@@ -76,17 +75,17 @@ $ bin/pulsar-admin namespaces set-clusters
my-tenant/my-namespace \
--clusters us-west,us-east,us-cent
```
-You can change the replication clusters for a namespace at any time, without
disruption to ongoing traffic. Replication channels are immediately set up or
stopped in all clusters as soon as the configuration changes.
+The replication clusters for a namespace can be changed at any time, without
disruption to ongoing traffic. Replication channels are immediately set up or
stopped in all clusters as soon as the configuration changes.
-### Use topics with geo-replication
+### Using topics with geo-replication
-Once you create a geo-replication namespace, any topics that producers or
consumers create within that namespace is replicated across clusters.
Typically, each application uses the `serviceUrl` for the local cluster.
+Once you've created a geo-replication namespace, any topics that producers or
consumers create within that namespace will be replicated across clusters.
Typically, each application will use the `serviceUrl` for the local cluster.
#### Selective replication
-By default, messages are replicated to all clusters configured for the
namespace. You can restrict replication selectively by specifying a replication
list for a message, and then that message is replicated only to the subset in
the replication list.
+By default, messages are replicated to all clusters configured for the
namespace. You can restrict replication selectively by specifying a replication
list for a message, and then that message will be replicated only to the subset
in the replication list.
-The following is an example for the [Java API](client-libraries-java.md). Note
the use of the `setReplicationClusters` method when you construct the {@inject:
javadoc:Message:/client/org/apache/pulsar/client/api/Message} object:
+The following is an example for the [Java API](client-libraries-java.md). Note
the use of the `setReplicationClusters` method when constructing the {@inject:
javadoc:Message:/client/org/apache/pulsar/client/api/Message} object:
```java
List<String> restrictReplicationTo = Arrays.asList(
@@ -114,15 +113,15 @@ $ bin/pulsar-admin persistent stats
persistent://my-tenant/my-namespace/my-topic
Each cluster reports its own local stats, including the incoming and outgoing
replication rates and backlogs.
-#### Delete a geo-replication topic
+#### Deleting a geo-replication topic
-Given that geo-replication topics exist in multiple regions, directly deleting
a geo-replication topic is not possible. Instead, you should rely on automatic
topic garbage collection.
+Given that geo-replication topics exist in multiple regions, it's not possible
to directly delete a geo-replication topic. Instead, you should rely on
automatic topic garbage collection.
-In Pulsar, a topic is automatically deleted when the topic meets the following
three conditions:
-- no producers or consumers are connected to it;
-- no subscriptions to it;
+In Pulsar, a topic is automatically deleted when it meets the following three
conditions:
+- when no producers or consumers are connected to it;
+- there are no subscriptions to it;
- no more messages are kept for retention.
-For geo-replication topics, each region uses a fault-tolerant mechanism to
decide when deleting the topic locally is safe.
+For geo-replication topics, each region uses a fault-tolerant mechanism to
decide when it's safe to delete the topic locally.
You can explicitly disable topic garbage collection by setting
`brokerDeleteInactiveTopicsEnabled` to `false` in your [broker
configuration](reference-configuration.md#broker).
@@ -134,7 +133,7 @@ Pulsar supports replicated subscriptions, so you can keep
subscription state in
In case of failover, a consumer can restart consuming from the failure point
in a different cluster.
-### Enable replicated subscription
+### Enabling replicated subscription
Replicated subscription is disabled by default. You can enable replicated
subscription when creating a consumer.
diff --git a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
b/site2/website/versioned_docs/version-2.4.1/administration-geo.md
similarity index 60%
copy from site2/website/versioned_docs/version-2.5.0/administration-geo.md
copy to site2/website/versioned_docs/version-2.4.1/administration-geo.md
index e467141..2fe64b5 100644
--- a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
+++ b/site2/website/versioned_docs/version-2.4.1/administration-geo.md
@@ -1,5 +1,5 @@
---
-id: version-2.5.0-administration-geo
+id: version-2.4.1-administration-geo
title: Pulsar geo-replication
sidebar_label: Geo-replication
original_id: administration-geo
@@ -7,51 +7,50 @@ original_id: administration-geo
*Geo-replication* is the replication of persistently stored message data
across multiple clusters of a Pulsar instance.
-## How geo-replication works
+## How it works
The diagram below illustrates the process of geo-replication across Pulsar
clusters:
-In this diagram, whenever **P1**, **P2**, and **P3** producers publish
messages to the **T1** topic on **Cluster-A**, **Cluster-B**, and **Cluster-C**
clusters respectively, those messages are instantly replicated across clusters.
Once the messages are replicated, **C1** and **C2** consumers can consume those
messages from their respective clusters.
+In this diagram, whenever **P1**, **P2**, and **P3** producers publish
messages to the **T1** topic on **Cluster-A**, **Cluster-B**, and **Cluster-C**
clusters respectively, those messages are instantly replicated across clusters.
Once replicated, **C1** and **C2** consumers can consume those messages from
their respective clusters.
-Without geo-replication, **C1** and **C2** consumers are not able to consume
messages that **P3** producer publishes.
+Without geo-replication, **C1** and **C2** consumers are not able to consume
messages published by **P3** producer.
## Geo-replication and Pulsar properties
-You must enable geo-replication on a per-tenant basis in Pulsar. You can
enable geo-replication between clusters only when a tenant is created that
allows access to both clusters.
+Geo-replication must be enabled on a per-tenant basis in Pulsar.
Geo-replication can be enabled between clusters only when a tenant has been
created that allows access to both clusters.
-Although geo-replication must be enabled between two clusters, actually
geo-replication is managed at the namespace level. You must complete the
following tasks to enable geo-replication for a namespace:
+Although geo-replication must be enabled between two clusters, it's actually
managed at the namespace level. You must complete the following tasks to enable
geo-replication for a namespace:
-* [Enable geo-replication namespaces](#enable-geo-replication-namespaces)
+* [Enable geo-replication namespaces](#enabling-geo-replication-namespaces)
* Configure that namespace to replicate across two or more provisioned clusters
-Any message published on *any* topic in that namespace is replicated to all
clusters in the specified set.
+Any message published on *any* topic in that namespace will be replicated to
all clusters in the specified set.
## Local persistence and forwarding
-When messages are produced on a Pulsar topic, messages are first persisted in
the local cluster, and then forwarded asynchronously to the remote clusters.
+When messages are produced on a Pulsar topic, they are first persisted in the
local cluster, and then forwarded asynchronously to the remote clusters.
-In normal cases, when connectivity issues are none, messages are replicated
immediately, at the same time as they are dispatched to local consumers.
Typically, the network [round-trip
time](https://en.wikipedia.org/wiki/Round-trip_delay_time) (RTT) between the
remote regions defines end-to-end delivery latency.
+In normal cases, when there are no connectivity issues, messages are
replicated immediately, at the same time as they are dispatched to local
consumers. Typically, end-to-end delivery latency is defined by the network
[round-trip time](https://en.wikipedia.org/wiki/Round-trip_delay_time) (RTT)
between the remote regions.
Applications can create producers and consumers in any of the clusters, even
when the remote clusters are not reachable (like during a network partition).
-> #### Subscriptions are local to a cluster
-> While producers and consumers can publish to and consume from any cluster in
a Pulsar instance, subscriptions are local to the clusters in which the
subscriptions are created and cannot be transferred between clusters. If you do
need to transfer a subscription, you need to create a new subscription in the
desired cluster.
+Producers and consumers can publish messages to and consume messages from any
cluster in a Pulsar instance. However, subscriptions cannot only be local to
the cluster where the subscriptions are created but also can be transferred
between clusters after replicated subscription is enabled. Once replicated
subscription is enabled, you can keep subscription state in synchronization.
Therefore, a topic can be asynchronously replicated across multiple
geographical regions. In case of failover [...]
-In the aforementioned example, the **T1** topic is replicated among three
clusters, **Cluster-A**, **Cluster-B**, and **Cluster-C**.
+In the aforementioned example, the **T1** topic is being replicated among
three clusters, **Cluster-A**, **Cluster-B**, and **Cluster-C**.
-All messages produced in any of the three clusters are delivered to all
subscriptions in other clusters. In this case, **C1** and **C2** consumers
receive all messages that **P1**, **P2**, and **P3** producers publish.
Ordering is still guaranteed on a per-producer basis.
+All messages produced in any of the three clusters are delivered to all
subscriptions in other clusters. In this case, **C1** and **C2** consumers will
receive all messages published by **P1**, **P2**, and **P3** producers.
Ordering is still guaranteed on a per-producer basis.
-## Configure replication
+## Configuring replication
As stated in [Geo-replication and Pulsar
properties](#geo-replication-and-pulsar-properties) section, geo-replication in
Pulsar is managed at the [tenant](reference-terminology.md#tenant) level.
-### Grant permissions to properties
+### Granting permissions to properties
-To replicate to a cluster, the tenant needs permission to use that cluster.
You can grant permission to the tenant when you create the tenant or grant
later.
+To replicate to a cluster, the tenant needs permission to use that cluster.
You can grant permission to the tenant when you create it or grant later.
-Specify all the intended clusters when you create a tenant:
+Specify all the intended clusters when creating a tenant:
```shell
$ bin/pulsar-admin tenants create my-tenant \
@@ -61,7 +60,7 @@ $ bin/pulsar-admin tenants create my-tenant \
To update permissions of an existing tenant, use `update` instead of `create`.
-### Enable geo-replication namespaces
+### Enabling geo-replication namespaces
You can create a namespace with the following command sample.
@@ -76,17 +75,17 @@ $ bin/pulsar-admin namespaces set-clusters
my-tenant/my-namespace \
--clusters us-west,us-east,us-cent
```
-You can change the replication clusters for a namespace at any time, without
disruption to ongoing traffic. Replication channels are immediately set up or
stopped in all clusters as soon as the configuration changes.
+The replication clusters for a namespace can be changed at any time, without
disruption to ongoing traffic. Replication channels are immediately set up or
stopped in all clusters as soon as the configuration changes.
-### Use topics with geo-replication
+### Using topics with geo-replication
-Once you create a geo-replication namespace, any topics that producers or
consumers create within that namespace is replicated across clusters.
Typically, each application uses the `serviceUrl` for the local cluster.
+Once you've created a geo-replication namespace, any topics that producers or
consumers create within that namespace will be replicated across clusters.
Typically, each application will use the `serviceUrl` for the local cluster.
#### Selective replication
-By default, messages are replicated to all clusters configured for the
namespace. You can restrict replication selectively by specifying a replication
list for a message, and then that message is replicated only to the subset in
the replication list.
+By default, messages are replicated to all clusters configured for the
namespace. You can restrict replication selectively by specifying a replication
list for a message, and then that message will be replicated only to the subset
in the replication list.
-The following is an example for the [Java API](client-libraries-java.md). Note
the use of the `setReplicationClusters` method when you construct the {@inject:
javadoc:Message:/client/org/apache/pulsar/client/api/Message} object:
+The following is an example for the [Java API](client-libraries-java.md). Note
the use of the `setReplicationClusters` method when constructing the {@inject:
javadoc:Message:/client/org/apache/pulsar/client/api/Message} object:
```java
List<String> restrictReplicationTo = Arrays.asList(
@@ -114,15 +113,15 @@ $ bin/pulsar-admin persistent stats
persistent://my-tenant/my-namespace/my-topic
Each cluster reports its own local stats, including the incoming and outgoing
replication rates and backlogs.
-#### Delete a geo-replication topic
+#### Deleting a geo-replication topic
-Given that geo-replication topics exist in multiple regions, directly deleting
a geo-replication topic is not possible. Instead, you should rely on automatic
topic garbage collection.
+Given that geo-replication topics exist in multiple regions, it's not possible
to directly delete a geo-replication topic. Instead, you should rely on
automatic topic garbage collection.
-In Pulsar, a topic is automatically deleted when the topic meets the following
three conditions:
-- no producers or consumers are connected to it;
-- no subscriptions to it;
+In Pulsar, a topic is automatically deleted when it meets the following three
conditions:
+- when no producers or consumers are connected to it;
+- there are no subscriptions to it;
- no more messages are kept for retention.
-For geo-replication topics, each region uses a fault-tolerant mechanism to
decide when deleting the topic locally is safe.
+For geo-replication topics, each region uses a fault-tolerant mechanism to
decide when it's safe to delete the topic locally.
You can explicitly disable topic garbage collection by setting
`brokerDeleteInactiveTopicsEnabled` to `false` in your [broker
configuration](reference-configuration.md#broker).
@@ -134,7 +133,7 @@ Pulsar supports replicated subscriptions, so you can keep
subscription state in
In case of failover, a consumer can restart consuming from the failure point
in a different cluster.
-### Enable replicated subscription
+### Enabling replicated subscription
Replicated subscription is disabled by default. You can enable replicated
subscription when creating a consumer.
@@ -155,4 +154,4 @@ Consumer<String> consumer =
client.newConsumer(Schema.STRING)
### Limitations
-When you enable replicated subscription, you're creating a consistent
distributed snapshot to establish an association between message ids from
different clusters. The snapshots are taken periodically. The default value is
`1 second`. It means that a consumer failing over to a different cluster can
potentially receive 1 second of duplicates. You can also configure the
frequency of the snapshot in the `broker.conf` file.
+When you enable replicated subscription, you're creating a consistent
distributed snapshot to establish an association between message ids from
different clusters. The snapshots are taken periodically. The default value is
`1 second`. It means that a consumer failing over to a different cluster can
potentially receive 1 second of duplicates. You can also configure the
frequency of the snapshot in the `broker.conf` file.
\ No newline at end of file
diff --git a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
b/site2/website/versioned_docs/version-2.4.2/administration-geo.md
similarity index 60%
copy from site2/website/versioned_docs/version-2.5.0/administration-geo.md
copy to site2/website/versioned_docs/version-2.4.2/administration-geo.md
index e467141..237c4cc 100644
--- a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
+++ b/site2/website/versioned_docs/version-2.4.2/administration-geo.md
@@ -1,5 +1,5 @@
---
-id: version-2.5.0-administration-geo
+id: version-2.4.2-administration-geo
title: Pulsar geo-replication
sidebar_label: Geo-replication
original_id: administration-geo
@@ -7,51 +7,50 @@ original_id: administration-geo
*Geo-replication* is the replication of persistently stored message data
across multiple clusters of a Pulsar instance.
-## How geo-replication works
+## How it works
The diagram below illustrates the process of geo-replication across Pulsar
clusters:
-In this diagram, whenever **P1**, **P2**, and **P3** producers publish
messages to the **T1** topic on **Cluster-A**, **Cluster-B**, and **Cluster-C**
clusters respectively, those messages are instantly replicated across clusters.
Once the messages are replicated, **C1** and **C2** consumers can consume those
messages from their respective clusters.
+In this diagram, whenever **P1**, **P2**, and **P3** producers publish
messages to the **T1** topic on **Cluster-A**, **Cluster-B**, and **Cluster-C**
clusters respectively, those messages are instantly replicated across clusters.
Once replicated, **C1** and **C2** consumers can consume those messages from
their respective clusters.
-Without geo-replication, **C1** and **C2** consumers are not able to consume
messages that **P3** producer publishes.
+Without geo-replication, **C1** and **C2** consumers are not able to consume
messages published by **P3** producer.
## Geo-replication and Pulsar properties
-You must enable geo-replication on a per-tenant basis in Pulsar. You can
enable geo-replication between clusters only when a tenant is created that
allows access to both clusters.
+Geo-replication must be enabled on a per-tenant basis in Pulsar.
Geo-replication can be enabled between clusters only when a tenant has been
created that allows access to both clusters.
-Although geo-replication must be enabled between two clusters, actually
geo-replication is managed at the namespace level. You must complete the
following tasks to enable geo-replication for a namespace:
+Although geo-replication must be enabled between two clusters, it's actually
managed at the namespace level. You must complete the following tasks to enable
geo-replication for a namespace:
-* [Enable geo-replication namespaces](#enable-geo-replication-namespaces)
+* [Enable geo-replication namespaces](#enabling-geo-replication-namespaces)
* Configure that namespace to replicate across two or more provisioned clusters
-Any message published on *any* topic in that namespace is replicated to all
clusters in the specified set.
+Any message published on *any* topic in that namespace will be replicated to
all clusters in the specified set.
## Local persistence and forwarding
-When messages are produced on a Pulsar topic, messages are first persisted in
the local cluster, and then forwarded asynchronously to the remote clusters.
+When messages are produced on a Pulsar topic, they are first persisted in the
local cluster, and then forwarded asynchronously to the remote clusters.
-In normal cases, when connectivity issues are none, messages are replicated
immediately, at the same time as they are dispatched to local consumers.
Typically, the network [round-trip
time](https://en.wikipedia.org/wiki/Round-trip_delay_time) (RTT) between the
remote regions defines end-to-end delivery latency.
+In normal cases, when there are no connectivity issues, messages are
replicated immediately, at the same time as they are dispatched to local
consumers. Typically, end-to-end delivery latency is defined by the network
[round-trip time](https://en.wikipedia.org/wiki/Round-trip_delay_time) (RTT)
between the remote regions.
Applications can create producers and consumers in any of the clusters, even
when the remote clusters are not reachable (like during a network partition).
-> #### Subscriptions are local to a cluster
-> While producers and consumers can publish to and consume from any cluster in
a Pulsar instance, subscriptions are local to the clusters in which the
subscriptions are created and cannot be transferred between clusters. If you do
need to transfer a subscription, you need to create a new subscription in the
desired cluster.
+Producers and consumers can publish messages to and consume messages from any
cluster in a Pulsar instance. However, subscriptions cannot only be local to
the cluster where the subscriptions are created but also can be transferred
between clusters after replicated subscription is enabled. Once replicated
subscription is enabled, you can keep subscription state in synchronization.
Therefore, a topic can be asynchronously replicated across multiple
geographical regions. In case of failover [...]
-In the aforementioned example, the **T1** topic is replicated among three
clusters, **Cluster-A**, **Cluster-B**, and **Cluster-C**.
+In the aforementioned example, the **T1** topic is being replicated among
three clusters, **Cluster-A**, **Cluster-B**, and **Cluster-C**.
-All messages produced in any of the three clusters are delivered to all
subscriptions in other clusters. In this case, **C1** and **C2** consumers
receive all messages that **P1**, **P2**, and **P3** producers publish.
Ordering is still guaranteed on a per-producer basis.
+All messages produced in any of the three clusters are delivered to all
subscriptions in other clusters. In this case, **C1** and **C2** consumers will
receive all messages published by **P1**, **P2**, and **P3** producers.
Ordering is still guaranteed on a per-producer basis.
-## Configure replication
+## Configuring replication
As stated in [Geo-replication and Pulsar
properties](#geo-replication-and-pulsar-properties) section, geo-replication in
Pulsar is managed at the [tenant](reference-terminology.md#tenant) level.
-### Grant permissions to properties
+### Granting permissions to properties
-To replicate to a cluster, the tenant needs permission to use that cluster.
You can grant permission to the tenant when you create the tenant or grant
later.
+To replicate to a cluster, the tenant needs permission to use that cluster.
You can grant permission to the tenant when you create it or grant later.
-Specify all the intended clusters when you create a tenant:
+Specify all the intended clusters when creating a tenant:
```shell
$ bin/pulsar-admin tenants create my-tenant \
@@ -61,7 +60,7 @@ $ bin/pulsar-admin tenants create my-tenant \
To update permissions of an existing tenant, use `update` instead of `create`.
-### Enable geo-replication namespaces
+### Enabling geo-replication namespaces
You can create a namespace with the following command sample.
@@ -76,17 +75,17 @@ $ bin/pulsar-admin namespaces set-clusters
my-tenant/my-namespace \
--clusters us-west,us-east,us-cent
```
-You can change the replication clusters for a namespace at any time, without
disruption to ongoing traffic. Replication channels are immediately set up or
stopped in all clusters as soon as the configuration changes.
+The replication clusters for a namespace can be changed at any time, without
disruption to ongoing traffic. Replication channels are immediately set up or
stopped in all clusters as soon as the configuration changes.
-### Use topics with geo-replication
+### Using topics with geo-replication
-Once you create a geo-replication namespace, any topics that producers or
consumers create within that namespace is replicated across clusters.
Typically, each application uses the `serviceUrl` for the local cluster.
+Once you've created a geo-replication namespace, any topics that producers or
consumers create within that namespace will be replicated across clusters.
Typically, each application will use the `serviceUrl` for the local cluster.
#### Selective replication
-By default, messages are replicated to all clusters configured for the
namespace. You can restrict replication selectively by specifying a replication
list for a message, and then that message is replicated only to the subset in
the replication list.
+By default, messages are replicated to all clusters configured for the
namespace. You can restrict replication selectively by specifying a replication
list for a message, and then that message will be replicated only to the subset
in the replication list.
-The following is an example for the [Java API](client-libraries-java.md). Note
the use of the `setReplicationClusters` method when you construct the {@inject:
javadoc:Message:/client/org/apache/pulsar/client/api/Message} object:
+The following is an example for the [Java API](client-libraries-java.md). Note
the use of the `setReplicationClusters` method when constructing the {@inject:
javadoc:Message:/client/org/apache/pulsar/client/api/Message} object:
```java
List<String> restrictReplicationTo = Arrays.asList(
@@ -114,15 +113,15 @@ $ bin/pulsar-admin persistent stats
persistent://my-tenant/my-namespace/my-topic
Each cluster reports its own local stats, including the incoming and outgoing
replication rates and backlogs.
-#### Delete a geo-replication topic
+#### Deleting a geo-replication topic
-Given that geo-replication topics exist in multiple regions, directly deleting
a geo-replication topic is not possible. Instead, you should rely on automatic
topic garbage collection.
+Given that geo-replication topics exist in multiple regions, it's not possible
to directly delete a geo-replication topic. Instead, you should rely on
automatic topic garbage collection.
-In Pulsar, a topic is automatically deleted when the topic meets the following
three conditions:
-- no producers or consumers are connected to it;
-- no subscriptions to it;
+In Pulsar, a topic is automatically deleted when it meets the following three
conditions:
+- when no producers or consumers are connected to it;
+- there are no subscriptions to it;
- no more messages are kept for retention.
-For geo-replication topics, each region uses a fault-tolerant mechanism to
decide when deleting the topic locally is safe.
+For geo-replication topics, each region uses a fault-tolerant mechanism to
decide when it's safe to delete the topic locally.
You can explicitly disable topic garbage collection by setting
`brokerDeleteInactiveTopicsEnabled` to `false` in your [broker
configuration](reference-configuration.md#broker).
@@ -133,8 +132,7 @@ To delete a geo-replication topic, close all producers and
consumers on the topi
Pulsar supports replicated subscriptions, so you can keep subscription state
in sync, within a sub-second timeframe, in the context of a topic that is being
asynchronously replicated across multiple geographical regions.
In case of failover, a consumer can restart consuming from the failure point
in a different cluster.
-
-### Enable replicated subscription
+### Enabling replicated subscription
Replicated subscription is disabled by default. You can enable replicated
subscription when creating a consumer.
@@ -155,4 +153,4 @@ Consumer<String> consumer =
client.newConsumer(Schema.STRING)
### Limitations
-When you enable replicated subscription, you're creating a consistent
distributed snapshot to establish an association between message ids from
different clusters. The snapshots are taken periodically. The default value is
`1 second`. It means that a consumer failing over to a different cluster can
potentially receive 1 second of duplicates. You can also configure the
frequency of the snapshot in the `broker.conf` file.
+When you enable replicated subscription, you're creating a consistent
distributed snapshot to establish an association between message ids from
different clusters. The snapshots are taken periodically. The default value is
`1 second`. It means that a consumer failing over to a different cluster can
potentially receive 1 second of duplicates. You can also configure the
frequency of the snapshot in the `broker.conf` file.
\ No newline at end of file
diff --git a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
b/site2/website/versioned_docs/version-2.5.0/administration-geo.md
index e467141..3c0854d 100644
--- a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
+++ b/site2/website/versioned_docs/version-2.5.0/administration-geo.md
@@ -36,8 +36,7 @@ In normal cases, when connectivity issues are none, messages
are replicated imme
Applications can create producers and consumers in any of the clusters, even
when the remote clusters are not reachable (like during a network partition).
-> #### Subscriptions are local to a cluster
-> While producers and consumers can publish to and consume from any cluster in
a Pulsar instance, subscriptions are local to the clusters in which the
subscriptions are created and cannot be transferred between clusters. If you do
need to transfer a subscription, you need to create a new subscription in the
desired cluster.
+Producers and consumers can publish messages to and consume messages from any
cluster in a Pulsar instance. However, subscriptions cannot only be local to
the cluster where the subscriptions are created but also can be transferred
between clusters after replicated subscription is enabled. Once replicated
subscription is enabled, you can keep subscription state in synchronization.
Therefore, a topic can be asynchronously replicated across multiple
geographical regions. In case of failover [...]
In the aforementioned example, the **T1** topic is replicated among three
clusters, **Cluster-A**, **Cluster-B**, and **Cluster-C**.
diff --git a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
b/site2/website/versioned_docs/version-2.5.1/administration-geo.md
similarity index 92%
copy from site2/website/versioned_docs/version-2.5.0/administration-geo.md
copy to site2/website/versioned_docs/version-2.5.1/administration-geo.md
index e467141..1c7a9e5 100644
--- a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
+++ b/site2/website/versioned_docs/version-2.5.1/administration-geo.md
@@ -1,5 +1,5 @@
---
-id: version-2.5.0-administration-geo
+id: version-2.5.1-administration-geo
title: Pulsar geo-replication
sidebar_label: Geo-replication
original_id: administration-geo
@@ -36,8 +36,7 @@ In normal cases, when connectivity issues are none, messages
are replicated imme
Applications can create producers and consumers in any of the clusters, even
when the remote clusters are not reachable (like during a network partition).
-> #### Subscriptions are local to a cluster
-> While producers and consumers can publish to and consume from any cluster in
a Pulsar instance, subscriptions are local to the clusters in which the
subscriptions are created and cannot be transferred between clusters. If you do
need to transfer a subscription, you need to create a new subscription in the
desired cluster.
+Producers and consumers can publish messages to and consume messages from any
cluster in a Pulsar instance. However, subscriptions cannot only be local to
the cluster where the subscriptions are created but also can be transferred
between clusters after replicated subscription is enabled. Once replicated
subscription is enabled, you can keep subscription state in synchronization.
Therefore, a topic can be asynchronously replicated across multiple
geographical regions. In case of failover [...]
In the aforementioned example, the **T1** topic is replicated among three
clusters, **Cluster-A**, **Cluster-B**, and **Cluster-C**.
diff --git a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
b/site2/website/versioned_docs/version-2.5.2/administration-geo.md
similarity index 92%
copy from site2/website/versioned_docs/version-2.5.0/administration-geo.md
copy to site2/website/versioned_docs/version-2.5.2/administration-geo.md
index e467141..6e20a34 100644
--- a/site2/website/versioned_docs/version-2.5.0/administration-geo.md
+++ b/site2/website/versioned_docs/version-2.5.2/administration-geo.md
@@ -1,5 +1,5 @@
---
-id: version-2.5.0-administration-geo
+id: version-2.5.2-administration-geo
title: Pulsar geo-replication
sidebar_label: Geo-replication
original_id: administration-geo
@@ -36,8 +36,7 @@ In normal cases, when connectivity issues are none, messages
are replicated imme
Applications can create producers and consumers in any of the clusters, even
when the remote clusters are not reachable (like during a network partition).
-> #### Subscriptions are local to a cluster
-> While producers and consumers can publish to and consume from any cluster in
a Pulsar instance, subscriptions are local to the clusters in which the
subscriptions are created and cannot be transferred between clusters. If you do
need to transfer a subscription, you need to create a new subscription in the
desired cluster.
+Producers and consumers can publish messages to and consume messages from any
cluster in a Pulsar instance. However, subscriptions cannot only be local to
the cluster where the subscriptions are created but also can be transferred
between clusters after replicated subscription is enabled. Once replicated
subscription is enabled, you can keep subscription state in synchronization.
Therefore, a topic can be asynchronously replicated across multiple
geographical regions. In case of failover [...]
In the aforementioned example, the **T1** topic is replicated among three
clusters, **Cluster-A**, **Cluster-B**, and **Cluster-C**.
