配置

了解如何在 Alauda Container Platform 上配置 CloudNativePG Cluster: PostgreSQL 参数、用户和数据库、复制、存储以及镜像。首次部署请参阅快速入门;了解架构请参阅 架构。

PostgreSQL 参数

spec:
  postgresql:
    parameters:
      shared_buffers: 512MB
      max_connections: "200"
      work_mem: 8MB
    pg_hba:
      - host all all 10.0.0.0/8 scram-sha-256
  • 一组参数由 operator 控制,设置后会被拒绝 (archive_mode、archive_command、restore_command、port、 hot_standby、ssl*、synchronous_standby_names、 shared_preload_libraries、恢复目标、监听/日志/文件路径设置)。请改用专用字段: spec.postgresql.shared_preload_libraries、 spec.postgresql.synchronous(如下)。
  • 常用调优参数(max_connections、shared_buffers、 work_mem、effective_cache_size、autovacuum 和检查点设置等)均可使用。
  • operator 会注入合理的默认值,包括 wal_level=logical、archive_timeout=5min、wal_keep_size=512MB, 以及 TLS ≥ 1.3。
  • ALTER SYSTEM 默认禁用 (spec.postgresql.enableAlterSystem)——配置采用声明式方式; 更改会在集群中滚动生效,其行为由 spec.primaryUpdateStrategy(默认值为 unsupervised)和 spec.primaryUpdateMethod(restart 或 switchover)控制。
  • pg_hba 条目会插入 operator 管理的固定规则(本地 peer 访问、经证书身份验证的复制)与末尾默认规则 host all all all scram-sha-256 之间。

用户和数据库

CloudNativePG 不会将密码直接存储在 Cluster 资源中。 operator 应用的所有密码都来自与集群位于同一命名空间中的 Kubernetes Secret,类型为 kubernetes.io/basic-auth。 您可以让 operator 生成这些 Secret,也可以自行创建并按名称引用。

PostgreSQL 角色配置方式默认值读取的 Secret
原生应用所有者 (app)spec.bootstrap.initdb已创建,随机密码<cluster>-app 或 spec.bootstrap.initdb.secret
超级用户 (postgres)spec.enableSuperuserAccess、spec.superuserSecret无密码(已禁用网络登录)<cluster>-superuser 或 spec.superuserSecret
其他角色DatabaseRole 资源或 spec.managed.roles不创建每个角色对应的 passwordSecret

凭证 Secret

自行创建的凭证 Secret 必须:

  • 包含 type: kubernetes.io/basic-auth,且其中包含键 username 和 password;
  • 包含 username,其值必须与所用 PostgreSQL 角色完全匹配 (app / initdb.owner、postgres 或受管理角色名称)。如果不匹配,实例管理器会拒绝该 Secret,且不会应用密码;
  • 包含标签 cnpg.io/reload: "true"。operator 只监视带有此标签的 Secret,因此添加该标签后,密码更改会立即应用到 PostgreSQL;如果未添加,则只有在之后发生无关的协调时才会应用更改。operator 生成的 Secret 已包含此标签。

使用 kubectl:

kubectl create secret generic pg-demo-app-creds -n pg-demo \
  --type=kubernetes.io/basic-auth \
  --from-literal=username=app \
  --from-literal=password='S3cure-Passw0rd'
kubectl label secret pg-demo-app-creds -n pg-demo cnpg.io/reload=true

或者使用声明式配置:

apiVersion: v1
kind: Secret
metadata:
  name: pg-demo-app-creds
  namespace: pg-demo
  labels:
    cnpg.io/reload: "true"
type: kubernetes.io/basic-auth
stringData:
  username: app
  password: S3cure-Passw0rd

自行创建的 Secret 只包含 username 和 password。operator 生成的 Secret (<cluster>-app、<cluster>-superuser) 还会包含可直接使用的连接详细信息:

键内容
username、user角色名称
password生成的密码
dbname数据库名称(超级用户 Secret 中为 *)
host、port读写 Service 名称,5432
uri、jdbc-uri使用带命名空间的 Service 主机名的连接字符串
fqdn-uri、fqdn-jdbc-uri同上,但使用完全限定的 Service 主机名
pgpass一行 .pgpass 格式的内容

