PIP-370: configurable remote topic creation in geo-replication

Background knowledge

The current topic creation behavior when enabling Geo-Replication Users using Geo-Replication backup data across multiple clusters, as well as Admin APIs related to Geo-Replication and internal replicators of brokers, will trigger topics of auto-creation between clusters.

• For partitioned topics.
  • After enabling namespace-level Geo-Replication: the broker will create topics on the remote cluster automatically when calling pulsar-admin topics create-partitioned-topic. It does not depend on enabling allowAutoTopicCreation.
  • When enabling topic-level Geo-Replication on a partitioned topic: the broker will create topics on the remote cluster automatically. It does not depend on enabling allowAutoTopicCreation.
  • When calling pulsar-admin topics update-partitioned-topic -p {partitions}, the broker will also update partitions on the remote cluster automatically.
• For non-partitioned topics and partitions of partitioned topics.
  • The internal Geo-Replicator will trigger topics auto-creation for remote clusters. (Highlight) It depends on enabling allowAutoTopicCreation. In fact, this behavior is not related to Geo-Replication, it is the behavior of the internal producer of Geo-Replicator,

Motivation

In the following scenarios, automatic topic creation across clusters is problematic due to race conditions during deployments, and there is no choice that prevents pulsar resource creation affects each other between clusters.

• Users want to maintain pulsar resources manually.
• Users pulsar resources using GitOps CD automated deployment, for which
  • Clusters are deployed simultaneously without user intervention.
  • Each cluster is precisely configured from git repo config variables - including the list of all tenants/namespaces/topics to be created in each cluster.
  • Clusters are configured to be exact clones of each other in terms of pulsar resources.

Passed solution: disable allowAutoTopicCreation, the APIs pulsar-admin topics create-partitioned-topic still create topics on the remote cluster when enabled namespace level replication, the API enable topic-level replication still create topics, And the internal replicator will keep printing error logs due to a not found error.

Goals

• Phase 1: Introduce a flag to disable the replicators to automatically trigger topic creation.
• Phase 2: Move all topic creation/expand-partitions behaviors related to Replication to the internal Replicator, pulsar admin API that relates to pulsar topics management does not care about replication anymore.
  • Move the topic creation operations from pulsar-admin topics create-partitioned-topic and pulsar-admin topics set-replication-clusters to the component Replicator in the broker internal.
  • (The same as before)When calling pulsar-admin topics update-partitioned-topic -p {partitions}, the broker will also update partitions on the remote cluster automatically.

Note: the proposal will only focus on phase one, and the detailed design for phase two with come up with another proposal.

Detailed Design

Configuration

broker.conf

# Whether the internal replication of the local cluster will trigger topic auto-creation on the remote cluster.
# 1. After enabling namespace-level Geo-Replication: whether the local broker will create topics on the remote cluster automatically when calling `pulsar-admin topics create-partitioned-topic`.
# 2. When enabling topic-level Geo-Replication on a partitioned topic: whether the local broker will create topics on the remote cluster.
# 3. Whether the internal Geo-Replicator in the local cluster will trigger non-persistent topic auto-creation for remote clusters.
# It is not a dynamic config, the default value is "true" to preserve backward-compatible behavior.
createTopicToRemoteClusterForReplication=true

Design & Implementation Details

Phase 1: Introduce a flag to disable the replicators to automatically trigger topic creation.

• If createTopicToRemoteClusterForReplication is set to false.
  1. After enabling namespace-level Geo-Replication: the broker will not create topics on the remote cluster automatically when calling pulsar-admin topics create-partitioned-topic.
  2. When enabling topic-level Geo-Replication on a partitioned topic: broker will not create topics on the remote cluster automatically.
  3. The internal Geo-Replicator will not trigger topic auto-creation for remote clusters, it just keeps retrying to check if the topic exists on the remote cluster, once the topic is created, the replicator starts.
  4. It does not change the behavior of creating subscriptions after enabling enableReplicatedSubscriptions, the subscription will also be created on the remote cluster after users enable. enableReplicatedSubscriptions.
  5. The config allowAutoTopicCreation still works for the local cluster as before, it will not be affected by the new config createTopicToRemoteClusterForReplication.
