跨集群灾难恢复

本指南介绍如何在两个 ACP 集群之间运行一个 PostgreSQL 数据库,并在第二个站点设置一个只读副本,以便在第一个站点发生故障时将其提升为主库。本指南采用 CloudNativePG 分布式拓扑:在每个站点各创建一个 Cluster 资源,并在 spec.replica 中相互指定对方。kubectl cnpg dr 命令用于注册这对资源、检查状态、在两个站点之间复制证书,以及执行计划内切换和带保护措施的故障转移。控制台实例页面中的 DR 选项卡通过 Job 执行相同的命令(请参阅控制台)。

在据此设计部署之前,请阅读支持声明。跨站点故障转移是需要人工授权的手动操作,两个站点之间的复制是异步的。

TIP

在每条 kubectl 命令中,都应将 CNPG 集群指定为 cluster.postgresql.cnpg.io。在已安装 Cluster API 的 ACP 集群上,裸 cluster 名称会解析为 Cluster API 的资源。

支持声明

项目状态
复制通过固定的 NodePort 进行流式复制,并使用 sslmode: verify-full 验证,此外,两个站点都可以读取 Barman Cloud WAL 归档(如下方的拓扑 C)。异步。
已验证范围v1.29.2-acp.1:Alauda CloudNativePG v1.29.2-acp.1 operator、PostgreSQL 17、Barman Cloud plugin 0.12,在 ACP 4.2.5 和 ACP 4.4.0 之间,amd64,站点之间使用 IPv4,并在第三个集群(ACP 4.1)上运行 DR observer,同时使用 plugin 版本中随附的 kubectl cnpg dr 命令。v1.30.1-acp.1:部署、计划内切换、非计划故障转移和重建均在使用 PostgreSQL 18.6 的预发布版本上运行,位于 ACP 4.4.0 和 ACP 4.2.5 之间,amd64。ACP 4.2.5 一侧对 operator 的镜像设置进行了实验室修改;在该次运行中,两个站点还使用了一个托管在其中一个站点上的对象存储,并且 observer 运行在某个站点上,而非第三个集群中。使用 operator v1.30.1-acp.1 的预发布 CLI(2026-11-09):在 release-1.30-acp kubectl cnpg dr 57d2a2b3f(默认构建)上,使用 CloudNativePG operator v1.30.1-acp.1、PostgreSQL 18.6、Barman Cloud plugin 0.15.1,在同一 ACP 4.4.0(Kubernetes 1.35)的两个业务集群之间运行,架构为 amd64、IPv4,对象存储位于两个站点之外。已运行:部署、直接访问路径、注册、两个方向的计划内切换(gateway 和 direct 上下文)、在源可访问和不可访问时运行 dr failover(--skip-demote-source)、在解除隔离前降级、使用 register replacement 手动重建,以及切换回原站点。该 fence 是实验室 fence,未经过资格验证,且本次运行未测量 RPO。该 CLI 早于这样一项变更:将未指定时间线的实例视为未观测实例;使用此版本的 CLI 时,在一次运行中,对已隔离(cnpg.io/fencedInstances)或不可访问的站点 A 执行降级的故障转移会暂停,而不会完成,并通过 operation resume --skip-demote-source 完成(请参阅非计划故障转移);该暂停和恢复已于 2026-11-10 在 ACP 4.4.0 上进行检查。未运行:控制台、observer 和告警、证书轮换、从归档恢复,以及中断的切换。其他组合未经测试。
所需集群两个 ACP 集群,每个站点一个。站点之间没有仲裁,因此运行数据库不需要第三个集群。对象存储和 DR observer 必须位于两个站点之外(请参阅规划部署)。
计划内切换通过 kubectl cnpg dr switchover 支持:已记录日志,中断后可恢复,完成时不丢失数据。
非计划故障转移kubectl cnpg dr failover:已记录日志,需要人工授权;如果没有丢失站点的已注册隔离范围的 fence 回执,则会拒绝执行(请参阅隔离和非计划故障转移)。该回执是您的确认:故障转移的安全性依赖于您具备资格的基础设施 fence,而命令无法验证该 fence。旧站点上已确认但尚未复制到新站点的数据将会丢失。
故障恢复手动将旧主库重建为存活站点的新克隆,使用 dr register replacement 记录该克隆,然后执行计划内切换(请参阅故障恢复)。不支持将原主库原地重新加入。
ACP 版本ACP 4.1 至 4.4。在 ACP 4.5 上的 DR 尚未得到验证。
控制台实例页面的 DR 选项卡,并且只有一个 ACP global 集群。使用两个 global 集群时,该页面为只读;请使用 CLI。如果 ACP global 丢失,请通过直接访问路径使用 CLI。在此版本中,ACP Global Cluster DR 移动到备用 global 后的控制台不受支持,也未经验证。
站点之间的自动故障转移不提供。两个 ACP 集群之间没有仲裁器。
站点之间的同步复制不支持。
仅 IPv6 的集群、其他存储或架构未验证。

1.30 operator 为每个集群持有的主 Lease 持续时间为 15 s。在 v1.30.1 运行中,未观察到它对切换或故障转移时序产生影响。

测量结果的含义

本指南中的数据来自低负载下每个场景的一次运行(每秒约 4 次写入,每个站点 2 个实例)。这些数据用于显示数量级,并不构成保证。第一张表来自 v1.29.2-acp.1。

观测项值
dr switchover,从开始到操作完成未中断时为 52–66 s
切换中丢失的已确认行无;进行了七次切换,其中三次是有意中断后恢复的
故障转移,从故障发生到新主库首次写入(仅数据库)43–61 s
拓扑 C 中故障转移丢失的行,先切断链路298 行中有 14 行(约 3.3 s 的写入)
仅使用归档复制时丢失的行自上次归档分段以来的全部数据(本次运行中约 58 s)
故障恢复:将旧主库重建为从节点小型数据库为 78–341 s;数据库越大,耗时越长

v1.30.1-acp.1 运行(采用“已验证范围”下列出的限制,每秒约 3 次写入)测得:

观测项值
dr switchover,从开始到受保护五次切换中为 334–349 s;其中大部分时间用于等待受保护(请参阅限制)
切换中丢失的已确认行无;进行了五次切换
故障转移,从将站点 B 提升为主库到首次写入两次均为 184 s,此时对象存储不可访问(请参阅限制)
故障转移中丢失的行切断前没有已确认的数据丢失;切断与其 fence 之间的 2.5 s 内,站点 A 确认了 3 行
将旧主库重建为从节点小型数据库为 87–88 s

应用恢复时间(连接路由、连接池重新连接)不包含在内,并且取决于您的环境。请规划您自己的演练来测量该时间(请参阅演练)。

客户前提条件

本指南涵盖数据库。在生产环境依赖本指南之前,您还需要具备以下条件,而本指南不提供这些条件:

  • 每个站点都有合格的基础设施 fence:能够关闭或隔离所有可以运行该站点数据库 pod 的节点,防止这些节点重新启动,并阻止其卷在其他位置挂载,同时记录执行人员及执行时间。如果没有此条件,请勿执行非计划故障转移(请参阅 Fencing)。
  • 由应用团队负责的应用切换操作步骤:包括 DNS、负载均衡器或 Pooler 变更、连接池、计划任务和直接客户端,以及阻止旧站点接收写入的方法。
  • 用于监控的第三个故障域:位于两个站点之外的位置(第三个集群、VM 或平台的 global 监控),用于运行 DR 观察器及其告警规则,并且已端到端测试告警路由。在站点内部运行的监控器会在该站点丢失时停止发送信号。
  • 位于两个站点之外的对象存储:与其所有者约定基础备份和 WAL 的保留策略,并安排恢复测试。
  • 能够使用 CA 捆绑包验证每个 API server 的 Kubeconfig 上下文(请参阅 Contexts),其中包括每个站点一个直接上下文,该上下文不经过 ACP global,并使用其自身预置的凭证(请参阅 Direct access paths),同时为 DR 职责指定人员(请参阅 Permissions)。
  • 仅适用于控制台:已部署 RDS Framework(rds-operator),并且有一个 ACP global 集群(请参阅 Console)。CLI 不需要这些条件。

选择拓扑

拓扑复制路径用途
C:streaming + 对象存储通过 NodePort 进行 streaming;链路中断时,从节点回退到 WAL 归档推荐。这是支持声明涵盖且被 dr preflight switchover 接受的唯一拓扑。
A:仅对象存储WAL 归档 → 对象存储 → 恢复实验性功能。故障转移会丢失上次归档分段之后的所有数据,以及主库失去对象存储后提交的其他数据。
B:仅 streaming通过 NodePort 进行 streaming实验性功能。如果链路中断而旧主库继续接受写入,这些写入将丢失;长时间中断可能需要完整重新克隆,因为没有任何机制为远程从节点保留 WAL。