原生应用数据库和所有者密码

spec.bootstrap.initdb 会创建原生应用数据库及其所有者。默认情况下,数据库为 app,所有者为 app,operator 会使用随机密码生成 <cluster>-app Secret。

若要在创建集群时指定密码,请先创建凭证 Secret(见上文——username 必须等于 spec.bootstrap.initdb.owner),然后引用该 Secret:

spec:
  bootstrap:
    initdb:
      database: app
      owner: app
      secret:
        name: pg-demo-app-creds   # no <cluster>-app Secret is generated

从备份引导集群或从其他集群克隆集群时,spec.bootstrap.recovery.secret 和 spec.bootstrap.pg_basebackup.secret 也可以像上述方式一样接受原生应用所有者 Secret。

之后更改密码:更新正在使用的 Secret 中的 password 键(<cluster>-app 或 initdb.secret 引用的 Secret)。添加 cnpg.io/reload: "true" 标签后,实例管理器会立即在主节点上运行 ALTER ROLE;客户端必须使用新密码重新连接。

kubectl patch secret pg-demo-app-creds -n pg-demo --type=merge \
  -p '{"stringData":{"password":"N3w-Passw0rd"}}'

超级用户 (postgres) 密码

默认禁用通过网络访问超级用户 (spec.enableSuperuserAccess: false):operator 会将 postgres 角色的密码设置为 NULL,并且只通过本地 peer 和 TLS 客户端证书身份验证来管理实例。

  • 生成密码:设置 spec.enableSuperuserAccess: true。operator 会创建 <cluster>-superuser Secret。

  • 使用自定义密码:创建包含 username: postgres 的凭证 Secret(并添加 cnpg.io/reload: "true" 标签),然后设置两个字段:

    spec:
      enableSuperuserAccess: true
      superuserSecret:
        name: pg-demo-superuser-creds
WARNING

除非 spec.enableSuperuserAccess 为 true,否则 spec.superuserSecret 不会生效。禁用访问时,operator 会忽略 Secret 的内容,并将 postgres 密码保持为 NULL;之后如果将 enableSuperuserAccess 改回 false,operator 生成的 <cluster>-superuser Secret 也会被删除(自行创建的 Secret 会保留)。

其他角色

其他角色采用声明式配置。提供两种形式,可用于不同角色:

  • DatabaseRole 资源(推荐)——每个角色使用一个资源,独立于 Cluster 清单。适用于 GitOps,也适合由应用团队管理自己的角色。
  • spec.managed.roles——在 Cluster 中内联列出角色。

DatabaseRole 示例——该资源、引用的 Cluster 和密码 Secret 必须位于同一命名空间:

apiVersion: postgresql.cnpg.io/v1
kind: DatabaseRole
metadata:
  name: pg-demo-alice
  namespace: pg-demo
spec:
  cluster:
    name: pg-demo
  name: alice                      # PostgreSQL role name (immutable)
  login: true                      # roles default to login: false
  createdb: true
  inRoles:
    - pg_monitor
  passwordSecret:
    name: alice-creds              # basic-auth Secret, username: alice
  databaseRoleReclaimPolicy: retain   # retain (default) | delete

等效的内联形式:

spec:
  managed:
    roles:
      - name: alice
        ensure: present          # present (default) | absent
        login: true
        createdb: true
        inRoles:
          - pg_monitor
        passwordSecret:
          name: alice-creds

注意事项:

  • 角色默认为 login: false。对于客户端要连接的角色,请设置 login: true。
  • 如果没有 passwordSecret,创建角色时会将密码设为 NULL。 disablePassword: true 会显式将密码设为 NULL;不能与 passwordSecret 组合使用。
  • 移除角色:内联角色使用 ensure: absent。DatabaseRole 不接受 ensure;请改为删除资源,而 databaseRoleReclaimPolicy 决定 PostgreSQL 中的处理方式——retain(默认值)会保留角色,delete 会运行 DROP ROLE(该操作会失败,资源将保持 Terminating 状态,而角色仍拥有对象)。
  • 如果在 spec.managed.roles 和 DatabaseRole 中同时声明了同名角色,则以 spec.managed.roles 为准:不会应用 DatabaseRole,并会报告带有 database role is already managed by the CNPG cluster 的 applied: false。
  • 如果 DatabaseRole 指向已存在的角色,则会接管该角色,并重置所有未指定的属性(例如,会撤销不在 inRoles 中的成员关系)。名称 postgres、streaming_replica 以及以 pg_ 或 cnpg_ 开头的名称均为保留名称。
  • 使用 kubectl get databaserole -n pg-demo 查看进度(Applied 列)。