• If createTopicToRemoteClusterForReplication is set to true. a. All components work as before, see details: Motivation -> The current topic creation behavior when enabling Geo-Replication

Phase 2: The replicator will check remote topics' partitioned metadata and update partitions in the remote cluster to the same as the current cluster if needed.

• If createTopicToRemoteClusterForReplication is set to false.
  • The behavior is the same as Phase 1.
• If createTopicToRemoteClusterForReplication is set to true.
  • Pulsar admin API that relates to pulsar topics management does not care about replication anymore.
  • When a replicator for a topic partition starts, it checks the partitioned metadata in the remote cluster first and updates partitions in the remote cluster to the same as the current cluster if needed. Seem the example as follows:

partitions of local cluster	partitions of remote cluster	After PIP-370 Phase 2	Before PIP-370 Phase 2
2	no topic exists	create a partitioned topic with 2 partitions in the remote cluster	the replicator will only trigger partition creation ({topic}-partition-0 and {topic}-partition-1), and will not care about partitioned metadata.
2	1	In dispute: The replicator copies messages from partition-0 to the remote cluster, does not copy any data for partition-1 and just prints error logs in the background.	the replicator will only trigger partition creation ({topic}-partition-0 and {topic}-partition-1), and the partitioned metadata in the remote cluster is still 1
2	2	modifies nothing.	The same as “After PIP-370 Phase 2”
2	>2	In dispute: modifies nothing, the messages will be copied to the same partition in the remote cluster, and no message will be copied to the partition who is larger than 2 in the remote cluster	The same as “After PIP-370 Phase 2”
2	0(non-partitioned topic)	In dispute: The replicator does not copy any data and just prints error logs in the background.	the replicator will only trigger partition creation ({topic}-partition-0 and {topic}-partition-1), then users will get 3 non-partitioned topics: [{tp}, {topic}-partition-0, {topic}-partition-1.
0(non-partitioned topic)	0(non-partitioned topic)	Copy data normally	It is the same as before PIP-370.
0(non-partitioned topic)	no topic exists	create a non-partitioned topic in the remote cluster.	It is the same as before PIP-370.
0(non-partitioned topic)	>=1	In dispute: The replicator does not copy any data and just prints error logs in the background.	The replicator will only trigger a non-partitioned topic's creation, then users will get 1 non-partitioned topic and 1 partitioned topic.

Metrics

Name	Description	Attributes	Units
pulsar_replication_disconnected_count	Counter. The number of replicators.	cluster, namespace, topic	-

Monitoring

• If pulsar_broker_replication_disconnected_count keeps larger than 0 for a period of time, it means some replicators do not work, we should push an alert out.

Backward & Forward Compatibility

Regarding to Phase-1

This PIP guarantees full compatibility with default settings(the default value of createTopicToRemoteClusterForReplication is true). If you want to cherry-pick PIP-370 for another branch in the future, you need to cherry-pick PIP-344 as well. Because the behavior of disables createTopicToRemoteClusterForReplication depends on the API PulsarClient.getPartitionsForTopic(String topic, boolean metadataAutoCreationEnabled), which was introduced by PIP-344.

Regarding to Phase-2

The two scenarios are as follows, the replication will not work as before, which will lead backlog increase, please take care of checking your clusters before upgrading.

• local_cluster.topic.partitions = 2 and remote_cluster.topic.partitions = 0(non-partitioned topic): see detail in the section Design & Implementation Details -> Phase-2.
• local_cluster.topic.partitions = 0(non-partitioned topic) and and remote_cluster.topic.partitions >= 1: see detail in the section Design & Implementation Details -> Phase-2.

Links

• Mailing List discussion thread: https://lists.apache.org/thread/9fx354cqcy3412w1nx8kwdf9h141omdg
• Mailing List voting thread: https://lists.apache.org/thread/vph22st5td1rdh1gd68gkrnp9doo6ct2