本指南的其余部分介绍拓扑 C。

规划部署

开始之前,请记录两个站点的以下信息,并将记录与变更文档一同保存:

项目站点 A(主站点)站点 B(从站点)
拓扑中的站点名称(下方的 site-a、site-b)
ACP 集群和 kubectl 上下文
Namespace
Cluster 名称(下方的 pg-a、pg-b)
对端连接的 streaming 主机名(下方的 pg-a.dr.internal、pg-b.dr.internal)
该主机名解析到的节点 IP
为 streaming 固定的 NodePort(下方的 31581、31582)
对象存储端点、bucket 和前缀
归档 serverName
直接 kubectl 上下文(下方的 site-a-direct):该站点自身的 API server、其 CA,以及该站点使用其令牌的 ServiceAccount
fence 方法(fence.method)以及 fence 必须覆盖的每个节点或 VM(fence.resourceIDs)
紧急情况下如何关闭并隔离该站点的数据库节点(不重启、不重新调度或重新挂载卷),以及由谁执行
谁有权批准切换、故障转移和删除 PVC

此外,请选择一个拓扑名称(下方的 pgdr),以及一个位于两个站点之外、供 DR 观察器使用的位置。

网络

  • 每个站点的数据库 pod 都必须能够双向访问另一个站点节点 IP 上固定的 NodePort:切换后会使用返回路径。
  • 使用防火墙或网络策略,将 NodePort 限制为仅对端站点的地址可访问。NodePort 是集群每个节点地址上的普通 PostgreSQL 端口。
  • 两个站点和观察器都必须能够访问对象存储;观察器还必须能够访问两个站点的 NodePort 和 API server。

请从 pod 而不是节点 shell 检查可达性:pod 网络和节点网络可能不同。

Streaming 主机名

sslmode: verify-full 会检查 server certificate 是否包含从节点连接时使用的主机名。生成的 server certificate 无法将节点 IP 作为名称,因此每个站点都需要一个主机名:从对端的 pod 解析时,该名称必须指向本站点自身的节点 IP,并将其列在 .spec.certificates.serverAltDNSNames 中。

在您的私有 DNS 中添加一条记录;如果没有私有 DNS,则在对端的 namespace 中创建带有手动 Endpoints 的 headless Service。对于站点 A 的主机名,请在站点 B 上执行:

apiVersion: v1
kind: Service
metadata:
  name: peer-site-a
spec:
  clusterIP: None
  ports:
  - { name: postgres, port: 31581, targetPort: 31581, protocol: TCP }
---
apiVersion: v1
kind: Endpoints
metadata:
  name: peer-site-a      # same name as the Service; no selector, so nothing overwrites it
subsets:
- addresses:
  - ip: <site-A node IP 1>
  - ip: <site-A node IP 2>
  ports:
  - { name: postgres, port: 31581, protocol: TCP }

此时主机名为 peer-site-a.<ns>.svc.cluster.local。在站点 A 上为站点 B 创建镜像对象。站点 A 的节点发生变化时,请更新 Endpoints。本指南其余部分使用 pg-a.dr.internal 和 pg-b.dr.internal 表示这两个主机名。

对象存储

使用专用于 DR 归档的 bucket,启用 HTTPS、防止通过生命周期策略删除,并为每个站点配置两种凭证:

  • 用于归档、可写入该站点自身前缀的写入凭证;
  • 用于恢复、可读取对端前缀的读取凭证。

Barman Cloud plugin 不会检查对端凭证是否为只读:请在对象存储策略中仅授予该凭证读取对端前缀的权限,并测试该策略。共享或测试 bucket 可能会被您无法控制的作业清空。

使用专用于 DR 归档且托管在两个站点之外的 bucket。切勿将对象存储托管在这两个站点中的任何一个上。故障转移期间被提升的站点会先从已丢失站点的归档中恢复 WAL:如果该存储也随已丢失站点一同宕机,提升操作会等待恢复超时(请参阅 Limitations)。如果每个站点使用一个对象存储,请将每个对象存储托管在另一个站点之外。

The plugin

dr 命令属于 Alauda 构建的 kubectl cnpg plugin;上游 CloudNativePG plugin 不包含这些命令。使用一个 kubeconfig,其中包含每个站点的上下文:

  • 每个上下文都必须使用 CA bundle 验证其 API server(certificate-authority-data 或 certificate-authority);更改集群的命令会拒绝不包含 CA 的上下文(context "..." has no CA bundle ... mutating dr commands require one),因此无法注册不含 CA 的控制台 kubeconfig。从 ACP 控制台下载的 kubeconfig 可能会跳过该检查:使用前请添加 CA;
  • 跨两个站点执行的命令需要 --from-context 和 --to-context,并拒绝全局的 --context、--server、--cluster、--tls-server-name 和 --insecure-skip-tls-verify 标志,以确保不会将一个端点应用到两侧;
  • -n 设置两侧的 namespace。

每次执行更改集群的命令之前,plugin 都会打印其在两侧连接的对象信息(API server、CA 指纹、namespace、Cluster UID、系统 ID 和用户),并请求确认。请仔细阅读这些信息。

直接访问路径

ACP 提供的上下文通过 ACP global 上的平台网关访问各个站点。如果 ACP global 丢失,这些上下文将无法访问任何内容。请为每个站点提供一个用于访问其自身 API server 的第二个直接上下文,并将其注册在 accessPaths 下:

  • 每条直接访问路径都需要自己的凭证,并且必须在 ACP global 正常运行时配置。 网关上下文的 ACP (dex) 令牌不能用于直接 API server 认证:register 会因 its credential does not authenticate (401) 拒绝该路径。该站点上的 ServiceAccount 令牌可以使用。
  • 使用凭证时,该凭证必须有效。 为直接访问路径签发的 ServiceAccount 令牌(kubectl create token ... --duration ...)会在所选有效时长结束时过期:请在过期前以及每次故障转移演练前签发新令牌。过期令牌在需要使用时会像缺少令牌一样失效。在验证过程中,register 曾因直接访问路径使用过期的 ServiceAccount 令牌而拒绝该路径,并显示 its credential does not authenticate (401);inspect 和 preflight 则报告 the server has asked for the client to provide credentials。register 随 401 打印的 ACP 登录提示不适用于过期的 ServiceAccount 令牌:请改为签发新令牌。 控制台不会使用这些令牌:它会在每个站点为每项操作签发一个新的 20 分钟 dr-promoter 令牌(请参阅 Console)。
  • 该路径的主体必须能够读取站点的 Namespace。 register 会比较通过每条路径看到的 namespace UID 与通过 context 看到的 UID,并拒绝报告该 UID 为 unknown 的路径。请将 inspector.yaml 的 namespace-reader ClusterRole 绑定到该主体。示例调用将该 ClusterRole 标记为 Optional:对于直接访问路径,它是必需的。
  • 每个上下文(无论是网关上下文还是直接上下文)都需要 CA bundle。

控制台

Data Services 控制台中 CloudNativePG 实例页面的 DR 选项卡会显示已注册的配对,并启动切换和故障转移。它会在站点上(即执行器)通过 Job 运行 kubectl cnpg dr 命令,并为每个站点的 dr-promoter ServiceAccount 使用短期令牌。

  • 前提条件:仅当已部署 RDS Framework(rds-operator)时,控制台才会列出 CloudNativePG 实例;如果未部署,页面会显示 RDS Framework has not been deployed。在验证中(ACP 4.4.0、rds-operator v4.4.0,与 CloudNativePG 一同部署超过三天),它对 CloudNativePG 没有影响,不拥有对 postgresql.cnpg.io 资源的任何权限,也不拥有 DR namespace 中的任何资源;使用它时,控制台切换和故障转移均通过。CLI 不需要它。
  • ACP 项目和 acpCluster。Cluster 的 namespace 必须在每个站点都属于一个 ACP 项目,并且 topology.yaml 的每个站点都需要 acpCluster:即其 ACP 集群的名称,控制台通过该名称读取它。它不是站点身份的一部分,也没有安全检查会读取它。
  • 只能有一个 ACP global。存在两个 ACP global 时,页面为只读;请使用 CLI。如果 ACP global 丢失,请使用带有直接访问路径的 CLI(kubectl cnpg dr failover)。本版本不支持也未验证将 ACP Global Cluster DR 移动到备用 global 后使用控制台的场景。
  • 谁可以启动操作。页面会使用 serviceaccounts/token 创建 dr-promoter 令牌,而 ACP 项目管理员默认没有该权限。在两个站点上应用 operator-token.yaml(角色 cnpg-dr-operator-token:针对 serviceaccounts/token 执行 create,且仅适用于 dr-promoter ServiceAccount),并将其绑定到执行 DR 操作的人员。dr-promoter ServiceAccount 本身来自两个站点上的 promoter-serviceaccount.yaml,并具有 promoter-admission.yaml(请参阅 Permissions)。
  • 令牌。对于每项操作,页面都会创建执行器 Job、每个站点上的 anchor Secret,以及每个站点一个绑定到该 anchor 的 dr-promoter 令牌,有效期为 1200 秒(即 Job 的 900 秒 deadline 加上余量)。删除 Job 和 anchor 会撤销这些令牌;恢复执行时会获取新令牌。它构建的 kubeconfig 使用每个站点的已注册访问路径。
  • 设置向导是生成器。它会生成 topology.yaml、RBAC 清单以及供你检查和运行的脚本;不会自行运行设置操作。
  • 故障转移后,页面会显示红色警告,指出旧站点在重建之前处于未受保护状态(请参阅 Failback)。

