云原生后端数据库运维【免费下载链接】postgres-operatorPostgres operator creates and manages PostgreSQL clusters running in Kubernetes项目地址https://gitcode.com/gh_mirrors/po/postgres-operator点击查看免费下载本指南以 README.md 为核心骨架结合仓库内的 概念文档、快速上手、配置参数参考、集群清单参考 以及 v1→v2 迁移指南并辅以pkg/目录下的控制器与集群源码系统讲解 Postgres Operator 的工作原理、功能矩阵、版本支持、部署方式与迁移要点。读完本文你将掌握如何在 Kubernetes 上通过 CRD 清单声明式地创建、升级、备份和删除 Patroni 驱动的高可用 PostgreSQL 集群并理解滚动更新、在线扩容、连接池、就地大版本升级等关键能力的实现机制。一、Postgres Operator 是什么核心工作模型Postgres Operator 在 Kubernetes 上交付易于运行、开箱即用的高可用 PostgreSQL 集群底层由 Patroni 驱动README 原文delivers an easy to run highly-available PostgreSQL clusters on Kubernetes powered by Patroni。它的核心设计哲学是只通过 Postgres 清单即 CRD进行配置从而无缝融入没有 Kubernetes API 直接访问权限的自动化 CI/CD 流水线以基础设施即代码Infrastructure as Code替代人工运维。概念文档 将它的工作方式归纳为四条循环监听清单变化operator 监听 PostgreSQL 集群清单manifest的增、删、改事件并据此变更运行中的集群。当用户提交一个新清单时operator 拉取该清单并创建一整套必要的实体——如 K8s StatefulSet、Postgres 角色、Service 与 Endpoint 等。监听自身配置变化operator 同时监听自身配置的变化。例如当 Pod 中的 Docker 镜像变更时operator 会执行滚动更新rolling update即逐个重启每个受管 StatefulSet 的 Pod 以应用新镜像。周期性对账operator 定期把每个 Postgres 集群的实际状态与清单定义的期望状态进行同步sync确保两者收敛一致。在源码中这一机制体现为 pkg/controller/operator_config.go 中的resync_period默认30m与repair_period默认5m两个配置项。免人工介入所有配置均通过清单完成无需直接访问 K8s API方便自动化部署流水线集成。职责边界Scopeoperator 的职责聚焦于供应provisioning、修改配置与清理使用 Patroni 的 Postgres 集群——既包括 K8s 资源层面也包括集群启动后的数据库与角色供应。它尽量把工作交给 Kubernetes 与 Patroni 完成尤其是集群引导和高可用自身只承担滚动更新等全局性编排。监控Monitoring与调优tuningPostgres不在当前 operator 的职责范围内但可以通过全局可配置的 sidecar灵活补充 Prometheus、ZMON 等工具。二、Operator 功能全览README 罗列了 operator 的核心功能。以下逐条展开并结合源码说明其实现路径。1. 滚动更新Rolling updates集群清单的任何变更——包括快速的次版本升级——都会触发滚动更新operator 逐个重新创建 StatefulSet 的 Pod用新镜像/新配置替换旧实例。滚动更新由 pkg/cluster/cluster.go 的Update流程驱动其中compareStatefulSetWithpkg/cluster/cluster.go负责对比新旧 StatefulSet 并判断是否需要滚动。与之相关的还有enable_lazy_spilo_upgrade参数默认false开启后 operator 只更新 StatefulSet 中的镜像Spilo 与 InitContainer而不立即执行滚动更新假设 Pod 会在稍后如节点轮换时以新镜像重启。2. 在线卷扩容Live volume resize支持不重启 Pod的在线卷扩容覆盖AWS EBS与PVC两种场景。该行为由storage_resize_mode配置项控制共四种取值模式行为ebsoperator 直接调整 EBS 卷并在 Pod 内执行resizefspvcoperator 仅修改 PVC 定义默认值mixed通过 AWS API 调整大小、类型、吞吐量与 IOPS并调用 PVC 变更完成文件系统扩容off禁用卷扩容相关实现位于 pkg/util/volumesEBS 相关见 pkg/util/volumes/ebs.go。注意 AWS 上运行需要 Spilo 容器以特权模式运行spilo_privileged: true因为 EBS 扩容依赖该能力。3. 数据库连接池PGBouncer通过PGBouncer提供数据库连接池。连接池既可以按集群清单启用enableConnectionPooler/enableReplicaConnectionPooler也可以在 operator 配置中预设全局默认值见 pkg/util/constants/pooler.go。全局默认配置包括connection_pooler_number_of_instancespooler 实例数默认2也是最低要求connection_pooler_image默认镜像ghcr.io/zalando/postgres-operator/pgbouncer:v2.0.3connection_pooler_max_db_connectionspooler 最大连接数默认60会在多个 pooler Pod 间均分即默认两实例时每 Pod 30 连接connection_pooler_mode默认transaction事务级池化可选sessionconnection_pooler_schema默认pooler用于存放凭据查询函数connection_pooler_user默认pooler。连接池的核心处理逻辑见 pkg/cluster/connection_pooler.go。4. 快速的就地大版本升级In-place major version upgrade支持原地in-place大版本升级并可对全部集群执行全局升级。升级模式由major_version_upgrade_mode配置源码默认值见 pkg/util/config/config.goCRD 合并逻辑见 pkg/controller/operator_config.go模式行为offoperator 不执行任何升级manual由清单触发升级动作默认值full清单变更或低于minimal_major_version时自动触发升级三种模式下在清单中调高版本号都会触发 Pod 滚动更新。当模式为full时GetDesiredMajorVersionpkg/cluster/majorversionupgrade.go会把低于minimal_major_version默认14的集群版本覆盖为target_major_version默认18模式为off时major_version_upgrade_team_allow_list中的团队集群仍可升级见 pkg/cluster/majorversionupgrade.go。升级成败会以last-major-upgrade-success/last-major-upgrade-failure注解写回 Postgres 资源pkg/cluster/majorversionupgrade.go。5. Pod 引导期保护与可配置维护窗口集群在引导bootstrap阶段受到保护并支持可配置的维护窗口maintenance windows。enable_maintenance_windows默认true控制该特性maintenance_windows定义允许执行自动大版本升级、主 Pod 迁移等维护操作的时间窗口支持01:00-06:00每日或Sat:00:00-04:00指定星期两种格式时间为 UTC。清单中的maintenanceWindows字段可覆盖全局配置。集群级 Pod 中断预算PDB默认开启enable_pod_disruption_budget: truePDB 名称模板为postgres-{cluster}-pdbpdb_name_format。6. 集群恢复与克隆AWS / GCS / Azure支持在AWS、GCS、Azure上恢复和克隆 Postgres 集群。克隆通过清单的clone顶层键配置可从一个正在运行的集群或S3 上的 basebackup克隆支持cluster源集群名、uid源集群的 K8s UID保证 S3 bucket 路径唯一、timestamp恢复截止时间戳非包含式、s3_wal_path、s3_endpoint、s3_access_key_id等参数。恢复能力建立在 Spilo WAL 归档之上相关配置见下文备份与 WAL 归档。7. 逻辑备份Logical backups除了 WAL 归档还可以配置逻辑备份到 S3 或 GCS bucket。逻辑备份由 operator 管理的 K8sCronJob执行对副本运行pg_dumpall若可能把压缩结果上传到configured-s3-bucket-prefix/pg_cluster_name/cluster_k8s_uuid/logical_backups示例镜像见 logical-backup/Dockerfile。关键参数CRD 配置下归入logical_backup键logical_backup_scheduleCron 格式调度默认30 00 * * *logical_backup_s3_bucket/logical_backup_s3_bucket_prefix默认spilo/logical_backup_s3_sse默认AES256logical_backup_providers3默认、gcs或azlogical_backup_s3_retention_time备份保留时间如3 days、2 weeks、1 month新备份上传后删除过期文件logical_backup_successful_jobs_history_limit/logical_backup_failed_jobs_history_limit均默认3logical_backup_ttl_seconds_after_finished完成后自动删除任务默认86400秒。每个集群清单里可用enableLogicalBackup默认false、logicalBackupRetention、logicalBackupSchedule单独控制。8. Standby 集群Standby cluster可从S3 / GCS WAL 归档或远程主机创建 standby 集群。清单的standby顶层键支持s3_wal_path、gs_wal_path、standby_host远程主库地址、standby_port默认5432、standby_primary_slot_name。三者至少指定其一且s3_wal_path与gs_wal_path互斥可与standby_host组合获得额外冗余。一个可直接使用的示例见 manifests/standby-manifest.yaml。9. 面向非云环境的可配置性operator 不强制依赖云厂商watched_namespace、storage_resize_mode: off、etcd_host当使用 etcd 而非 Kubernetes 原生 DCS 时、自定义storageClass等参数使其可以在裸机、本地 kind/minikube 等环境运行。10. 基础凭据与用户管理在 K8s 上提供基础的凭据与用户管理简化应用部署。清单的users段声明要创建的数据库用户支持SUPERUSER、REPLICATION、CREATEROLE、CREATEDB、BYPASSRLS、LOGIN/NOLOGIN等标志databases段声明数据库及其属主。operator 会把每个用户凭据写入 K8s Secret模板见secret_name_template默认{namespace}.{username}.{cluster}.credentials.{tprkind}.{tprgroup}支持enable_password_rotation默认false、password_rotation_interval默认90天、password_rotation_user_retention默认180天也支持不额外建用户的原地改密usersWithInPlaceSecretRotation。此外可通过 Teams API 自动创建团队成员用户见teams_api配置组。11. 自定义 TLS 证书清单的tls键支持加载自定义证书secretName指定承载证书的 K8s Secret可由 CertManager 等工具管理certificateFile默认tls.crt、privateKeyFile默认tls.key、caFile与caSecretName定义 CA 路径。使用前需要在清单或全局配置中定义spiloFSGroup/spilo_fsgroup。12. 可视化 UI提供创建与编辑 Postgres 集群清单的 Web UIpostgres-operator-ui。UI 通过 operator 的 REST APIapi_port默认8080工作具体用法见 docs/operator-ui.mdUI 源码位于 ui/。13. OpenShift 兼容兼容OpenShift部署时需把kubernetes_use_configmaps设为true因为 OpenShift 不支持用 Endpoints 存储 leader 与配置键并使用专用的 RBAC 清单 manifests/operator-service-account-rbac-openshift.yaml。14. 多架构支持Multi-archoperator 与 Spilo 镜像均支持多种 CPU 架构multi-arch。三、PostgreSQL 能力版本支持支持PostgreSQL 18起始版本 14对应 Spilo 镜像ghcr.io/zalando/spilo-18详见 manifests/configmap.yaml 中的docker_image。Patroni 流复制集群所有集群通过Patroni构建流复制拓扑主库与副本使用applicationspilo标签标识spilo-role标签标识当前角色主/副本。operator 会为主库与副本分别创建 Service/Endpoint副本 Service 带-repl后缀由 Patroni 负责故障转移与角色切换。基于时间点恢复PITR通过 pg_basebackup 与 WAL-G 或 WAL-E经由 Spilo 镜像实现基于时间点恢复。WAL 归档目标由wal_s3_bucketS3、wal_gs_bucketGCS、wal_az_storage_accountAzure等全局参数配置。预加载库Preload librariesSpilo 镜像预加载了 bg_mon、pg_stat_statements、pgextwlist、pg_auth_mon。内置流行扩展Spilo 内置了大量流行的 Postgres 扩展包括来自 READMEdecoderbufs、hypopg、pg_cron、pg_repack、pg_partman、pg_stat_kcache、pg_audit、pgfaceting、pgq、pgvector、plpgsql_check、plproxy、postgis、roaringbitmap、set_user、timescaledb。此外operator 还通过 Postgres 逻辑解码与pgoutput插件支持变更数据捕获CDC流清单streams键并为每个applicationId创建独立的逻辑复制槽与PUBLICATION消费端可对接 Debezium 等外部工具详见 docs/reference/cluster_manifest.md。四、版本支持矩阵README 给出了各 release 对 Postgres、Kubernetes 与 Golang 的版本支持情况以仓库当前内容为准ReleasePostgres versionsK8s versionsGolangv2.0.314 → 181.271.26.4v1.15.113 → 171.271.25.3v1.14.013 → 171.271.23.4v1.13.012 → 161.271.22.5v1.12.011 → 161.271.22.3v1.11.011 → 161.271.21.7其中 v2.0.x 系列是当前主线版本仓库中的 Helm chart 与部署清单manifests/postgres-operator.yaml默认使用v2.0.3镜像。README 同时说明该项目由 Zalando 开发并已在生产环境中运行超过五年。五、快速上手本节内容基于 docs/quickstart.md可在本地 Kubernetes 环境minikube / kind / k3d或 Docker Desktop 内置 K8s快速体验。前置条件一个本地 K8s 集群minikube容器/VM 内建集群需 Docker/KVM 等、kind 或 k3d基于 Docker 的多节点集群均可kubectl命令行工具。配置方式说明operator 的配置只能在部署新集群之前完成有两种互斥方式ConfigMap传统方式或OperatorConfiguration CRD。详见 docs/reference/operator_parameters.md。下文以 ConfigMap 方式为例。部署方式三选一方式一手动应用 YAML 清单注意 manifests/ 目录仅为示例应按实际环境调整命名空间等git clone https://github.com/zalando/postgres-operator.git cd postgres-operator # 按顺序应用以下清单 kubectl create -f manifests/configmap.yaml # operator 配置 kubectl create -f manifests/operator-service-account-rbac.yaml # 身份与权限 kubectl create -f manifests/postgres-operator.yaml # operator Deployment kubectl create -f manifests/api-service.yaml # 供 UI 使用的 operator API方式二Kustomizationkubectl 1.14kubectl apply -k github.com/zalando/postgres-operator/manifests方式三Helm chart仅支持 Helm v3v1.8.0 起移除 Helm v2 支持# 添加 operator 与 UI 的 chart 仓库 helm repo add postgres-operator-charts https://opensource.zalando.com/postgres-operator/charts/postgres-operator helm repo add postgres-operator-ui-charts https://opensource.zalando.com/postgres-operator/charts/postgres-operator-ui # 安装 helm install postgres-operator postgres-operator-charts/postgres-operator helm install postgres-operator-ui postgres-operator-ui-charts/postgres-operator-ui仓库自带的 chart 源码位于 charts/postgres-operator/ 与 charts/postgres-operator-ui/。OpenShift 部署需将kubernetes_use_configmaps设为true并使用专用 RBACoc create -f manifests/operator-service-account-rbac-openshift.yaml本地一键启动仓库提供自动化脚本启动 minikube 并应用 manifests/minimal-postgres-manifest.yaml./run_operator_locally.sh检查 operator 是否运行启动可能需要数秒务必先确认 operator Pod 处于Running状态再提交集群清单# YAML 清单部署 kubectl get pod -l namepostgres-operator # Helm chart 部署 kubectl get pod -l app.kubernetes.io/namepostgres-operator若未进入Running用kubectl describe查看事件或直接查看日志kubectl logs $(kubectl get pod -l namepostgres-operator --outputname)部署 operator UI可选确保 operator 的 REST API 通过 manifests/api-service.yaml 可达并在 UI 的 部署清单 中配置该 API 地址。然后# 手动部署 kubectl apply -f ui/manifests/ # 或 kustomization kubectl apply -k github.com/zalando/postgres-operator/ui/manifests # 或 helm chart helm install postgres-operator-ui ./charts/postgres-operator-ui确认 UI Pod 运行后通过端口转发访问浏览器打开localhost:8081kubectl get pod -l namepostgres-operator-ui kubectl port-forward svc/postgres-operator-ui 8081:80创建第一个 Postgres 集群operator 运行后即监听postgresql资源事件。提交最小集群清单kubectl create -f manifests/minimal-postgres-manifest.yamlmanifests/minimal-postgres-manifest.yaml 的内容如下apiVersion: acid.zalan.do/v1 kind: postgresql metadata: name: acid-minimal-cluster spec: teamId: acid volume: size: 1Gi numberOfInstances: 2 users: zalando: # database owner - superuser - createdb foo_user: [] # role for application foo databases: foo: zalando # dbname: owner preparedDatabases: bar: {} postgresql: version: 18清单通过校验后operator 会创建 Service、Endpoint 与 StatefulSet并按其numberOfInstances拉起指定数量的 Pod。所有资源以集群名命名数据库 Pod 编号从-0开始运行 Zalando 的 Spilo 容器镜像主库与副本各有独立的 Service/Endpoint副本带-repl后缀。用标签验证# 查看集群 kubectl get postgresql # 查看数据库 Pod标签 spilo-role 标识当前主库 kubectl get pods -l applicationspilo -L spilo-role # 查看 Service kubectl get svc -l applicationspilo -L spilo-role更完整的配置示例见 manifests/complete-postgres-manifest.yaml其中展示了preparedDatabases预置数据库、默认角色与扩展、additionalVolumes、users等高级用法完整的键说明见 docs/reference/cluster_manifest.md。通过 psql 连接集群可对数据库 Pod 做端口转发连接详见 docs/user.md。用 minikube 时可直接从指向主库的 Service 取连接串export HOST_PORT$(minikube service acid-minimal-cluster --url | sed s,.*/,,) export PGHOST$(echo $HOST_PORT | cut -d: -f 1) export PGPORT$(echo $HOST_PORT | cut -d: -f 2)从 K8s Secret 中取密码。默认拒绝非加密连接需指定 SSL 模式export PGPASSWORD$(kubectl get secret postgres.acid-minimal-cluster.credentials.postgresql.acid.zalan.do -o jsonpath{.data.password} | base64 -d) export PGSSLMODErequire psql -U postgres删除集群直接删除postgresql自定义资源即可kubectl delete postgresql acid-minimal-cluster这会删除关联的 StatefulSet、数据库 Pod、Service 与 Endpoint释放 PersistentVolume 并删除 PodDisruptionBudget但Secret 不会被删除备份也会保留。注意若集群仍处于启动阶段或卡在引导期就删除可能出现postgresql资源已删而组件残留的情况见 issue #551此时重新部署一个干净的本地集群即可。六、从 v1 迁移到 v2如果你正在使用 v1.x 版本在部署 v2 operator 前务必阅读 docs/migrate.md。v2.0 修改了部分默认值并移除了一批废弃字段要点如下。1. 默认启用 scram-sha-256 密码加密v2 operator 默认将密码加密方式设为scram-sha-256。除非在清单spec.postgresql.parameters中显式配置password_encryption: md5否则 operator 会用scram-sha-256重新加密受管 K8s Secret 中的密码并 ALTER 相应数据库用户升级后 Pod 会以滚动方式轮换请确保依赖这些凭据的客户端和驱动支持scram-sha-256。为兼容旧客户端当前默认 Spilo 镜像spilo-18:4.1-p2的pg_hba.conf仍允许md5密码因此可以只把清单用户切换到scram-sha-256未受管用户继续用md5连接。但该兼容不适用于依赖md5的pgBouncer连接这种情况需在清单中配置password_encryption: md5。注意修改清单中的加密方式需要重启 operator 才会更新数据库密码同时建议在下一个移除md5的 Spilo 镜像发布前主动更换未受管用户的md5密码。2. K8s Endpoints 已弃用改用 ConfigMapv1.x 默认使用 K8s Endpoints 存储 Patroni 的 HA 状态但 Endpoints 自 K8s 1.33 起被标记为弃用。v2.0 把kubernetes_use_configmaps的默认值改为true因此升级前必须显式把该参数设为false保留旧行为。官方明确警告不要让带副本的集群直接从 Endpoints 一步切换到 ConfigMap——滚动更新期间若 leader endpoint 与 leader configmap 同时存在有**脑裂split-brain**风险。安全的迁移步骤把所有数据库集群缩容到仅剩一个主实例把全局配置max_instances、min_instances设为1若配置了ignore_instance_limits_annotation_key先移除它等待所有集群健康将kubernetes_use_configmaps改为true——这会触发全部集群主 Pod 的替换期间会有与 Pod 重调度等长的停机再次确认集群健康且 ConfigMap 已创建每个集群应有三个 ConfigMap名称分别为集群名加-config、-failover、-leader后缀然后撤销第 1 步按清单缩放到目标实例数与 ConfigMap 同名的遗留 Endpoints 需要你或 K8s 垃圾回收机制自行删除。3. 已移除的清单字段请确保集群清单中不再出现以下字段否则请改用替代项v2 移除的字段替代字段init_containersinitContainerspod_priority_class_namepodPriorityClassNamereplicaLoadBalancerenableReplicaLoadBalanceruseLoadBalancerenableMasterLoadBalancer七、配置体系ConfigMap 与 OperatorConfiguration CRDoperator 支持两种互斥的配置方式详见 docs/reference/operator_parameters.mdConfigMap 方式传统配置放在由CONFIG_MAP_NAME环境变量指定的 key-value ConfigMap 中参数名以下划线分隔列表用逗号分隔map 用key:value逗号分隔。仓库示例即 manifests/configmap.yaml其中包含workers默认8、resync_period30m、repair_period5m、watched_namespace*表示全命名空间、docker_image默认 Spilo 镜像等完整默认配置。OperatorConfiguration CRD 方式推荐配置存于名为OperatorConfiguration的自定义资源中在 operator 部署清单 里设置POSTGRES_OPERATOR_CONFIGURATION_OBJECT环境变量指向它即可启用。CRD 配置没有内置默认值未提供的参数为空值建议复制 manifests/postgresql-operator-default-configuration.yaml 再修改。本地启用方式kubectl create -f manifests/operatorconfiguration.crd.yaml # 注册 CRD kubectl create -f manifests/postgresql-operator-default-configuration.yaml kubectl create -f manifests/operator-service-account-rbac.yaml kubectl create -f manifests/postgres-operator.yaml # 记得设置上述 env var kubectl get operatorconfigurations postgresql-operator-default-configuration -o yamlCRD 方式功能更强支持 YAML 嵌套结构官方建议使用它ConfigMap 方式后续将被废弃。注意 CRD 方式下resource_check_interval/resource_check_timeout无效改由CRD_READY_WAIT_INTERVAL/CRD_READY_WAIT_TIMEOUT环境变量控制在 cmd/main.go 中解析默认分别为 4s 与 30s。命令行与环境变量operator 还支持若干命令行参数-kubeconfig、-outofcluster、-nodatabaseaccess、-noteamsapi、-kubeqps默认 10、-kubeburst默认 20与环境变量CONFIG_MAP_NAME、OPERATOR_NAMESPACE、WATCHED_NAMESPACE、ENABLE_JSON_LOGGING等完整清单见 docs/reference/command_line_and_environment.md。八、文档导航README 指向的完整文档体系已转换为仓库根目录相对路径工作原理与核心概念安装与快速上手含全部部署选项K8s 上的 Postgres 使用体验Postgres Operator UI 使用指南DBA 选项从 RBAC 到备份构建、调试与扩展 operator配置参数参考Postgres 集群清单参考命令行选项与环境变量v1 到 v2 迁移指南相关源码与清单可直接在仓库中查阅控制器实现、集群生命周期管理、大版本升级逻辑、连接池实现、部署清单、最小集群清单 与 完整集群清单。赞分享云原生后端数据库运维【免费下载链接】postgres-operatorPostgres operator creates and manages PostgreSQL clusters running in Kubernetes项目地址https://gitcode.com/gh_mirrors/po/postgres-operator点击查看免费下载相关推荐Postgres Operator完全指南在Kubernetes上轻松管理高可用PostgreSQL集群Postgres Operator完全指南在Kubernetes上轻松管理高可用PostgreSQL集群 Postgres Operator是Zalando开云原生后端数据库运维快速上手Postgres-operator5分钟在Kubernetes部署高可用PostgreSQL集群快速上手Postgres operator5分钟在Kubernetes部署高可用PostgreSQL集群 在当今云原生时代Kubernetes已经成为容器编Meshery 集成指南在 Kubernetes 上以声明式设计运行 k6 性能测试Meshery 集成指南在 Kubernetes 上以声明式设计运行 k6 性能测试 本指南聚焦 Meshery 与 Grafana k6 Operator云原生微服务运维DevOps上一篇NSZ终极指南高效无损压缩Nintendo Switch游戏文件的完整解决方案下一篇5分钟搞定Boss Show Time插件 - 求职者必备的招聘时间管理神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/13 2:19:32 · 阅读 1.2k Postgres Operator 完全指南：在 Kubernetes 上以声明式方式运行高可用 PostgreSQL 集群
云原生后端数据库运维【免费下载链接】postgres-operatorPostgres operator creates and manages PostgreSQL clusters running in Kubernetes项目地址https://gitcode.com/gh_mirrors/po/postgres-operator点击查看免费下载本指南以 README.md 为核心骨架结合仓库内的 概念文档、快速上手、配置参数参考、集群清单参考 以及 v1→v2 迁移指南并辅以pkg/目录下的控制器与集群源码系统讲解 Postgres Operator 的工作原理、功能矩阵、版本支持、部署方式与迁移要点。读完本文你将掌握如何在 Kubernetes 上通过 CRD 清单声明式地创建、升级、备份和删除 Patroni 驱动的高可用 PostgreSQL 集群并理解滚动更新、在线扩容、连接池、就地大版本升级等关键能力的实现机制。一、Postgres Operator 是什么核心工作模型Postgres Operator 在 Kubernetes 上交付易于运行、开箱即用的高可用 PostgreSQL 集群底层由 Patroni 驱动README 原文delivers an easy to run highly-available PostgreSQL clusters on Kubernetes powered by Patroni。它的核心设计哲学是只通过 Postgres 清单即 CRD进行配置从而无缝融入没有 Kubernetes API 直接访问权限的自动化 CI/CD 流水线以基础设施即代码Infrastructure as Code替代人工运维。概念文档 将它的工作方式归纳为四条循环监听清单变化operator 监听 PostgreSQL 集群清单manifest的增、删、改事件并据此变更运行中的集群。当用户提交一个新清单时operator 拉取该清单并创建一整套必要的实体——如 K8s StatefulSet、Postgres 角色、Service 与 Endpoint 等。监听自身配置变化operator 同时监听自身配置的变化。例如当 Pod 中的 Docker 镜像变更时operator 会执行滚动更新rolling update即逐个重启每个受管 StatefulSet 的 Pod 以应用新镜像。周期性对账operator 定期把每个 Postgres 集群的实际状态与清单定义的期望状态进行同步sync确保两者收敛一致。在源码中这一机制体现为 pkg/controller/operator_config.go 中的resync_period默认30m与repair_period默认5m两个配置项。免人工介入所有配置均通过清单完成无需直接访问 K8s API方便自动化部署流水线集成。职责边界Scopeoperator 的职责聚焦于供应provisioning、修改配置与清理使用 Patroni 的 Postgres 集群——既包括 K8s 资源层面也包括集群启动后的数据库与角色供应。它尽量把工作交给 Kubernetes 与 Patroni 完成尤其是集群引导和高可用自身只承担滚动更新等全局性编排。监控Monitoring与调优tuningPostgres不在当前 operator 的职责范围内但可以通过全局可配置的 sidecar灵活补充 Prometheus、ZMON 等工具。二、Operator 功能全览README 罗列了 operator 的核心功能。以下逐条展开并结合源码说明其实现路径。1. 滚动更新Rolling updates集群清单的任何变更——包括快速的次版本升级——都会触发滚动更新operator 逐个重新创建 StatefulSet 的 Pod用新镜像/新配置替换旧实例。滚动更新由 pkg/cluster/cluster.go 的Update流程驱动其中compareStatefulSetWithpkg/cluster/cluster.go负责对比新旧 StatefulSet 并判断是否需要滚动。与之相关的还有enable_lazy_spilo_upgrade参数默认false开启后 operator 只更新 StatefulSet 中的镜像Spilo 与 InitContainer而不立即执行滚动更新假设 Pod 会在稍后如节点轮换时以新镜像重启。2. 在线卷扩容Live volume resize支持不重启 Pod的在线卷扩容覆盖AWS EBS与PVC两种场景。该行为由storage_resize_mode配置项控制共四种取值模式行为ebsoperator 直接调整 EBS 卷并在 Pod 内执行resizefspvcoperator 仅修改 PVC 定义默认值mixed通过 AWS API 调整大小、类型、吞吐量与 IOPS并调用 PVC 变更完成文件系统扩容off禁用卷扩容相关实现位于 pkg/util/volumesEBS 相关见 pkg/util/volumes/ebs.go。注意 AWS 上运行需要 Spilo 容器以特权模式运行spilo_privileged: true因为 EBS 扩容依赖该能力。3. 数据库连接池PGBouncer通过PGBouncer提供数据库连接池。连接池既可以按集群清单启用enableConnectionPooler/enableReplicaConnectionPooler也可以在 operator 配置中预设全局默认值见 pkg/util/constants/pooler.go。全局默认配置包括connection_pooler_number_of_instancespooler 实例数默认2也是最低要求connection_pooler_image默认镜像ghcr.io/zalando/postgres-operator/pgbouncer:v2.0.3connection_pooler_max_db_connectionspooler 最大连接数默认60会在多个 pooler Pod 间均分即默认两实例时每 Pod 30 连接connection_pooler_mode默认transaction事务级池化可选sessionconnection_pooler_schema默认pooler用于存放凭据查询函数connection_pooler_user默认pooler。连接池的核心处理逻辑见 pkg/cluster/connection_pooler.go。4. 快速的就地大版本升级In-place major version upgrade支持原地in-place大版本升级并可对全部集群执行全局升级。升级模式由major_version_upgrade_mode配置源码默认值见 pkg/util/config/config.goCRD 合并逻辑见 pkg/controller/operator_config.go模式行为offoperator 不执行任何升级manual由清单触发升级动作默认值full清单变更或低于minimal_major_version时自动触发升级三种模式下在清单中调高版本号都会触发 Pod 滚动更新。当模式为full时GetDesiredMajorVersionpkg/cluster/majorversionupgrade.go会把低于minimal_major_version默认14的集群版本覆盖为target_major_version默认18模式为off时major_version_upgrade_team_allow_list中的团队集群仍可升级见 pkg/cluster/majorversionupgrade.go。升级成败会以last-major-upgrade-success/last-major-upgrade-failure注解写回 Postgres 资源pkg/cluster/majorversionupgrade.go。5. Pod 引导期保护与可配置维护窗口集群在引导bootstrap阶段受到保护并支持可配置的维护窗口maintenance windows。enable_maintenance_windows默认true控制该特性maintenance_windows定义允许执行自动大版本升级、主 Pod 迁移等维护操作的时间窗口支持01:00-06:00每日或Sat:00:00-04:00指定星期两种格式时间为 UTC。清单中的maintenanceWindows字段可覆盖全局配置。集群级 Pod 中断预算PDB默认开启enable_pod_disruption_budget: truePDB 名称模板为postgres-{cluster}-pdbpdb_name_format。6. 集群恢复与克隆AWS / GCS / Azure支持在AWS、GCS、Azure上恢复和克隆 Postgres 集群。克隆通过清单的clone顶层键配置可从一个正在运行的集群或S3 上的 basebackup克隆支持cluster源集群名、uid源集群的 K8s UID保证 S3 bucket 路径唯一、timestamp恢复截止时间戳非包含式、s3_wal_path、s3_endpoint、s3_access_key_id等参数。恢复能力建立在 Spilo WAL 归档之上相关配置见下文备份与 WAL 归档。7. 逻辑备份Logical backups除了 WAL 归档还可以配置逻辑备份到 S3 或 GCS bucket。逻辑备份由 operator 管理的 K8sCronJob执行对副本运行pg_dumpall若可能把压缩结果上传到configured-s3-bucket-prefix/pg_cluster_name/cluster_k8s_uuid/logical_backups示例镜像见 logical-backup/Dockerfile。关键参数CRD 配置下归入logical_backup键logical_backup_scheduleCron 格式调度默认30 00 * * *logical_backup_s3_bucket/logical_backup_s3_bucket_prefix默认spilo/logical_backup_s3_sse默认AES256logical_backup_providers3默认、gcs或azlogical_backup_s3_retention_time备份保留时间如3 days、2 weeks、1 month新备份上传后删除过期文件logical_backup_successful_jobs_history_limit/logical_backup_failed_jobs_history_limit均默认3logical_backup_ttl_seconds_after_finished完成后自动删除任务默认86400秒。每个集群清单里可用enableLogicalBackup默认false、logicalBackupRetention、logicalBackupSchedule单独控制。8. Standby 集群Standby cluster可从S3 / GCS WAL 归档或远程主机创建 standby 集群。清单的standby顶层键支持s3_wal_path、gs_wal_path、standby_host远程主库地址、standby_port默认5432、standby_primary_slot_name。三者至少指定其一且s3_wal_path与gs_wal_path互斥可与standby_host组合获得额外冗余。一个可直接使用的示例见 manifests/standby-manifest.yaml。9. 面向非云环境的可配置性operator 不强制依赖云厂商watched_namespace、storage_resize_mode: off、etcd_host当使用 etcd 而非 Kubernetes 原生 DCS 时、自定义storageClass等参数使其可以在裸机、本地 kind/minikube 等环境运行。10. 基础凭据与用户管理在 K8s 上提供基础的凭据与用户管理简化应用部署。清单的users段声明要创建的数据库用户支持SUPERUSER、REPLICATION、CREATEROLE、CREATEDB、BYPASSRLS、LOGIN/NOLOGIN等标志databases段声明数据库及其属主。operator 会把每个用户凭据写入 K8s Secret模板见secret_name_template默认{namespace}.{username}.{cluster}.credentials.{tprkind}.{tprgroup}支持enable_password_rotation默认false、password_rotation_interval默认90天、password_rotation_user_retention默认180天也支持不额外建用户的原地改密usersWithInPlaceSecretRotation。此外可通过 Teams API 自动创建团队成员用户见teams_api配置组。11. 自定义 TLS 证书清单的tls键支持加载自定义证书secretName指定承载证书的 K8s Secret可由 CertManager 等工具管理certificateFile默认tls.crt、privateKeyFile默认tls.key、caFile与caSecretName定义 CA 路径。使用前需要在清单或全局配置中定义spiloFSGroup/spilo_fsgroup。12. 可视化 UI提供创建与编辑 Postgres 集群清单的 Web UIpostgres-operator-ui。UI 通过 operator 的 REST APIapi_port默认8080工作具体用法见 docs/operator-ui.mdUI 源码位于 ui/。13. OpenShift 兼容兼容OpenShift部署时需把kubernetes_use_configmaps设为true因为 OpenShift 不支持用 Endpoints 存储 leader 与配置键并使用专用的 RBAC 清单 manifests/operator-service-account-rbac-openshift.yaml。14. 多架构支持Multi-archoperator 与 Spilo 镜像均支持多种 CPU 架构multi-arch。三、PostgreSQL 能力版本支持支持PostgreSQL 18起始版本 14对应 Spilo 镜像ghcr.io/zalando/spilo-18详见 manifests/configmap.yaml 中的docker_image。Patroni 流复制集群所有集群通过Patroni构建流复制拓扑主库与副本使用applicationspilo标签标识spilo-role标签标识当前角色主/副本。operator 会为主库与副本分别创建 Service/Endpoint副本 Service 带-repl后缀由 Patroni 负责故障转移与角色切换。基于时间点恢复PITR通过 pg_basebackup 与 WAL-G 或 WAL-E经由 Spilo 镜像实现基于时间点恢复。WAL 归档目标由wal_s3_bucketS3、wal_gs_bucketGCS、wal_az_storage_accountAzure等全局参数配置。预加载库Preload librariesSpilo 镜像预加载了 bg_mon、pg_stat_statements、pgextwlist、pg_auth_mon。内置流行扩展Spilo 内置了大量流行的 Postgres 扩展包括来自 READMEdecoderbufs、hypopg、pg_cron、pg_repack、pg_partman、pg_stat_kcache、pg_audit、pgfaceting、pgq、pgvector、plpgsql_check、plproxy、postgis、roaringbitmap、set_user、timescaledb。此外operator 还通过 Postgres 逻辑解码与pgoutput插件支持变更数据捕获CDC流清单streams键并为每个applicationId创建独立的逻辑复制槽与PUBLICATION消费端可对接 Debezium 等外部工具详见 docs/reference/cluster_manifest.md。四、版本支持矩阵README 给出了各 release 对 Postgres、Kubernetes 与 Golang 的版本支持情况以仓库当前内容为准ReleasePostgres versionsK8s versionsGolangv2.0.314 → 181.271.26.4v1.15.113 → 171.271.25.3v1.14.013 → 171.271.23.4v1.13.012 → 161.271.22.5v1.12.011 → 161.271.22.3v1.11.011 → 161.271.21.7其中 v2.0.x 系列是当前主线版本仓库中的 Helm chart 与部署清单manifests/postgres-operator.yaml默认使用v2.0.3镜像。README 同时说明该项目由 Zalando 开发并已在生产环境中运行超过五年。五、快速上手本节内容基于 docs/quickstart.md可在本地 Kubernetes 环境minikube / kind / k3d或 Docker Desktop 内置 K8s快速体验。前置条件一个本地 K8s 集群minikube容器/VM 内建集群需 Docker/KVM 等、kind 或 k3d基于 Docker 的多节点集群均可kubectl命令行工具。配置方式说明operator 的配置只能在部署新集群之前完成有两种互斥方式ConfigMap传统方式或OperatorConfiguration CRD。详见 docs/reference/operator_parameters.md。下文以 ConfigMap 方式为例。部署方式三选一方式一手动应用 YAML 清单注意 manifests/ 目录仅为示例应按实际环境调整命名空间等git clone https://github.com/zalando/postgres-operator.git cd postgres-operator # 按顺序应用以下清单 kubectl create -f manifests/configmap.yaml # operator 配置 kubectl create -f manifests/operator-service-account-rbac.yaml # 身份与权限 kubectl create -f manifests/postgres-operator.yaml # operator Deployment kubectl create -f manifests/api-service.yaml # 供 UI 使用的 operator API方式二Kustomizationkubectl 1.14kubectl apply -k github.com/zalando/postgres-operator/manifests方式三Helm chart仅支持 Helm v3v1.8.0 起移除 Helm v2 支持# 添加 operator 与 UI 的 chart 仓库 helm repo add postgres-operator-charts https://opensource.zalando.com/postgres-operator/charts/postgres-operator helm repo add postgres-operator-ui-charts https://opensource.zalando.com/postgres-operator/charts/postgres-operator-ui # 安装 helm install postgres-operator postgres-operator-charts/postgres-operator helm install postgres-operator-ui postgres-operator-ui-charts/postgres-operator-ui仓库自带的 chart 源码位于 charts/postgres-operator/ 与 charts/postgres-operator-ui/。OpenShift 部署需将kubernetes_use_configmaps设为true并使用专用 RBACoc create -f manifests/operator-service-account-rbac-openshift.yaml本地一键启动仓库提供自动化脚本启动 minikube 并应用 manifests/minimal-postgres-manifest.yaml./run_operator_locally.sh检查 operator 是否运行启动可能需要数秒务必先确认 operator Pod 处于Running状态再提交集群清单# YAML 清单部署 kubectl get pod -l namepostgres-operator # Helm chart 部署 kubectl get pod -l app.kubernetes.io/namepostgres-operator若未进入Running用kubectl describe查看事件或直接查看日志kubectl logs $(kubectl get pod -l namepostgres-operator --outputname)部署 operator UI可选确保 operator 的 REST API 通过 manifests/api-service.yaml 可达并在 UI 的 部署清单 中配置该 API 地址。然后# 手动部署 kubectl apply -f ui/manifests/ # 或 kustomization kubectl apply -k github.com/zalando/postgres-operator/ui/manifests # 或 helm chart helm install postgres-operator-ui ./charts/postgres-operator-ui确认 UI Pod 运行后通过端口转发访问浏览器打开localhost:8081kubectl get pod -l namepostgres-operator-ui kubectl port-forward svc/postgres-operator-ui 8081:80创建第一个 Postgres 集群operator 运行后即监听postgresql资源事件。提交最小集群清单kubectl create -f manifests/minimal-postgres-manifest.yamlmanifests/minimal-postgres-manifest.yaml 的内容如下apiVersion: acid.zalan.do/v1 kind: postgresql metadata: name: acid-minimal-cluster spec: teamId: acid volume: size: 1Gi numberOfInstances: 2 users: zalando: # database owner - superuser - createdb foo_user: [] # role for application foo databases: foo: zalando # dbname: owner preparedDatabases: bar: {} postgresql: version: 18清单通过校验后operator 会创建 Service、Endpoint 与 StatefulSet并按其numberOfInstances拉起指定数量的 Pod。所有资源以集群名命名数据库 Pod 编号从-0开始运行 Zalando 的 Spilo 容器镜像主库与副本各有独立的 Service/Endpoint副本带-repl后缀。用标签验证# 查看集群 kubectl get postgresql # 查看数据库 Pod标签 spilo-role 标识当前主库 kubectl get pods -l applicationspilo -L spilo-role # 查看 Service kubectl get svc -l applicationspilo -L spilo-role更完整的配置示例见 manifests/complete-postgres-manifest.yaml其中展示了preparedDatabases预置数据库、默认角色与扩展、additionalVolumes、users等高级用法完整的键说明见 docs/reference/cluster_manifest.md。通过 psql 连接集群可对数据库 Pod 做端口转发连接详见 docs/user.md。用 minikube 时可直接从指向主库的 Service 取连接串export HOST_PORT$(minikube service acid-minimal-cluster --url | sed s,.*/,,) export PGHOST$(echo $HOST_PORT | cut -d: -f 1) export PGPORT$(echo $HOST_PORT | cut -d: -f 2)从 K8s Secret 中取密码。默认拒绝非加密连接需指定 SSL 模式export PGPASSWORD$(kubectl get secret postgres.acid-minimal-cluster.credentials.postgresql.acid.zalan.do -o jsonpath{.data.password} | base64 -d) export PGSSLMODErequire psql -U postgres删除集群直接删除postgresql自定义资源即可kubectl delete postgresql acid-minimal-cluster这会删除关联的 StatefulSet、数据库 Pod、Service 与 Endpoint释放 PersistentVolume 并删除 PodDisruptionBudget但Secret 不会被删除备份也会保留。注意若集群仍处于启动阶段或卡在引导期就删除可能出现postgresql资源已删而组件残留的情况见 issue #551此时重新部署一个干净的本地集群即可。六、从 v1 迁移到 v2如果你正在使用 v1.x 版本在部署 v2 operator 前务必阅读 docs/migrate.md。v2.0 修改了部分默认值并移除了一批废弃字段要点如下。1. 默认启用 scram-sha-256 密码加密v2 operator 默认将密码加密方式设为scram-sha-256。除非在清单spec.postgresql.parameters中显式配置password_encryption: md5否则 operator 会用scram-sha-256重新加密受管 K8s Secret 中的密码并 ALTER 相应数据库用户升级后 Pod 会以滚动方式轮换请确保依赖这些凭据的客户端和驱动支持scram-sha-256。为兼容旧客户端当前默认 Spilo 镜像spilo-18:4.1-p2的pg_hba.conf仍允许md5密码因此可以只把清单用户切换到scram-sha-256未受管用户继续用md5连接。但该兼容不适用于依赖md5的pgBouncer连接这种情况需在清单中配置password_encryption: md5。注意修改清单中的加密方式需要重启 operator 才会更新数据库密码同时建议在下一个移除md5的 Spilo 镜像发布前主动更换未受管用户的md5密码。2. K8s Endpoints 已弃用改用 ConfigMapv1.x 默认使用 K8s Endpoints 存储 Patroni 的 HA 状态但 Endpoints 自 K8s 1.33 起被标记为弃用。v2.0 把kubernetes_use_configmaps的默认值改为true因此升级前必须显式把该参数设为false保留旧行为。官方明确警告不要让带副本的集群直接从 Endpoints 一步切换到 ConfigMap——滚动更新期间若 leader endpoint 与 leader configmap 同时存在有**脑裂split-brain**风险。安全的迁移步骤把所有数据库集群缩容到仅剩一个主实例把全局配置max_instances、min_instances设为1若配置了ignore_instance_limits_annotation_key先移除它等待所有集群健康将kubernetes_use_configmaps改为true——这会触发全部集群主 Pod 的替换期间会有与 Pod 重调度等长的停机再次确认集群健康且 ConfigMap 已创建每个集群应有三个 ConfigMap名称分别为集群名加-config、-failover、-leader后缀然后撤销第 1 步按清单缩放到目标实例数与 ConfigMap 同名的遗留 Endpoints 需要你或 K8s 垃圾回收机制自行删除。3. 已移除的清单字段请确保集群清单中不再出现以下字段否则请改用替代项v2 移除的字段替代字段init_containersinitContainerspod_priority_class_namepodPriorityClassNamereplicaLoadBalancerenableReplicaLoadBalanceruseLoadBalancerenableMasterLoadBalancer七、配置体系ConfigMap 与 OperatorConfiguration CRDoperator 支持两种互斥的配置方式详见 docs/reference/operator_parameters.mdConfigMap 方式传统配置放在由CONFIG_MAP_NAME环境变量指定的 key-value ConfigMap 中参数名以下划线分隔列表用逗号分隔map 用key:value逗号分隔。仓库示例即 manifests/configmap.yaml其中包含workers默认8、resync_period30m、repair_period5m、watched_namespace*表示全命名空间、docker_image默认 Spilo 镜像等完整默认配置。OperatorConfiguration CRD 方式推荐配置存于名为OperatorConfiguration的自定义资源中在 operator 部署清单 里设置POSTGRES_OPERATOR_CONFIGURATION_OBJECT环境变量指向它即可启用。CRD 配置没有内置默认值未提供的参数为空值建议复制 manifests/postgresql-operator-default-configuration.yaml 再修改。本地启用方式kubectl create -f manifests/operatorconfiguration.crd.yaml # 注册 CRD kubectl create -f manifests/postgresql-operator-default-configuration.yaml kubectl create -f manifests/operator-service-account-rbac.yaml kubectl create -f manifests/postgres-operator.yaml # 记得设置上述 env var kubectl get operatorconfigurations postgresql-operator-default-configuration -o yamlCRD 方式功能更强支持 YAML 嵌套结构官方建议使用它ConfigMap 方式后续将被废弃。注意 CRD 方式下resource_check_interval/resource_check_timeout无效改由CRD_READY_WAIT_INTERVAL/CRD_READY_WAIT_TIMEOUT环境变量控制在 cmd/main.go 中解析默认分别为 4s 与 30s。命令行与环境变量operator 还支持若干命令行参数-kubeconfig、-outofcluster、-nodatabaseaccess、-noteamsapi、-kubeqps默认 10、-kubeburst默认 20与环境变量CONFIG_MAP_NAME、OPERATOR_NAMESPACE、WATCHED_NAMESPACE、ENABLE_JSON_LOGGING等完整清单见 docs/reference/command_line_and_environment.md。八、文档导航README 指向的完整文档体系已转换为仓库根目录相对路径工作原理与核心概念安装与快速上手含全部部署选项K8s 上的 Postgres 使用体验Postgres Operator UI 使用指南DBA 选项从 RBAC 到备份构建、调试与扩展 operator配置参数参考Postgres 集群清单参考命令行选项与环境变量v1 到 v2 迁移指南相关源码与清单可直接在仓库中查阅控制器实现、集群生命周期管理、大版本升级逻辑、连接池实现、部署清单、最小集群清单 与 完整集群清单。赞分享云原生后端数据库运维【免费下载链接】postgres-operatorPostgres operator creates and manages PostgreSQL clusters running in Kubernetes项目地址https://gitcode.com/gh_mirrors/po/postgres-operator点击查看免费下载相关推荐Postgres Operator完全指南在Kubernetes上轻松管理高可用PostgreSQL集群Postgres Operator完全指南在Kubernetes上轻松管理高可用PostgreSQL集群 Postgres Operator是Zalando开云原生后端数据库运维快速上手Postgres-operator5分钟在Kubernetes部署高可用PostgreSQL集群快速上手Postgres operator5分钟在Kubernetes部署高可用PostgreSQL集群 在当今云原生时代Kubernetes已经成为容器编Meshery 集成指南在 Kubernetes 上以声明式设计运行 k6 性能测试Meshery 集成指南在 Kubernetes 上以声明式设计运行 k6 性能测试 本指南聚焦 Meshery 与 Grafana k6 Operator云原生微服务运维DevOps上一篇NSZ终极指南高效无损压缩Nintendo Switch游戏文件的完整解决方案下一篇5分钟搞定Boss Show Time插件 - 求职者必备的招聘时间管理神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考