Geo-replication is the replication of persistently stored message data across multiple clusters of a Pulsar instance.
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 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 published by P3 producer.
Geo-replication and Pulsar properties
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, 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
- Configure that namespace to replicate across two or more provisioned clusters
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, they are first persisted in the local cluster, and then forwarded asynchronously to the remote clusters.
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 (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 they are created and cannot be transferred between clusters. If you do need to transfer a subscription, you’ll need to create a new subscription in the desired cluster.
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 will receive all messages published by P1, P2, and P3 producers. Ordering is still guaranteed on a per-producer basis.
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 it or grant later.
Specify all the intended clusters when creating a tenant:
bin/pulsar-admin tenants create my-tenant \ --admin-roles my-admin-role \ --allowed-clusters us-west,us-east,us-cent
To update permissions of an existing tenant, use
update instead of
Enabling geo-replication namespaces
You can create a namespace with the following command sample.
bin/pulsar-admin namespaces create my-tenant/my-namespace
Initially, the namespace is not assigned to any cluster. You can assign the namespace to clusters using the
bin/pulsar-admin namespaces set-clusters my-tenant/my-namespace \ --clusters us-west,us-east,us-cent
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.
Using topics with geo-replication
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.
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.
List<String> restrictReplicationTo = Arrays.asList( "us-west", "us-east" ); Producer producer = client.newProducer() .topic("some-topic") .create(); producer.newMessage() .value("my-payload".getBytes()) .setReplicationClusters(restrictReplicationTo) .send();
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.
Deleting a geo-replication topic
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 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 it's safe to delete the topic locally.
You can explicitly disable topic garbage collection by setting
false in your broker configuration.
To delete a geo-replication topic, close all producers and consumers on the topic, and delete all of its local subscriptions in every replication cluster. When Pulsar determines that no valid subscription for the topic remains across the system, it will garbage collect the topic.