其他数据库

其他数据库各自对应一个 Database 资源:

apiVersion: postgresql.cnpg.io/v1
kind: Database
metadata:
  name: pg-demo-reporting
  namespace: pg-demo
spec:
  cluster:
    name: pg-demo
  name: reporting                 # PostgreSQL database name
  owner: alice                    # an existing role, e.g. from a DatabaseRole
  extensions:
    - name: vector                # pgvector
      ensure: present
  databaseReclaimPolicy: retain   # retain (default) | delete

使用 databaseReclaimPolicy: delete 时,删除 Database 资源也会删除 PostgreSQL 中的数据库;使用 retain 时则会保留数据库。

从 Console 创建集群

TIP

在 ACP Console(Data Services → CloudNativePG → Create)中,Form 视图会使用上述默认值创建集群:创建一个 app 数据库及其所有者,并将生成的密码写入 <cluster>-app Secret;不设置超级用户密码。

若要在创建时设置自定义密码(bootstrap.initdb.secret、superuserSecret 或 managed.roles 下的角色),请先在目标命名空间中创建 kubernetes.io/basic-auth Secret,然后将 Create 页面切换到 YAML 视图并添加上述字段;或者使用 kubectl 应用清单。随时可以从 <cluster>-app / <cluster>-superuser Secret 中读取生成的密码。

扩展和 pgaudit

standard PostgreSQL operands bundle 包含 pgvector、pgaudit、PostGIS、 zhparser、TimescaleDB(Apache-2 OSS,PG 15+)和 pg_failover_slots — 均无需 Kubernetes ImageVolume 功能门控即可使用。

大多数扩展通过 Database 资源(spec.extensions,见上文)或普通的 CREATE EXTENSION 按数据库启用。其中两个是加载时扩展,必须通过 spec.postgresql.shared_preload_libraries 声明(裸的 shared_preload_libraries GUC 由 operator 控制,且会被拒绝):

spec:
  postgresql:
    shared_preload_libraries:
      - pgaudit
      - pg_failover_slots
      - timescaledb        # PG 15+ only
    parameters:
      pgaudit.log: "ddl, write"   # configure pgaudit declaratively
  • pgaudit 必须以声明方式配置。 它是由 operator 管理的扩展:手动执行的 CREATE EXTENSION pgaudit 会在下一次重启时被删除。将 pgaudit 添加到 shared_preload_libraries,并按照上文设置 pgaudit.* 参数 — operator 会为你创建并维护该扩展。
  • pg_failover_slots 按设计仅支持预加载(没有 CREATE EXTENSION 步骤):一旦位于 shared_preload_libraries 中,它会 自动将逻辑复制槽同步到备用节点。
  • timescaledb 需要 shared_preload_libraries,且仅适用于 PG 15–18 (Debian trixie 没有 PG 14 的 OSS 软件包)。仅提供 Apache-2 版本 — 不包含 TSL 功能(压缩、连续聚合)。

复制和高可用性

spec:
  instances: 3
  postgresql:
    synchronous:                 # optional synchronous replication
      method: any
      number: 1
      dataDurability: required   # 'preferred' favors availability
  affinity:
    podAntiAffinityType: required   # default 'preferred'
    topologyKey: kubernetes.io/hostname

故障转移会自动进行(operator 会提升复制进度最靠前的 副本)。可通过 cnpg kubectl 插件(kubectl cnpg promote <cluster> <instance>)执行手动切换。

服务和外部访问

每个集群都会获得三个 ClusterIP 服务:

服务路由到
<cluster>-rw主节点(读写)
<cluster>-ro仅副本(只读)
<cluster>-r任意实例

这些服务始终为 ClusterIP。请勿使用 kubectl edit/patch 更改其类型:此更改不会在任何位置声明, 并且服务重新创建时会丢失(例如恢复后)。 如需使用其他服务类型(NodePort、 LoadBalancer)访问数据库,请在 Cluster 中声明其他服务:

