清单映射

从 Zalando CR(acid.zalan.do/v1 postgresql)到 CloudNativePG 资源(postgresql.cnpg.io/v1)的逐字段映射。

产品交付物中附带自动转换脚本 zalando-to-cnpg(operator 源代码仓库,hack/zalando-to-cnpg/):该脚本会生成一个 Cluster 以及 Pooler/Database 资源,并针对每个无法映射的字段输出明确的 WARN —— 将每条警告视为一项检查清单。

图例:直接 = 复制;转换 = 重命名/转换;机制 = 不同的资源或方法;无 = 没有等效项(工具会发出警告)。

核心

ZalandoCloudNativePG类型备注
metadata.namemetadata.name直接CNPG 中没有 teamId- 前缀规则;重命名会更改服务 DNS 名称。
spec.teamId—无仅为约定;通过 inheritedMetadata 作为标签保留。
spec.numberOfInstancesspec.instances直接Zalando 0(休眠)→ 注解 cnpg.io/hibernation: "on",而不是 instances: 0。
spec.dockerImagespec.imageName转换绝不可复制 —— Spilo 镜像无法与 CNPG 一起使用。根据 postgresql.version → 该主版本对应的 PostgreSQL operand 镜像进行推导。
spec.postgresql.version镜像主版本转换CNPG 会从镜像推断版本。
spec.envspec.env转换删除 Spilo/WAL-G 变量(WAL_S3_BUCKET、USE_WALG_*、AWS_*、…)——备份配置转移到 barman-cloud ObjectStore。

存储和资源

ZalandoCloudNativePG类型备注
spec.volume.sizespec.storage.size直接支持原地扩容;两者都不支持缩容。
spec.volume.storageClassspec.storage.storageClass直接
spec.volume.selectorspec.storage.pvcTemplate.selector转换
spec.volume.subPath / iops / throughput—无PGDATA 布局固定;IOPS/吞吐量原先通过 AWS EBS API 调用设置——应通过 StorageClass 表达。
spec.additionalVolumes—无(部分支持)Secrets/ConfigMaps → spec.projectedVolumeTemplate;数据卷 → spec.tablespaces / spec.walStorage。
spec.resourcesspec.resources直接如果 Zalando CR 中未设置,则应用 operator 配置中的默认值——在 CNPG 中设置明确的值。

用户和数据库

ZalandoCloudNativePG类型备注
spec.usersspec.managed.roles[]转换标志一一对应(superuser、createdb、createrole、replication、bypassrls;nologin → login: false)。⚠ Zalando 用户默认具有 LOGIN 权限;CNPG managed 角色默认具有 login: false —— 工具始终显式输出 login。
凭证 Secretsmanaged.roles[].passwordSecret机制CNPG 要求使用 kubernetes.io/basic-auth Secrets。将密码从 Zalando 的 <user>.<cluster>.credentials... Secrets 复制过来,以保持应用凭证正常工作。
spec.usersWithSecretRotation(+ 原地变体)—无不支持自动密码轮换。
spec.databasesbootstrap.initdb.{database,owner} + Database CR转换第一个条目用于引导集群;每个后续条目都会变为一个 Database 资源。
spec.preparedDatabasesDatabase CR(schemas、extensions)+ 角色转换Zalando 自动角色层次结构(<db>_owner/_reader/_writer + 默认权限)不会自动创建——请合成角色并执行 GRANT(例如 postInitApplicationSQL)。

PostgreSQL 配置

