From e2c51bf1c333c7cb1155e6b8e116bb0fef4524c0 Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Mon, 20 Jul 2026 17:19:26 +0800 Subject: [PATCH 1/3] docs: clarify Global DR network requirements --- docs/en/install/global_dr.mdx | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/en/install/global_dr.mdx b/docs/en/install/global_dr.mdx index 2c8196483..1ee5accac 100644 --- a/docs/en/install/global_dr.mdx +++ b/docs/en/install/global_dr.mdx @@ -77,7 +77,24 @@ The roles of **Primary Cluster** and **Standby Cluster** are relative: the clust * A unified domain which will be the `Platform Access Address`, and the TLS certificate plus private key for serving HTTPS on that domain; * A dedicated virtual IP address for each cluster — one for the **Primary Cluster** and another for the Standby Cluster; - * Preconfigure the load balancer to route TCP traffic on ports `80`, `443`, `6443`, `2379`, and `11443` to the control-plane nodes behind the corresponding VIP. +### Network Requirements + +The unified domain is a prerequisite for disaster recovery. During normal operation, the domain resolves only to the **Primary Cluster** VIP. The Standby Cluster therefore reaches services on the Primary Cluster through the domain or the Primary Cluster VIP. + +Before installing either cluster, complete both of the following network preparations: + +* Configure each cluster's load balancer to forward the required TCP ports on its VIP to the control plane nodes behind that VIP. Configure port `80` only when users access the platform over HTTP. +* Allow the required TCP ports in **both directions** between the Primary Cluster and Standby Cluster networks. Apply the rules to firewalls, security groups, router ACLs, and any other inter-site network controls. + +| TCP port | Service | Why it is required | +|----------|---------|--------------------| +| `443` | platform HTTPS | The Standby Cluster uses the Platform Access Address to reach the active platform. The etcd synchronization plugin uses this address, and logging and monitoring components send alert callbacks to it. | +| `80` | platform HTTP | Required only when users access the platform over HTTP. The connectivity requirement is otherwise the same as for port `443`. | +| `6443` | Kubernetes API server | During installation or reinstallation of the etcd synchronization plugin, the Standby Cluster connects to the active cluster API server to obtain the etcd CA material required for synchronization. | +| `11443` | Built-in image registry | The Standby Cluster pulls platform and plugin images from the registry configured through the Platform Access Address. | +| `2379` | etcd | The etcd synchronization plugin on the Standby Cluster reads etcd data from the Primary Cluster and writes it to the local standby etcd. | + +The network policy must be bidirectional because the cluster roles are reversed after failover. Before failover, the effective service traffic is normally from Standby to Primary. After failover, the former Primary becomes the new Standby and must reach the new Primary on the same ports. This requirement does not make etcd replication bidirectional: only the current Standby Cluster runs synchronization toward its local etcd. ## Procedure From b089d022a45f4a0d24bf04d245a33054ef5b8b5c Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Mon, 20 Jul 2026 18:32:31 +0800 Subject: [PATCH 2/3] docs: use official etcd Synchronizer terminology --- docs/en/install/global_dr.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/en/install/global_dr.mdx b/docs/en/install/global_dr.mdx index 1ee5accac..29067b8e4 100644 --- a/docs/en/install/global_dr.mdx +++ b/docs/en/install/global_dr.mdx @@ -68,7 +68,7 @@ The roles of **Primary Cluster** and **Standby Cluster** are relative: the clust 2. Point the domain to the **Primary Cluster's** VIP and install the **Primary Cluster**; 3. Temporarily switch DNS resolution to the standby VIP to install the Standby Cluster; 4. Copy the ETCD encryption key of the **Primary Cluster** to the nodes that will later be the control plane nodes of Standby Cluster; -5. Install and enable the etcd synchronization plugin; +5. Install and enable ** etcd Synchronizer**; 6. Verify sync status and perform regular checks; 7. In case of failure, switch DNS to the standby cluster to complete disaster recovery. @@ -79,7 +79,7 @@ The roles of **Primary Cluster** and **Standby Cluster** are relative: the clust ### Network Requirements -The unified domain is a prerequisite for disaster recovery. During normal operation, the domain resolves only to the **Primary Cluster** VIP. The Standby Cluster therefore reaches services on the Primary Cluster through the domain or the Primary Cluster VIP. +The unified domain is a prerequisite for disaster recovery. During normal operation, the domain resolves only to the **Primary Cluster** VIP. The Standby Cluster uses the domain to access platform services on the Primary Cluster. Before installing either cluster, complete both of the following network preparations: @@ -88,13 +88,13 @@ Before installing either cluster, complete both of the following network prepara | TCP port | Service | Why it is required | |----------|---------|--------------------| -| `443` | platform HTTPS | The Standby Cluster uses the Platform Access Address to reach the active platform. The etcd synchronization plugin uses this address, and logging and monitoring components send alert callbacks to it. | +| `443` | platform HTTPS | The Standby Cluster uses the Platform Access Address to reach the active platform. ** etcd Synchronizer** uses this address, and logging and monitoring components send alert callbacks to it. | | `80` | platform HTTP | Required only when users access the platform over HTTP. The connectivity requirement is otherwise the same as for port `443`. | -| `6443` | Kubernetes API server | During installation or reinstallation of the etcd synchronization plugin, the Standby Cluster connects to the active cluster API server to obtain the etcd CA material required for synchronization. | +| `6443` | Kubernetes API server | During installation or reinstallation of ** etcd Synchronizer**, the Standby Cluster connects to the active cluster API server to obtain the etcd CA material required for synchronization. | | `11443` | Built-in image registry | The Standby Cluster pulls platform and plugin images from the registry configured through the Platform Access Address. | -| `2379` | etcd | The etcd synchronization plugin on the Standby Cluster reads etcd data from the Primary Cluster and writes it to the local standby etcd. | +| `2379` | etcd | ** etcd Synchronizer** on the Standby Cluster reads etcd data from the Primary Cluster and writes it to the local standby etcd. | -The network policy must be bidirectional because the cluster roles are reversed after failover. Before failover, the effective service traffic is normally from Standby to Primary. After failover, the former Primary becomes the new Standby and must reach the new Primary on the same ports. This requirement does not make etcd replication bidirectional: only the current Standby Cluster runs synchronization toward its local etcd. +The network policy must be bidirectional because the cluster roles are reversed after failover. Before failover, the effective service traffic is normally from Standby to Primary. After failover, the former Primary becomes the new Standby and must reach the new Primary on the same ports. This requirement does not make etcd replication bidirectional: ** etcd Synchronizer** runs only on the current Standby Cluster and writes synchronized data to its local etcd. ## Procedure @@ -250,8 +250,8 @@ If the following components are installed, restart their services: ## Disaster Recovery Process - -This procedure uninstalls the etcd synchronization plugin. Before you uninstall it, confirm that the standby cluster data is consistent with the primary cluster. Uninstalling the plugin while the standby is missing data that the primary holds can cause owner references to resolve incorrectly, and workload-cluster node `Machine` objects — including immutable-OS clusters, where this destroys the backing virtual machine — may be deleted. If the consistency check reports missing or surplus keys, do not uninstall the plugin; resolve the inconsistency or contact technical support first. + +This procedure uninstalls ** etcd Synchronizer**. Before you uninstall it, confirm that the standby cluster data is consistent with the primary cluster. Uninstalling the plugin while the standby is missing data that the primary holds can cause owner references to resolve incorrectly, and workload-cluster node `Machine` objects — including immutable-OS clusters, where this destroys the backing virtual machine — may be deleted. If the consistency check reports missing or surplus keys, do not uninstall the plugin; resolve the inconsistency or contact technical support first. 1. Restart Elasticsearch on the standby cluster in case it is necessary: @@ -281,7 +281,7 @@ This procedure uninstalls the etcd synchronization plugin. Before you uninstall kubectl get machines.platform.tkestack.io ``` -3. Uninstall the etcd synchronization plugin; +3. Uninstall ** etcd Synchronizer**; 4. Remove port forwarding for `2379` from both VIPs; 5. Switch the platform domain DNS to the standby VIP, which now becomes the Primary Cluster; 6. Verify DNS resolution: From 5b77d3a4ef5c5ec2cbdab0fc577fc7a5fb1681c7 Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Mon, 20 Jul 2026 18:49:31 +0800 Subject: [PATCH 3/3] docs: link DR network requirements from prerequisites --- docs/en/install/global_dr.mdx | 2 +- docs/en/install/prepare/prerequisites.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/install/global_dr.mdx b/docs/en/install/global_dr.mdx index 29067b8e4..1e7d11fae 100644 --- a/docs/en/install/global_dr.mdx +++ b/docs/en/install/global_dr.mdx @@ -77,7 +77,7 @@ The roles of **Primary Cluster** and **Standby Cluster** are relative: the clust * A unified domain which will be the `Platform Access Address`, and the TLS certificate plus private key for serving HTTPS on that domain; * A dedicated virtual IP address for each cluster — one for the **Primary Cluster** and another for the Standby Cluster; -### Network Requirements +### Network Requirements \{#network-requirements} The unified domain is a prerequisite for disaster recovery. During normal operation, the domain resolves only to the **Primary Cluster** VIP. The Standby Cluster uses the domain to access platform services on the Primary Cluster. diff --git a/docs/en/install/prepare/prerequisites.mdx b/docs/en/install/prepare/prerequisites.mdx index afe76cdd0..3c8381c1d 100644 --- a/docs/en/install/prepare/prerequisites.mdx +++ b/docs/en/install/prepare/prerequisites.mdx @@ -227,6 +227,6 @@ This rule is designed to ensure that the `global` cluster can receive traffic fr - It is recommended to configure health checks on the LoadBalancer to monitor the port status. -- If you plan to implement a disaster recovery plan for the `global` cluster, you need to open port `2379` for all control plane nodes for ETCD data synchronization between the primary and disaster recovery clusters. +- Global Cluster Disaster Recovery requires load balancer listeners on both cluster VIPs and bidirectional network access between the Primary and Standby Cluster networks. See [Network Requirements](../global_dr.mdx#network-requirements). - The platform only supports HTTPS by default. If HTTP support is required, you need to open the HTTP port for all control plane nodes.