跨集群灾难恢复
本指南介绍如何在两个 ACP 集群之间运行一个 PostgreSQL 数据库,并在第二个站点设置一个只读副本,以便在第一个站点发生故障时将其提升为主库。本指南采用 CloudNativePG 分布式拓扑:在每个站点各创建一个 Cluster 资源,并在 spec.replica 中相互指定对方。kubectl cnpg dr 命令用于注册这对资源、检查状态、在两个站点之间复制证书,以及执行计划内切换和带保护措施的故障转移。控制台实例页面中的 DR 选项卡通过 Job 执行相同的命令(请参阅控制台)。
在据此设计部署之前,请阅读支持声明。跨站点故障转移是需要人工授权的手动操作,两个站点之间的复制是异步的。
在每条 kubectl 命令中,都应将 CNPG 集群指定为 cluster.postgresql.cnpg.io。在已安装 Cluster API 的 ACP 集群上,裸 cluster 名称会解析为 Cluster API 的资源。
目录
支持声明测量结果的含义客户前提条件选择拓扑规划部署网络Streaming 主机名对象存储The plugin直接访问路径控制台部署1. 对象存储(两个站点)2. 站点 A 上的主集群3. 将站点 A 的凭证复制到站点 B4. 站点 B 上的从集群应用凭证5. 站点 A 上的返回路径6. 注册配对7. 验证监控计划切换如果计划切换被中断故障转移前的隔离非计划故障转移数据丢失迁移应用流量故障恢复第 2 天操作证书轮换权限对象存储保留和凭证升级复制不会携带的内容演练与验收限制支持声明
1.30 operator 为每个集群持有的主 Lease 持续时间为 15 s。在 v1.30.1 运行中,未观察到它对切换或故障转移时序产生影响。
测量结果的含义
本指南中的数据来自低负载下每个场景的一次运行(每秒约 4 次写入,每个站点 2 个实例)。这些数据用于显示数量级,并不构成保证。第一张表来自 v1.29.2-acp.1。
v1.30.1-acp.1 运行(采用“已验证范围”下列出的限制,每秒约 3 次写入)测得:
应用恢复时间(连接路由、连接池重新连接)不包含在内,并且取决于您的环境。请规划您自己的演练来测量该时间(请参阅演练)。
客户前提条件
本指南涵盖数据库。在生产环境依赖本指南之前,您还需要具备以下条件,而本指南不提供这些条件:
- 每个站点都有合格的基础设施 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。
规划部署
开始之前,请记录两个站点的以下信息,并将记录与变更文档一同保存:
此外,请选择一个拓扑名称(下方的 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 上执行:
此时主机名为 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-operatorv4.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-promoterServiceAccount),并将其绑定到执行 DR 操作的人员。dr-promoterServiceAccount 本身来自两个站点上的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 历史记录中:
在站点 A 上,为其自身前缀创建一个 ObjectStore,并为对端前缀创建一个:
在站点 B 上进行镜像配置:site-b-own(写入,前缀为 site-b)和
site-a-peer(读取,前缀为 site-a)。如果端点使用私有 CA,请将
endpointCA 添加到每个 ObjectStore。
2. 站点 A 上的主集群
固定 nodePort。否则,重建的集群会获得新的端口,从而导致对端的连接设置失效。
wal_keep_size 是站点 A 为流式连接中断的从节点保留的 WAL;更长的间隔会从归档中填充。
将其大小设置为至少峰值每秒 WAL 字节数 × 希望能够承受的中断时长 × 1.5,并为其在 WAL 卷上预留空间。
3. 将站点 A 的凭证复制到站点 B
站点 B 从站点 A 克隆,因此首先需要站点 A 的 CA 证书和复制客户端证书。在配对注册之前,使用
--bootstrap 复制它们:
此命令会将 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 上的从集群
必须配置以下三项:
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会拒绝任何其他设置。
应用凭证
两个站点必须使用同一个应用 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 会创建它,或在重建后更新它:
当两个 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:
然后将站点 B 的凭证复制到站点 A:
请保持此顺序。--bootstrap 拒绝写入未在 .spec.replica.source(pg-a does not name pg-b)中指明源站点的 Cluster,因此必须先应用补丁。
6. 注册配对
在文件 topology.yaml 中描述两个站点:
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保留为事故操作步骤的自由文本备注。
然后注册配对:
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:
7. 验证
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:
在宣布部署就绪之前,请在站点 A 写入一行测试数据,并在站点 B 读取该行。
监控
CloudNativePG 的站点级指标无法区分空闲的源端和故障的副本,并且在所在站点丢失时会停止工作。DR observer(kubectl cnpg dr observe)弥补了这一缺口。它运行在第三个故障域中,每 10 秒读取两个站点的数据。它还会在主集群上写入一行心跳数据,并测量该行数据在副本上的时效。它绝不会提升、降级或修补任何内容。
清单位于 operator 仓库中的 docs/src/samples/dr/observer/ 和 docs/src/samples/monitoring/ 下:
-
心跳 schema:在站点 A 的主集群上,以超级用户身份执行一次。它会创建
cnpg_dr.heartbeat表,以及一个只能读取和更新该表、并调用两个只读函数的dr_observer角色;该表会复制到站点 B:psql在 pod 内运行,因此脚本通过标准输入传入。通过.spec.managed.roles中的passwordSecret,为dr_observer提供密码,并在两个Cluster资源上都进行配置,以便在计划切换后继续有效。 -
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-*-caSecret 执行get(其中只包含ca.crt,绝不包含ca.key)。站点命名空间中的 ServiceAccount 配合有时限的令牌(kubectl create token)即可通过 ACP API proxy 工作;请在令牌过期前续期。 - 主机名:observer 会验证其连接的主机名。如果它通过自身的名称解析站点,例如通过其命名空间中的无头 Service 解析,则还要将这些名称添加到两个
Cluster资源的serverAltDNSNames中。
- 每个站点的 CA:使用
-
告警规则(
prometheusrule-dr-observer.yaml):部署在第三个故障域的 Prometheus 或 VictoriaMetrics 上。编辑 expected-topology 组:site-b是预期的副本,以及预期进行流式复制的站点。 -
站点指标(
podmonitor-dr-sites.yaml):部署在每个站点的命名空间中,并使用该站点的dr_site值,用于归档和备份告警。
示例同时带有 prometheus: kube-prometheus(ACP Prometheus)和 victoriametrics: victoriametrics(ACP 4.4,会自动转换为 VictoriaMetrics 对象)标签;请保留两者。
这些规则会将观测结果与预期拓扑进行比较。每次计划切换或故障转移后,都要更新 observer 配置中的 expectedAuthority 以及规则的 expected-topology 组;在完成更新之前,observer 会告警拓扑与预期不符。
规则已加载,并不意味着有人会收到告警:请将所依赖的每条告警都作为演练的一部分进行测试。
计划切换
在不丢失数据的情况下,将主库从站点 A 切换至站点 B。请在维护窗口内进行规划;如果应用无法容忍几秒钟的只读时间,请先停止应用写入。每次只能由一人执行切换,并且必须在已记录的变更下进行。
-
检查并规划。
plan switchover会执行预检并打印确切的变更;它不需要凭证,也不会进行任何变更:使用直接上下文且每个站点使用不同的
Cluster名称时,命令需要--from-cluster和--to-cluster;请始终提供这两个参数。 -
使用该计划运行。对于注册信息、站点、
ClusterUID 或 API server 已不再匹配的计划,命令会拒绝执行:命令会打印两端的身份信息并请求确认(在脚本中,
--yes可跳过提示)。随后,它会声明两个Cluster资源,使站点 A 降级,等待其降级令牌,并等待站点 A 的每个实例进入恢复状态;然后使用该令牌提升站点 B,等待站点 A 跟随,并释放声明。每个步骤都会先记录在日志中(站点 B 上为dr-operation-pgdr),再发送出去;每次变更都是条件补丁,如果其他人已更改Cluster,操作就会失败。 -
将应用流量移至站点 B,然后更新 observer 和规则(参见监控)。
如果要在站点 B 接受写入后立即移动流量,请添加 --until database:命令会在此处停止,操作将保持打开状态,直到你使用 kubectl cnpg dr operation resume pgdr <operation ID> $D 完成操作。
如果计划切换被中断
命令会打印其操作 ID。如果操作被中断(连接丢失、终端关闭或发生崩溃),请查看日志,然后按照它打印的下一步安全操作执行:
- 一旦要求站点 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 恢复后,绝不能重新加入应用。
非计划故障转移
故障转移会在没有降级令牌的情况下提升站点 B,并丢失站点 B 尚未接收的数据。其安全性依赖于你对站点 A 执行的合格基础设施隔离:该命令会检查你的隔离回执是否完整、是否为最新、是否绑定到此操作以及已注册的隔离范围,而不会检查隔离是否真实存在。只有在具备隔离记录时才能运行该命令。
-
确定站点 A 已丢失。站点之间的链路中断不等于站点丢失:如果站点 A 仍为应用提供服务,则不要执行故障转移。仅凭
CNPGDRSiteUnobservable无法区分这两种情况。 -
按照上述说明快速隔离站点 A:在验证中,站点 A 与站点 B 失去连接后由站点 A 确认的行均已丢失(参见数据丢失)。
-
记录站点 B 已推进到的位置,以便评估丢失情况:
这会告诉你站点 B 已重放到什么位置,而不是站点 A 已确认到什么位置。如果站点 A 的最后位置未知,请将丢失量记录为未知。
-
检查是否存在打开的
dr操作。如果 ACP global 丢失,请使用直接上下文(site-a-direct、site-b-direct): -
选择一个操作 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 上)已足够:--dry-run配合--operation-id和--fence-receipt,会根据注册信息检查回执,并打印注册摘要,且不会进行任何变更。请在执行实际命令前运行它。 -
检查后执行故障转移。位置参数是
Cluster名称;当各站点的名称不同时,无论使用网关上下文还是直接上下文,都始终提供--from-cluster和--to-cluster:--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:命令会从日志记录的阶段继续,并提升站点 B。
-
验证
pg-b报告的主库是否接受写入。这可能需要几分钟:提升操作首先会等待从站点 A 的归档中恢复 WAL(参见限制)。然后将工作交接给应用所有者,以迁移应用流量;并更新 observer 和规则(参见监控)。
现在必须重建站点 A(参见故障恢复)。如果站点 A 的 API 可访问且仍将自身标记为主库,则必须在移除任何隔离措施之前将其降级:
必须提供 promotionToken: null:当设置了提升令牌时,webhook 会拒绝降级。在验证中,降级前移除隔离措施曾使站点 A 恢复读写约 8 秒。如果写入在任何时候到达两个站点,CNPGDRConflictingWriters 都会触发。
数据丢失
复制是异步的,故障转移导致的数据丢失没有上限:
- 仅使用对象存储时(拓扑 A),故障转移会丢失自上一个归档分段以来的所有数据,以及站点 A 在失去对象存储后提交的任何数据。
- 在一次站点丢失运行中(ACP 4.4),切断前确认的行没有丢失,而切断后确认的 103 行中有 99 行丢失。
- 在一次站点 A 与站点 B 隔离但仍可访问对象存储的运行中,没有数据丢失。这是一次运行中的观察结果,不应视为可依赖的特性。
应按照操作步骤允许的最快速度隔离站点 A,并根据应用自身对已确认写入的记录统计丢失量。
迁移应用流量
数据库提升只是恢复工作的一部分。应用所有者需要:
- 将客户端指向站点 B:DNS、负载均衡器或站点 B 上的
Pooler; - 重启或排空仍持有站点 A 连接的连接池和计划任务;
- 确认没有任何内容仍可写入站点 A(通过其隔离措施,或在其 API 可访问时确认其已降级);
- 针对站点 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 降级,再解除其隔离(参见计划外故障转移)。
只有幸存站点的新克隆才是有效的替代项。从站点 A 的自有旧归档恢复的 Cluster,或在其旧卷上重新创建的副本,可能与站点 B 具有相同的系统 ID,甚至相同的时间线编号,但持有不同的历史记录。在验证中,此类副本一直停留在 record with incorrect prev-link,而 CloudNativePG 报告其为 Cluster in healthy state。register replacement 会拒绝它;不要绕过这一拒绝。
-
在删除任何内容之前保留站点 A 的数据。 站点 B 最后一次重放位置之后写入站点 A 的行,仅存在于站点 A 的卷上。在站点 A 仍处于隔离状态时:
-
将站点 A 的 PersistentVolume 的回收策略设置为
Retain,以便删除 PVC 不会删除数据: -
如果存储支持快照,则对这些卷创建 VolumeSnapshot;
-
从隔离副本中导出需要协调的行,绝不要将站点 A 重新接入应用网络。故障转移中丢失的行仍只存在于站点 A 的旧 PVC 上:如果业务需要这些数据,请在删除任何内容之前将其提取出来。
-
-
获得具名批准,由数据所有者批准删除站点 A 的
Cluster和 PVC。保留这些卷或快照,直到分叉数据完成协调,或数据所有者释放它们。释放后,删除保留的 PersistentVolume。使用 TopoLVM 时,删除RetainPersistentVolume 不会释放磁盘:还必须删除其logicalvolumes.topolvm.cybozu.com对象,该对象与 PersistentVolume 同名。 -
在站点 A 上删除
pg-a及其 PVC。重新创建之前,确认 PVC 已消失;否则重新创建的 Cluster 可能与旧 PVC 名称发生竞争(参见creationTimestamp)。站点 A 上的dr-peer-site-b-*副本不归Cluster所有,因此会保留;如果缺失,请先使用credentials sync --bootstrap将其从站点 B 复制到站点 A。 -
将
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也会被接受;其他任何引导方式都不接受。 -
等待
pg-a正常运行并从站点 B 进行流复制。在注册之前,dr inspect会针对站点 A 报告criticalidentity-mismatch,而dr preflight switchover会失败:这是预期行为。 -
记录替代项。在
topology.yaml中,将站点 A 的archiveServerName设置为新名称(site-a-r1),不要更改其他内容,然后执行:该操作会在两个站点上写入下一版本的注册修订,并保留拓扑 UID,因此心跳行和 observer 配置仍然有效。除非站点 B 仍与其注册信息匹配且为主库,并且能够证明
pg-a是站点 B 的全新克隆,否则该操作不会写入任何内容并直接拒绝:该克隆必须由pg_basebackup从pg-b引导,或由recovery从站点 B 的已注册归档引导;其 PVC 至多比Cluster早 60 秒,且必须与站点 B 具有相同的系统 ID 和时间线、状态正常,并从pg-b进行复制。不得存在任何未完成的操作(退出代码5)。执行该操作的 custodian 需要对 PersistentVolumeClaims 具有list权限。 -
在站点 B 上,将
pg-b的externalClusters条目中针对pg-a的serverName更改为site-a-r1,这样后续切换就会从新归档恢复。该列表会整体替换: -
使用普通的
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;只需更新其预期拓扑(参见监控)。 -
如果希望站点 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 进入失败循环。
然后强制建立新的复制连接并检查其是否成功:现有连接会继续使用旧证书,因此在重新连接前 会掩盖问题。例如,在主库站点上:
在站点 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;
请在两个站点上应用它们:
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 在两个站点上必须具有相同内容(请参阅应用凭证)。
演练与验收
在生产环境使用前、任一站点发生任何变更后,以及每年至少两次执行以下演练:
记录每次演练的详细信息:运行的命令、时间戳、隔离记录、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 端口;请在外部限制访问。
- 仅在支持声明列出的版本和网络条件下进行了验证,每种场景在低负载下运行一次。运行中双站点对的升级、持续数小时或数天的长时间断开、向人员交付告警以及应用恢复时间均未进行验证。