bitnamicharts/cloudnative-pg

Bitnami CloudNativePG 软件包

CloudNativePG 是一款开源工具，用于在 Kubernetes 上管理 PostgreSQL 数据库，涵盖从设置到日常维护的全流程。

CloudNativePG 概述

商标说明：本软件列表由 Bitnami 打包。所提及的相关商标归各自公司所有，使用这些商标并不意味着任何关联或背书。

TL;DR（快速入门）

console
helm install my-release oci://registry-1.docker.io/bitnamicharts/cloudnative-pg

如需在生产环境中使用 CloudNativePG？请尝试 VMware Tanzu Application Catalog，即 Bitnami 目录的商业版。

⚠️ 重要通知：Bitnami 目录即将变更

自 2025 年 8 月 28 日起，Bitnami 将升级其公共目录，通过新的 Bitnami Secure Images 计划 提供精选的强化、安全聚焦型镜像。作为此次转型的一部分：

• 首次向社区用户开放热门容器镜像的安全优化版本。
• Bitnami 将开始在免费层级中弃用对非强化、基于 Debian 的软件镜像的支持，并逐步从公共目录中移除非最新标签。因此，社区用户将只能访问数量减少的强化镜像。这些镜像仅以“latest”标签发布，仅供开发使用。
• 自 8 月 28 日起，在两周内，所有现有容器镜像（包括旧版或版本化标签，如 2.50.0、10.6）将从公共目录（docker.io/bitnami）迁移至“Bitnami Legacy”仓库（docker.io/bitnamilegacy），且不再接收更新。
• 对于生产工作负载和长期支持，建议用户采用 Bitnami Secure Images，包括强化容器、更小的***面、CVE 透明度（通过 VEX/KEV）、SBOM 以及企业支持。

这些变更旨在通过推广软件供应链完整性和最新部署的最佳实践，提升所有 Bitnami 用户的安全态势。更多详情，请访问 https://github.com/bitnami/containers/issues/83267%E3%80%82

简介

本图表使用 Helm 包管理器在 Kubernetes 集群上引导部署 https://github.com/bitnami/containers/tree/main/bitnami/cloudnative-pg%E3%80%82

前提条件

• Kubernetes 1.23+
• Helm 3.8.0+

安装图表

要安装发布名称为 my-release 的图表：

console
helm install my-release REGISTRY_NAME/REPOSITORY_NAME/cloudnative-pg

注意：需将占位符 REGISTRY_NAME 和 REPOSITORY_NAME 替换为 Helm 图表仓库和仓库的引用。例如，对于 Bitnami，需使用 REGISTRY_NAME=registry-1.docker.io 和 REPOSITORY_NAME=bitnamicharts。

该命令使用默认配置在 Kubernetes 集群上部署 CloudNativePG。参数 部分列出了安装过程中可配置的参数。

提示：使用 helm list 列出所有发布。

配置和安装详情

操作器配置

Bitnami CloudNativePG 图表允许使用 ConfigMaps 和 Secrets 配置操作器。通过 operator.configuration 和 operator.secretConfiguration 参数进行配置。两者兼容，且 operator.secretConfiguration 部分的配置优先级高于 operator.configuration。以下示例为操作器添加额外配置参数：

yaml
operator:
  configuration:
    EXPIRING_CHECK_THRESHOLD: 12
  secretConfiguration:
    CERTIFICATE_DURATION: 120

也可使用现有 ConfigMaps 和 Secrets，通过 operator.existingConfigMap 和 operator.existingSecret 参数（注意：这些参数与 operator.configuration 和 operator.secretConfiguration 参数不兼容）。

资源请求和限制

Bitnami 图表允许为图表部署内的所有容器设置资源请求和限制。这些配置位于 operator 和 pluginBarmanCloud 部分下的 *.resources 值中（参见参数表）。设置请求对于生产工作负载至关重要，应根据具体用例调整。

为简化此过程，图表包含 operator 和 pluginBarmanCloud 部分下的 *.resourcesPreset 值，可根据不同预设自动设置 *.resources 部分。有关这些预设的详细信息，请参见 https://github.com/bitnami/charts/blob/main/bitnami/common/templates/_resources.tpl#L15%E3%80%82%E4%BD%86%E5%9C%A8%E7%94%9F%E4%BA%A7%E5%B7%A5%E4%BD%9C%E8%B4%9F%E8%BD%BD%E4%B8%AD%EF%BC%8C%E4%B8%8D%E5%BB%BA%E8%AE%AE%E4%BD%BF%E7%94%A8 resourcesPreset，因为它可能无法完全适应具体需求。有关容器资源管理的更多信息，请参见 Kubernetes 官方文档。

备份和恢复

Bitnami CloudNativePG 图表包含 plugin-barman-cloud，用于执行备份操作。通过设置 pluginBarmanCloud.enabled=true 启用：

yaml
pluginBarmanCloud:
  enabled: true

有关如何部署 BarmanObjectStore 对象和启用备份操作，请参见上游 plugin-barman-cloud 文档。

Prometheus 指标