spec:
  managed:
    services:
      disabledDefaultServices: ["ro", "r"]   # optional; rw cannot be disabled
      additional:
        - selectorType: rw                   # rw | ro | r
          updateStrategy: patch              # default; or replace
          serviceTemplate:
            metadata:
              name: pg-demo-rw-nodeport      # must not be <cluster>-rw/-ro/-r
              annotations: {}                # optional, e.g. load-balancer settings
            spec:
              type: NodePort                 # or LoadBalancer
              ports:                         # optional; only to pin the nodePort
                - name: postgres
                  port: 5432
                  targetPort: 5432
                  nodePort: 30432
  • operator 拥有服务 selector(来自 selectorType),因此请勿设置 spec.selector。该服务会在故障转移和切换期间跟随主节点。
  • 编辑 serviceTemplate 会更改活动服务,包括其 type。从 additional 中移除某个条目会删除该服务。
  • updateStrategy: patch(默认)仅应用模板中自上次协调以来更改的字段。 它不会还原对活动服务进行的带外编辑。例如:将 type 更改为 ClusterIP,再改回 NodePort,同时保留固定的 nodePort。 服务会以随机端口恢复,且 operator 不会报告错误。使用 updateStrategy: replace 可强制活动服务与 模板完全匹配。replace 会在每次更改时删除并重新创建服务,因此通过该服务的连接会短暂 中断,且 ClusterIP/nodePort 可能发生变化,除非将其固定。
  • LoadBalancer 服务需要集群中存在负载均衡器实现;如果没有, EXTERNAL-IP 会保持为 <pending>。
  • 准入 webhook 会拒绝禁用 rw、重新使用保留的 <cluster>-rw/-ro/-r 名称以及重复的服务名称。
  • 将 PostgreSQL 暴露在集群外会扩大其攻击面。 请使用 pg_hba 限制客户端,并针对 LoadBalancer 配置 spec.loadBalancerSourceRanges。

存储

spec:
  storage:
    size: 10Gi                  # grow in place by raising it (no shrink)
    storageClass: sc-topolvm    # use a TopoLVM class for production
  walStorage:                   # optional dedicated WAL volume
    size: 5Gi
    storageClass: sc-topolvm

通过 spec.tablespaces 支持表空间(每个表空间都有自己的 PVC)。

镜像和升级

Operand 镜像默认为 operator bundle 中随附的版本。 如需显式固定版本,请将 spec.imageName 设置为平台 registry 中的 PostgreSQL Operand 镜像——始终使用不可变标签。次版本 更新会执行滚动重启;主版本升级采用声明式方式 (更改镜像主版本;集群会执行离线升级)。请参阅 升级。

IPv6 说明

在单栈 IPv6 集群上,不包含上游 url.Build bracket 修复(上游 PR #10682)的 operator 版本无法通过裸 IPv6 Pod IP 访问 instance manager。双栈集群不受影响。请参阅所用 operator 版本的 release notes。

故障排查快速参考

症状首要检查项
集群卡在 Setting up primaryinitdb job Pod 事件:镜像拉取、PVC pending、storage class
Unable to create required cluster objects目标命名空间中的 operator RBAC
Prometheus 中没有指标是否存在 PodMonitor 标签 prometheus: kube-prometheus?请参阅 Grafana dashboards 指南(How To 部分)
备份卡住cnpg-system 中的 barman-cloud plugin 日志;ObjectStore 凭证/端点
LoadBalancer service EXTERNAL-IP 仍处于 <pending> 状态集群没有 load-balancer provider;使用 NodePort,请参阅服务和外部访问
WAL 卷正在填满WAL 归档中断——请在备份监控面板上检查 WAL segments awaiting archive

商标声明

CloudNativePG™ 是 The Linux Foundation 的商标。

PostgreSQL® 是 PostgreSQL Community Association of Canada 的注册商标。

Alauda 是独立供应商。本产品与 The Linux Foundation、PostgreSQL Community Association of Canada 均无关联,亦未获其认可或赞助。所有商标均归其各自所有者所有,在此仅用于标识。