CloudNativePG Operator 配置指南ConfigMap/Secret 参数详解与实战定制【免费下载链接】cloudnative-pgThe most popular Kubernetes Operator for PostgreSQL.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudnative-pgCloudNativePG Operator 遵循约定优于配置convention over configuration的设计理念默认安装即可开箱即用但当你需要让 Operator 创建的资源继承自定义标签/注解、更换默认 PostgreSQL/PgBouncer 镜像、调整升级节奏或开启证书与监控定制时就需要掌握其运行期配置机制。本文以 CloudNativePG 官方 Operator 配置文档为核心结合仓库源码逐项解析全部配置参数、ConfigMap/Secret 定义方式、配置热加载流程与 pprof 性能剖析方法帮助你精准定制 Operator 行为。配置机制总览CloudNativePG Operator 本身由一个标准的 KubernetesDeployment部署清单安装而来。默认情况下它被安装在cnpg-system命名空间Deployment 名称为cnpg-controller-manager该 Deployment 的完整定义位于 config/manager/manager.yaml在 manifests 中通过 config/default/kustomization.yaml 组装发布。Operator 的行为定制完全依赖一个与 Deployment 同命名空间、名为cnpg-controller-manager-config的ConfigMap或Secret放置位置必须与 Operator Deployment 位于同一命名空间默认cnpg-system名称约定默认固定为cnpg-controller-manager-config并通过 controller 子命令的--config-map-name与--secret-name两个 flag 传入见 internal/cmd/manager/controller/cmd.go生效方式配置只在 Operator 进程启动加载配置时读取一次不会自动感知ConfigMap/Secret 的后续变更修改后必须重启/滚动 Operator Pod 才能生效且变更只对重启后新建的资源生效。配置优先级Secret 覆盖 ConfigMap配置同时支持 ConfigMap 与 Secret 两种载体。加载时遵循明确顺序Operator 先读取 ConfigMap再读取 Secret若同一参数在两者中都出现以 Secret 中的值为准。这一点在源码中有直接实现证据——loadConfiguration函数先调用readConfigMap填充configData再调用readSecret用 Secret 数据覆盖同名键见 internal/cmd/manager/controller/controller.go。从更底层的解析看pkg/configparser/configparser.go 中ReadConfigMap对每个字段通过env标签识别的取值顺序是先取代码内定义的默认值若环境变量存在则覆盖默认值若 ConfigMap/Secret 的data中存在同名键则最终覆盖。也就是说运行期配置ConfigMap/Secret的优先级高于 Pod 环境变量环境变量又高于代码默认值。所有配置项在 internal/configuration/configuration.go 的Data结构体中均有env:XXX标签对应字段类型字符串、布尔、整数、逗号分隔列表、指针整数决定了值的解析方式。可用配置项全表Operator 从 ConfigMap/Secret 中查找以下环境变量形式的配置项配置项说明CERTIFICATE_DURATION生成的证书有效时长天。默认 90。CLUSTERS_ROLLOUT_DELAYOperator 升级时不同集群之间滚动升级的等待时长秒。用于错峰升级、降低系统影响。默认0即集群间升级无延迟。CREATE_ANY_SERVICE设为true时为集群创建-anyService。默认false。DRAIN_TAINTS指定被解释为节点驱逐drain信号的污点键。默认包含 kubectl 驱逐、Cluster Autoscaler 与 Karpenter 常用的污点node.kubernetes.io/unschedulable、ToBeDeletedByClusterAutoscaler、karpenter.sh/disrupted、karpenter.sh/disruption。ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES设为true时Operator 升级后对 instance manager 执行原地in-place更新避免集群发生滚动更新默认false。ENABLE_WEBHOOK_NAMESPACE_SUFFIX设为true时Operator 查找名称带-OPERATOR_NAMESPACE后缀的MutatingWebhookConfiguration与ValidatingWebhookConfiguration如cnpg-mutating-webhook-configuration-cnpg-team-a。用于在同一集群运行多个命名空间级 Operator 实例时避免名称冲突。Operator 不会创建带后缀的配置需要你先创建好再启动若开启该标志但未设置OPERATOR_NAMESPACEOperator 将拒绝启动。默认false。EXPIRING_CHECK_THRESHOLD判定证书即将过期的天数阈值。默认 7。INCLUDE_PLUGINS逗号分隔的插件列表这些插件将始终包含在 Cluster 的调谐reconciliation中。INHERITED_ANNOTATIONS注解名列表。当这些注解定义在Cluster元数据上时会被继承到 Operator 生成的所有资源含 Pod。INHERITED_LABELS标签名列表。当这些标签定义在Cluster元数据上时会被继承到 Operator 生成的所有资源含 Pod。INSTANCES_ROLLOUT_DELAYOperator 升级时同一集群内单个 PostgreSQL 实例之间滚动升级的等待时长秒。默认0即同一集群内实例升级无延迟。KUBERNETES_CLUSTER_DOMAIN定义 Kubernetes 集群内 Service FQDN 的域名后缀。留空时默认为cluster.local。MANAGE_WEBHOOK_CONFIGURATIONS默认trueOperator 将自身 CA 证书注入MutatingWebhookConfiguration与ValidatingWebhookConfiguration。当 CA 由外部注入如 cert-manager 的 CA injector 或 GitOps 工具时设为false。该开关独立于 webhook 服务证书——只要 Operator 拥有自己的 PKI服务证书始终由 Operator 管理。METRICS_CERT_DIROperator metrics 服务 TLS 证书的存放目录。设置后8080 端口上的 metrics 端点启用 TLS目录需按 Kubernetes TLS Secret 惯例包含tls.crt与tls.key。未设置时 metrics 服务无 TLS默认行为。MONITORING_QUERIES_CONFIGMAPOperator 命名空间中某个 ConfigMap 的名称其中在queries键下存放一组默认查询将应用到所有创建的 Cluster。MONITORING_QUERIES_SECRETOperator 命名空间中某个 Secret 的名称其中在queries键下存放一组默认查询将应用到所有创建的 Cluster。OPERATOR_IMAGE_NAME用于引导 Pod 的 Operator 镜像名。默认使用安装时指定的镜像。PGBOUNCER_IMAGE_NAME新建 Pooler 默认使用的 PgBouncer 镜像名。默认使用 Operator 内置的版本。POSTGRES_IMAGE_NAME新建集群默认使用的 PostgreSQL 镜像名。默认使用 Operator 内置的版本。PULL_SECRET_NAMEOperator 命名空间中附加拉取 Secret 的名称用于下载镜像。STANDBY_TCP_USER_TIMEOUT备库到主库复制连接的TCP_USER_TIMEOUTsocket 选项毫秒。默认 50005 秒设为0使用系统默认值。WATCH_NAMESPACEOperator 监听资源的命名空间可逗号分隔多个。未设置时监听所有命名空间集群级模式。在源码中以上默认值90 天证书、7 天过期阈值、cluster.local集群域名、默认污点列表、ManageWebhookConfigurations: true等集中定义于 internal/configuration/configuration.go 与newDefaultConfig函数internal/configuration/configuration.go。其中DRAIN_TAINTS、INHERITED_ANNOTATIONS、INHERITED_LABELS这类列表型参数在解析时按逗号切分并去除空白见 pkg/configparser/configparser.go。重要多 Operator 并存的限制CloudNativePG目前不支持在同一集群运行多个 Operator。虽然可以通过命名空间级部署配合ENABLE_WEBHOOK_NAMESPACE_SUFFIX与WATCH_NAMESPACE实现多实例共存但多个 Operator 仍然共享同一套 CRD无法保证跨多个并发 Operator 的向后兼容升级。关键参数深度解析标签与注解继承INHERITED_ANNOTATIONS / INHERITED_LABELS这是最常见的定制诉求让所有由 Operator 生成的资源Deployment、Service、PVC、Pod 等自动携带你在Cluster上定义的特定标签与注解便于统一监控、网络策略或成本归集。其底层判定逻辑是IsAnnotationInherited/IsLabelInherited函数它们调用evaluateGlobPatterns对配置的列表逐项执行通配符匹配见 internal/configuration/configuration.go 与 internal/configuration/configuration.go。值得特别注意的是INHERITED_ANNOTATIONS与INHERITED_LABELS的值支持路径风格的通配符path-like wildcards。例如值example.com/*会同时匹配example.com/one与example.com/two——这为按域名前缀批量继承提供了便捷手段。镜像与拉取 SecretPOSTGRES_IMAGE_NAME / PGBOUNCER_IMAGE_NAME / OPERATOR_IMAGE_NAME / PULL_SECRET_NAME当私有镜像仓库要求认证时可通过PULL_SECRET_NAME指定 Operator 命名空间内的一个拉取 Secret。其工作机制在 internal/controller/cluster_create.go 的copyPullSecretFromOperator中实现Operator 为每个新建的 PostgreSQL 集群复制该 Secret复制后命名为cluster-name-pull并设置继承元数据与所有权。需要说明的两点查找 Secret 的命名空间是安装 Operator 的命名空间如果 Operator 找不到该 Secret会静默忽略此配置参数开发环境未通过 Deployment 启动时同样返回空。默认的拉取 Secret 名称为cnpg-pull-secret见 internal/configuration/configuration.go。镜像类参数则支持在不开新集群的情况下更换默认 PostgreSQL / PgBouncer / Operator 镜像。证书管理CERTIFICATE_DURATION / EXPIRING_CHECK_THRESHOLD / MANAGE_WEBHOOK_CONFIGURATIONS / METRICS_CERT_DIROperator 自带 PKI 体系为 webhook 服务与集群间通信生成证书。CERTIFICATE_DURATION默认 90 天控制生成证书的有效期EXPIRING_CHECK_THRESHOLD默认 7 天用于判定证书即将过期以便轮换。若证书注入与轮换交给外部工具如 cert-manager 或 GitOps 流水线则将MANAGE_WEBHOOK_CONFIGURATIONS设为false——该开关只影响 webhook 配置中 CA 证书包的注入不影响 webhook 服务证书本身的管理见 internal/cmd/manager/controller/controller.go 中ensurePKI对ManageWebhookConfigurations的使用。METRICS_CERT_DIR则用于给 8080 端口的 metrics 服务开启 TLS源码中buildMetricsOpts在配置了该目录后会以tls.crt/tls.key作为证书文件并开启SecureServing见 internal/cmd/manager/controller/controller.go。升级节奏CLUSTERS_ROLLOUT_DELAY / INSTANCES_ROLLOUT_DELAY / ENABLE_INSTANCE_MANAGER_INPLACE_UPDATESOperator 升级触发集群滚动时可通过两个延迟参数控制节奏CLUSTERS_ROLLOUT_DELAY控制集群之间的等待秒数跨集群错峰INSTANCES_ROLLOUT_DELAY控制同一集群内实例之间的等待秒数。两者默认均为0立即连续升级对应源码中GetClustersRolloutDelay/GetInstancesRolloutDelay将整数秒转换为time.Duration的实现internal/configuration/configuration.go。若希望 Operator 升级不重启任何 Pod可开启ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES: true让 instance manager 以原地替换可执行文件的方式更新详见 docs/src/installation_upgrade.md。监控查询注入MONITORING_QUERIES_CONFIGMAP / MONITORING_QUERIES_SECRET指定 Operator 命名空间中承载默认 Prometheus 查询的 ConfigMap 或 Secret 名称查询内容放在queries键下这些查询会被应用到之后创建的所有 Cluster实现监控指标的全局统一注入。源码中对应MonitoringQueriesConfigmap/MonitoringQueriesSecret两个字段internal/configuration/configuration.go。网络与故障转移相关KUBERNETES_CLUSTER_DOMAIN / STANDBY_TCP_USER_TIMEOUT / DRAIN_TAINTSKUBERNETES_CLUSTER_DOMAIN覆盖集群内 Service FQDN 的域名后缀默认cluster.local适用于使用自定义 DNS 域名的 Kubernetes 集群STANDBY_TCP_USER_TIMEOUT为备库复制连接设置 TCP 用户超时毫秒默认 5000配置会写入备库的primary_conninfo其字段类型为指针整数源码中未设置保持 nilinstance manager 使用默认 5000ms、显式设 0 则走系统默认值的逻辑见 internal/configuration/configuration.goDRAIN_TAINTS定义哪些污点被视为节点驱逐信号驱动 Operator 的优雅故障转移行为默认覆盖 Kubernetes 内置不可调度污点、Cluster Autoscaler 的待删除污点以及 Karpenter 的中断污点internal/configuration/configuration.go。定义 Operator ConfigMap下面是一个完整的 ConfigMap 示例它配置了资源继承的注解/标签名、开启 instance manager 原地更新并设置了集群间与实例间的滚动升级延迟apiVersion: v1 kind: ConfigMap metadata: name: cnpg-controller-manager-config namespace: cnpg-system data: CLUSTERS_ROLLOUT_DELAY: 60 ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES: true INHERITED_ANNOTATIONS: categories INHERITED_LABELS: environment, workload, app INSTANCES_ROLLOUT_DELAY: 10注意布尔值与数值均以字符串形式写入dataYAML 中建议加引号如60、true列表值以逗号分隔。定义 Operator Secret对于不希望明文暴露的配置如未来可能引入的敏感参数可使用同名的 Secret。示例内容与上面 ConfigMap 一致载体改为SecretapiVersion: v1 kind: Secret metadata: name: cnpg-controller-manager-config namespace: cnpg-system type: Opaque stringData: CLUSTERS_ROLLOUT_DELAY: 60 ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES: true INHERITED_ANNOTATIONS: categories INHERITED_LABELS: environment, workload, app INSTANCES_ROLLOUT_DELAY: 10由于 Secret 的优先级高于 ConfigMap先 ConfigMap 后 Secret后者覆盖前者你也可以把通用参数放在 ConfigMap、把个别敏感/覆盖参数放在同名 Secret 中组合使用。重新加载配置配置不会热更新。修改 ConfigMap/Secret 后必须重建 Operator Pod 才能重新加载。如果通过官方 manifest 安装可执行滚动重启kubectl rollout restart deployment \ -n cnpg-system \ cnpg-controller-manager通用做法是直接删除 Operator PodDeployment 会自动重建按命名空间替换[NAMESPACE_NAME_HERE]kubectl delete pods -n [NAMESPACE_NAME_HERE] \ -l app.kubernetes.io/namecloudnative-pg警告定制只会应用到配置重载之后新建的Cluster资源存量 Cluster 不会自动获得新的继承标签/注解或新的默认镜像等设置。以上述示例为准如果Cluster定义中包含categories注解以及environment、workload、app中的任一标签它们就会被继承到该集群 Deployment 生成的所有资源上。无 Admission Webhook 时的默认化与校验回退CloudNativePG 通常通过 admission webhook 对资源做默认值填充与校验。当 webhook 未安装或暂时无法响应时Operator 会在调谐reconciliation过程中执行同样的默认化与校验作为回退。若资源校验失败调谐会停止原因呈现在资源状态中Cluster进入Invalid cluster definition阶段Backup进入invalid backup definition阶段后者在 internal/controller/backup_controller.go 中有对应处理Pooler与ScheduledBackup则写入.status.error字段。状态中只列出出错的字段路径完整的校验错误可能包含字段值仅写入 Operator 日志。修正 spec 后错误会被清除并恢复调谐。回退校验同样遵循cnpg.io/validation: disabled注解——该注解可以禁用校验webhook 与调谐回退一视同仁。校验被禁用时的警告提示在 internal/webhook/v1/common.go 中定义。性能剖析启用 pprofOperator 可在localhost:6060暴露 pprof HTTP 服务用于性能剖析与问题排查。默认关闭需编辑 Operator Deployment 为容器 args 增加--pprof-servertruekubectl edit deployment -n cnpg-system cnpg-controller-manager在 args 列表中加入该 flag例如containers: - args: - controller - --leader-elect - --config-map-namecnpg-controller-manager-config - --secret-namecnpg-controller-manager-config - --log-levelinfo - --pprof-servertrue # relevant line command: - /manager保存后 Deployment 会滚动出新 Podpprof 服务随之生效。源码中 pprof 地址由getPprofServerAddress控制开启时返回0.0.0.0:6060对应 controller-runtime 的PprofBindAddress关闭时返回空串即不监听见 internal/cmd/manager/controller/controller.go。本地访问 pprof 端点使用端口转发kubectl port-forward -n cnpg-system deploy/cnpg-controller-manager 6060 curl -sS http://localhost:6060/debug/pprof/ go tool pprof http://localhost:6060/debug/pprof/profile?seconds30也可以直接用浏览器打开 http://localhost:6060/debug/pprof/ 查看堆、goroutine、CPU profile 等标准 pprof 页面。重要pprof 服务仅在 6060 端口提供纯 HTTP无任何认证上面的kubectl port-forward仅用于本地测试不是生产环境暴露该功能的正确方式请把 pprof 视为敏感调试接口切勿公网暴露确需远程访问时必须配合网络策略与访问控制加以保护。小结CloudNativePG Operator 的配置体系简洁而强大一个名为cnpg-controller-manager-config的 ConfigMap/Secret 承载全部运行期参数先 ConfigMap 后 Secret 的合并顺序配合环境变量与代码默认值形成了清晰的三级优先级资源继承、镜像定制、证书管理、升级节奏、监控注入与网络调优等能力全部由 22 个环境变量形式的键驱动。理解其加载时机仅在启动时读取、重启后对新建资源生效是正确实施变更的前提。若需进一步深入可阅读以下仓库资源配置结构体与全部默认值internal/configuration/configuration.go配置解析默认值→环境变量→ConfigMap/Secret的实现pkg/configparser/configparser.go配置加载顺序与 pprof、metrics TLS 启动逻辑internal/cmd/manager/controller/controller.gocontroller 子命令 flag 定义--config-map-name、--secret-name、--pprof-serverinternal/cmd/manager/controller/cmd.go拉取 Secret 复制为cluster-name-pull的实现internal/controller/cluster_create.go配置解析的单元测试internal/configuration/configuration_test.goinstance manager 原地更新ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES详解docs/src/installation_upgrade.md【免费下载链接】cloudnative-pgThe most popular Kubernetes Operator for PostgreSQL.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudnative-pg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考