通过将 operator 和 pluginBarmanCloud 部分下的 *.metrics.enabled 设置为 true，可将此图表与 Prometheus 集成。这将在 metrics 服务中公开 cloudnative-pg 原生 Prometheus 端点，可在 operator 和 pluginBarmanCloud 部分下的 *.metrics.service 部分进行配置。它将包含必要的注解，以便被 Prometheus 自动抓取。

对于 PostgreSQL 实例本身，图表部署带有基本查询的监控查询 ConfigMap 或 Secret。这些可在 operator.metrics.monitoringQueries 部分配置。

Prometheus 要求

需安装 Prometheus 或 Prometheus Operator 才能使集成工作。安装 https://github.com/bitnami/charts/tree/main/bitnami/prometheus 或 https://github.com/bitnami/charts/tree/main/bitnami/kube-prometheus%EF%BC%8C%E5%8F%AF%E8%BD%BB%E6%9D%BE%E5%9C%A8%E9%9B%86%E7%BE%A4%E4%B8%AD%E9%83%A8%E7%BD%B2 Prometheus。

与 Prometheus Operator 集成

通过将 operator 和 pluginBarmanCloud 部分下的 *.metrics.serviceMonitor.enabled=true 设置为 true，图表可部署 ServiceMonitor 对象以与 Prometheus Operator 集成。确保集群中已安装 Prometheus Operator CustomResourceDefinitions，否则将失败并显示以下错误：

text
no matches for kind "ServiceMonitor" in version "monitoring.coreos.com/v1"

安装 https://github.com/bitnami/charts/tree/main/bitnami/kube-prometheus 以获取必要的 CRD 和 Prometheus Operator。

滚动标签与不可变标签

强烈建议在生产环境中使用不可变标签。这可确保如果相同标签更新为不同镜像，部署不会自动更改。

如果主容器有新版本、重大变更或严重漏洞，Bitnami 将发布新图表以更新其容器。

额外环境变量

如需添加额外环境变量（用于高级操作，如自定义初始化脚本），可使用 operator 和 pluginBarmanCloud 部分下的 extraEnvVars 属性：

yaml
operator:
  extraEnvVars:
    - name: LOG_LEVEL
      value: error

或者，可使用包含环境变量的 ConfigMap 或 Secret。为此，使用 operator 和 pluginBarmanCloud 部分下的 extraEnvVarsCM 或 extraEnvVarsSecret 值。

边车容器

如果需要在 cloudnative-pg 所在的同一 Pod 中添加额外容器（如额外指标或日志导出器），可在 operator 和 pluginBarmanCloud 部分下使用 sidecars 参数定义：

yaml
operator:
  sidecars:
  - name: your-image-name
    image: your-image
    imagePullPolicy: Always
    ports:
    - name: portname
      containerPort: 1234

如果这些边车容器导出额外端口，可使用 *.service.extraPorts 参数（如可用）添加额外端口定义，如下例所示：

yaml
operator:
  service:
    extraPorts:
    - name: extraPort
      port: 11311
      targetPort: 11311

如需在同一 Pod 中添加额外初始化容器，可在 operator 和 pluginBarmanCloud 部分下使用 initContainers 参数定义。示例如下：

yaml
initContainers:
  - name: your-image-name
    image: your-image
    imagePullPolicy: Always
    ports:
      - name: portname
        containerPort: 1234

了解更多关于 边车容器 和 初始化容器 的信息。

部署额外资源

除操作器外，可能还需要部署 PostgreSQL Cluster、ImageCatalog 或其他操作器对象。为此，图表允许使用 extraDeploy 参数添加其他对象的完整规范。以下示例创建一个 PostgreSQL Cluster 对象和包含角色凭据的 Secret：

yaml
extraDeploy:
- apiVersion: v1
  kind: Secret
  metadata:
    name: my-cluster-example-user
    labels:
      cnpg.io/reload: "true"
  type: kubernetes.io/basic-auth
  stringData:
    username: my_user
    password: bitnami1234
- apiVersion: postgresql.cnpg.io/v1
  kind: Cluster
  metadata:
    name: my-cluster-example
  spec:
    instances: 3
    storage:
      size: 1Gi
    managed:
      roles:
        - name: my_user
          ensure: present
          comment: MY User
          login: true
          superuser: true
          passwordSecret:
            name: my-cluster-example-user

有关可用对象的列表，请参见 CloudNativePG 官方文档。

Pod 亲和性

此图表允许在 operator 和 pluginBarmanCloud 部分下使用 affinity 参数设置自定义亲和性。有关 Pod 亲和性的更多信息，请参见 Kubernetes 文档。

作为替代方案，可使用 https://github.com/bitnami/charts/tree/main/bitnami/common#affinities 图表中提供的 Pod 亲和性、Pod 反亲和性和节点亲和性预设配置。为此，在 operator 和 pluginBarmanCloud 部分下设置 podAffinityPreset、podAntiAffinityPreset 或 nodeAffinityPreset 参数。

参数

全局参数

通用参数

cloudnative-pg 操作器参数

注意：此图表的 README 超出了 DockerHub 25000 字符的长度限制，因此已被截断。完整 README 可参见 https://github.com/bitnami/charts/blob/main/bitnami/cloudnative-pg/README.md