部署

1. 对象存储(两个站点)

从文件创建凭证 Secret,使密钥不会出现在命令行或 shell 历史记录中:

kubectl --context site-a -n <ns> create secret generic archive-site-a-write \
  --from-file=ACCESS_KEY_ID=./site-a-write-key-id \
  --from-file=ACCESS_SECRET_KEY=./site-a-write-secret
kubectl --context site-a -n <ns> create secret generic archive-site-b-read \
  --from-file=ACCESS_KEY_ID=./site-b-read-key-id \
  --from-file=ACCESS_SECRET_KEY=./site-b-read-secret

在站点 A 上,为其自身前缀创建一个 ObjectStore,并为对端前缀创建一个:

apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
  name: site-a-own
spec:
  retentionPolicy: 14d
  configuration:
    destinationPath: s3://<bucket>/site-a
    endpointURL: https://<object-store-endpoint>
    s3Credentials:
      accessKeyId: { name: archive-site-a-write, key: ACCESS_KEY_ID }
      secretAccessKey: { name: archive-site-a-write, key: ACCESS_SECRET_KEY }
    wal: { compression: gzip }
---
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
  name: site-b-peer
spec:
  configuration:
    destinationPath: s3://<bucket>/site-b
    endpointURL: https://<object-store-endpoint>
    s3Credentials:
      accessKeyId: { name: archive-site-b-read, key: ACCESS_KEY_ID }
      secretAccessKey: { name: archive-site-b-read, key: ACCESS_SECRET_KEY }
    wal: { compression: gzip }

在站点 B 上进行镜像配置:site-b-own(写入,前缀为 site-b)和 site-a-peer(读取,前缀为 site-a)。如果端点使用私有 CA,请将 endpointCA 添加到每个 ObjectStore。

2. 站点 A 上的主集群

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: pg-a
spec:
  instances: 2
  storage: { size: 10Gi }   # add storageClass: <name> if the cluster has no default StorageClass
  postgresql:
    parameters: { archive_timeout: "30s", wal_keep_size: "512MB" }
  certificates:
    serverAltDNSNames: [ pg-a.dr.internal ]
  bootstrap:
    initdb: { database: app, owner: app }
  managed:
    services:
      additional:
      - selectorType: rw
        serviceTemplate:
          metadata: { name: pg-a-rw-dr }
          spec:
            type: NodePort
            ports:
            - { name: postgres, port: 5432, targetPort: 5432, protocol: TCP, nodePort: 31581 }
  plugins:
  - name: barman-cloud.cloudnative-pg.io
    isWALArchiver: true
    parameters: { barmanObjectName: site-a-own, serverName: site-a }
WARNING

固定 nodePort。否则,重建的集群会获得新的端口,从而导致对端的连接设置失效。

wal_keep_size 是站点 A 为流式连接中断的从节点保留的 WAL;更长的间隔会从归档中填充。 将其大小设置为至少峰值每秒 WAL 字节数 × 希望能够承受的中断时长 × 1.5,并为其在 WAL 卷上预留空间。

3. 将站点 A 的凭证复制到站点 B

站点 B 从站点 A 克隆,因此首先需要站点 A 的 CA 证书和复制客户端证书。在配对注册之前,使用 --bootstrap 复制它们:

for kind in peer-ca replication-leaf; do
  kubectl cnpg dr credentials sync pgdr --bootstrap --kind $kind \
    --from-site site-a --to-site site-b \
    --from-context site-a --to-context site-b \
    --from-cluster pg-a --to-cluster pg-b -n <ns>
done

此命令会将 dr-peer-site-a-ca(仅 ca.crt)和 dr-peer-site-a-replication(tls.crt 和 tls.key,在检查密钥与证书匹配且证书签发给 streaming_replica 后)写入站点 B。它不会解码或复制 ca.key,即用于签署站点 A 证书的密钥。副本会添加标签;只有带有这些标签的现有 Secret 才会被覆盖。公共 receipt ConfigMap 会记录每个副本的指纹和有效期。

运行该命令的用户需要在站点 A 的 pg-a-ca 和 pg-a-replication Secret 上拥有 get:Kubernetes API 会返回完整的 Secret,因此即使命令不使用 CA 私钥,此职责也可以读取它。请由保管员负责此操作(请参阅 Permissions)。

4. 站点 B 上的从集群

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: pg-b
spec:
  instances: 2
  storage: { size: 10Gi }
  postgresql:
    parameters: { archive_timeout: "30s", wal_keep_size: "512MB" }
  certificates:
    serverAltDNSNames: [ pg-b.dr.internal ]
  bootstrap:
    pg_basebackup: { source: pg-a }
  replica: { self: pg-b, primary: pg-a, source: pg-a }
  managed:
    services:
      additional:
      - selectorType: rw
        serviceTemplate:
          metadata: { name: pg-b-rw-dr }
          spec:
            type: NodePort
            ports:
            - { name: postgres, port: 5432, targetPort: 5432, protocol: TCP, nodePort: 31582 }
  plugins:
  - name: barman-cloud.cloudnative-pg.io
    isWALArchiver: true
    parameters: { barmanObjectName: site-b-own, serverName: site-b }
  externalClusters:
  - name: pg-b
    plugin: { name: barman-cloud.cloudnative-pg.io, parameters: { barmanObjectName: site-b-own, serverName: site-b } }
  - name: pg-a
    connectionParameters:
      host: pg-a.dr.internal
      port: "31581"
      user: streaming_replica
      dbname: postgres
      sslmode: verify-full
      tcp_user_timeout: "10000"
    sslCert: { name: dr-peer-site-a-replication, key: tls.crt }
    sslKey: { name: dr-peer-site-a-replication, key: tls.key }
    sslRootCert: { name: dr-peer-site-a-ca, key: ca.crt }
    plugin: { name: barman-cloud.cloudnative-pg.io, parameters: { barmanObjectName: site-a-peer, serverName: site-a } }

必须配置以下三项:

  • replica.self 必须列在 externalClusters 中。 否则,admission webhook 会拒绝带有 External cluster pg-b not found 的 Cluster。
  • 必须在流式连接上设置 tcp_user_timeout。 当链路静默丢弃数据包(防火墙丢弃或网络分区)时,否则 WAL receiver 会等待内核连接超时后才失败;每台主机大约需要 130 秒。PostgreSQL 仅在连接尝试之间读取 WAL 归档,因此归档回退会停滞数分钟。 connect_timeout 没有帮助:WAL receiver 会异步连接并忽略它(在验证中,网络静默丢弃数据包时,一次 WAL receiver 连接尝试耗时 263 秒)。使用 tcp_user_timeout: "10000" 后,每次尝试会在约 10 秒后失败,并且从节点会继续从归档恢复。
  • 使用 sslmode: verify-full,并配置站点 A 在 serverAltDNSNames 中列出的主机名,以及从 dr-peer-site-a-* 复制的证书。 dr preflight switchover 会拒绝任何其他设置。

应用凭证

WARNING

两个站点必须使用同一个应用 Secret。使用 Cluster 引导的 initdb 会生成自己的 <cluster>-app Secret,并包含随机密码;而使用 pg_basebackup 引导的从节点(例如站点 B)没有该 Secret,也没有任何机制在站点之间使它们保持一致。只有主集群会将该 Secret 应用到数据库,并且每个实例管理器对给定版本的 Secret 在每个进程中只应用一次。使用两个不同的 Secret 时,切换后生效的密码取决于哪些 Pod 在切换前重启过,应用将失去访问权限。