ZalandoCloudNativePG类型备注
spec.postgresql.parametersspec.postgresql.parameters转换复制,但不包括由 operator 控制的参数(工具会将其移除并发出警告):archive_*、restore_command、port、hot_standby、恢复目标、ssl*、synchronous_standby_names、shared_preload_libraries(→ 专用字段)、监听/日志/文件路径设置。调优参数(max_connections、shared_buffers、……)均会直接传递。
spec.patroni.pg_hbaspec.postgresql.pg_hba转换CNPG 会在前面添加固定规则,并在末尾追加 host all all all scram-sha-256;Zalando 的列表会替换整个文件。Spilo 特有的行(pam、standby)会被移除。
spec.patroni.initdbspec.bootstrap.initdb转换encoding/locale/data-checksums 映射;仅适用于全新引导。
spec.patroni.synchronous_modespec.postgresql.synchronous转换→ {method: any, number: <synchronous_node_count or 1>};非严格模式 → dataDurability: preferred,synchronous_mode_strict: true → required。
spec.patroni.slotsspec.replicationSlots机制HA 插槽会自动创建;用于 CDC 的永久逻辑插槽 → Publication/Subscription 资源或 SQL。
spec.patroni.ttl / loop_wait / retry_timeout / maximum_lag_on_failover / failsafe_mode—无Patroni/DCS 调优没有对应项(相关项:spec.failoverDelay、spec.probes)。

连接池、服务、网络

ZalandoCloudNativePG类型备注
spec.enableConnectionPooler独立的 Pooler 资源机制⚠ Zalando 的默认池模式为事务;CNPG 的默认模式为会话 — 请显式设置 pgbouncer.poolMode: transaction。Zalando 默认有 2 个实例,而 CNPG 默认有 1 个。应用需改为指向 Pooler 服务。
spec.enableReplicaConnectionPooler第二个 Pooler,带有 type: ro机制
spec.connectionPooler.*Pooler.spec.*转换numberOfInstances → instances;mode → pgbouncer.poolMode;maxDBConnections → pgbouncer.parameters;资源/镜像 → pod template。
spec.enableMasterLoadBalancer / enableReplicaLoadBalancerspec.managed.services.additional[]机制添加 {selectorType: rw or ro, serviceTemplate: {spec: {type: LoadBalancer}}} — 默认服务不会被修改;服务 DNS 名称会变化。
spec.allowedSourceRanges…serviceTemplate.spec.loadBalancerSourceRanges转换
spec.serviceAnnotations(以及各角色变体)服务模板 / inheritedMetadata.annotations转换
spec.podAnnotationsspec.inheritedMetadata.annotations转换适用于所有生成的对象。

调度和 pod 属性

ZalandoCloudNativePG类型备注
spec.nodeAffinityspec.affinity.nodeAffinity直接CNPG 添加反亲和性控制(podAntiAffinityType、topologyKey)。
spec.tolerationsspec.affinity.tolerations直接注意其位于 affinity 下。
spec.podPriorityClassNamespec.priorityClassName直接
spec.schedulerNamespec.schedulerName直接
spec.spiloRunAsUser / spiloRunAsGroup / spiloFSGroupspec.postgresUID / postgresGID转换CNPG 的默认 uid/gid 为 26(Spilo 使用 101);通常应省略。
spec.sidecars / spec.initContainers—无有意不支持。Metrics sidecar → 内置 exporter;初始化逻辑 → bootstrap.initdb.postInit*SQL。
spec.maintenanceWindows—无最接近的是:spec.primaryUpdateStrategy: supervised。

备份、克隆、备用、TLS、CDC

ZalandoCloudNativePG类型备注
spec.enableLogicalBackup + schedule—无CNPG 通过 ScheduledBackup 执行物理备份(⚠ 6 字段 cron — 添加一个秒字段)。如有需要,将逻辑转储保留为自定义 CronJob。
spec.clone(无时间戳)spec.bootstrap.pg_basebackup + externalClusters机制从运行中的集群克隆 — 可对正在运行的 Zalando 集群执行(这是受支持的迁移路径)。
spec.clone(时间戳 / s3 字段)bootstrap.recovery + externalClusters[].barmanObjectStore机制仅支持从 barman 格式的存档克隆 — CNPG 无法读取 Spilo WAL-E/WAL-G 存档。
spec.standby(S3 WAL 路径)—无存档不兼容,情况相同。
spec.standby(主机/端口)spec.replica + externalClusters机制外部主库的流复制备用实例;通过切换 replica.enabled 将其提升。
spec.tlsspec.certificates转换单 Secret 模型拆分为服务器/客户端(+复制)证书;SAN 必须覆盖 <cluster>-rw.<ns>.svc。最简单的方式是省略它,让 CNPG 自行管理。
spec.streams(CDC)—无基于 Publication/Subscription 资源重新设计,或使用外部 Debezium(wal_level=logical 是 CNPG 默认值)。

