CloudNativePG 1.19 版本发布说明深度解析从 standby 备份到实例生命周期控制【免费下载链接】cloudnative-pgThe most popular Kubernetes Operator for PostgreSQL.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudnative-pgCloudNativePG 1.19 是 2023 年 2 月至 11 月期间维护的次版本线涵盖 1.19.0 至 1.19.6 共 7 个补丁版本。该版本线引入了「从备库standby发起物理备份」「延迟故障切换failoverDelay」「基于 CSI VolumeSnapshot 的冷备份与恢复」等核心能力同时系统性地重构了 PostgreSQL 实例的启停超时模型与复制参数管理方式。本文以官方发布说明为骨架结合当前仓库源码api/v1/cluster_types.go、api/v1/backup_types.go 等逐条展开帮助读者完整理解 1.19 的每一项变更以及它们在实际集群运维中的意义。说明本文以仓库中的 docs/src/release_notes/old/v1.19.md 为唯一事实骨架文中所有源码引用均来自当前仓库对应实现。1. 版本线概览与支持周期CloudNativePG 1.19 系列共发布 7 个版本发布节奏与日期如下版本发布日期定位1.19.02023 年 2 月 14 日特性基线版本1.19.12023 年 3 月 20 日补丁版本1.19.22023 年 4 月 27 日补丁版本1.19.32023 年 6 月 12 日补丁版本1.19.42023 年 7 月 27 日补丁版本1.19.52023 年 10 月 11 日补丁版本含重要默认值变更1.19.62023 年 11 月 3 日1.19 系列收尾版本官方在 1.19.6 发布时明确提示这将是 1.19.X 系列的最后一次发布建议用户尽快升级到更新的次版本1.19.5 发布时也预告了 End-of-LifeEOL日期为 2023 年 11 月 9 日。因此若你仍在运行 1.19 系列应优先规划升级到 1.20 及更高版本。另外1.19.0 的发布说明中有一条重要声明PostgreSQL 10 已到达其生命周期终点EOL不再受支持1.19 系列支持的 PostgreSQL 版本为 11 及更新版本。官方建议尽快规划向 PostgreSQL 15 的迁移并指向文档 docs/src/database_import.md 了解 PostgreSQL 大版本离线升级major offline upgrade的细节。2. Version 1.19.0特性基线1.19.0 是 1.19 系列的功能地基其引入的特性大多持续沿用至今。2.1 从备库发起备份.spec.backup.target prefer-standby1.19.0 在备份功能中引入了.spec.backup.target选项当设置为prefer-standby时物理基础备份physical base backup将优先由对齐程度最高的备库most aligned replica执行从而把备份产生的 I/O 压力从主库转移到备库显著降低对生产主库的影响。这一设计在当前的 API 定义中依然可见api/v1/cluster_types.go#L2424-L2436 定义了BackupTarget字符串类型及两个常量BackupTargetPrimary primary与BackupTargetStandby prefer-standbyapi/v1/cluster_types.go#L2460-L2467 中.spec.backup.target的可选值为空字符串、primary与prefer-standby且kubebuilder:default:prefer-standby即默认策略即为优先使用备库api/v1/backup_types.go#L131-L139 表明单个Backup资源可以覆盖集群级目标策略Target字段为空时回退到cluster.spec.backup.target可选值同样被 webhook 校验限定为primary;prefer-standby。从源码结构看集群默认值填充逻辑位于 api/v1/cluster_defaults.go#L88-L90当r.Spec.Backup ! nil r.Spec.Backup.Target 时Target会被设置为DefaultBackupTarget即prefer-standby。这意味着只要启用了备份配置且未显式指定1.19 起备份默认就会寻找可用的备库来执行。2.2 延迟故障切换failoverDelay参数当主库被检测为不健康时1.19.0 引入failoverDelay参数来控制故障切换流程的启动延迟——即在主库失联后等待一段时间再触发 failover为「短暂抖动」留出缓冲避免不必要的切换。源码中 api/v1/cluster_types.go#L375-L387 定义// The time in seconds that is allowed for a primary PostgreSQL instance // to gracefully shutdown during a switchover. // ... // to be unhealthy // kubebuilder:default:0 // optional FailoverDelay int32 json:failoverDelay,omitempty默认值为 0即默认立即触发故障切换。对应地集群状态中新增了currentPrimaryFailingSinceTimestamp字段用于记录主库被检测为不健康的时间点见 api/v1/cluster_types.go#L1063-L1068。该字段在.spec.failoverDelay被设置或执行在线升级online upgrade期间上报。2.3 其他特性与增强Kubernetes projected volumes 支持#1269实例 Pod 可以挂载 projected volumes用于注入 Secret、ConfigMap、Downward API 等组合内容简化配置注入。自定义环境变量#1275允许通过自定义环境变量对 PostgreSQL 服务进程进行更细粒度的控制。cnpg插件新增backup命令#1348可直接通过 kubectl 插件为集群发起一次新的基础备份。独立 WAL 卷能力增强#1066允许在已有 PostgreSQL 集群上将 WAL 文件迁移到独立卷这是walStorage特性在 1.19 中的关键补强同期修复了使用pvcTemplate时walStorage无法扩容的问题#1315。WAL 可观测性增强#1382为 Prometheus exporter 增加与 WAL 尺寸相关的额外指标包括与min_wal_size、max_wal_size、keep_wal_size、wal_keep_segments等价的取值以及独立 WAL 卷中可存放的最大 WAL 数量。streaming_replica用户数据库注释#1349为该内置复制用户补充数据库注释同时修复了以streaming_replica身份执行CHECKPOINT的问题#1408。文档与安装体验新增 GKE webhook 防火墙问题说明#1364、recovery中postgresql.conf注意事项#1211、插件包安装指引#1357、各次版本支持的 PostgreSQL 版本对照#1355、PVC 分组含义说明#1344以及 DigitalOcean S3 兼容 Spaces 的示例#1289架构文档进一步细化了 Kubernetes 层#1432。默认 PostgreSQL 版本更新新集群定义默认 PostgreSQL 版本更新到 15.2#1430。技术增强为发布分支增加每日端到端冒烟测试#1235。2.4 修复要点waitForWalArchiveWorking对连接错误更健壮#1399保证 PVC 角色始终一致#1380ExecCommand严格遵守超时#1242未安装 Prometheus 时避免PodMonitor的不必要协调#1238、#1213。3. Version 1.19.1备份目标策略与复制参数1.19.1 发布于 2023 年 3 月 20 日主要围绕备份策略的灵活性与实例管理可观测性展开。3.1 覆盖默认备份目标策略#1602此前所有Backup与ScheduledBackup都会继承集群级的备份目标策略1.19.1 允许在单个备份资源上覆盖默认目标策略。这与前文 api/v1/backup_types.go#L131-L139 中Target字段的行为一致——单次备份既可以走primary也可以走prefer-standby。3.2 新增psql命令#1668cnpg插件新增psql命令允许用户直接与某个 Pod默认是主库建立psql会话简化日常排障。同时report命令的--logs选项也在此系列中持续增强。3.3 PgBouncer 池化增强#1395池化器Pooler支持 IPv6 以及自定义pg_hba规则适应更复杂的网络与安全要求。3.4 其他要点debug集群日志级别扩展到initdbjob#1503备份可观测性增强新增两个指标并在 status 中提供更多信息#1428文档记录实例管理器的 API 调用#1641采用 Renovate 进行依赖跟踪与更新#1367、#1473操作员镜像注入所有支持架构的二进制文件#1513备份对象存储中改用备份名称匹配资源#1650利用 Barman 3.3 引入的--name选项使备份与对象存储的关联更健壮。修复方面包括probe 错误处理的 panic 防护#1716、HTTP 与 controller-runtime 日志统一为 JSON 格式#1442、单实例集群正确添加 WAL 存储#1570、status命令正确显示 WAL 归档信息#1666、未设置AdditionalPodAffinity/AdditionalPodAntiAffinity时nodeAffinity依然生效#1663、在线升级阶段引入故障切换延迟避免无谓触发 failover#1728。4. Version 1.19.2报告命令与安全加固1.19.22023 年 4 月 27 日内容相对精简report命令的--logs选项在可用时同时包含前一轮 Pod 日志#1811-any服务默认禁用#1755减少无明确指向的服务暴露安全方面允许通过本地文件 override 自定义SeccompProfile#1827修复用户提供的 PostgreSQL 配置会在initdb引导阶段、服务器首次启动之前应用#1858确保初始化即使用目标配置。5. Version 1.19.3VolumeSnapshot 冷备份与恢复1.19.32023 年 6 月 12 日是功能量较大的一次补丁版本其中两项能力构成了 CloudNativePG 卷快照备份体系的基础。5.1cnpg插件新增snapshot命令#1960该命令基于 Kubernetes 标准资源VolumeSnapshot从备库standby创建集群的一致冷备份cold backup与在线热备份形成互补。冷备份需要短暂暂停实例以保证文件系统一致性适合对在线窗口要求不严苛的场景。5.2 从 CSI VolumeSnapshot 恢复#19601.19.3 首次实现了通过.spec.bootstrap.recovery.volumeSnapshot配置段从一组 CSIVolumeSnapshot资源执行恢复。这在当前 API 中有直接体现api/v1/backup_types.go#L111-L114 定义BackupMethodVolumeSnapshot volumeSnapshot作为三种备份方法之一另两种为barmanObjectStore与plugin见 api/v1/backup_types.go#L141-L146api/v1/backup_funcs.go#L86-L96 的SetSnapshotElements从一组VolumeSnapshot填充备份状态中的Elements列表并记录每个快照对应的 PVC 角色类型与表空间名称api/v1/backup_types.go#L176-L178 定义了仅属于 volumeSnapshot 方法的BackupSnapshotStatus状态结构。此外备份方法枚举校验barmanObjectStore;volumeSnapshot;plugin与默认值barmanObjectStore也都能在 api/v1/backup_types.go#L141-L146 中查到。5.3 其他增强pg_failover_slots加入受管理的扩展列表#2057Grafana dashboard 改进并更新文档与快速入门指引#1916import配置段引入schemaOnly选项#2234引导新集群时只导入/导出数据库结构而不导入数据。该字段在 api/v1/cluster_types.go#L2076-L2079 中定义为true时仅执行pg_restore的pre-data与post-data段跳过数据导入默认false支持TopologySpreadConstraints管理实例 Pod 的调度分布#2202Pooler支持PodMonitorPgBouncer 监控#2034与部署策略自定义#1983允许覆盖默认 Kubernetes 调度器#2013默认 PostgreSQL 版本更新至 15.3#2022默认 PgBouncer 版本更新至 1.19#2018。5.4 修复与内部改进角色凭据以独立事务协调避免单角色失败导致全部角色同步回滚#2004集群恢复期间移除 fencing#1987删除 Pod 时的日志改进#2136修复 k3d 引擎未绑定变量导致无法搭建的问题#2157指标中正确上报 PostgreSQL 版本#2126文档中walStorage键名修正#2140当操作员无法连接实例时暂停协调并给出清晰诊断#2145、#2233、#2242帮助快速定位网络问题导致的异常。6. Version 1.19.4日志命令与调度优先级1.19.42023 年 7 月 27 日聚焦可观测性与调度能力新增logs命令#2375cnpg插件支持获取或持续跟随follow集群内所有 Pod 的日志一条命令即可聚合查看整个集群的日志流priorityClassName支持#2043可在 Pod 上指定优先级类帮助 Kubernetes 做出更合理的调度决策抢占/优先级节点用量监控#2257新增指标与状态字段监控 CloudNativePG 集群对节点的资源占用文档增强#1390、#2344补充 hugepages 相关的故障排查指引并扩展 FAQ技术增强#2419恢复流程开始前增加前置检查若无法继续则给出更明确的错误诊断。修复包括恢复目标设置逻辑与 PostgreSQL 行为对齐#2460仅在创建 ServiceAccount 时设置 ownerMetadata防止接管不属于本集群的 ServiceAccount#2462保证 initdb 与恢复时 PGDATA 目录权限正确#2384修复配置 reload 期间实例管理器可能的崩溃#2393避免在后续备份成功后仍触发LastFailedArchiveTime告警#1751防止 Service 误指向非实例 Pod#2336。同时更新了全部项目依赖至最新版本。7. Version 1.19.5实例生命周期默认值重构1.19.52023 年 10 月 11 日包含本版本线中最值得注意的行为变更——它重构了实例启停与切换的超时模型并给出了新的一致性默认值。7.1 新的启停超时模型参数旧默认值新默认值含义stopDelay30 秒1800 秒允许 PostgreSQL 实例优雅关闭的最大窗口#2848smartShutdownTimeout—新增180 秒为 PostgreSQL 智能关闭smart shutdown预留的完成时间窗口startDelay30 秒3600 秒允许实例启动含恢复的最大窗口#2847switchoverDelay40000000 秒3600 秒切换switchover期间允许主实例优雅关闭的时间#2846其中停止 PostgreSQL 的总体超时公式为max(stopDelay - smartShutdownTimeout, 30)即先给 PostgreSQL 预留smartShutdownTimeout默认 180 秒完成智能关闭若超时未完成再以stopDelay - smartShutdownTimeout作为快速关闭fast shutdown的剩余窗口且下限为 30 秒。这些默认值在源码中均有对应实现api/v1/cluster_funcs.go#L741-L747GetMaxStartDelay()spec.maxStartDelay大于 0 时取之否则返回DefaultStartupDelayapi/v1/cluster_funcs.go#L757-L763GetSmartShutdownTimeout()spec.smartShutdownTimeout非空时取其值否则返回 180api/v1/cluster_types.go#L367-L373 中SmartShutdownTimeout的注释明确给出默认 180 秒并提示应为操作员执行 fast shutdown 预留stopDelay - smartShutdownTimeout的时间api/v1/cluster_funcs.go#L805-L811GetMaxSwitchoverDelay()spec.maxSwitchoverDelay大于 0 时取之否则返回DefaultMaxSwitchoverDelay即 3600 秒。升级注意stopDelay从 30 秒变为 1800 秒意味着在默认情况下实例停止会等待更长的时间用于数据落盘与优雅退出这更适合大规模、高负载生产集群若你的场景需要快速回收节点请显式配置较小的stopDelay。7.2 startup probe 取代 livenessProbe 初始延迟#28471.19.5 用 Kubernetes 启动探针startup probe取代 livenessProbe 的初始延迟以更合理地处理 PostgreSQL 服务进程启动尤其是启动耗时的恢复场景避免在启动早期被误判为不健康。7.3 标签体系收敛弃用postgresql标签#27441.19.5 停止支持postgresql标签统一由 1.18 引入的cnpg.io/cluster取代同时新增cnpg.io/instanceRole标签并弃用原有role标签#2915。若你的监控、网络策略或其他工具仍依赖旧标签升级前需同步调整。7.4 其他变更默认操作镜像更新为 PostgreSQL 16.0Fencing 改用 fast shutdown#3051围栏fencing实例时由智能关闭改为快速关闭确保被隔离实例更快停止webhook 组名从 kb.io 改为 cnpg.io#2851cnpg hibernate插件命令改用 PVC 上的ClusterManifestAnnotationName与PgControldataAnnotationName注解#2657技术增强用gen-crd-api-reference-docs替换k8s-api-docgen自动生成 API 参考文档#2606。7.5 安全默认 seccompProfile#2926操作员 Deployment 增加默认seccompProfile为容器运行提供额外的系统调用隔离层这与 1.19.2 允许通过本地文件自定义 SeccompProfile#1827相互配合。7.6 新增注解与资源校验cnpg.io/coredumpFilter注解#2733控制 PostgreSQL 崩溃后生成的 core dump 内容默认排除共享内存段避免 dump 文件过大临时卷的 ephemeral-storage 限制#2830可为共享内存与临时数据的 ephemeral 卷配置存储上限资源校验#2663通过 webhook 校验资源 limits 与 requestsshared_buffers与 Pod 内存协调#2840确保 PostgreSQL 的shared_buffers与 Pod 分配的内存资源保持一致凭据 Secret 新增uri与jdbc-uri字段#2186方便应用直接以统一 URI 连接数据库新阶段「Waiting for the instances to become active」#2612集群等待副本就绪时有更细粒度的状态控制Pod 滚动条件检测改进#2243通过podSpec注解更准确地判断滚动更新条件status命令新增主库时间戳与运行时长#2953。7.7 修复要点主实例优先重建优先具备 primary 角色的就绪 PVC#2544恢复时遵循cnpg.io/skipEmptyWalArchiveCheck注解跳过空 WAL 归档检查#2731修复主库 Pod 存活但 PostgreSQL 宕机时集群卡死的问题#2966启用复制槽时不再将副本集群中的 designated primary 当作普通 HA 副本处理#2960Service 在 selector 变更或标签/注解需要变化时重新协调#2918恢复引导时 owner 与 database 默认取app#2957避免缓存集群的写读并发问题#2884生成的 Role 的ResourceName段去空、去重并排序#2875ContinuousArchiving条件在出错时正确置为 failed#2625Backup协调循环只在备份完成或失败时停止提升中断场景下的韧性#2591协调 PodMonitor 的 labels 与 annotations#2583修复 Role 对象缺少 RBACresourceNames导致的备份失败#2956。可观测性修复包括默认pg_stat_replication指标增加 TCP 端口标签#2961、修复 Prometheus 的pg_wal_stat默认指标#2569、改进pg_replication默认指标#2744、#2750、Grafana dashboard 使用alertInstanceLabelFilter替代alertName、指标采集强制standard_conforming_strings#2888。8. Version 1.19.6收尾版本1.19.62023 年 11 月 3 日是 1.19 系列的收官版本status命令增强#3101cnpg插件的status命令在活动流式基础备份进行中显示进度信息PgBouncer 的max_prepared_statements#3174允许通过Pooler资源配置 PgBouncer 的max_prepared_statements参数。该参数属于 PgBouncer 连接池行为配置在仓库文档 docs/src/connection_pooling.md#L597-L599 中也被列为可配置参数之一。修复切换期间挂起/恢复 WAL 归档#3227切换switchover期间挂起 WAL 归档完成后恢复避免归档过程中因角色变动产生不一致实例管理器统一使用synchronous_commit local#3143确保实例管理器在管理 PostgreSQL 集群时始终使用本地同步提交语义避免外部配置干扰复制流用户的自定义证书修复#3209通过.spec.certificates.replicationTLSSecret提供的自定义证书现在可以正常工作。源码中 api/v1/cluster_funcs.go#L698-L703 的GetReplicationSecretName()表明当Spec.Certificates.ReplicationTLSSecret非空时复制用户证书使用该 Secret 名称否则使用默认的clusterName-replicationcnpg.io/cluster标签应用到 Pooler Pod#3153。变更复制参数配置从postgresql.auto.conf迁移到override.conf#2812实例管理器不再通过 PGDATA 中的postgresql.auto.conf控制复制相关设置而是使用独立文件override.conf。仓库 pkg/configfile/configfile_test.go#L148-L162 的测试印证了该文件的 include 管理机制CloudNativePG 会在postgresql.conf中追加include override.conf将复制参数与用户配置清晰分离降低被ALTER SYSTEM意外覆盖的风险。技术增强实例管理器改用 PostgreSQL 扩展查询协议extended query protocol#3152提升与 PostgreSQL 交互的效率与安全性。9. 升级到 1.19 的检查清单综合整个 1.19 版本线升级前请重点确认以下事项标签依赖postgresql标签已被废弃1.19.5#2744请将所有依赖迁移到cnpg.io/cluster同时role标签开始被cnpg.io/instanceRole取代#2915。超时默认值变化stopDelay30→1800、startDelay30→3600、switchoverDelay40000000→3600均发生大幅变化评估你的节点维护、驱逐drain流程是否可接受更长的等待窗口。webhook 组名从 kb.io 改为 cnpg.io#2851检查依赖 webhook 配置的工具与网络策略。复制参数文件从postgresql.auto.conf迁移到override.conf#2812若你曾直接修改前者需改为通过 operator 配置管理。PostgreSQL 版本1.19 不再支持 PostgreSQL 10且默认镜像先后更新为 15.3/16.0确认目标 PostgreSQL 主版本符合支持范围。安全基线operator 默认启用seccompProfile#2926确认你的运行时环境如 OpenShift SCC、自定义 CRI兼容默认 seccomp 配置。10. 结语CloudNativePG 1.19 是一个「承上启下」的版本线它一方面补齐了从备库备份、VolumeSnapshot 冷备份/恢复、延迟故障切换等关键运维能力另一方面通过超时模型重构、标签收敛与复制参数文件迁移为后续版本的稳定性与可维护性奠定了基础。文中涉及的源码与配置说明均可直接在仓库中继续深挖实例生命周期超时默认值 api/v1/cluster_funcs.go#L741-L811备份目标策略与快照方法 api/v1/backup_types.go#L111-L178、api/v1/cluster_types.go#L2424-L2468复制参数 override.conf 管理 pkg/configfile/configfile_test.go#L148-L193完整发布说明原文 docs/src/release_notes/old/v1.19.md【免费下载链接】cloudnative-pgThe most popular Kubernetes Operator for PostgreSQL.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudnative-pg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CloudNativePG 1.19 版本发布说明深度解析从 standby 备份到实例生命周期控制【免费下载链接】cloudnative-pgThe most popular Kubernetes Operator for PostgreSQL.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudnative-pgCloudNativePG 1.19 是 2023 年 2 月至 11 月期间维护的次版本线涵盖 1.19.0 至 1.19.6 共 7 个补丁版本。该版本线引入了「从备库standby发起物理备份」「延迟故障切换failoverDelay」「基于 CSI VolumeSnapshot 的冷备份与恢复」等核心能力同时系统性地重构了 PostgreSQL 实例的启停超时模型与复制参数管理方式。本文以官方发布说明为骨架结合当前仓库源码api/v1/cluster_types.go、api/v1/backup_types.go 等逐条展开帮助读者完整理解 1.19 的每一项变更以及它们在实际集群运维中的意义。说明本文以仓库中的 docs/src/release_notes/old/v1.19.md 为唯一事实骨架文中所有源码引用均来自当前仓库对应实现。1. 版本线概览与支持周期CloudNativePG 1.19 系列共发布 7 个版本发布节奏与日期如下版本发布日期定位1.19.02023 年 2 月 14 日特性基线版本1.19.12023 年 3 月 20 日补丁版本1.19.22023 年 4 月 27 日补丁版本1.19.32023 年 6 月 12 日补丁版本1.19.42023 年 7 月 27 日补丁版本1.19.52023 年 10 月 11 日补丁版本含重要默认值变更1.19.62023 年 11 月 3 日1.19 系列收尾版本官方在 1.19.6 发布时明确提示这将是 1.19.X 系列的最后一次发布建议用户尽快升级到更新的次版本1.19.5 发布时也预告了 End-of-LifeEOL日期为 2023 年 11 月 9 日。因此若你仍在运行 1.19 系列应优先规划升级到 1.20 及更高版本。另外1.19.0 的发布说明中有一条重要声明PostgreSQL 10 已到达其生命周期终点EOL不再受支持1.19 系列支持的 PostgreSQL 版本为 11 及更新版本。官方建议尽快规划向 PostgreSQL 15 的迁移并指向文档 docs/src/database_import.md 了解 PostgreSQL 大版本离线升级major offline upgrade的细节。2. Version 1.19.0特性基线1.19.0 是 1.19 系列的功能地基其引入的特性大多持续沿用至今。2.1 从备库发起备份.spec.backup.target prefer-standby1.19.0 在备份功能中引入了.spec.backup.target选项当设置为prefer-standby时物理基础备份physical base backup将优先由对齐程度最高的备库most aligned replica执行从而把备份产生的 I/O 压力从主库转移到备库显著降低对生产主库的影响。这一设计在当前的 API 定义中依然可见api/v1/cluster_types.go#L2424-L2436 定义了BackupTarget字符串类型及两个常量BackupTargetPrimary primary与BackupTargetStandby prefer-standbyapi/v1/cluster_types.go#L2460-L2467 中.spec.backup.target的可选值为空字符串、primary与prefer-standby且kubebuilder:default:prefer-standby即默认策略即为优先使用备库api/v1/backup_types.go#L131-L139 表明单个Backup资源可以覆盖集群级目标策略Target字段为空时回退到cluster.spec.backup.target可选值同样被 webhook 校验限定为primary;prefer-standby。从源码结构看集群默认值填充逻辑位于 api/v1/cluster_defaults.go#L88-L90当r.Spec.Backup ! nil r.Spec.Backup.Target 时Target会被设置为DefaultBackupTarget即prefer-standby。这意味着只要启用了备份配置且未显式指定1.19 起备份默认就会寻找可用的备库来执行。2.2 延迟故障切换failoverDelay参数当主库被检测为不健康时1.19.0 引入failoverDelay参数来控制故障切换流程的启动延迟——即在主库失联后等待一段时间再触发 failover为「短暂抖动」留出缓冲避免不必要的切换。源码中 api/v1/cluster_types.go#L375-L387 定义// The time in seconds that is allowed for a primary PostgreSQL instance // to gracefully shutdown during a switchover. // ... // to be unhealthy // kubebuilder:default:0 // optional FailoverDelay int32 json:failoverDelay,omitempty默认值为 0即默认立即触发故障切换。对应地集群状态中新增了currentPrimaryFailingSinceTimestamp字段用于记录主库被检测为不健康的时间点见 api/v1/cluster_types.go#L1063-L1068。该字段在.spec.failoverDelay被设置或执行在线升级online upgrade期间上报。2.3 其他特性与增强Kubernetes projected volumes 支持#1269实例 Pod 可以挂载 projected volumes用于注入 Secret、ConfigMap、Downward API 等组合内容简化配置注入。自定义环境变量#1275允许通过自定义环境变量对 PostgreSQL 服务进程进行更细粒度的控制。cnpg插件新增backup命令#1348可直接通过 kubectl 插件为集群发起一次新的基础备份。独立 WAL 卷能力增强#1066允许在已有 PostgreSQL 集群上将 WAL 文件迁移到独立卷这是walStorage特性在 1.19 中的关键补强同期修复了使用pvcTemplate时walStorage无法扩容的问题#1315。WAL 可观测性增强#1382为 Prometheus exporter 增加与 WAL 尺寸相关的额外指标包括与min_wal_size、max_wal_size、keep_wal_size、wal_keep_segments等价的取值以及独立 WAL 卷中可存放的最大 WAL 数量。streaming_replica用户数据库注释#1349为该内置复制用户补充数据库注释同时修复了以streaming_replica身份执行CHECKPOINT的问题#1408。文档与安装体验新增 GKE webhook 防火墙问题说明#1364、recovery中postgresql.conf注意事项#1211、插件包安装指引#1357、各次版本支持的 PostgreSQL 版本对照#1355、PVC 分组含义说明#1344以及 DigitalOcean S3 兼容 Spaces 的示例#1289架构文档进一步细化了 Kubernetes 层#1432。默认 PostgreSQL 版本更新新集群定义默认 PostgreSQL 版本更新到 15.2#1430。技术增强为发布分支增加每日端到端冒烟测试#1235。2.4 修复要点waitForWalArchiveWorking对连接错误更健壮#1399保证 PVC 角色始终一致#1380ExecCommand严格遵守超时#1242未安装 Prometheus 时避免PodMonitor的不必要协调#1238、#1213。3. Version 1.19.1备份目标策略与复制参数1.19.1 发布于 2023 年 3 月 20 日主要围绕备份策略的灵活性与实例管理可观测性展开。3.1 覆盖默认备份目标策略#1602此前所有Backup与ScheduledBackup都会继承集群级的备份目标策略1.19.1 允许在单个备份资源上覆盖默认目标策略。这与前文 api/v1/backup_types.go#L131-L139 中Target字段的行为一致——单次备份既可以走primary也可以走prefer-standby。3.2 新增psql命令#1668cnpg插件新增psql命令允许用户直接与某个 Pod默认是主库建立psql会话简化日常排障。同时report命令的--logs选项也在此系列中持续增强。3.3 PgBouncer 池化增强#1395池化器Pooler支持 IPv6 以及自定义pg_hba规则适应更复杂的网络与安全要求。3.4 其他要点debug集群日志级别扩展到initdbjob#1503备份可观测性增强新增两个指标并在 status 中提供更多信息#1428文档记录实例管理器的 API 调用#1641采用 Renovate 进行依赖跟踪与更新#1367、#1473操作员镜像注入所有支持架构的二进制文件#1513备份对象存储中改用备份名称匹配资源#1650利用 Barman 3.3 引入的--name选项使备份与对象存储的关联更健壮。修复方面包括probe 错误处理的 panic 防护#1716、HTTP 与 controller-runtime 日志统一为 JSON 格式#1442、单实例集群正确添加 WAL 存储#1570、status命令正确显示 WAL 归档信息#1666、未设置AdditionalPodAffinity/AdditionalPodAntiAffinity时nodeAffinity依然生效#1663、在线升级阶段引入故障切换延迟避免无谓触发 failover#1728。4. Version 1.19.2报告命令与安全加固1.19.22023 年 4 月 27 日内容相对精简report命令的--logs选项在可用时同时包含前一轮 Pod 日志#1811-any服务默认禁用#1755减少无明确指向的服务暴露安全方面允许通过本地文件 override 自定义SeccompProfile#1827修复用户提供的 PostgreSQL 配置会在initdb引导阶段、服务器首次启动之前应用#1858确保初始化即使用目标配置。5. Version 1.19.3VolumeSnapshot 冷备份与恢复1.19.32023 年 6 月 12 日是功能量较大的一次补丁版本其中两项能力构成了 CloudNativePG 卷快照备份体系的基础。5.1cnpg插件新增snapshot命令#1960该命令基于 Kubernetes 标准资源VolumeSnapshot从备库standby创建集群的一致冷备份cold backup与在线热备份形成互补。冷备份需要短暂暂停实例以保证文件系统一致性适合对在线窗口要求不严苛的场景。5.2 从 CSI VolumeSnapshot 恢复#19601.19.3 首次实现了通过.spec.bootstrap.recovery.volumeSnapshot配置段从一组 CSIVolumeSnapshot资源执行恢复。这在当前 API 中有直接体现api/v1/backup_types.go#L111-L114 定义BackupMethodVolumeSnapshot volumeSnapshot作为三种备份方法之一另两种为barmanObjectStore与plugin见 api/v1/backup_types.go#L141-L146api/v1/backup_funcs.go#L86-L96 的SetSnapshotElements从一组VolumeSnapshot填充备份状态中的Elements列表并记录每个快照对应的 PVC 角色类型与表空间名称api/v1/backup_types.go#L176-L178 定义了仅属于 volumeSnapshot 方法的BackupSnapshotStatus状态结构。此外备份方法枚举校验barmanObjectStore;volumeSnapshot;plugin与默认值barmanObjectStore也都能在 api/v1/backup_types.go#L141-L146 中查到。5.3 其他增强pg_failover_slots加入受管理的扩展列表#2057Grafana dashboard 改进并更新文档与快速入门指引#1916import配置段引入schemaOnly选项#2234引导新集群时只导入/导出数据库结构而不导入数据。该字段在 api/v1/cluster_types.go#L2076-L2079 中定义为true时仅执行pg_restore的pre-data与post-data段跳过数据导入默认false支持TopologySpreadConstraints管理实例 Pod 的调度分布#2202Pooler支持PodMonitorPgBouncer 监控#2034与部署策略自定义#1983允许覆盖默认 Kubernetes 调度器#2013默认 PostgreSQL 版本更新至 15.3#2022默认 PgBouncer 版本更新至 1.19#2018。5.4 修复与内部改进角色凭据以独立事务协调避免单角色失败导致全部角色同步回滚#2004集群恢复期间移除 fencing#1987删除 Pod 时的日志改进#2136修复 k3d 引擎未绑定变量导致无法搭建的问题#2157指标中正确上报 PostgreSQL 版本#2126文档中walStorage键名修正#2140当操作员无法连接实例时暂停协调并给出清晰诊断#2145、#2233、#2242帮助快速定位网络问题导致的异常。6. Version 1.19.4日志命令与调度优先级1.19.42023 年 7 月 27 日聚焦可观测性与调度能力新增logs命令#2375cnpg插件支持获取或持续跟随follow集群内所有 Pod 的日志一条命令即可聚合查看整个集群的日志流priorityClassName支持#2043可在 Pod 上指定优先级类帮助 Kubernetes 做出更合理的调度决策抢占/优先级节点用量监控#2257新增指标与状态字段监控 CloudNativePG 集群对节点的资源占用文档增强#1390、#2344补充 hugepages 相关的故障排查指引并扩展 FAQ技术增强#2419恢复流程开始前增加前置检查若无法继续则给出更明确的错误诊断。修复包括恢复目标设置逻辑与 PostgreSQL 行为对齐#2460仅在创建 ServiceAccount 时设置 ownerMetadata防止接管不属于本集群的 ServiceAccount#2462保证 initdb 与恢复时 PGDATA 目录权限正确#2384修复配置 reload 期间实例管理器可能的崩溃#2393避免在后续备份成功后仍触发LastFailedArchiveTime告警#1751防止 Service 误指向非实例 Pod#2336。同时更新了全部项目依赖至最新版本。7. Version 1.19.5实例生命周期默认值重构1.19.52023 年 10 月 11 日包含本版本线中最值得注意的行为变更——它重构了实例启停与切换的超时模型并给出了新的一致性默认值。7.1 新的启停超时模型参数旧默认值新默认值含义stopDelay30 秒1800 秒允许 PostgreSQL 实例优雅关闭的最大窗口#2848smartShutdownTimeout—新增180 秒为 PostgreSQL 智能关闭smart shutdown预留的完成时间窗口startDelay30 秒3600 秒允许实例启动含恢复的最大窗口#2847switchoverDelay40000000 秒3600 秒切换switchover期间允许主实例优雅关闭的时间#2846其中停止 PostgreSQL 的总体超时公式为max(stopDelay - smartShutdownTimeout, 30)即先给 PostgreSQL 预留smartShutdownTimeout默认 180 秒完成智能关闭若超时未完成再以stopDelay - smartShutdownTimeout作为快速关闭fast shutdown的剩余窗口且下限为 30 秒。这些默认值在源码中均有对应实现api/v1/cluster_funcs.go#L741-L747GetMaxStartDelay()spec.maxStartDelay大于 0 时取之否则返回DefaultStartupDelayapi/v1/cluster_funcs.go#L757-L763GetSmartShutdownTimeout()spec.smartShutdownTimeout非空时取其值否则返回 180api/v1/cluster_types.go#L367-L373 中SmartShutdownTimeout的注释明确给出默认 180 秒并提示应为操作员执行 fast shutdown 预留stopDelay - smartShutdownTimeout的时间api/v1/cluster_funcs.go#L805-L811GetMaxSwitchoverDelay()spec.maxSwitchoverDelay大于 0 时取之否则返回DefaultMaxSwitchoverDelay即 3600 秒。升级注意stopDelay从 30 秒变为 1800 秒意味着在默认情况下实例停止会等待更长的时间用于数据落盘与优雅退出这更适合大规模、高负载生产集群若你的场景需要快速回收节点请显式配置较小的stopDelay。7.2 startup probe 取代 livenessProbe 初始延迟#28471.19.5 用 Kubernetes 启动探针startup probe取代 livenessProbe 的初始延迟以更合理地处理 PostgreSQL 服务进程启动尤其是启动耗时的恢复场景避免在启动早期被误判为不健康。7.3 标签体系收敛弃用postgresql标签#27441.19.5 停止支持postgresql标签统一由 1.18 引入的cnpg.io/cluster取代同时新增cnpg.io/instanceRole标签并弃用原有role标签#2915。若你的监控、网络策略或其他工具仍依赖旧标签升级前需同步调整。7.4 其他变更默认操作镜像更新为 PostgreSQL 16.0Fencing 改用 fast shutdown#3051围栏fencing实例时由智能关闭改为快速关闭确保被隔离实例更快停止webhook 组名从 kb.io 改为 cnpg.io#2851cnpg hibernate插件命令改用 PVC 上的ClusterManifestAnnotationName与PgControldataAnnotationName注解#2657技术增强用gen-crd-api-reference-docs替换k8s-api-docgen自动生成 API 参考文档#2606。7.5 安全默认 seccompProfile#2926操作员 Deployment 增加默认seccompProfile为容器运行提供额外的系统调用隔离层这与 1.19.2 允许通过本地文件自定义 SeccompProfile#1827相互配合。7.6 新增注解与资源校验cnpg.io/coredumpFilter注解#2733控制 PostgreSQL 崩溃后生成的 core dump 内容默认排除共享内存段避免 dump 文件过大临时卷的 ephemeral-storage 限制#2830可为共享内存与临时数据的 ephemeral 卷配置存储上限资源校验#2663通过 webhook 校验资源 limits 与 requestsshared_buffers与 Pod 内存协调#2840确保 PostgreSQL 的shared_buffers与 Pod 分配的内存资源保持一致凭据 Secret 新增uri与jdbc-uri字段#2186方便应用直接以统一 URI 连接数据库新阶段「Waiting for the instances to become active」#2612集群等待副本就绪时有更细粒度的状态控制Pod 滚动条件检测改进#2243通过podSpec注解更准确地判断滚动更新条件status命令新增主库时间戳与运行时长#2953。7.7 修复要点主实例优先重建优先具备 primary 角色的就绪 PVC#2544恢复时遵循cnpg.io/skipEmptyWalArchiveCheck注解跳过空 WAL 归档检查#2731修复主库 Pod 存活但 PostgreSQL 宕机时集群卡死的问题#2966启用复制槽时不再将副本集群中的 designated primary 当作普通 HA 副本处理#2960Service 在 selector 变更或标签/注解需要变化时重新协调#2918恢复引导时 owner 与 database 默认取app#2957避免缓存集群的写读并发问题#2884生成的 Role 的ResourceName段去空、去重并排序#2875ContinuousArchiving条件在出错时正确置为 failed#2625Backup协调循环只在备份完成或失败时停止提升中断场景下的韧性#2591协调 PodMonitor 的 labels 与 annotations#2583修复 Role 对象缺少 RBACresourceNames导致的备份失败#2956。可观测性修复包括默认pg_stat_replication指标增加 TCP 端口标签#2961、修复 Prometheus 的pg_wal_stat默认指标#2569、改进pg_replication默认指标#2744、#2750、Grafana dashboard 使用alertInstanceLabelFilter替代alertName、指标采集强制standard_conforming_strings#2888。8. Version 1.19.6收尾版本1.19.62023 年 11 月 3 日是 1.19 系列的收官版本status命令增强#3101cnpg插件的status命令在活动流式基础备份进行中显示进度信息PgBouncer 的max_prepared_statements#3174允许通过Pooler资源配置 PgBouncer 的max_prepared_statements参数。该参数属于 PgBouncer 连接池行为配置在仓库文档 docs/src/connection_pooling.md#L597-L599 中也被列为可配置参数之一。修复切换期间挂起/恢复 WAL 归档#3227切换switchover期间挂起 WAL 归档完成后恢复避免归档过程中因角色变动产生不一致实例管理器统一使用synchronous_commit local#3143确保实例管理器在管理 PostgreSQL 集群时始终使用本地同步提交语义避免外部配置干扰复制流用户的自定义证书修复#3209通过.spec.certificates.replicationTLSSecret提供的自定义证书现在可以正常工作。源码中 api/v1/cluster_funcs.go#L698-L703 的GetReplicationSecretName()表明当Spec.Certificates.ReplicationTLSSecret非空时复制用户证书使用该 Secret 名称否则使用默认的clusterName-replicationcnpg.io/cluster标签应用到 Pooler Pod#3153。变更复制参数配置从postgresql.auto.conf迁移到override.conf#2812实例管理器不再通过 PGDATA 中的postgresql.auto.conf控制复制相关设置而是使用独立文件override.conf。仓库 pkg/configfile/configfile_test.go#L148-L162 的测试印证了该文件的 include 管理机制CloudNativePG 会在postgresql.conf中追加include override.conf将复制参数与用户配置清晰分离降低被ALTER SYSTEM意外覆盖的风险。技术增强实例管理器改用 PostgreSQL 扩展查询协议extended query protocol#3152提升与 PostgreSQL 交互的效率与安全性。9. 升级到 1.19 的检查清单综合整个 1.19 版本线升级前请重点确认以下事项标签依赖postgresql标签已被废弃1.19.5#2744请将所有依赖迁移到cnpg.io/cluster同时role标签开始被cnpg.io/instanceRole取代#2915。超时默认值变化stopDelay30→1800、startDelay30→3600、switchoverDelay40000000→3600均发生大幅变化评估你的节点维护、驱逐drain流程是否可接受更长的等待窗口。webhook 组名从 kb.io 改为 cnpg.io#2851检查依赖 webhook 配置的工具与网络策略。复制参数文件从postgresql.auto.conf迁移到override.conf#2812若你曾直接修改前者需改为通过 operator 配置管理。PostgreSQL 版本1.19 不再支持 PostgreSQL 10且默认镜像先后更新为 15.3/16.0确认目标 PostgreSQL 主版本符合支持范围。安全基线operator 默认启用seccompProfile#2926确认你的运行时环境如 OpenShift SCC、自定义 CRI兼容默认 seccomp 配置。10. 结语CloudNativePG 1.19 是一个「承上启下」的版本线它一方面补齐了从备库备份、VolumeSnapshot 冷备份/恢复、延迟故障切换等关键运维能力另一方面通过超时模型重构、标签收敛与复制参数文件迁移为后续版本的稳定性与可维护性奠定了基础。文中涉及的源码与配置说明均可直接在仓库中继续深挖实例生命周期超时默认值 api/v1/cluster_funcs.go#L741-L811备份目标策略与快照方法 api/v1/backup_types.go#L111-L178、api/v1/cluster_types.go#L2424-L2468复制参数 override.conf 管理 pkg/configfile/configfile_test.go#L148-L193完整发布说明原文 docs/src/release_notes/old/v1.19.md【免费下载链接】cloudnative-pgThe most popular Kubernetes Operator for PostgreSQL.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudnative-pg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