创建站点 B 后,将站点 A 的应用 Secret 复制到站点 B,且不要将其打印出来,然后检查两个站点是否保存了相同的数据。 在验证中,pg-b-app 在 pg_basebackup 从节点上不存在,因此 patch 因 NotFound 而失败;apply 会创建它,或在重建后更新它:

kubectl --context site-a -n <ns> get secret <cluster>-app -o json \
  | jq '{apiVersion, kind, type, data, metadata: {name: .metadata.name}}' \
  | kubectl --context site-b -n <ns> apply -f -
for ctx in site-a site-b; do
  kubectl --context $ctx -n <ns> get secret <cluster>-app -o json | jq -S .data | sha256sum
done

当两个 Cluster 资源具有相同的名称和 namespace 时(如验证中所示),直接复制整个 Secret 是正确的:此时,host、uri、 jdbc-uri、fqdn-uri、fqdn-jdbc-uri 和 pgpass 会在两个站点上分别指向正确的 Service。如果名称不同,例如本指南中的 pg-a 和 pg-b,请将 username 和 password 复制到 pg-b-app,并重建其中嵌入站点 B 主机名和密码的密钥(此变体未经验证);或者让应用根据 username 和 password 构建连接。

站点重建后,在将其切换为活动站点之前,重新执行复制操作(请参阅 Failback)。如果启用超级用户访问,<cluster>-superuser 也同样适用。

5. 站点 A 上的返回路径

将拓扑添加到 pg-a,使其能够在切换后跟随站点 B:

kubectl --context site-a -n <ns> patch cluster.postgresql.cnpg.io pg-a --type merge -p '
{"spec":{"replica":{"self":"pg-a","primary":"pg-a","source":"pg-b"},
 "externalClusters":[
  {"name":"pg-a","plugin":{"name":"barman-cloud.cloudnative-pg.io","parameters":{"barmanObjectName":"site-a-own","serverName":"site-a"}}},
  {"name":"pg-b","connectionParameters":{"host":"pg-b.dr.internal","port":"31582","user":"streaming_replica","dbname":"postgres","sslmode":"verify-full","tcp_user_timeout":"10000"},
   "sslCert":{"name":"dr-peer-site-b-replication","key":"tls.crt"},"sslKey":{"name":"dr-peer-site-b-replication","key":"tls.key"},"sslRootCert":{"name":"dr-peer-site-b-ca","key":"ca.crt"},
   "plugin":{"name":"barman-cloud.cloudnative-pg.io","parameters":{"barmanObjectName":"site-b-peer","serverName":"site-b"}}}]}}'

然后将站点 B 的凭证复制到站点 A:

for kind in peer-ca replication-leaf; do
  kubectl cnpg dr credentials sync pgdr --bootstrap --kind $kind \
    --from-site site-b --to-site site-a \
    --from-context site-b --to-context site-a \
    --from-cluster pg-b --to-cluster pg-a -n <ns>
done
INFO

请保持此顺序。--bootstrap 拒绝写入未在 .spec.replica.source(pg-a does not name pg-b)中指明源站点的 Cluster,因此必须先应用补丁。

6. 注册配对

在文件 topology.yaml 中描述两个站点:

name: pgdr
sites:
- site: site-a
  context: site-a
  namespace: <ns>
  cluster: pg-a
  streamingHost: pg-a.dr.internal
  streamingPort: 31581
  archiveServerName: site-a
  fenceScope: "how site A's database nodes are powered off, and by whom"
  fence:
    method: <your fence method>
    resourceIDs: [<every node or VM a fence of site A must cover>]
  accessPaths:
  - name: direct
    context: site-a-direct
- site: site-b
  context: site-b
  namespace: <ns>
  cluster: pg-b
  streamingHost: pg-b.dr.internal
  streamingPort: 31582
  archiveServerName: site-b
  fenceScope: "how site B's database nodes are powered off, and by whom"
  fence:
    method: <your fence method>
    resourceIDs: [<every node or VM a fence of site B must cover>]
  accessPaths:
  - name: direct
    context: site-b-direct
  • context 是命令访问站点所通过的 context,例如 ACP gateway。
  • accessPaths 列出访问同一站点的其他 context,例如站点自身的 API server。每个站点至少注册一条直接路径(请参阅 Direct access paths):仅通过 ACP gateway 注册的拓扑在 ACP global 丢失后无法执行故障转移。在验证中,此类故障转移因 site "site-a" (context "...") is not reached through its registered identity 而被拒绝;添加直接的 accessPaths 后则成功。 register 会检查每条路径是否到达相同的 namespace 和 Cluster,并使用不同的 API server。
  • fence 是结构化的隔离范围:方法以及对站点执行隔离时必须覆盖的每个资源。未配置该项的站点无法执行故障转移。fence.method 是你为合格隔离操作步骤指定的标识符,例如 bmc-power-off-v2:它不能为空;工具只会将其与 receipt 进行比较,并将其记录在日志中,不会对其进行解释。fenceScope 保留为事故操作步骤的自由文本备注。

然后注册配对:

kubectl cnpg dr register --file topology.yaml --dry-run   # review what it writes
kubectl cnpg dr register --file topology.yaml

register 除非两个站点均可访问、具有相同的非空 system ID 并且彼此互相指明对方,否则拒绝继续。它会在两个站点上写入不可变的注册 ConfigMap(dr-registration-pgdr-r1,包含双方的 UID、system ID、API server 和 CA 指纹)、指针 dr-registration-pgdr、操作日志 dr-operation-pgdr,以及每个 Cluster 上的注释。此后,每个 dr 命令都会拒绝 UID 或 system ID 与注册信息不同的 Cluster:已删除并重新创建的集群不会被静默采用。fenceScope 仅会被记录,供事故操作步骤使用;不会对其进行检查。

不要以 dr-promoter ServiceAccount 运行 register、credentials sync 或 dr bootstrap:它们需要保管员权限(请参阅 Permissions)。

注册后,--bootstrap 会被拒绝。使用普通的 credentials sync 刷新副本,并提供 namespace 和两个 context:

kubectl cnpg dr credentials sync pgdr --kind <peer-ca|replication-leaf> \
  --from-site site-a --to-site site-b -n <ns> --from-context site-a --to-context site-b

7. 验证

D="-n <ns> --from-context site-a --to-context site-b"
kubectl cnpg dr inspect pgdr $D                 # both sides, cross-site findings
kubectl cnpg dr credentials check pgdr $D       # copies match their sources, expiry
kubectl cnpg dr preflight switchover pgdr $D    # every check must pass

inspect 为只读操作,即使一侧不可访问也能运行。对于每一侧,它会显示注册信息、期望角色(来自 .spec.replica.primary)和观察到的角色、证书到期时间,以及是否存在未完成的操作。其发现结果具有严重性:两个集群被指定为或被观察为主集群,或者 UID 或 system ID 与注册信息不一致,均属于 critical。-o json 为你自己的检查提供稳定的 schema。

如果某站点当前的主集群被列在 Cluster 状态中但没有 timeline(operator 无法访问该站点,或者其 PostgreSQL 未运行,例如站点已被隔离),则不会观察到该站点:其观察到的角色为 unknown (instance <pod> is listed with no timeline: not reached, or PostgreSQL is not running (fenced))。如果该条目仍声称自己已脱离恢复状态,而另一站点报告其为主集群,inspect 会报告 critical 发现项 unconfirmed-observed-primary,而不是 both-observed-primary:

side <side>: current primary <pod> is listed out of recovery with no timeline (not reached, or not running), while side <side> reports a primary: split-brain cannot be ruled out until it is fenced or reached

在宣布部署就绪之前,请在站点 A 写入一行测试数据,并在站点 B 读取该行。

监控

CloudNativePG 的站点级指标无法区分空闲的源端和故障的副本,并且在所在站点丢失时会停止工作。DR observer(kubectl cnpg dr observe)弥补了这一缺口。它运行在第三个故障域中,每 10 秒读取两个站点的数据。它还会在主集群上写入一行心跳数据,并测量该行数据在副本上的时效。它绝不会提升、降级或修补任何内容。

