#清单映射
从 Zalando CR(acid.zalan.do/v1 postgresql)到 CloudNativePG 资源(postgresql.cnpg.io/v1)的逐字段映射。
产品交付物中附带自动转换脚本 zalando-to-cnpg(operator 源代码仓库,hack/zalando-to-cnpg/):该脚本会生成一个 Cluster 以及 Pooler/Database 资源,并针对每个无法映射的字段输出明确的 WARN —— 将每条警告视为一项检查清单。
图例:直接 = 复制;转换 = 重命名/转换;机制 = 不同的资源或方法;无 = 没有等效项(工具会发出警告)。
#目录
核心存储和资源用户和数据库PostgreSQL 配置连接池、服务、网络调度和 pod 属性备份、克隆、备用、TLS、CDCFork 专属的 Zalando 字段(之前的 ACP PostgreSQL 版本)示例商标声明#核心
| Zalando | CloudNativePG | 类型 | 备注 |
|---|---|---|---|
metadata.name | metadata.name | 直接 | CNPG 中没有 teamId- 前缀规则;重命名会更改服务 DNS 名称。 |
spec.teamId | — | 无 | 仅为约定;通过 inheritedMetadata 作为标签保留。 |
spec.numberOfInstances | spec.instances | 直接 | Zalando 0(休眠)→ 注解 cnpg.io/hibernation: "on",而不是 instances: 0。 |
spec.dockerImage | spec.imageName | 转换 | 绝不可复制 —— Spilo 镜像无法与 CNPG 一起使用。根据 postgresql.version → 该主版本对应的 PostgreSQL operand 镜像进行推导。 |
spec.postgresql.version | 镜像主版本 | 转换 | CNPG 会从镜像推断版本。 |
spec.env | spec.env | 转换 | 删除 Spilo/WAL-G 变量(WAL_S3_BUCKET、USE_WALG_*、AWS_*、…)——备份配置转移到 barman-cloud ObjectStore。 |
#存储和资源
| Zalando | CloudNativePG | 类型 | 备注 |
|---|---|---|---|
spec.volume.size | spec.storage.size | 直接 | 支持原地扩容;两者都不支持缩容。 |
spec.volume.storageClass | spec.storage.storageClass | 直接 | |
spec.volume.selector | spec.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.resources | spec.resources | 直接 | 如果 Zalando CR 中未设置,则应用 operator 配置中的默认值——在 CNPG 中设置明确的值。 |
#用户和数据库
| Zalando | CloudNativePG | 类型 | 备注 |
|---|---|---|---|
spec.users | spec.managed.roles[] | 转换 | 标志一一对应(superuser、createdb、createrole、replication、bypassrls;nologin → login: false)。⚠ Zalando 用户默认具有 LOGIN 权限;CNPG managed 角色默认具有 login: false —— 工具始终显式输出 login。 |
| 凭证 Secrets | managed.roles[].passwordSecret | 机制 | CNPG 要求使用 kubernetes.io/basic-auth Secrets。将密码从 Zalando 的 <user>.<cluster>.credentials... Secrets 复制过来,以保持应用凭证正常工作。 |
spec.usersWithSecretRotation(+ 原地变体) | — | 无 | 不支持自动密码轮换。 |
spec.databases | bootstrap.initdb.{database,owner} + Database CR | 转换 | 第一个条目用于引导集群;每个后续条目都会变为一个 Database 资源。 |
spec.preparedDatabases | Database CR(schemas、extensions)+ 角色 | 转换 | Zalando 自动角色层次结构(<db>_owner/_reader/_writer + 默认权限)不会自动创建——请合成角色并执行 GRANT(例如 postInitApplicationSQL)。 |
#PostgreSQL 配置
| Zalando | CloudNativePG | 类型 | 备注 |
|---|---|---|---|
spec.postgresql.parameters | spec.postgresql.parameters | 转换 | 复制,但不包括由 operator 控制的参数(工具会将其移除并发出警告):archive_*、restore_command、port、hot_standby、恢复目标、ssl*、synchronous_standby_names、shared_preload_libraries(→ 专用字段)、监听/日志/文件路径设置。调优参数(max_connections、shared_buffers、……)均会直接传递。 |
spec.patroni.pg_hba | spec.postgresql.pg_hba | 转换 | CNPG 会在前面添加固定规则,并在末尾追加 host all all all scram-sha-256;Zalando 的列表会替换整个文件。Spilo 特有的行(pam、standby)会被移除。 |
spec.patroni.initdb | spec.bootstrap.initdb | 转换 | encoding/locale/data-checksums 映射;仅适用于全新引导。 |
spec.patroni.synchronous_mode | spec.postgresql.synchronous | 转换 | → {method: any, number: <synchronous_node_count or 1>};非严格模式 → dataDurability: preferred,synchronous_mode_strict: true → required。 |
spec.patroni.slots | spec.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)。 |
#连接池、服务、网络
| Zalando | CloudNativePG | 类型 | 备注 |
|---|---|---|---|
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 / enableReplicaLoadBalancer | spec.managed.services.additional[] | 机制 | 添加 {selectorType: rw or ro, serviceTemplate: {spec: {type: LoadBalancer}}} — 默认服务不会被修改;服务 DNS 名称会变化。 |
spec.allowedSourceRanges | …serviceTemplate.spec.loadBalancerSourceRanges | 转换 | |
spec.serviceAnnotations(以及各角色变体) | 服务模板 / inheritedMetadata.annotations | 转换 | |
spec.podAnnotations | spec.inheritedMetadata.annotations | 转换 | 适用于所有生成的对象。 |
#调度和 pod 属性
| Zalando | CloudNativePG | 类型 | 备注 |
|---|---|---|---|
spec.nodeAffinity | spec.affinity.nodeAffinity | 直接 | CNPG 添加反亲和性控制(podAntiAffinityType、topologyKey)。 |
spec.tolerations | spec.affinity.tolerations | 直接 | 注意其位于 affinity 下。 |
spec.podPriorityClassName | spec.priorityClassName | 直接 | |
spec.schedulerName | spec.schedulerName | 直接 | |
spec.spiloRunAsUser / spiloRunAsGroup / spiloFSGroup | spec.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
| Zalando | CloudNativePG | 类型 | 备注 |
|---|---|---|---|
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.tls | spec.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 + retentionPolicy | CNPG 的第一次备份是全新的完整备份。 |
spec.exporter / enableExporter | spec.monitoring(内置 exporter) | 请参阅 Grafana dashboards 指南(How To 部分)。 |
spec.enablePgpool2 | — | 仅支持 PgBouncer Pooler;查询负载均衡 ≈ -ro 服务 + 应用路由。 |
spec.clusterReplication | spec.replica + externalClusters(+ promotion/demotion tokens) | CNPG 副本集群(分布式拓扑)模型。 |
spec.usersCustomizedPasswd | managed.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 执行了写入操作。
应用程序需要进行的更改:
| Zalando | CloudNativePG | |
|---|---|---|
| 写入端点 | acid-orders.<ns>.svc | acid-orders-rw.<ns>.svc(或 Pooler 服务) |
| 读取端点 | acid-orders-repl.<ns>.svc | acid-orders-ro.<ns>.svc |
| 凭证 | orders_svc.acid-orders.credentials... secret | acid-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 没有关联,也未获得其认可或赞助。所有商标均归其各自所有者所有,在此仅用于标识目的。