安装
本页面介绍如何安装 Alauda Data Services Relational Database E3 operator。安装 operator 后,您可以通过应用 Cluster CR 来部署第一个 PostgreSQL 集群(Functions 指南将在后续版本中提供)。
前提条件
- Alauda Container Platform (ACP) 集群,版本为 4.1 至 4.4。此版本已在 ACP 4.1.6、4.2.5、4.3.2、4.3.3(arm64、仅 IPv6)和 4.4.0 上完成验证。安装前,请运行下面的镜像重写检查;如果输出
RULE NEEDED,请添加相应规则。 - 集群管理员或平台管理员访问权限。
- 为您的版本下载的
cloudnative-pg软件包(.tgz)——通常通过平台目录 UI 安装。 - 目标集群中可用的块模式 StorageClass(例如
global-topolvmsc)。
检查集群是否需要镜像重写规则
此版本的镜像发布在 registry-dev.alauda.io 下。在某些 ACP 集群中,平台的 Marketplace 组件会在创建 pod 时将此类镜像重写为 <platform registry>/3rdparty/<path>,但平台 registry 中不存在该路径,因此 operator 和数据库 pod 无法启动。
集群是否执行此操作取决于该组件的版本,而不仅仅是 ACP 版本:截至 2026-10-30,ACP 4.1.6 和 4.2.5 集群需要此规则,而使用更新组件的 ACP 4.3.2 集群、ACP 4.3.3 集群和 ACP 4.4.0 集群不需要。ACP 4.3.3 及更高版本以及 ACP 4.4 不受影响。在受影响的集群上,您会看到:
- operator 的 CSV 一直处于
Installing,或失败并重试; - pod 事件针对类似
<platform registry>/3rdparty/eco-oss/postgres/cloudnative-pg:<version>的镜像显示ErrImagePull或ImagePullBackOff。拉取错误可能显示为x509: certificate signed by unknown authority:这意味着镜像不在该路径下,而不是证书问题。
请在安装 operator 的集群上(而不是 global 集群,除非 operator 在该集群上运行),在软件包已推送到该集群之后且在安装或升级 operator 之前,运行以下步骤。推送软件包会创建规则所需的 cloudnative-pg ImageWhiteList。
-
检查是否需要该规则。此操作仅向 admission webhook 询问它将如何重写软件包中的某个镜像(
--dry-run=server);不会创建任何内容:如果输出
OK,请跳过本节的其余部分。如果IMG为空,则表示软件包尚未推送到此集群。 -
添加规则。以下脚本可以安全地运行多次:如果
registry-dev.alauda.io已存在规则,则不执行任何操作;如果已有规则,则会追加规则而不是替换规则。不要对该字段使用mergepatch,因为它会替换整个列表。 -
等待约 15 秒(webhook 会缓存规则),然后再次运行步骤 1:它必须输出
OK。 -
如果 operator 已安装且其 pod 启动失败,请删除
cnpg-system中的cnpg-controller-manager和barman-cloudpod,使其使用重写后的镜像重新创建:仅当 PostgreSQL 实例 pod 本身卡在
ImagePullBackOff时才删除该 pod;切勿因此重启正在运行的实例。
该规则属于 cloudnative-pg ImageWhiteList,仅适用于列出名称的镜像:其他产品的 registry-dev.alauda.io 镜像不会被此规则重写,该产品需要使用自己的规则。该规则是由您创建的集群配置,而不是由软件包创建的:如果集群重建或 ImageWhiteList 被重新创建,请再次添加该规则;平台升级到 ACP 4.3.3 或更高版本,或 ACP 4.4 后,您可以将其删除(不删除也无害)。
该规则不适用于 Kubernetes image volumes(.spec.postgresql.extensions[].image):ACP 完全不会重写这些卷。有关此处应使用的引用,请参阅 release notes。
通过平台目录安装(推荐)
- 在左侧导航栏中,前往 Marketplace > Operator Hub。
- 选择目标集群。
- 在
platformcatalog source 下搜索 Alauda Data Services Relational Database E3。 - 点击 安装。
- 在安装对话框中,接受建议的命名空间
cnpg-system(bundle 通过operatorframework.io/suggested-namespaceannotation 声明此命名空间),选择 channelstable、安装计划审批方式Automatic,然后确认。 - 等待 operator 的 CSV 进入 Succeeded 阶段,且
cnpg-controller-managerdeployment 状态为1/1 Ready。
验证安装
CSV 状态为 Succeeded 后:
预期结果:
- 一个阶段为
Succeeded的 CSVcloudnative-pg.<version>。 - Deployment
cnpg-controller-manager有 1/1 个就绪副本。 - 一个处于 Running 状态的 operator pod
cnpg-controller-manager-<hash>。
检查 operator 环境中的 ACP 特定默认值:
您应看到:
ENABLE_IMAGE_REWRITE_TOLERANCE = truePOSTGRES_IMAGE_NAME = registry-dev.alauda.io/eco-oss/postgres/cnpg/postgresql:18.6-202610260653-standard-trixiePGBOUNCER_IMAGE_NAME = registry-dev.alauda.io/eco-oss/postgres/cnpg/pgbouncer:1.25.2-202610260735-trixie
如果缺少 ENABLE_IMAGE_REWRITE_TOLERANCE,则您使用的是 pre-v1.29.0-acp.1 构建版本。有关补救操作步骤,请参阅 Upgrade。
后续步骤
- Architecture — operator + Cluster CR 模型。
- Upgrade — 补丁/次要版本升级操作步骤。
- Release Notes — 各版本变更。
“创建 Cluster”操作指南和故障排除参考内容计划在未来的文档版本中发布。目前,架构页面介绍了 Cluster CR 模型,升级页面则包含常见安装问题的诊断操作步骤。
商标声明
CloudNativePG™ 是 The Linux Foundation 的商标。
PostgreSQL® 是 PostgreSQL Community Association of Canada 的注册商标。
Alauda 是独立供应商。本产品与 The Linux Foundation、PostgreSQL Community Association of Canada 没有关联,也未获得其认可或赞助。所有商标均归其各自所有者所有,此处仅用于标识目的。