清单位于 operator 仓库中的 docs/src/samples/dr/observer/ 和 docs/src/samples/monitoring/ 下:

  1. 心跳 schema:在站点 A 的主集群上,以超级用户身份执行一次。它会创建 cnpg_dr.heartbeat 表,以及一个只能读取和更新该表、并调用两个只读函数的 dr_observer 角色;该表会复制到站点 B:

    # the topologyUID of the registration
    kubectl --context site-a -n <ns> get configmap dr-registration-pgdr-r1 \
      -o jsonpath='{.data.registration\.json}'
    # run on the current primary pod of pg-a (.status.currentPrimary)
    kubectl --context site-a -n <ns> exec -i <pg-a primary pod> -c postgres -- \
      psql -d postgres -v topology_uid=<topologyUID> < heartbeat.sql

    psql 在 pod 内运行,因此脚本通过标准输入传入。通过 .spec.managed.roles 中的 passwordSecret,为 dr_observer 提供密码,并在两个 Cluster 资源上都进行配置,以便在计划切换后继续有效。

  2. Observer(observer/):在第三个故障域中部署使用 kubectl-cnpg-dr-observer 镜像的 Deployment。使用标签形式设置镜像 <registry>/eco-oss/postgres/kubectl-cnpg-dr-observer:<operator version>,标签应与已安装的 operator release 一致。不要使用 digest(@sha256:...)引用:ACP ImageWhiteList 重写会匹配引用字符串,因此 digest 引用不会被重写为平台 registry,而是从源 registry 拉取;在隔离网络集群中这会失败。为每个站点配置 SQL 端点(pg-a.dr.internal:31581、verify-full),并设置 expectedAuthority: site-a。

    • 每个站点的 CA:使用 sql.caFrom: peer-copy。随后,observer 会从站点 B 上 dr-peer-site-a-ca 的副本中读取站点 A 的 CA(反之亦然);只有当 CA 带有副本标签且与其接收记录匹配时才会接受,否则会保留上一次接受的 CA。CA 轮换并执行 credentials sync 后,observer 会在约一分钟内使用新的 CA,无需重启。另一种方式是使用 sql.caFile,并为每个站点挂载一个 Secret;但每次轮换或重建后都必须手动刷新。
    • 每个站点的 Kubeconfig:为该站点上的主体配置权限,将其绑定到 inspector Role 和 observer-rbac.yaml 的 observer Role;该角色仅允许对两个 dr-peer-*-ca Secret 执行 get(其中只包含 ca.crt,绝不包含 ca.key)。站点命名空间中的 ServiceAccount 配合有时限的令牌(kubectl create token)即可通过 ACP API proxy 工作;请在令牌过期前续期。
    • 主机名:observer 会验证其连接的主机名。如果它通过自身的名称解析站点,例如通过其命名空间中的无头 Service 解析,则还要将这些名称添加到两个 Cluster 资源的 serverAltDNSNames 中。
  3. 告警规则(prometheusrule-dr-observer.yaml):部署在第三个故障域的 Prometheus 或 VictoriaMetrics 上。编辑 expected-topology 组:site-b 是预期的副本,以及预期进行流式复制的站点。

  4. 站点指标(podmonitor-dr-sites.yaml):部署在每个站点的命名空间中,并使用该站点的 dr_site 值,用于归档和备份告警。

示例同时带有 prometheus: kube-prometheus(ACP Prometheus)和 victoriametrics: victoriametrics(ACP 4.4,会自动转换为 VictoriaMetrics 对象)标签;请保留两者。

告警含义首要响应
CNPGDRSiteUnobservableobserver 无法读取某个站点检查站点以及从 observer 到该站点的路径;将其视为可能的站点丢失,而不是执行故障转移的理由
CNPGDRExpectedReceiverDown预期的副本未进行流式复制检查链路、NodePort 和证书;该副本现在仅从归档中推进
CNPGDRRecoveryStale副本上的心跳数据已超过预算时间(120 秒)副本未从流或归档中重放数据;故障转移时的风险数据量正在增加
CNPGDRRecoveryObservationMissingobserver 无法读取预期副本上的心跳数据检查副本所在站点以及 observer 到该站点的路径;在告警解除前,无法得知重放时效
CNPGDRHeartbeatWriterUnavailable无法在预期的主集群上提交心跳数据检查站点 A 是否接受写入
CNPGDRConflictingWriters多个站点接受写入脑裂。停止当前不应作为主集群的站点上的写入
CNPGDRCredentialCopyMismatch对等站点上的副本不再与其源端匹配针对相应类型和方向运行 credentials sync
CNPGDRCertificateExpiringDR 证书将在 14 天内过期(7 天:严重)续期,然后运行 credentials sync
CNPGDRObserverCASourceInvalidobserver 已连续 5 分钟拒绝某站点的 dr-peer-<site>-ca 副本,或无法读取该副本,并使用其上一次接受的 CA 进行探测运行 credentials check,然后运行 credentials sync;否则,该站点下一次 CA 轮换会使 observer 失去感知能力
CNPGDRWALArchiveFailing、CNPGDRWALArchiveBacklog归档失败,或 WAL 正在等待归档检查对象存储端点和凭证
CNPGDRBaseBackupTooOld26 小时内没有基础备份检查计划备份
CNPGDRObserverDown、CNPGDRClockUnknownobserver 本身未正常工作,或其时钟不可信恢复 observer;在此之前,DR 处于未监控状态

这些规则会将观测结果与预期拓扑进行比较。每次计划切换或故障转移后,都要更新 observer 配置中的 expectedAuthority 以及规则的 expected-topology 组;在完成更新之前,observer 会告警拓扑与预期不符。

规则已加载,并不意味着有人会收到告警:请将所依赖的每条告警都作为演练的一部分进行测试。

计划切换

在不丢失数据的情况下,将主库从站点 A 切换至站点 B。请在维护窗口内进行规划;如果应用无法容忍几秒钟的只读时间,请先停止应用写入。每次只能由一人执行切换,并且必须在已记录的变更下进行。

  1. 检查并规划。plan switchover 会执行预检并打印确切的变更;它不需要凭证,也不会进行任何变更:

    D="-n <ns> --from-context site-a --to-context site-b --from-cluster pg-a --to-cluster pg-b"
    kubectl cnpg dr plan switchover pgdr $D --output-file plan.json

    使用直接上下文且每个站点使用不同的 Cluster 名称时,命令需要 --from-cluster 和 --to-cluster;请始终提供这两个参数。

  2. 使用该计划运行。对于注册信息、站点、Cluster UID 或 API server 已不再匹配的计划,命令会拒绝执行:

    kubectl cnpg dr switchover pgdr $D --plan plan.json

    命令会打印两端的身份信息并请求确认(在脚本中,--yes 可跳过提示)。随后,它会声明两个 Cluster 资源,使站点 A 降级,等待其降级令牌,并等待站点 A 的每个实例进入恢复状态;然后使用该令牌提升站点 B,等待站点 A 跟随,并释放声明。每个步骤都会先记录在日志中(站点 B 上为 dr-operation-pgdr),再发送出去;每次变更都是条件补丁,如果其他人已更改 Cluster,操作就会失败。

  3. 将应用流量移至站点 B,然后更新 observer 和规则(参见监控)。

如果要在站点 B 接受写入后立即移动流量,请添加 --until database:命令会在此处停止,操作将保持打开状态,直到你使用 kubectl cnpg dr operation resume pgdr <operation ID> $D 完成操作。

如果计划切换被中断

命令会打印其操作 ID。如果操作被中断(连接丢失、终端关闭或发生崩溃),请查看日志,然后按照它打印的下一步安全操作执行:

kubectl cnpg dr operation inspect pgdr $D
kubectl cnpg dr operation resume pgdr <operation ID> $D
退出代码含义执行此操作
0已达到请求的里程碑无需操作
3已暂停:无法观测到某项变更的结果恢复对两个站点的访问,然后运行 operation resume
4已暂停:操作之外的某项变更更改了 Cluster查明谁更改了什么(operation inspect),然后运行 operation resume
5存在打开或待处理的操作operation inspect,然后运行 operation resume;在其关闭前会拒绝新的 switchover
6数据库已切换,但保护尚未得到验证:尚未观测到旧站点跟随新的主库,或尚未确认归档通常只需几分钟(参见限制):再次运行 operation resume;该命令会列出仍缺少的内容
1其他任何错误阅读消息
  • 一旦要求站点 A 停止,就无法回滚。 恢复操作应向前推进:继续执行该操作。operation abort 仅在任何角色发生变更之前(阶段 PREPARED 和 CLAIMED)有效,之后会被拒绝。
  • 如果无法干净地停止首个执行者(例如跳转主机崩溃),请在可能的情况下停止它,然后使用 operation resume pgdr <operation ID> $D --take-over 接管:之前执行者的变更随后会无法通过检查。
  • 降级后,切勿手动重新提升站点 A,也切勿从站点 B 移除提升令牌。如果完全无法使用该插件,站点 B 上的 kubectl get configmap dr-operation-pgdr -o jsonpath='{.data.journal\.json}' 会显示阶段和待处理的变更。

再次运行 switchover 并提供已完成操作的 ID 时,会返回其记录的结果且不会进行任何变更;已用于其他操作的 ID 会被拒绝。

故障转移前的隔离

