升级

本页面介绍如何升级 Alauda Data Services Relational Database E3 operator。PostgreSQL server 版本升级(例如 PG 17 → PG 18)属于单独的事项;请参阅下方的 PostgreSQL Major Version Upgrade。

兼容性矩阵

Alauda Data Services Relational Database E3 软件包版本上游 CNPG 版本PostgreSQL server 版本Kubernetes 版本ACP 版本
v1.29.0-acp.x (Alpha)v1.29.014, 15, 16, 17, 181.27+4.3+
v1.30.1-acp.1v1.30.114, 15, 16, 17, 181.32 到 1.35(已在 ACP 上验证);上游测试版本为 1.34、1.35、1.364.1 到 4.4(使用 image rewrite rule,其检查会打印 RULE NEEDED)

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),并且可能会破坏 OLM replaces 链。
  • 大版本升级:请阅读上游 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.io leases 权限。如果你已将 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 升级前:

  1. 验证所有集群均处于健康状态:

    kubectl get cluster.postgresql.cnpg.io -A

    每个集群的 STATUS 都应为 Cluster in healthy state。请勿在集群处于降级状态时升级(正在进行故障切换、存在副本堆积量或 pod 处于 pending 状态)。

  2. 验证备份为最新(如果已安装 Barman Cloud plugin):

    kubectl get scheduledbackup,backup -A

    最近一次成功的 Backup 应在你的 RPO 窗口内。

  3. 验证 catalog source 健康状态:

    kubectl get catalogsource -n cpaas-system platform -o jsonpath='{.status.connectionState.lastObservedState}'

    应输出 READY。

  4. 验证 CRD 兼容性(仅适用于跨 minor 版本升级): 检查新版本的 release notes,了解 CRD 字段弃用情况。使用已弃用字段的 Cluster CR 可能会在升级后验证失败。

operator 升级操作步骤

Web Console
kubectl
  1. 将新 package 推送到集群的 catalog(Marketplace 管理员操作)。
  2. 运行镜像重写检查;如果报告 RULE NEEDED,请在批准升级之前添加相应规则。否则,新 operator pod 无法拉取其镜像,升级会停滞在 ImagePullBackOff。
  3. 在 Marketplace > Operator Hub 中,cloudnative-pg package 会显示升级内置指标。
  4. (仅限手动批准)在 operator 详情页上点击升级横幅 → 批准 InstallPlan。
  5. 在 Operator Hub > Installed Operators 中监视 CSV。状态转换为 Pending → Installing → Replacing →(删除旧 CSV)→ Succeeded。
  6. 验证 operator pod 已完成轮换:
    kubectl get pods -n cnpg-system -l app.kubernetes.io/name=cloudnative-pg

升级后验证

新 CSV 达到 Succeeded 后:

  1. Operator pod 为 Running 1/1:

    kubectl get pods -n cnpg-system
  2. 现有 Cluster 保持健康:

    kubectl get cluster.postgresql.cnpg.io -A
  3. PostgreSQL pod 不会不必要地重启:operator 升级本身不会重建 PG pod。仅当新 operator 检测到需要滚动更新的配置漂移时,才会触及 PG pod(例如,更新后的 spec.imageName 引用了已移动的标签)。

  4. CSV 环境变量健全性检查(尤其是在通过 CSV 格式变更进行升级后):

    kubectl get deploy cnpg-controller-manager -n cnpg-system \
      -o jsonpath='{.spec.template.spec.containers[0].env}' | python3 -c "
    import json,sys
    [print(e['name'], '=', e.get('value','')) for e in json.load(sys.stdin)
     if e['name'] in ('ENABLE_IMAGE_REWRITE_TOLERANCE','POSTGRES_IMAGE_NAME','PGBOUNCER_IMAGE_NAME')]"

回滚注意事项

OLM 不支持自动回滚。如果升级导致 Cluster 处于降级状态:

  1. 不要手动删除 CSV — 这会升级为“升级卡住”恢复流程(见下文)。
  2. 首先检查 operator 日志:kubectl logs -n cnpg-system deploy/cnpg-controller-manager。operator 可能正在报告协调错误;修复原因后,这些错误可能会自行消除。
  3. 如果确实需要回滚,请通过 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: 字段,自动升级通常会发生死锁。

恢复序列

# 1. Push the new bundle (creates the bare ArtifactVersion alongside the existing rc)
violet push --platform-address <ACP_URL> ... cloudnative-pg.stable.ALL.<new-version>.tgz

# 2. Delete the old rc.X.gSHA ArtifactVersion — REQUIRED to remove the SemVer §11 winner
kubectl delete artifactversion cloudnative-pg.<old-version-with-rc-suffix> -n cpaas-system

# 3. Bounce OLM components to rebuild the gRPC catalog index
kubectl delete pod -n cpaas-system -l service_name=olm-registry-platform
kubectl delete pod -n cpaas-system -l app=catalog-operator

# 4. Nuke stale CSVs + InstallPlans in cnpg-system
kubectl delete csv -n cnpg-system --all
kubectl delete installplan -n cnpg-system --all

# 5. Delete + recreate the Subscription — WITHOUT startingCSV pin
#    (startingCSV pin can deadlock in this state; let OLM resolve to the channel head naturally)
kubectl delete subscription -n cnpg-system cloudnative-pg
cat <<EOF | kubectl apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: cloudnative-pg
  namespace: cnpg-system
spec:
  channel: stable
  installPlanApproval: Automatic
  name: cloudnative-pg
  source: platform
  sourceNamespace: cpaas-system
EOF

# 6. Wait for the new CSV to reach Succeeded
kubectl wait csv/cloudnative-pg.<new-version> -n cnpg-system \
  --for=jsonpath='{.status.phase}'=Succeeded --timeout=5m

此恢复序列具有破坏性(步骤 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:

  1. 使用逻辑复制(Subscription + Publication CR)将旧主版本的 Cluster 复制到新主版本的 Cluster,然后进行切换。
  2. 或使用备份与恢复:通过 pg_dump 风格的逻辑导出,然后恢复到新主版本的 Cluster。
  3. 或使用上游 cnpg-i-pgupgrade CNPG-I 插件(Alauda 发行版提供时)。

整个资源舰队的 PG 镜像版本通过 ClusterImageCatalog 集中管理(请参阅架构 / 镜像目录模型);更新目录会更新使用 imageCatalogRef 的 Cluster,但不会触发主版本升级 — 只会在同一主版本内更新次版本或补丁版本。

参考

商标声明

CloudNativePG™ 是 The Linux Foundation 的商标。

PostgreSQL® 是 PostgreSQL Community Association of Canada 的注册商标。

Alauda 是独立供应商。本产品与 The Linux Foundation、PostgreSQL Community Association of Canada 无关,也未获得其认可或赞助。所有商标均为其各自所有者的财产,在此仅用于识别目的。