You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by ur...@apache.org on 2022/09/09 12:01:55 UTC
[pulsar-site] branch main updated: Docs sync done from apache/pulsar(#200f433)
This is an automated email from the ASF dual-hosted git repository.
urfree pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 80af1645c39 Docs sync done from apache/pulsar(#200f433)
80af1645c39 is described below
commit 80af1645c39c7929eb588e1c1508fd4339ea2de0
Author: Pulsar Site Updater <de...@pulsar.apache.org>
AuthorDate: Fri Sep 9 12:01:50 2022 +0000
Docs sync done from apache/pulsar(#200f433)
---
site2/website-next/docs/client-libraries-java.md | 460 +++++++--------------
.../docs/concepts-cluster-level-failover.md | 163 ++++++++
site2/website-next/docs/tiered-storage-aliyun.md | 2 +-
site2/website-next/docs/tiered-storage-aws.md | 2 +-
site2/website-next/docs/tiered-storage-azure.md | 2 +-
.../website-next/docs/tiered-storage-filesystem.md | 2 +-
site2/website-next/docs/tiered-storage-gcs.md | 2 +-
site2/website-next/docs/tiered-storage-s3.md | 2 -
site2/website-next/sidebars.json | 19 +-
9 files changed, 326 insertions(+), 328 deletions(-)
diff --git a/site2/website-next/docs/client-libraries-java.md b/site2/website-next/docs/client-libraries-java.md
index 82568086b8d..69c3becbee6 100644
--- a/site2/website-next/docs/client-libraries-java.md
+++ b/site2/website-next/docs/client-libraries-java.md
@@ -103,8 +103,11 @@ PulsarClient client = PulsarClient.builder()
.build();
```
-> ### Default broker URLs for standalone clusters
-> If you run a cluster in [standalone mode](getting-started-standalone.md), the broker is available at the `pulsar://localhost:6650` URL by default.
+:::note
+
+If you run a cluster in [standalone mode](getting-started-standalone.md), the broker is available at the `pulsar://localhost:6650` URL by default.
+
+:::
If you create a client, you can use the `loadConf` configuration. The following parameters are available in `loadConf`.
@@ -158,322 +161,6 @@ Dpulsar.allocator.leak_detection=Disabled
Dpulsar.allocator.out_of_memory_policy=ThrowException
```
-### Cluster-level failover
-
-This chapter describes the concept, benefits, use cases, constraints, usage, working principles, and more information about the cluster-level failover. It contains the following sections:
-
-- [What is cluster-level failover?](#what-is-cluster-level-failover)
-
- * [Concept of cluster-level failover](#concept-of-cluster-level-failover)
-
- * [Why use cluster-level failover?](#why-use-cluster-level-failover)
-
- * [When to use cluster-level failover?](#when-to-use-cluster-level-failover)
-
- * [When cluster-level failover is triggered?](#when-cluster-level-failover-is-triggered)
-
- * [Why does cluster-level failover fail?](#why-does-cluster-level-failover-fail)
-
- * [What are the limitations of cluster-level failover?](#what-are-the-limitations-of-cluster-level-failover)
-
- * [What are the relationships between cluster-level failover and geo-replication?](#what-are-the-relationships-between-cluster-level-failover-and-geo-replication)
-
-- [How to use cluster-level failover?](#how-to-use-cluster-level-failover)
-
-- [How does cluster-level failover work?](#how-does-cluster-level-failover-work)
-
-#### What is cluster-level failover
-
-This chapter helps you better understand the concept of cluster-level failover.
-
-##### Concept of cluster-level failover
-
-````mdx-code-block
-<Tabs groupId="failover-choice"
- defaultValue="Automatic cluster-level failover"
- values={[{"label":"Automatic cluster-level failover","value":"Automatic cluster-level failover"},{"label":"Controlled cluster-level failover","value":"Controlled cluster-level failover"}]}>
-<TabItem value="Automatic cluster-level failover">
-
-Automatic cluster-level failover supports Pulsar clients switching from a primary cluster to one or several backup clusters automatically and seamlessly when it detects a failover event based on the configured detecting policy set by **users**.
-
-
-
-</TabItem>
-<TabItem value="Controlled cluster-level failover">
-
-Controlled cluster-level failover supports Pulsar clients switching from a primary cluster to one or several backup clusters. The switchover is manually set by **administrators**.
-
-
-
-</TabItem>
-
-</Tabs>
-````
-
-Once the primary cluster functions again, Pulsar clients can switch back to the primary cluster. Most of the time users won’t even notice a thing. Users can keep using applications and services without interruptions or timeouts.
-
-##### Why use cluster-level failover?
-
-The cluster-level failover provides fault tolerance, continuous availability, and high availability together. It brings a number of benefits, including but not limited to:
-
-* Reduced cost: services can be switched and recovered automatically with no data loss.
-
-* Simplified management: businesses can operate on an "always-on" basis since no immediate user intervention is required.
-
-* Improved stability and robustness: it ensures continuous performance and minimizes service downtime.
-
-> ##### When to use cluster-level failover?
-
-The cluster-level failover protects your environment in a number of ways, including but not limited to:
-
-* Disaster recovery: cluster-level failover can automatically and seamlessly transfer the production workload on a primary cluster to one or several backup clusters, which ensures minimum data loss and reduced recovery time.
-
-* Planned migration: if you want to migrate production workloads from an old cluster to a new cluster, you can improve the migration efficiency with cluster-level failover. For example, you can test whether the data migration goes smoothly in case of a failover event, identify possible issues and risks before the migration.
-
-##### When cluster-level failover is triggered?
-
-````mdx-code-block
-<Tabs groupId="failover-choice"
- defaultValue="Automatic cluster-level failover"
- values={[{"label":"Automatic cluster-level failover","value":"Automatic cluster-level failover"},{"label":"Controlled cluster-level failover","value":"Controlled cluster-level failover"}]}>
-<TabItem value="Automatic cluster-level failover">
-
-Automatic cluster-level failover is triggered when Pulsar clients cannot connect to the primary cluster for a prolonged period of time. This can be caused by any number of reasons including, but not limited to:
-
-* Network failure: internet connection is lost.
-
-* Power failure: shutdown time of a primary cluster exceeds time limits.
-
-* Service error: errors occur on a primary cluster (for example, the primary cluster does not function because of time limits).
-
-* Crashed storage space: the primary cluster does not have enough storage space, but the corresponding storage space on the backup server functions normally.
-
-</TabItem>
-<TabItem value="Controlled cluster-level failover">
-
-Controlled cluster-level failover is triggered when administrators set the switchover manually.
-
-</TabItem>
-
-</Tabs>
-````
-
-##### Why does cluster-level failover fail?
-
-Obviously, the cluster-level failover does not succeed if the backup cluster is unreachable by active Pulsar clients. This can happen for many reasons, including but not limited to:
-
-* Power failure: the backup cluster is shut down or does not function normally.
-
-* Crashed storage space: primary and backup clusters do not have enough storage space.
-
-* If the failover is initiated, but no cluster can assume the role of an available cluster due to errors, and the primary cluster is not able to provide service normally.
-
-* If you manually initiate a switchover, but services cannot be switched to the backup cluster server, then the system will attempt to switch services back to the primary cluster.
-
-* Fail to authenticate or authorize between 1) primary and backup clusters, or 2) between two backup clusters.
-
-##### What are the limitations of cluster-level failover?
-
-Currently, cluster-level failover can perform probes to prevent data loss, but it can not check the status of backup clusters. If backup clusters are not healthy, you cannot produce or consume data.
-
-#### What are the relationships between cluster-level failover and geo-replication?
-
-The cluster-level failover is an extension of [geo-replication](concepts-replication.md) to improve stability and robustness. The cluster-level failover depends on geo-replication, and they have some **differences** as below.
-
-Influence |Cluster-level failover|Geo-replication
-|---|---|---
-Do administrators have heavy workloads?|No or maybe.<br /><br />- For the **automatic** cluster-level failover, the cluster switchover is triggered automatically based on the policies set by **users**.<br /><br />- For the **controlled** cluster-level failover, the switchover is triggered manually by **administrators**.|Yes.<br /><br />If a cluster fails, immediate administration intervention is required.|
-Result in data loss?|No.<br /><br />For both **automatic** and **controlled** cluster-level failover, if the failed primary cluster doesn't replicate messages immediately to the backup cluster, the Pulsar client can't consume the non-replicated messages. After the primary cluster is restored and the Pulsar client switches back, the non-replicated data can still be consumed by the Pulsar client. Consequently, the data is not lost.<br /><br />- For the **automatic** cluster-level failover, [...]
-Result in Pulsar client failure? |No or maybe.<br /><br />- For **automatic** cluster-level failover, services can be switched and recovered automatically and the Pulsar client does not fail. <br /><br />- For **controlled** cluster-level failover, services can be switched and recovered manually, but the Pulsar client fails before administrators can take action. |Same as above.
-
-#### How to use cluster-level failover
-
-This section guides you through every step on how to configure cluster-level failover.
-
-**Tip**
-
-- You should configure cluster-level failover only when the cluster contains sufficient resources to handle all possible consequences. Workload intensity on the backup cluster may increase significantly.
-
-- Connect clusters to an uninterruptible power supply (UPS) unit to reduce the risk of unexpected power loss.
-
-**Requirements**
-
-* Pulsar client 2.10 or later versions.
-
-* For backup clusters:
-
- * The number of BookKeeper nodes should be equal to or greater than the ensemble quorum.
-
- * The number of ZooKeeper nodes should be equal to or greater than 3.
-
-* **Turn on geo-replication** between the primary cluster and any dependent cluster (primary to backup or backup to backup) to prevent data loss.
-
-* Set `replicateSubscriptionState` to `true` when creating consumers.
-
-````mdx-code-block
-<Tabs groupId="failover-choice"
- defaultValue="Automatic cluster-level failover"
- values={[{"label":"Automatic cluster-level failover","value":"Automatic cluster-level failover"},{"label":"Controlled cluster-level failover","value":"Controlled cluster-level failover"}]}>
-<TabItem value="Automatic cluster-level failover">
-
-This is an example of how to construct a Java Pulsar client to use automatic cluster-level failover. The switchover is triggered automatically.
-
-```java
-private PulsarClient getAutoFailoverClient() throws PulsarClientException {
- ServiceUrlProvider failover = AutoClusterFailover.builder()
- .primary("pulsar://localhost:6650")
- .secondary(Collections.singletonList("pulsar://other1:6650", "pulsar://other2:6650"))
- .failoverDelay(30, TimeUnit.SECONDS)
- .switchBackDelay(60, TimeUnit.SECONDS)
- .checkInterval(1000, TimeUnit.MILLISECONDS)
- .secondaryTlsTrustCertsFilePath("/path/to/ca.cert.pem")
- .secondaryAuthentication("org.apache.pulsar.client.impl.auth.AuthenticationTls",
- "tlsCertFile:/path/to/my-role.cert.pem,tlsKeyFile:/path/to/my-role.key-pk8.pem")
-
- .build();
-
- PulsarClient pulsarClient = PulsarClient.builder()
- .build();
-
- failover.initialize(pulsarClient);
- return pulsarClient;
-}
-```
-
-Configure the following parameters:
-
-Parameter|Default value|Required?|Description
-|---|---|---|---
-`primary`|N/A|Yes|Service URL of the primary cluster.
-`secondary`|N/A|Yes|Service URL(s) of one or several backup clusters.<br /><br />You can specify several backup clusters using a comma-separated list.<br /><br /> Note that:<br />- The backup cluster is chosen in the sequence shown in the list. <br />- If all backup clusters are available, the Pulsar client chooses the first backup cluster.
-`failoverDelay`|N/A|Yes|The delay before the Pulsar client switches from the primary cluster to the backup cluster.<br /><br />Automatic failover is controlled by a probe task: <br />1) The probe task first checks the health status of the primary cluster. <br /> 2) If the probe task finds the continuous failure time of the primary cluster exceeds `failoverDelayMs`, it switches the Pulsar client to the backup cluster.
-`switchBackDelay`|N/A|Yes|The delay before the Pulsar client switches from the backup cluster to the primary cluster.<br /><br />Automatic failover switchover is controlled by a probe task: <br /> 1) After the Pulsar client switches from the primary cluster to the backup cluster, the probe task continues to check the status of the primary cluster. <br /> 2) If the primary cluster functions well and continuously remains active longer than `switchBackDelay`, the Pulsar client switches back [...]
-`checkInterval`|30s|No|Frequency of performing a probe task (in seconds).
-`secondaryTlsTrustCertsFilePath`|N/A|No|Path to the trusted TLS certificate file of the backup cluster.
-`secondaryAuthentication`|N/A|No|Authentication of the backup cluster.
-
-</TabItem>
-<TabItem value="Controlled cluster-level failover">
-
-This is an example of how to construct a Java Pulsar client to use controlled cluster-level failover. The switchover is triggered by administrators manually.
-
-**Note**: you can have one or several backup clusters but can only specify one.
-
-```java
-public PulsarClient getControlledFailoverClient() throws IOException {
- Map<String, String> header = new HashMap();
- header.put("service_user_id", "my-user");
- header.put("service_password", "tiger");
- header.put("clusterA", "tokenA");
- header.put("clusterB", "tokenB");
-
- ServiceUrlProvider provider =
- ControlledClusterFailover.builder()
- .defaultServiceUrl("pulsar://localhost:6650")
- .checkInterval(1, TimeUnit.MINUTES)
- .urlProvider("http://localhost:8080/test")
- .urlProviderHeader(header)
- .build();
-
- PulsarClient pulsarClient =
- PulsarClient.builder()
- .build();
-
- provider.initialize(pulsarClient);
- return pulsarClient;
-}
-```
-
-Parameter|Default value|Required?|Description
-|---|---|---|---
-`defaultServiceUrl`|N/A|Yes|Pulsar service URL.
-`checkInterval`|30s|No|Frequency of performing a probe task (in seconds).
-`urlProvider`|N/A|Yes|URL provider service.
-`urlProviderHeader`|N/A|No|`urlProviderHeader` is a map containing tokens and credentials. <br /><br />If you enable authentication or authorization between Pulsar clients and primary and backup clusters, you need to provide `urlProviderHeader`.
-
-Here is an example of how `urlProviderHeader` works.
-
-
-
-Assume that you want to connect Pulsar client 1 to cluster A.
-
-1. Pulsar client 1 sends the token *t1* to the URL provider service.
-
-2. The URL provider service returns the credential *c1* and the cluster A URL to the Pulsar client.
-
- The URL provider service manages all tokens and credentials. It returns different credentials based on different tokens and different target cluster URLs to different Pulsar clients.
-
- **Note**: **the credential must be in a JSON file and contain parameters as shown**.
-
- ```java
- {
- "serviceUrl": "pulsar+ssl://target:6651",
- "tlsTrustCertsFilePath": "/security/ca.cert.pem",
- "authPluginClassName":"org.apache.pulsar.client.impl.auth.AuthenticationTls",
- "authParamsString": " \"tlsCertFile\": \"/security/client.cert.pem\"
- \"tlsKeyFile\": \"/security/client-pk8.pem\" "
- }
- ```
-
-3. Pulsar client 1 connects to cluster A using credential *c1*.
-
-</TabItem>
-
-</Tabs>
-````
-
-#### How does cluster-level failover work?
-
-This chapter explains the working process of cluster-level failover. For more implementation details, see [PIP-121](https://github.com/apache/pulsar/issues/13315).
-
-````mdx-code-block
-<Tabs groupId="failover-choice"
- defaultValue="Automatic cluster-level failover"
- values={[{"label":"Automatic cluster-level failover","value":"Automatic cluster-level failover"},{"label":"Controlled cluster-level failover","value":"Controlled cluster-level failover"}]}>
-<TabItem value="Automatic cluster-level failover">
-
-In an automatic failover cluster, the primary cluster and backup cluster are aware of each other's availability. The automatic failover cluster performs the following actions without administrator intervention:
-
-1. The Pulsar client runs a probe task at intervals defined in `checkInterval`.
-
-2. If the probe task finds the failure time of the primary cluster exceeds the time set in the `failoverDelay` parameter, it searches backup clusters for an available healthy cluster.
-
- 2a) If there are healthy backup clusters, the Pulsar client switches to a backup cluster in the order defined in `secondary`.
-
- 2b) If there is no healthy backup cluster, the Pulsar client does not perform the switchover, and the probe task continues to look for an available backup cluster.
-
-3. The probe task checks whether the primary cluster functions well or not.
-
- 3a) If the primary cluster comes back and the continuous healthy time exceeds the time set in `switchBackDelay`, the Pulsar client switches back to the primary cluster.
-
- 3b) If the primary cluster does not come back, the Pulsar client does not perform the switchover.
-
-
-
-</TabItem>
-<TabItem value="Controlled cluster-level failover">
-
-1. The Pulsar client runs a probe task at intervals defined in `checkInterval`.
-
-2. The probe task fetches the service URL configuration from the URL provider service, which is configured by `urlProvider`.
-
- 2a) If the service URL configuration is changed, the probe task switches to the target cluster without checking the health status of the target cluster.
-
- 2b) If the service URL configuration is not changed, the Pulsar client does not perform the switchover.
-
-3. If the Pulsar client switches to the target cluster, the probe task continues to fetch service URL configuration from the URL provider service at intervals defined in `checkInterval`.
-
- 3a) If the service URL configuration is changed, the probe task switches to the target cluster without checking the health status of the target cluster.
-
- 3b) If the service URL configuration is not changed, it does not perform the switchover.
-
-
-
-</TabItem>
-
-</Tabs>
-````
-
## Producer
In Pulsar, producers write messages to topics. Once you've instantiated a {@inject: javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object (as in the section [above](#client-configuration)), you can create a {@inject: javadoc:Producer:/client/org/apache/pulsar/client/api/Producer} for a specific Pulsar [topic](reference-terminology.md#topic).
@@ -1654,3 +1341,140 @@ PulsarClient client = PulsarClient.builder()
.build();
```
+## Cluster-level failover
+
+For more concepts and reference information about cluster-level failover, including concept, benefits, use cases, constraints, usage and working principles, see [Cluster-level failover](concepts-cluster-level-failover.md).
+
+:::tip
+
+- You should configure cluster-level failover only when the cluster contains sufficient resources to handle all possible consequences. Workload intensity on the backup cluster may increase significantly.
+
+- Connect clusters to an uninterruptible power supply (UPS) unit to reduce the risk of unexpected power loss.
+
+:::
+
+**Requirements**
+
+* Pulsar client 2.10 or later versions.
+
+* For backup clusters:
+
+ * The number of BookKeeper nodes should be equal to or greater than the ensemble quorum.
+
+ * The number of ZooKeeper nodes should be equal to or greater than 3.
+
+* **Turn on geo-replication** between the primary cluster and any dependent cluster (primary to backup or backup to backup) to prevent data loss.
+
+* Set `replicateSubscriptionState` to `true` when creating consumers.
+
+````mdx-code-block
+<Tabs groupId="failover-choice"
+ defaultValue="Automatic cluster-level failover"
+ values={[{"label":"Automatic cluster-level failover","value":"Automatic cluster-level failover"},{"label":"Controlled cluster-level failover","value":"Controlled cluster-level failover"}]}>
+<TabItem value="Automatic cluster-level failover">
+
+This is an example of how to construct a Java Pulsar client to use automatic cluster-level failover. The switchover is triggered automatically.
+
+```java
+private PulsarClient getAutoFailoverClient() throws PulsarClientException {
+ ServiceUrlProvider failover = AutoClusterFailover.builder()
+ .primary("pulsar://localhost:6650")
+ .secondary(Collections.singletonList("pulsar://other1:6650", "pulsar://other2:6650"))
+ .failoverDelay(30, TimeUnit.SECONDS)
+ .switchBackDelay(60, TimeUnit.SECONDS)
+ .checkInterval(1000, TimeUnit.MILLISECONDS)
+ .secondaryTlsTrustCertsFilePath("/path/to/ca.cert.pem")
+ .secondaryAuthentication("org.apache.pulsar.client.impl.auth.AuthenticationTls",
+ "tlsCertFile:/path/to/my-role.cert.pem,tlsKeyFile:/path/to/my-role.key-pk8.pem")
+
+ .build();
+
+ PulsarClient pulsarClient = PulsarClient.builder()
+ .build();
+
+ failover.initialize(pulsarClient);
+ return pulsarClient;
+}
+```
+
+Configure the following parameters:
+
+Parameter|Default value|Required?|Description
+|---|---|---|---
+`primary`|N/A|Yes|Service URL of the primary cluster.
+`secondary`|N/A|Yes|Service URL(s) of one or several backup clusters.<br /><br />You can specify several backup clusters using a comma-separated list.<br /><br /> Note that:<br />- The backup cluster is chosen in the sequence shown in the list. <br />- If all backup clusters are available, the Pulsar client chooses the first backup cluster.
+`failoverDelay`|N/A|Yes|The delay before the Pulsar client switches from the primary cluster to the backup cluster.<br /><br />Automatic failover is controlled by a probe task: <br />1) The probe task first checks the health status of the primary cluster. <br /> 2) If the probe task finds the continuous failure time of the primary cluster exceeds `failoverDelayMs`, it switches the Pulsar client to the backup cluster.
+`switchBackDelay`|N/A|Yes|The delay before the Pulsar client switches from the backup cluster to the primary cluster.<br /><br />Automatic failover switchover is controlled by a probe task: <br /> 1) After the Pulsar client switches from the primary cluster to the backup cluster, the probe task continues to check the status of the primary cluster. <br /> 2) If the primary cluster functions well and continuously remains active longer than `switchBackDelay`, the Pulsar client switches back [...]
+`checkInterval`|30s|No|Frequency of performing a probe task (in seconds).
+`secondaryTlsTrustCertsFilePath`|N/A|No|Path to the trusted TLS certificate file of the backup cluster.
+`secondaryAuthentication`|N/A|No|Authentication of the backup cluster.
+
+</TabItem>
+<TabItem value="Controlled cluster-level failover">
+
+This is an example of how to construct a Java Pulsar client to use controlled cluster-level failover. The switchover is triggered by administrators manually.
+
+**Note**: you can have one or several backup clusters but can only specify one.
+
+```java
+public PulsarClient getControlledFailoverClient() throws IOException {
+ Map<String, String> header = new HashMap();
+ header.put("service_user_id", "my-user");
+ header.put("service_password", "tiger");
+ header.put("clusterA", "tokenA");
+ header.put("clusterB", "tokenB");
+
+ ServiceUrlProvider provider =
+ ControlledClusterFailover.builder()
+ .defaultServiceUrl("pulsar://localhost:6650")
+ .checkInterval(1, TimeUnit.MINUTES)
+ .urlProvider("http://localhost:8080/test")
+ .urlProviderHeader(header)
+ .build();
+
+ PulsarClient pulsarClient =
+ PulsarClient.builder()
+ .build();
+
+ provider.initialize(pulsarClient);
+ return pulsarClient;
+}
+```
+
+Parameter|Default value|Required?|Description
+|---|---|---|---
+`defaultServiceUrl`|N/A|Yes|Pulsar service URL.
+`checkInterval`|30s|No|Frequency of performing a probe task (in seconds).
+`urlProvider`|N/A|Yes|URL provider service.
+`urlProviderHeader`|N/A|No|`urlProviderHeader` is a map containing tokens and credentials. <br /><br />If you enable authentication or authorization between Pulsar clients and primary and backup clusters, you need to provide `urlProviderHeader`.
+
+Here is an example of how `urlProviderHeader` works.
+
+
+
+Assume that you want to connect Pulsar client 1 to cluster A.
+
+1. Pulsar client 1 sends the token *t1* to the URL provider service.
+
+2. The URL provider service returns the credential *c1* and the cluster A URL to the Pulsar client.
+
+ The URL provider service manages all tokens and credentials. It returns different credentials based on different tokens and different target cluster URLs to different Pulsar clients.
+
+ **Note**: **the credential must be in a JSON file and contain parameters as shown**.
+
+ ```java
+ {
+ "serviceUrl": "pulsar+ssl://target:6651",
+ "tlsTrustCertsFilePath": "/security/ca.cert.pem",
+ "authPluginClassName":"org.apache.pulsar.client.impl.auth.AuthenticationTls",
+ "authParamsString": " \"tlsCertFile\": \"/security/client.cert.pem\"
+ \"tlsKeyFile\": \"/security/client-pk8.pem\" "
+ }
+ ```
+
+3. Pulsar client 1 connects to cluster A using credential *c1*.
+
+</TabItem>
+
+</Tabs>
+````
\ No newline at end of file
diff --git a/site2/website-next/docs/concepts-cluster-level-failover.md b/site2/website-next/docs/concepts-cluster-level-failover.md
new file mode 100644
index 00000000000..4375913d4f9
--- /dev/null
+++ b/site2/website-next/docs/concepts-cluster-level-failover.md
@@ -0,0 +1,163 @@
+---
+id: concepts-cluster-level-failover
+title: Cluster-level failover
+sidebar_label: "Cluster-level failover"
+---
+
+This chapter describes the concept, benefits, use cases, constraints, usage, working principles, and more information about the cluster-level failover.
+
+### Concept of cluster-level failover
+
+````mdx-code-block
+<Tabs groupId="failover-choice"
+ defaultValue="Automatic cluster-level failover"
+ values={[{"label":"Automatic cluster-level failover","value":"Automatic cluster-level failover"},{"label":"Controlled cluster-level failover","value":"Controlled cluster-level failover"}]}>
+<TabItem value="Automatic cluster-level failover">
+
+Automatic cluster-level failover supports Pulsar clients switching from a primary cluster to one or several backup clusters automatically and seamlessly when it detects a failover event based on the configured detecting policy set by **users**.
+
+
+
+</TabItem>
+<TabItem value="Controlled cluster-level failover">
+
+Controlled cluster-level failover supports Pulsar clients switching from a primary cluster to one or several backup clusters. The switchover is manually set by **administrators**.
+
+
+
+</TabItem>
+
+</Tabs>
+````
+
+Once the primary cluster functions again, Pulsar clients can switch back to the primary cluster. Most of the time users won’t even notice a thing. Users can keep using applications and services without interruptions or timeouts.
+
+### Why use cluster-level failover?
+
+The cluster-level failover provides fault tolerance, continuous availability, and high availability together. It brings a number of benefits, including but not limited to:
+
+* Reduced cost: services can be switched and recovered automatically with no data loss.
+
+* Simplified management: businesses can operate on an "always-on" basis since no immediate user intervention is required.
+
+* Improved stability and robustness: it ensures continuous performance and minimizes service downtime.
+
+### When to use cluster-level failover?
+
+The cluster-level failover protects your environment in a number of ways, including but not limited to:
+
+* Disaster recovery: cluster-level failover can automatically and seamlessly transfer the production workload on a primary cluster to one or several backup clusters, which ensures minimum data loss and reduced recovery time.
+
+* Planned migration: if you want to migrate production workloads from an old cluster to a new cluster, you can improve the migration efficiency with cluster-level failover. For example, you can test whether the data migration goes smoothly in case of a failover event, identify possible issues and risks before the migration.
+
+### When cluster-level failover is triggered?
+
+````mdx-code-block
+<Tabs groupId="failover-choice"
+ defaultValue="Automatic cluster-level failover"
+ values={[{"label":"Automatic cluster-level failover","value":"Automatic cluster-level failover"},{"label":"Controlled cluster-level failover","value":"Controlled cluster-level failover"}]}>
+<TabItem value="Automatic cluster-level failover">
+
+Automatic cluster-level failover is triggered when Pulsar clients cannot connect to the primary cluster for a prolonged period of time. This can be caused by any number of reasons including, but not limited to:
+
+* Network failure: internet connection is lost.
+
+* Power failure: shutdown time of a primary cluster exceeds time limits.
+
+* Service error: errors occur on a primary cluster (for example, the primary cluster does not function because of time limits).
+
+* Crashed storage space: the primary cluster does not have enough storage space, but the corresponding storage space on the backup server functions normally.
+
+</TabItem>
+<TabItem value="Controlled cluster-level failover">
+
+Controlled cluster-level failover is triggered when administrators set the switchover manually.
+
+</TabItem>
+
+</Tabs>
+````
+
+### Why does cluster-level failover fail?
+
+Obviously, the cluster-level failover does not succeed if the backup cluster is unreachable by active Pulsar clients. This can happen for many reasons, including but not limited to:
+
+* Power failure: the backup cluster is shut down or does not function normally.
+
+* Crashed storage space: primary and backup clusters do not have enough storage space.
+
+* If the failover is initiated, but no cluster can assume the role of an available cluster due to errors, and the primary cluster is not able to provide service normally.
+
+* If you manually initiate a switchover, but services cannot be switched to the backup cluster server, then the system will attempt to switch services back to the primary cluster.
+
+* Fail to authenticate or authorize between 1) primary and backup clusters, or 2) between two backup clusters.
+
+### What are the limitations of cluster-level failover?
+
+Currently, cluster-level failover can perform probes to prevent data loss, but it can not check the status of backup clusters. If backup clusters are not healthy, you cannot produce or consume data.
+
+### What are the relationships between cluster-level failover and geo-replication?
+
+The cluster-level failover is an extension of [geo-replication](concepts-replication.md) to improve stability and robustness. The cluster-level failover depends on geo-replication, and they have some **differences** as below.
+
+| Influence | Cluster-level failover [...]
+|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
+| Do administrators have heavy workloads? | No or maybe.<br /><br />- For the **automatic** cluster-level failover, the cluster switchover is triggered automatically based on the policies set by **users**.<br /><br />- For the **controlled** cluster-level failover, the switchover is triggered manually by **administrators**. [...]
+| Result in data loss? | No.<br /><br />For both **automatic** and **controlled** cluster-level failover, if the failed primary cluster doesn't replicate messages immediately to the backup cluster, the Pulsar client can't consume the non-replicated messages. After the primary cluster is restored and the Pulsar client switches back, the non-replicated data can still be consumed by the Pulsar client. Consequently, the data is not lost.<br /><br />- For the **automatic** [...]
+| Result in Pulsar client failure? | No or maybe.<br /><br />- For **automatic** cluster-level failover, services can be switched and recovered automatically and the Pulsar client does not fail. <br /><br />- For **controlled** cluster-level failover, services can be switched and recovered manually, but the Pulsar client fails before administrators can take action. [...]
+
+### How does cluster-level failover work?
+
+This chapter explains the working process of cluster-level failover. For more implementation details, see [PIP-121](https://github.com/apache/pulsar/issues/13315).
+
+````mdx-code-block
+<Tabs groupId="failover-choice"
+ defaultValue="Automatic cluster-level failover"
+ values={[{"label":"Automatic cluster-level failover","value":"Automatic cluster-level failover"},{"label":"Controlled cluster-level failover","value":"Controlled cluster-level failover"}]}>
+<TabItem value="Automatic cluster-level failover">
+
+In an automatic failover cluster, the primary cluster and backup cluster are aware of each other's availability. The automatic failover cluster performs the following actions without administrator intervention:
+
+1. The Pulsar client runs a probe task at intervals defined in `checkInterval`.
+
+2. If the probe task finds the failure time of the primary cluster exceeds the time set in the `failoverDelay` parameter, it searches backup clusters for an available healthy cluster.
+
+ 2a) If there are healthy backup clusters, the Pulsar client switches to a backup cluster in the order defined in `secondary`.
+
+ 2b) If there is no healthy backup cluster, the Pulsar client does not perform the switchover, and the probe task continues to look for an available backup cluster.
+
+3. The probe task checks whether the primary cluster functions well or not.
+
+ 3a) If the primary cluster comes back and the continuous healthy time exceeds the time set in `switchBackDelay`, the Pulsar client switches back to the primary cluster.
+
+ 3b) If the primary cluster does not come back, the Pulsar client does not perform the switchover.
+
+
+
+</TabItem>
+<TabItem value="Controlled cluster-level failover">
+
+1. The Pulsar client runs a probe task at intervals defined in `checkInterval`.
+
+2. The probe task fetches the service URL configuration from the URL provider service, which is configured by `urlProvider`.
+
+ 2a) If the service URL configuration is changed, the probe task switches to the target cluster without checking the health status of the target cluster.
+
+ 2b) If the service URL configuration is not changed, the Pulsar client does not perform the switchover.
+
+3. If the Pulsar client switches to the target cluster, the probe task continues to fetch service URL configuration from the URL provider service at intervals defined in `checkInterval`.
+
+ 3a) If the service URL configuration is changed, the probe task switches to the target cluster without checking the health status of the target cluster.
+
+ 3b) If the service URL configuration is not changed, it does not perform the switchover.
+
+
+
+</TabItem>
+
+</Tabs>
+````
+
+### How to use cluster-level failover
+
+Only Java clients support cluster-level failover at this moment. See [Java client document](client-libraries-java.md#cluster-level-failover).
diff --git a/site2/website-next/docs/tiered-storage-aliyun.md b/site2/website-next/docs/tiered-storage-aliyun.md
index c8c63e2e7ca..c14ef0e93b9 100644
--- a/site2/website-next/docs/tiered-storage-aliyun.md
+++ b/site2/website-next/docs/tiered-storage-aliyun.md
@@ -14,7 +14,7 @@ Follow the steps below to install the Aliyun OSS offloader.
- Pulsar: 2.8.0 or later versions
-This example uses Pulsar 2.8.0.
+### Steps
1. [Download the Pulsar tarball](getting-started-standalone.md#step-1-download-pulsar-distribution).
2. Download and untar the Pulsar offloaders package, then copy the Pulsar offloaders as `offloaders` in the Pulsar directory. See [Install tiered storage offloaders](tiered-storage-overview.md#how-to-install-tiered-storage-offloaders).
diff --git a/site2/website-next/docs/tiered-storage-aws.md b/site2/website-next/docs/tiered-storage-aws.md
index bc5f8bf390e..f13248bf8ac 100644
--- a/site2/website-next/docs/tiered-storage-aws.md
+++ b/site2/website-next/docs/tiered-storage-aws.md
@@ -14,7 +14,7 @@ Follow the steps below to install the AWS S3 offloader.
- Pulsar: 2.4.2 or later versions
-This example uses Pulsar 2.5.1.
+### Steps
1. [Download the Pulsar tarball](getting-started-standalone.md#step-1-download-pulsar-distribution).
2. Download and untar the Pulsar offloaders package, then copy the Pulsar offloaders as `offloaders` in the Pulsar directory. See [Install tiered storage offloaders](tiered-storage-overview.md#how-to-install-tiered-storage-offloaders).
diff --git a/site2/website-next/docs/tiered-storage-azure.md b/site2/website-next/docs/tiered-storage-azure.md
index 54248644bd9..8c68a24a314 100644
--- a/site2/website-next/docs/tiered-storage-azure.md
+++ b/site2/website-next/docs/tiered-storage-azure.md
@@ -14,7 +14,7 @@ Follow the steps below to install the Azure BlobStore offloader.
- Pulsar: 2.6.2 or later versions
-This example uses Pulsar 2.6.2.
+### Steps
1. [Download the Pulsar tarball](getting-started-standalone.md#step-1-download-pulsar-distribution).
2. Download and untar the Pulsar offloaders package, then copy the Pulsar offloaders as `offloaders` in the Pulsar directory. See [Install tiered storage offloaders](tiered-storage-overview.md#how-to-install-tiered-storage-offloaders).
diff --git a/site2/website-next/docs/tiered-storage-filesystem.md b/site2/website-next/docs/tiered-storage-filesystem.md
index 0eefe4758d6..56fadd90368 100644
--- a/site2/website-next/docs/tiered-storage-filesystem.md
+++ b/site2/website-next/docs/tiered-storage-filesystem.md
@@ -20,7 +20,7 @@ This section describes how to install the filesystem offloader.
- Pulsar: 2.4.2 or higher versions
-This example uses Pulsar 2.5.1.
+### Steps
1. [Download the Pulsar tarball](getting-started-standalone.md#step-1-download-pulsar-distribution).
2. Download and untar the Pulsar offloaders package, then copy the Pulsar offloaders as `offloaders` in the Pulsar directory. See [Install tiered storage offloaders](tiered-storage-overview.md#how-to-install-tiered-storage-offloaders).
diff --git a/site2/website-next/docs/tiered-storage-gcs.md b/site2/website-next/docs/tiered-storage-gcs.md
index 638652c8a98..bcc59a1f7e9 100644
--- a/site2/website-next/docs/tiered-storage-gcs.md
+++ b/site2/website-next/docs/tiered-storage-gcs.md
@@ -14,7 +14,7 @@ Follow the steps below to install the GCS offloader.
- Pulsar: 2.4.2 or later versions
-This example uses Pulsar 2.5.1.
+### Steps
1. [Download the Pulsar tarball](getting-started-standalone.md#step-1-download-pulsar-distribution).
2. Download and untar the Pulsar offloaders package, then copy the Pulsar offloaders as `offloaders` in the Pulsar directory. See [Install tiered storage offloaders](tiered-storage-overview.md#how-to-install-tiered-storage-offloaders).
diff --git a/site2/website-next/docs/tiered-storage-s3.md b/site2/website-next/docs/tiered-storage-s3.md
index eac7e19ad04..5f8c675960e 100644
--- a/site2/website-next/docs/tiered-storage-s3.md
+++ b/site2/website-next/docs/tiered-storage-s3.md
@@ -18,8 +18,6 @@ Follow the steps below to install the S3 offloader.
### Steps
-This example uses Pulsar 2.9.3.
-
1. [Download the Pulsar tarball](getting-started-standalone.md#step-1-download-pulsar-distribution).
2. Download and untar the Pulsar offloaders package, then copy the Pulsar offloaders as `offloaders` in the Pulsar directory. See [Install tiered storage offloaders](tiered-storage-overview.md#how-to-install-tiered-storage-offloaders).
diff --git a/site2/website-next/sidebars.json b/site2/website-next/sidebars.json
index 5879f3b36b7..1c8ed289f4d 100644
--- a/site2/website-next/sidebars.json
+++ b/site2/website-next/sidebars.json
@@ -26,6 +26,7 @@
"concepts-architecture-overview",
"concepts-clients",
"concepts-replication",
+ "concepts-cluster-level-failover",
"concepts-multi-tenancy",
"concepts-authentication",
"concepts-topic-compaction",
@@ -198,7 +199,13 @@
{
"type": "category",
"label": "Transactions",
- "items": ["txn-why", "txn-what", "txn-how", "txn-use", "txn-monitor"]
+ "items": [
+ "txn-why",
+ "txn-what",
+ "txn-how",
+ "txn-use",
+ "txn-monitor"
+ ]
},
{
"type": "category",
@@ -274,7 +281,9 @@
{
"type": "category",
"label": "Performance",
- "items": ["performance-pulsar-perf"]
+ "items": [
+ "performance-pulsar-perf"
+ ]
},
{
"type": "category",
@@ -310,7 +319,11 @@
{
"type": "category",
"label": "Adaptors",
- "items": ["adaptors-kafka", "adaptors-spark", "adaptors-storm"]
+ "items": [
+ "adaptors-kafka",
+ "adaptors-spark",
+ "adaptors-storm"
+ ]
},
{
"type": "category",