故障转移会在没有令牌的情况下提升站点 B。如果站点 A 仍在运行,且任何客户端仍可访问它,则两个站点都会接受写入,而站点 A 上的写入会在重建站点 A 时丢失。

故障转移前,获授权执行故障转移的人员必须使用基础设施平台,而不是站点 A 的 Kubernetes API,确认站点 A 的每个 PostgreSQL 实例都已停止且无法重新启动:

  • 关闭或隔离所有能够运行站点 A 数据库 Pod 的节点,而不仅是当前正在运行这些 Pod 的节点;
  • 禁用任何可能使这些 Pod 恢复运行的机制:自动重启、自动扩缩容、重新调度到其他节点;
  • 确保站点 A 的数据库卷无法挂载到其他节点。

从基础设施所有者处获取书面记录:隔离了什么、由谁执行、何时执行,以及如何保持隔离。没有记录,就不能执行故障转移。你在 dr failover 的隔离回执中声明的就是这份记录。

我们自己的演练使用的是操作步骤级别的重启保持,而不是合格的隔离,并记录为 fenceQualified=false。发布版本的插件拒绝演练功能:客户无法使用演练配置文件。

仅隔离站点 A 的网络本身并不足够:分区内部的任何对象(例如本地作业)仍可向 PostgreSQL 写入,而且隔离不会阻止重启。无法访问的 API、失败的 ping,或设置 cnpg.io/fencedInstances 注解,都不能证明站点 A 已停止写入:operator 会在关停完成前设置该注解,并在某些转换过程中将其移除。任何 kubectl cnpg dr 命令也不会执行隔离。

保持站点 A 处于隔离状态,直到它已完成重建(参见故障恢复)。站点 A 恢复后,绝不能重新加入应用。

非计划故障转移

WARNING

故障转移会在没有降级令牌的情况下提升站点 B,并丢失站点 B 尚未接收的数据。其安全性依赖于你对站点 A 执行的合格基础设施隔离:该命令会检查你的隔离回执是否完整、是否为最新、是否绑定到此操作以及已注册的隔离范围,而不会检查隔离是否真实存在。只有在具备隔离记录时才能运行该命令。

  1. 确定站点 A 已丢失。站点之间的链路中断不等于站点丢失:如果站点 A 仍为应用提供服务,则不要执行故障转移。仅凭 CNPGDRSiteUnobservable 无法区分这两种情况。

  2. 按照上述说明快速隔离站点 A:在验证中,站点 A 与站点 B 失去连接后由站点 A 确认的行均已丢失(参见数据丢失)。

  3. 记录站点 B 已推进到的位置,以便评估丢失情况:

    kubectl --context site-b -n <ns> exec <pg-b primary pod> -c postgres -- \
      psql -Atc "select pg_last_wal_replay_lsn(), pg_last_xact_replay_timestamp()"

    这会告诉你站点 B 已重放到什么位置,而不是站点 A 已确认到什么位置。如果站点 A 的最后位置未知,请将丢失量记录为未知。

  4. 检查是否存在打开的 dr 操作。如果 ACP global 丢失,请使用直接上下文(site-a-direct、site-b-direct):

    kubectl cnpg dr operation inspect pgdr -n <ns> --from-context site-a --to-context site-b
    kubectl cnpg dr inspect pgdr -n <ns> --from-context site-a --to-context site-b
  5. 选择一个操作 ID,并为其写入隔离回执,即一个包含 schemaVersion: v1 和以下字段的 JSON 文件:operationID、topologyID、registrationDigest、sourceSiteID(site-a)、sourceClusterUID、fenceMethod 和 resourceIDs(它们必须匹配并覆盖站点 A 已注册的 fence)、providerActionIDs、lastVerifiedAt(默认不得早于 5 分钟,--fence-receipt-max-age)、latchedUntilExplicitRelease、reschedulingDisabled 和 oldVolumeBootPrevented(全部为 true)、performedBy、verifiedBy、evidenceURI、evidenceSHA256 和 reason。未知字段会被拒绝。

    操作 ID 由你选择;命令不会为故障转移生成操作 ID。每次故障转移都使用新的操作 ID,例如从 uuidgen 生成。请从存活站点读取注册值;提升者的权限(检查器 Role:get,位于 Cluster 和 ConfigMaps 上)已足够:

    ID=$(uuidgen)
    # <topology>/r<revision>/<sha256>
    ANN=$(kubectl --context site-b -n <ns> get cluster.postgresql.cnpg.io pg-b \
      -o jsonpath='{.metadata.annotations.dr\.cnpg\.alauda\.io/registration}')
    REVISION=$(echo "$ANN" | cut -d/ -f2)            # r<N>
    DIGEST=$(echo "$ANN" | cut -d/ -f3)              # registrationDigest
    kubectl --context site-b -n <ns> get configmap "dr-registration-pgdr-$REVISION" \
      -o jsonpath='{.data.registration\.json}' > registration.json
    jq -r '.topologyUID' registration.json                                 # topologyID
    jq -r '.sites[] | select(.site=="site-a") | .clusterUID' registration.json   # sourceClusterUID
    jq '.sites[] | select(.site=="site-a") | .fence' registration.json     # fenceMethod, resourceIDs

    --dry-run 配合 --operation-id 和 --fence-receipt,会根据注册信息检查回执,并打印注册摘要,且不会进行任何变更。请在执行实际命令前运行它。

  6. 检查后执行故障转移。位置参数是 Cluster 名称;当各站点的名称不同时,无论使用网关上下文还是直接上下文,都始终提供 --from-cluster 和 --to-cluster:

    F="-n <ns> --from-context site-a --to-context site-b --from-cluster pg-a --to-cluster pg-b"
    kubectl cnpg dr failover pg-b $F --dry-run --operation-id "$ID" --fence-receipt receipt.json
    kubectl cnpg dr failover pg-b $F --operation-id "$ID" \
      --fence-receipt receipt.json --accept-data-loss "$ID"

    --accept-data-loss 会重复操作 ID。如果无法读取站点 A(站点 A 已丢失,或 ACP global 丢失且只有站点 B 的直接路径可用),则必须添加 --skip-demote-source,否则命令会拒绝执行;添加后,命令不会尝试降级站点 A。如果站点 A 的 API server 可以响应,但拒绝 --from-context 的凭证(例如令牌已过期),即使提供了 --skip-demote-source,命令仍会拒绝执行:此时应改为省略 --from-context(以及 --from-cluster)。命令会打印已注册的隔离范围和回执,请求确认,并记录每个步骤。

    如果故障转移暂停(退出代码 3)。 当命令降级一个可访问的站点 A 时,会打印正在等待观测到原主站不可写……,并最多等待 --timeout 的一半时间,直到观测到站点 A 的每个实例都处于恢复状态。PostgreSQL 未运行的实例(例如使用 cnpg.io/fencedInstances 隔离的站点),或 operator 无法访问的实例,会在 Cluster 状态中列出,但没有时间线:它们未被观测到,因此命令无法确认站点 A 不可写。随后,命令会将操作置于暂停状态,而不会提升站点 B(退出代码 3,错误类 hold-unknown),下一步为原主站不可写后恢复,或使用 --skip-demote-source 和新的 --fence-receipt。这是故障关闭行为:因此,已隔离的站点 A 在此处始终会导致操作暂停。要继续操作,请为同一个操作 ID 签发一份最新的隔离回执(lastVerifiedAt 不得早于 --fence-receipt-max-age,默认 5 分钟),然后在不执行降级的情况下恢复。提供 --from-cluster 和 --to-cluster:

    kubectl cnpg dr operation resume pgdr "$ID" $F --skip-demote-source \
      --fence-receipt receipt-fresh.json --yes

    命令会从日志记录的阶段继续,并提升站点 B。

  7. 验证 pg-b 报告的主库是否接受写入。这可能需要几分钟:提升操作首先会等待从站点 A 的归档中恢复 WAL(参见限制)。然后将工作交接给应用所有者,以迁移应用流量;并更新 observer 和规则(参见监控)。

现在必须重建站点 A(参见故障恢复)。如果站点 A 的 API 可访问且仍将自身标记为主库,则必须在移除任何隔离措施之前将其降级:

kubectl --context site-a -n <ns> patch cluster.postgresql.cnpg.io pg-a \
  --type merge -p '{"spec":{"replica":{"primary":"pg-b","promotionToken":null}}}'

必须提供 promotionToken: null:当设置了提升令牌时,webhook 会拒绝降级。在验证中,降级前移除隔离措施曾使站点 A 恢复读写约 8 秒。如果写入在任何时候到达两个站点,CNPGDRConflictingWriters 都会触发。

数据丢失

