This is an automated email from the ASF dual-hosted git repository.
yubiao 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 1f90897c890 [improve] [pip] PIP-370: configurable remote topic
creation in geo-replication (#23124)
1f90897c890 is described below
commit 1f90897c890a3b41153b332264624916b926f3a7
Author: fengyubiao <[email protected]>
AuthorDate: Fri Aug 16 10:43:45 2024 +0800
[improve] [pip] PIP-370: configurable remote topic creation in
geo-replication (#23124)
---
pip/pip-370.md | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 109 insertions(+)
diff --git a/pip/pip-370.md b/pip/pip-370.md
new file mode 100644
index 00000000000..6699846cee1
--- /dev/null
+++ b/pip/pip-370.md
@@ -0,0 +1,109 @@
+# 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**
+```properties
+# 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
+
+<!--
+For each metric provide:
+* Full name
+* Description
+* Attributes (labels)
+* Unit
+-->
+| Name | Description | Attributes | Units|
+| --- | --- | --- | --- |
+| `pulsar_broker_replication_count` | Counter. The number of topics enabled
replication. | cluster | - |
+| `pulsar_broker_replication_disconnected_count` | Counter. The number of
topics that enabled replication and its replicator failed to connect | cluster
| - |
+
+
+# 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](https://github.com/apache/p [...]
+
+## 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
