升级
本页面介绍如何升级 Alauda Data Services Relational Database E3 operator。PostgreSQL server 版本升级(例如 PG 17 → PG 18)属于单独的事项;请参阅下方的 PostgreSQL Major Version Upgrade。
目录
兼容性矩阵升级路径升级到 v1.30升级策略升级前检查operator 升级操作步骤升级后验证回滚注意事项历史恢复:从带 rc 后缀的构建版本恢复恢复序列PostgreSQL 主版本升级参考商标声明兼容性矩阵
v1.29.x-acp.x 行以 v1.29.2-acp.1 结尾:上游 1.29.x 已于 2026-09-29 终止生命周期。请参阅 Lifecycle Policy。
有关特定版本的变更、新功能和已知限制,请参阅 release notes。
升级路径
- 补丁级升级(同一小版本内):支持任意方向。例如:
v1.29.0-acp.1 → v1.29.0-acp.2。 - 小版本升级:仅支持连续升级。例如:
v1.29.0 → v1.30.0。不支持跳过小版本(例如v1.29.0 → v1.31.0),并且可能会破坏 OLMreplaces链。 - 大版本升级:请阅读上游 CNPG release notes,了解不兼容变更;可能需要手动迁移 CR。
升级到 v1.30
v1.29.2-acp.1 → v1.30.1-acp.1 是连续的 minor 升级,请按照下方的Operator 升级操作步骤进行。上游 v1.30 增加了三项值得在批准 InstallPlan 前了解的行为。这些行为都不需要更改现有的 Cluster 资源。
- 安全的主节点选举 (
Lease)。 升级后,每个集群都会在其所在的命名空间中获得一个以集群命名的Lease,实例必须持有该对象才能担任主节点。operator 的 ClusterServiceVersion 会授予coordination.k8s.ioleases权限。如果你已将 operator 的 RBAC 替换为自定义配置,请在升级之前为leases添加create、get、list、update和watch,否则主节点将无法晋升。 - operator 到实例的身份验证。 operator 使用客户端证书对实例管理器的敏感状态端口端点(备份、
pg_controldata、部分 WAL 归档、实例管理器升级)进行身份验证。此过程是自动的,并要求状态端口通过 TLS 提供服务;上游自 v1.24 起默认启用 TLS,因此 Alauda 构建创建的所有集群均不受影响。状态、运行状况和探测端点仍未经过身份验证。 DatabaseRole为可选启用。 新 CRD 会随 operator 一起安装。现有的.spec.managed.roles条目仍可正常工作;要迁移角色,请先创建其DatabaseRole,然后再移除内联条目,因为两者同时存在时,Cluster规范具有优先权。
预计每个集群都会进行滚动更新。 默认情况下,升级 operator 还会升级每个 PostgreSQL pod 中的实例管理器,每次升级一个实例,先升级从节点,最后升级主节点(根据集群的 primaryUpdateMethod 进行重启或切换)。请据此在维护窗口内安排升级。
此版本还会更新 PostgreSQL operand 镜像(例如 18.4 → 18.6)。通过 imageName 或镜像目录固定镜像的集群,在更改相应引用前会保留当前 PostgreSQL 版本;更新 ACP 镜像目录会滚动更新所有使用该目录的集群。完整组件列表请参阅 Release Notes。
创建时未指定镜像的集群也不会自动升级到新的 minor 版本:创建集群时,operator 会将默认镜像写入 imageName,因此升级后集群仍会使用例如 18.4 的版本。要将集群升级到新的 minor 版本,请设置 imageName 或更新其镜像目录。
升级策略
Subscription 的 installPlanApproval 字段控制升级触发时机:
- 自动:当新 CSV 发布到 channel 时,OLM 立即应用升级。推荐用于非生产环境。
- 手动:OLM 创建 InstallPlan,但会暂停并等待人工批准后再应用。推荐用于生产环境。通过平台 UI 或
kubectl edit installplan -n cnpg-system <name>批准。
升级前检查
触发 operator 升级前:
-
验证所有集群均处于健康状态:
每个集群的
STATUS都应为Cluster in healthy state。请勿在集群处于降级状态时升级(正在进行故障切换、存在副本堆积量或 pod 处于 pending 状态)。 -
验证备份为最新(如果已安装 Barman Cloud plugin):
最近一次成功的 Backup 应在你的 RPO 窗口内。
-
验证 catalog source 健康状态:
应输出
READY。 -
验证 CRD 兼容性(仅适用于跨 minor 版本升级): 检查新版本的 release notes,了解 CRD 字段弃用情况。使用已弃用字段的 Cluster CR 可能会在升级后验证失败。
operator 升级操作步骤
- 将新 package 推送到集群的 catalog(Marketplace 管理员操作)。
- 运行镜像重写检查;如果报告
RULE NEEDED,请在批准升级之前添加相应规则。否则,新 operator pod 无法拉取其镜像,升级会停滞在ImagePullBackOff。 - 在 Marketplace > Operator Hub 中,
cloudnative-pgpackage 会显示升级内置指标。 - (仅限手动批准)在 operator 详情页上点击升级横幅 → 批准 InstallPlan。
- 在 Operator Hub > Installed Operators 中监视 CSV。状态转换为
Pending→Installing→Replacing→(删除旧 CSV)→Succeeded。 - 验证 operator pod 已完成轮换:
升级后验证
新 CSV 达到 Succeeded 后:
-
Operator pod 为 Running 1/1:
-
现有 Cluster 保持健康:
-
PostgreSQL pod 不会不必要地重启:operator 升级本身不会重建 PG pod。仅当新 operator 检测到需要滚动更新的配置漂移时,才会触及 PG pod(例如,更新后的
spec.imageName引用了已移动的标签)。 -
CSV 环境变量健全性检查(尤其是在通过 CSV 格式变更进行升级后):
回滚注意事项
OLM 不支持自动回滚。如果升级导致 Cluster 处于降级状态:
- 不要手动删除 CSV — 这会升级为“升级卡住”恢复流程(见下文)。
- 首先检查 operator 日志:
kubectl logs -n cnpg-system deploy/cnpg-controller-manager。operator 可能正在报告协调错误;修复原因后,这些错误可能会自行消除。 - 如果确实需要回滚,请通过
Subscription.spec.startingCSV手动固定旧 CSV。请注意,这可能会因陈旧状态而死锁 — 请参阅下面的恢复序列。
历史恢复:从带 rc 后缀的构建版本恢复
CNPG 标签约定 vMAJOR.MINOR.PATCH-acp.N(-rc.M.gSHA) 与 OLM 严格的 SemVer §11 排序规则以一种不直观的方式交互:预发布标识符越多,版本越高。因此,1.29.0-acp.1-rc.88.ge3a3c0c(5 个预发布标识符)的排名高于 1.29.0-acp.1(2 个预发布标识符),这颠倒了预期的“正式版本 > 预发布版本”语义。
当从预发布的 -rc.X.gSHA 构建版本升级到不带后缀的正式版本标签时,这一点非常重要。只要旧的 rc.X.gSHA ArtifactVersion 存在于 Cluster 中,OLM 就会将其选为 channel head — 这与预期相反。再加上 rc bundle 中可能不正确的 replaces: 字段,自动升级通常会发生死锁。
恢复序列
此恢复序列具有破坏性(步骤 4 和步骤 6 之间会短暂缺少 operator deployment),但不会影响 Cluster CR — PostgreSQL pod 会独立于 operator 继续运行。在此期间,PG 可用性得以保持。
如果现有 Cluster CR 在步骤 6 后由新 operator 进行协调,并且 operator 判断需要滚动更新(因为 Cluster.status.currentImage 与 CSV 的 POSTGRES_IMAGE_NAME 默认值不同,且 Cluster 未覆盖 imageName),预计 replica 会短暂轮换,但 primary 不会停机。
PostgreSQL 主版本升级
Operator 升级与 PostgreSQL 主版本升级彼此独立。升级 Operator 无需更改 PostgreSQL;升级 PostgreSQL 主版本也无需更改 Operator 版本。
CNPG 不支持原地升级 PG 主版本(例如,在同一个 Cluster 中从 PG 17 升级到 PG 18)。要在不同主版本之间迁移 Cluster:
- 使用逻辑复制(
Subscription+PublicationCR)将旧主版本的 Cluster 复制到新主版本的 Cluster,然后进行切换。 - 或使用备份与恢复:通过
pg_dump风格的逻辑导出,然后恢复到新主版本的 Cluster。 - 或使用上游
cnpg-i-pgupgradeCNPG-I 插件(Alauda 发行版提供时)。
整个资源舰队的 PG 镜像版本通过 ClusterImageCatalog 集中管理(请参阅架构 / 镜像目录模型);更新目录会更新使用 imageCatalogRef 的 Cluster,但不会触发主版本升级 — 只会在同一主版本内更新次版本或补丁版本。
参考
- 上游 Operator 升级流程:CloudNativePG Operator 升级
- 上游 PostgreSQL 主版本升级:CloudNativePG 声明式数据库
- ACP
violet push工作流:Marketplace 管理员指南(你的平台管理员应该有访问权限)
商标声明
CloudNativePG™ 是 The Linux Foundation 的商标。
PostgreSQL® 是 PostgreSQL Community Association of Canada 的注册商标。
Alauda 是独立供应商。本产品与 The Linux Foundation、PostgreSQL Community Association of Canada 无关,也未获得其认可或赞助。所有商标均为其各自所有者的财产,在此仅用于识别目的。