复制是异步的,故障转移导致的数据丢失没有上限:

  • 仅使用对象存储时(拓扑 A),故障转移会丢失自上一个归档分段以来的所有数据,以及站点 A 在失去对象存储后提交的任何数据。
  • 在一次站点丢失运行中(ACP 4.4),切断前确认的行没有丢失,而切断后确认的 103 行中有 99 行丢失。
  • 在一次站点 A 与站点 B 隔离但仍可访问对象存储的运行中,没有数据丢失。这是一次运行中的观察结果,不应视为可依赖的特性。

应按照操作步骤允许的最快速度隔离站点 A,并根据应用自身对已确认写入的记录统计丢失量。

迁移应用流量

数据库提升只是恢复工作的一部分。应用所有者需要:

  1. 将客户端指向站点 B:DNS、负载均衡器或站点 B 上的 Pooler;
  2. 重启或排空仍持有站点 A 连接的连接池和计划任务;
  3. 确认没有任何内容仍可写入站点 A(通过其隔离措施,或在其 API 可访问时确认其已降级);
  4. 针对站点 B 执行持续的真实事务,并记录首次成功的时间:这就是应用恢复时间。

WAL 复制不会传输的 Kubernetes 资源必须已存在于站点 B:应用 Secret、Pooler 资源、ScheduledBackup 资源、Service 和网络策略。扩展会随数据库复制,但站点 B 上的 operand 镜像必须提供这些扩展。

故障恢复

任何故障转移后,都要重建原主库。不支持在原位置重新加入,无论是对象存储模式还是流复制模式。当其历史记录发生分叉后,它将完全无法跟随新的主库:在验证中,重放失败并显示 requested timeline N is not a child of this server's history,而 CloudNativePG 仍报告集群正常。请手动将其重建为一个从站点 B 克隆的新从库,使用 kubectl cnpg dr register replacement 记录该从库,然后切换回去。kubectl cnpg dr bootstrap 会拒绝已注册的拓扑,因此需要手动编写从库清单,如下所示。

请保持以下顺序:先将站点 A 降级,再解除其隔离(参见计划外故障转移)。

WARNING

只有幸存站点的新克隆才是有效的替代项。从站点 A 的自有旧归档恢复的 Cluster,或在其旧卷上重新创建的副本,可能与站点 B 具有相同的系统 ID,甚至相同的时间线编号,但持有不同的历史记录。在验证中,此类副本一直停留在 record with incorrect prev-link,而 CloudNativePG 报告其为 Cluster in healthy state。register replacement 会拒绝它;不要绕过这一拒绝。

  1. 在删除任何内容之前保留站点 A 的数据。 站点 B 最后一次重放位置之后写入站点 A 的行,仅存在于站点 A 的卷上。在站点 A 仍处于隔离状态时:

    • 将站点 A 的 PersistentVolume 的回收策略设置为 Retain,以便删除 PVC 不会删除数据:

      for pv in $(kubectl --context site-a -n <ns> get pvc -l cnpg.io/cluster=pg-a \
                  -o jsonpath='{.items[*].spec.volumeName}'); do
        kubectl --context site-a patch pv "$pv" -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
      done
    • 如果存储支持快照,则对这些卷创建 VolumeSnapshot;

    • 从隔离副本中导出需要协调的行,绝不要将站点 A 重新接入应用网络。故障转移中丢失的行仍只存在于站点 A 的旧 PVC 上:如果业务需要这些数据,请在删除任何内容之前将其提取出来。

  2. 获得具名批准,由数据所有者批准删除站点 A 的 Cluster 和 PVC。保留这些卷或快照,直到分叉数据完成协调,或数据所有者释放它们。释放后,删除保留的 PersistentVolume。使用 TopoLVM 时,删除 Retain PersistentVolume 不会释放磁盘:还必须删除其 logicalvolumes.topolvm.cybozu.com 对象,该对象与 PersistentVolume 同名。

  3. 在站点 A 上删除 pg-a 及其 PVC。重新创建之前,确认 PVC 已消失;否则重新创建的 Cluster 可能与旧 PVC 名称发生竞争(参见 creationTimestamp)。站点 A 上的 dr-peer-site-b-* 副本不归 Cluster 所有,因此会保留;如果缺失,请先使用 credentials sync --bootstrap 将其从站点 B 复制到站点 A。

  4. 将 pg-a 重新创建为站点 B 的从库:使用从库的清单并交换站点(bootstrap.pg_basebackup 来自 pg-b、replica.primary: pg-b、replica.source: pg-b、两个 externalClusters 条目、固定的 NodePort、serverAltDNSNames),并使用新的归档 serverName(例如 site-a-r1),使其归档不会与旧时间线混用;register replacement 会拒绝旧归档。该克隆是站点 B 在新时间线上的全新基础备份。检查附加 Service 的固定 nodePort:未固定的端口会在重新创建 Service 时发生变化。如果重新创建的 pg-a 具有新的 CA,请再次将其凭证复制到站点 B(步骤 8)。来自站点 B归档的 recovery 也会被接受;其他任何引导方式都不接受。

  5. 等待 pg-a 正常运行并从站点 B 进行流复制。在注册之前,dr inspect 会针对站点 A 报告 critical identity-mismatch,而 dr preflight switchover 会失败:这是预期行为。

  6. 记录替代项。在 topology.yaml 中,将站点 A 的 archiveServerName 设置为新名称(site-a-r1),不要更改其他内容,然后执行:

    kubectl cnpg dr register replacement --file topology.yaml --site site-a \
      --reason "<change record>" --dry-run   # review what it writes
    kubectl cnpg dr register replacement --file topology.yaml --site site-a \
      --reason "<change record>"

    该操作会在两个站点上写入下一版本的注册修订,并保留拓扑 UID,因此心跳行和 observer 配置仍然有效。除非站点 B 仍与其注册信息匹配且为主库,并且能够证明 pg-a 是站点 B 的全新克隆,否则该操作不会写入任何内容并直接拒绝:该克隆必须由 pg_basebackup 从 pg-b 引导,或由 recovery 从站点 B 的已注册归档引导;其 PVC 至多比 Cluster 早 60 秒,且必须与站点 B 具有相同的系统 ID 和时间线、状态正常,并从 pg-b 进行复制。不得存在任何未完成的操作(退出代码 5)。执行该操作的 custodian 需要对 PersistentVolumeClaims 具有 list 权限。

  7. 在站点 B 上,将 pg-b 的 externalClusters 条目中针对 pg-a 的 serverName 更改为 site-a-r1,这样后续切换就会从新归档恢复。该列表会整体替换:

    EC=$(kubectl --context site-b -n <ns> get cluster.postgresql.cnpg.io pg-b -o json \
      | jq -c '[.spec.externalClusters[] | if .name == "pg-a"
                then .plugin.parameters.serverName = "site-a-r1" else . end]')
    kubectl --context site-b -n <ns> patch cluster.postgresql.cnpg.io pg-b \
      --type merge -p "{\"spec\":{\"externalClusters\":$EC}}"
  8. 使用普通的 credentials sync 将 pg-a 的新凭证复制到站点 B(不要使用 --bootstrap;该对已注册),复制两种类型,并使用 -n <ns> --from-context site-a --to-context site-b,然后使用 --from-context site-b --to-context site-a 运行验证。按照应用凭证中的说明,将站点 B 的应用 Secret 复制到站点 A,但交换上下文。 使用 caFrom: peer-copy 的 observer 会在一分钟内从复制内容中获取站点 A 的新 CA;只需更新其预期拓扑(参见监控)。

  9. 如果希望站点 A 再次成为主库,请从站点 B 执行一次计划内切换。

如果无法使用 register replacement,插件文档介绍了一个从头注册该对的紧急操作步骤。该操作会丢失拓扑 UID:必须重新写入心跳行并重新配置 observer。

第 2 天操作

证书轮换

operator 会续订每个站点自己的证书(默认有效期为 90 天), 但对等站点上的副本是快照。任一站点续订或重建后,都要对两种类型运行 credentials sync。

CloudNativePG 会将 externalClusters 中指定的 Secret 写入 实例内的文件,并且仅在 Cluster 发生变化时刷新这些文件, 而不是在 Secret 发生变化时刷新。credentials sync 因此还会在目标 Cluster 上设置注释 dr.cnpg.alauda.io/credential-<copy name>(新的指纹), 使其实例重新写入文件;它会打印 Annotated cluster ... so its instances re-read ...。通过任何其他方式更改的副本, 要等到 Cluster 发生变化后才会被获取。在验证中,如果没有该注释, 从库会保留旧 CA:正在运行的连接掩盖了这一问题,而下一次重新连接会因 certificate verify failed 进入失败循环。