Fork 专属的 Zalando 字段(之前的 ACP PostgreSQL 版本)

Zalando(ACP fork)CloudNativePG备注
spec.backup(WAL-G 调度/保留/存储)barman-cloud ObjectStore + spec.plugins + ScheduledBackup + retentionPolicyCNPG 的第一次备份是全新的完整备份。
spec.exporter / enableExporterspec.monitoring(内置 exporter)请参阅 Grafana dashboards 指南(How To 部分)。
spec.enablePgpool2—仅支持 PgBouncer Pooler;查询负载均衡 ≈ -ro 服务 + 应用路由。
spec.clusterReplicationspec.replica + externalClusters(+ promotion/demotion tokens)CNPG 副本集群(分布式拓扑)模型。
spec.usersCustomizedPasswdmanaged.roles[].passwordSecret将密码从 CR 移出,放入 basic-auth secrets。
spec.ipFamilyPrefer服务模板 ipFamilies/ipFamilyPolicy单栈 IPv6 需要 operator 中的 url.Build 修复(请参阅 Configuration)。

示例

Zalando 源配置:

apiVersion: acid.zalan.do/v1
kind: postgresql
metadata:
  name: acid-orders
spec:
  teamId: acid
  numberOfInstances: 3
  postgresql:
    version: "16"
    parameters:
      shared_buffers: 512MB
      max_connections: "300"
  volume:
    size: 20Gi
    storageClass: sc-topolvm
  users:
    orders_svc: [createdb]
    analyst: []
  databases:
    orders: orders_svc
  patroni:
    pg_hba: [host all all 10.0.0.0/8 md5]
    synchronous_mode: true
    synchronous_node_count: 1
  resources:
    requests: {cpu: "1", memory: 2Gi}
    limits: {cpu: "2", memory: 4Gi}
  enableConnectionPooler: true

转换结果(工具输出的内容——一个 Cluster 和一个 Pooler):

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: acid-orders
spec:
  instances: 3
  imageName: <postgresql-16-operand-image>   # per your platform registry
  inheritedMetadata:
    labels:
      acid.zalan.do/team: acid
  bootstrap:
    initdb:
      database: orders
      owner: orders_svc
  managed:
    roles:
      - {name: analyst, ensure: present, login: true}
      - {name: orders_svc, ensure: present, login: true, createdb: true}
  postgresql:
    parameters:
      shared_buffers: 512MB
      max_connections: "300"
    pg_hba: [host all all 10.0.0.0/8 md5]
    synchronous:
      method: any
      number: 1
      dataDurability: preferred   # synchronous_mode without 'strict'
  storage: {size: 20Gi, storageClass: sc-topolvm}
  resources:
    requests: {cpu: "1", memory: 2Gi}
    limits: {cpu: "2", memory: 4Gi}
---
apiVersion: postgresql.cnpg.io/v1
kind: Pooler
metadata:
  name: acid-orders-pooler-rw
spec:
  cluster: {name: acid-orders}
  type: rw
  instances: 2                   # Zalando default
  pgbouncer:
    poolMode: transaction        # Zalando default (CNPG default is session!)

在发布验证期间,已对这一确切转换进行了端到端验证:转换后的 manifest 已部署到健康的 3 实例集群中,并通过 SQL 验证了 bootstrap 数据库/所有者、角色标志、同步复制(ANY 1 (...))、参数和 pg_hba,同时还通过处于事务模式的 Pooler 执行了写入操作。

应用程序需要进行的更改:

ZalandoCloudNativePG
写入端点acid-orders.<ns>.svcacid-orders-rw.<ns>.svc(或 Pooler 服务)
读取端点acid-orders-repl.<ns>.svcacid-orders-ro.<ns>.svc
凭证orders_svc.acid-orders.credentials... secretacid-orders-app(bootstrap 所有者)/ 您的 basic-auth secrets

商标声明

CloudNativePG™ 是 The Linux Foundation 的商标。

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

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