配置
了解如何在 Alauda Container Platform 上配置 CloudNativePG Cluster:
PostgreSQL 参数、用户和数据库、复制、存储以及镜像。首次部署请参阅快速入门;了解架构请参阅 架构。
目录
PostgreSQL 参数用户和数据库凭证 Secret原生应用数据库和所有者密码超级用户 (postgres) 密码其他角色其他数据库从 Console 创建集群扩展和 pgaudit复制和高可用性服务和外部访问存储镜像和升级IPv6 说明故障排查快速参考商标声明PostgreSQL 参数
- 一组参数由 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,也可以自行创建并按名称引用。
凭证 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:
或者使用声明式配置:
自行创建的 Secret 只包含 username 和 password。operator 生成的 Secret (<cluster>-app、<cluster>-superuser) 还会包含可直接使用的连接详细信息:
原生应用数据库和所有者密码
spec.bootstrap.initdb 会创建原生应用数据库及其所有者。默认情况下,数据库为 app,所有者为 app,operator 会使用随机密码生成 <cluster>-app Secret。
若要在创建集群时指定密码,请先创建凭证 Secret(见上文——username 必须等于 spec.bootstrap.initdb.owner),然后引用该 Secret:
从备份引导集群或从其他集群克隆集群时,spec.bootstrap.recovery.secret 和 spec.bootstrap.pg_basebackup.secret 也可以像上述方式一样接受原生应用所有者 Secret。
之后更改密码:更新正在使用的 Secret 中的 password 键(<cluster>-app 或 initdb.secret 引用的 Secret)。添加 cnpg.io/reload: "true" 标签后,实例管理器会立即在主节点上运行 ALTER ROLE;客户端必须使用新密码重新连接。
超级用户 (postgres) 密码
默认禁用通过网络访问超级用户 (spec.enableSuperuserAccess: false):operator 会将 postgres 角色的密码设置为 NULL,并且只通过本地 peer 和 TLS 客户端证书身份验证来管理实例。
-
生成密码:设置
spec.enableSuperuserAccess: true。operator 会创建<cluster>-superuserSecret。 -
使用自定义密码:创建包含
username: postgres的凭证 Secret(并添加cnpg.io/reload: "true"标签),然后设置两个字段:
除非 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 必须位于同一命名空间:
等效的内联形式:
注意事项:
- 角色默认为
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 资源:
使用 databaseReclaimPolicy: delete 时,删除 Database 资源也会删除 PostgreSQL 中的数据库;使用 retain 时则会保留数据库。
从 Console 创建集群
在 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 控制,且会被拒绝):
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 功能(压缩、连续聚合)。
复制和高可用性
故障转移会自动进行(operator 会提升复制进度最靠前的
副本)。可通过 cnpg kubectl
插件(kubectl cnpg promote <cluster> <instance>)执行手动切换。
服务和外部访问
每个集群都会获得三个 ClusterIP 服务:
这些服务始终为 ClusterIP。请勿使用
kubectl edit/patch 更改其类型:此更改不会在任何位置声明,
并且服务重新创建时会丢失(例如恢复后)。
如需使用其他服务类型(NodePort、
LoadBalancer)访问数据库,请在 Cluster 中声明其他服务:
- 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.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。
故障排查快速参考
商标声明
CloudNativePG™ 是 The Linux Foundation 的商标。
PostgreSQL® 是 PostgreSQL Community Association of Canada 的注册商标。
Alauda 是独立供应商。本产品与 The Linux Foundation、PostgreSQL Community Association of Canada 均无关联,亦未获其认可或赞助。所有商标均归其各自所有者所有,在此仅用于标识。