然后强制建立新的复制连接并检查其是否成功:现有连接会继续使用旧证书,因此在重新连接前 会掩盖问题。例如,在主库站点上:

kubectl --context site-a -n <ns> exec <pg-a primary pod> -c postgres -- psql -Atc \
  "select pg_terminate_backend(pid) from pg_stat_replication where application_name like 'pg-b%'"

在站点 B 上,select status from pg_stat_wal_receiver 必须在几秒内再次显示 streaming。CNPGDRCredentialCopyMismatch 和 CNPGDRCertificateExpiring 会发出警告,而 credentials check 会按需报告 状态。在轮换期间,直到运行 credentials sync 之前, observer 无法验证已轮换的站点:CNPGDRSiteUnobservable 以及针对主库站点的 CNPGDRHeartbeatWriterUnavailable 会触发,并在同步后清除。删除已复制的 Secret 不会撤销已经复制到 其他位置的证书;如果怀疑密钥已泄露,则需要在受影响的站点上创建新的 CA,并在对等站点上 重新构建信任。

权限

operator 仓库在 docs/src/samples/dr/ 下为每项职责提供了 Role 和 RoleBinding; 请在两个站点上应用它们:

职责可以用于
Inspector读取指定的 Cluster 和 ConfigMaps;不能读取 Secretinspect、preflight、plan
ObserverInspector 的权限,另外还可以对两个 dr-peer-*-ca 副本执行 get(observer-rbac.yaml)使用 caFrom: peer-copy 的 DR observer
PromoterInspector 的权限,另外还可以对指定的 Cluster 和操作日志执行 patch;不能读取 Secretswitchover、failover、operation
dr-promoter ServiceAccount(promoter-serviceaccount.yaml)promoter 和 inspector Role,以及 namespace-reader ClusterRole;作为位于 Cluster 命名空间中的 ServiceAccount控制台 executor Job 的身份;也可用于直接访问路径
DR operator(operator-token.yaml,Role cnpg-dr-operator-token)对 serviceaccounts/token 执行 create,且仅适用于 dr-promoter ServiceAccount从控制台启动 DR 操作;在两个站点上将其绑定给执行这些操作的人员
Custodian创建 ConfigMaps,patch 指定的 Cluster,list PersistentVolumeClaims,读取 CNPG Secret 并写入副本register、register replacement、credentials sync(还会为目标 Cluster 添加注释)、bootstrap;绝不能作为 dr-promoter ServiceAccount

promoter-admission.yaml 是一个 ValidatingAdmissionPolicy(Kubernetes 1.30 或更高版本),允许 dr-promoter ServiceAccount 仅更改 dr 引擎在 Cluster 上修改的内容: .spec.replica.primary、.spec.replica.promotionToken 以及两个 dr.cnpg.alauda.io 注释。operator-token.yaml 要求其中指定 dr-promoter:编辑其 matchConditions (system:serviceaccount:<ns>:dr-promoter)以匹配你的命名空间,并在两个站点上应用它。该策略已作为 promoter 在真实切换和真实故障转移中进行了现场验证。它豁免 spec.postgresql.parameters.archive_mode, 因为 operator 每次角色变更时都会修改该参数。这也是为什么会更改其他字段的 register、credentials sync 和 bootstrap 不能以该 ServiceAccount 身份运行。

Kubernetes RBAC 无法将 patch 限制到某些字段,也无法区分 dr 命令和手动修补:任何能够执行切换的人,也可以手动提升某个站点, 并更改 Cluster 的任何其他字段。请将这些组保持较小规模,并审计对 Cluster 资源的更改。

对象存储保留和凭证

  • 为每个站点使用其自己的归档前缀(serverName);重建的 Cluster 会获得新的前缀。
  • 保留从你保留的最旧基础备份到现在所需的每个 WAL 文件和时间线历史文件。“保留 WAL 24 小时”之类的规则在最旧备份已是一周前时并不足够。确保存储桶生命周期规则不会删除备份工具仍需要的对象。
  • 按计划在主库站点执行基础备份(例如每天一次)。
  • 将删除归档对象的权限授予单独的所有者,而不是授予 Cluster 日常使用的凭证。
  • 按计划将归档恢复到隔离的命名空间中进行测试。上传成功或列出对象成功,并不能证明备份可以恢复。

升级

本版本未验证对正在运行的 DR 对执行升级。如果升级 operator 或 PostgreSQL minor 版本,请一次升级一个站点,并在每次升级后运行验证。两个站点必须运行相同的 PostgreSQL major 版本:物理复制无法跨 major 版本工作,而 major 升级需要单独规划。

复制不会携带的内容

WAL 复制数据库,但不会复制 Kubernetes 资源:应用用户的 Secret、Pooler 资源、ScheduledBackup 资源、Service 和网络策略必须存在于将成为主库的站点上。请提前在站点 B 上准备好这些资源。每个 Cluster 生成的应用 Secret 在两个站点上必须具有相同内容(请参阅应用凭证)。

演练与验收

在生产环境使用前、任一站点发生任何变更后,以及每年至少两次执行以下演练:

演练通过条件
在两个方向分别执行计划内切换,并让应用通过切换后的主库写入新主库上没有缺失任何已确认的事务;旧主库从新主库进行流式复制
有意中断切换(在运行中途停止命令),然后恢复执行operation resume 完成切换;没有数据丢失
使用主站点真实基础设施隔离机制执行故障转移提升为主库前已存在隔离记录;应用在站点 B 恢复;丢失的行数根据应用自身已确认写入的记录进行统计
执行故障恢复,包括卷保留、重建、register replacement 和证书复制拒绝从旧站点自身归档恢复的替代实例;接受新克隆并进行流式复制,preflight switchover 通过,切换回原站点时不丢失任何数据
将对象存储中的数据恢复到隔离的命名空间恢复的数据库成功启动,且数据检查通过
告警依赖的每条告警都会在注入故障时触发、送达值班人员,并恢复为正常状态
轮换每个站点的证书在执行 credentials sync 后,强制重新连接复制成功,且 observer 无需重启即可再次验证该站点

记录每次演练的详细信息:运行的命令、时间戳、隔离记录、dr inspect -o json 执行前后的输出、数据检查结果以及告警通知。失败的演练也必须保留在记录中。至少让一名非操作手册编写者执行一次演练。

限制

  • 站点之间不支持自动故障转移,也没有仲裁器。
  • 仅支持异步复制:故障转移时可能丢失已确认的写入,且没有固定的上限。
  • 故障转移的安全性取决于基础设施隔离机制:dr failover 检查的是隔离回执,而不是隔离机制本身。
  • 任何故障转移后,都必须重建原主库;不支持将其原地重新加入。
  • 控制台仅支持使用一个 ACP global;没有 ACP global 时,请结合直接访问路径使用 CLI。
  • 在非计划内故障转移期间,站点 B 的提升会等待从故障站点的对象存储恢复 WAL。在验证中,当该对象存储无法访问时,站点 B 在提升补丁应用后约 3 分钟(两次运行分别为 184 秒)才接受写入。请为每个站点配置一个不托管在另一站点上的对象存储(参见对象存储),并预期在对象存储无法访问时,故障转移时间会包含恢复超时时间。
  • operator 不会对齐两个站点的应用 Secret,并且仅在主库上、每个版本和 instance manager 进程各应用一次 Secret。请在站点 B 创建完成后以及每次重建后自行复制 Secret(参见应用凭证);否则,应用可能会在切换后失去访问权限。
  • 计划内切换只有在旧站点报告新时间线后才会报告为受保护。CloudNativePG 从从节点的最后一个检查点获取该信息,而检查点通常会在下一个重启点推进(由 checkpoint_timeout 驱动,默认为 5 分钟,以及 max_wal_size),因此受保护通常会在切换后的几分钟内出现。这不是保证的上限:如果命令超时先到期,命令会以代码 6 退出,随后由 operation resume 完成切换。
  • CloudNativePG 阶段 Cluster in healthy state 不能证明从节点正在重放;请依赖 observer 的 CNPGDRRecoveryStale 告警。
  • 复制的证书只有通过 credentials sync 才会到达实例(该操作会为 Cluster 添加注解);通过其他方式编辑的副本只有在 Cluster 下次发生变更时才会被获取。
  • 不会为对等端保留复制槽:wal_keep_size 可应对短暂中断,更长时间的中断则完全取决于归档。
  • NodePort 会在集群所有节点地址上暴露 PostgreSQL 端口;请在外部限制访问。
  • 仅在支持声明列出的版本和网络条件下进行了验证,每种场景在低负载下运行一次。运行中双站点对的升级、持续数小时或数天的长时间断开、向人员交付告警以及应用恢复时间均未进行验证。