安装

本页面介绍如何安装 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。

  1. 检查是否需要该规则。此操作仅向 admission webhook 询问它将如何重写软件包中的某个镜像(--dry-run=server);不会创建任何内容:

    REGISTRY=$(kubectl get cm -n kube-public global-info -o jsonpath='{.data.registryAddress}')
    IMG=$(kubectl -n cpaas-system get imagewhitelist cloudnative-pg -o jsonpath='{.spec.repoList[*]}' \
          | tr ' ' '\n' | grep '^registry-dev\.alauda\.io/' | head -1)
    WANT="$REGISTRY/${IMG#*/}"
    GOT=$(printf 'apiVersion: v1\nkind: Pod\nmetadata:\n  name: cnpg-rewrite-check\n  namespace: default\nspec:\n  containers:\n  - name: p\n    image: %s\n' "$IMG" \
          | kubectl create -f - --dry-run=server -o jsonpath='{.spec.containers[0].image}')
    if [ "$GOT" = "$WANT" ]; then echo "OK: no rule needed (or already in place)"; else echo "RULE NEEDED: $IMG -> $GOT"; fi

    如果输出 OK,请跳过本节的其余部分。如果 IMG 为空,则表示软件包尚未推送到此集群。

  2. 添加规则。以下脚本可以安全地运行多次:如果 registry-dev.alauda.io 已存在规则,则不执行任何操作;如果已有规则,则会追加规则而不是替换规则。不要对该字段使用 merge patch,因为它会替换整个列表。

    REGISTRY=$(kubectl get cm -n kube-public global-info -o jsonpath='{.data.registryAddress}')
    CUR=$(kubectl -n cpaas-system get imagewhitelist cloudnative-pg -o jsonpath='{.spec.rewriteRules}')
    RULE="{\"regexp\":\"registry-dev.alauda.io/(.*)\",\"replacement\":\"${REGISTRY}/\${1}\"}"
    if printf '%s' "$CUR" | grep -q 'registry-dev.alauda.io'; then
      echo "rule already present"
    elif [ -z "$CUR" ]; then
      kubectl -n cpaas-system patch imagewhitelist cloudnative-pg --type=json \
        -p "[{\"op\":\"add\",\"path\":\"/spec/rewriteRules\",\"value\":[${RULE}]}]"
    else
      kubectl -n cpaas-system patch imagewhitelist cloudnative-pg --type=json \
        -p "[{\"op\":\"add\",\"path\":\"/spec/rewriteRules/-\",\"value\":${RULE}}]"
    fi
  3. 等待约 15 秒(webhook 会缓存规则),然后再次运行步骤 1:它必须输出 OK。

  4. 如果 operator 已安装且其 pod 启动失败,请删除 cnpg-system 中的 cnpg-controller-manager 和 barman-cloud pod,使其使用重写后的镜像重新创建:

    kubectl -n cnpg-system delete pod -l app.kubernetes.io/name=cloudnative-pg
    kubectl -n cnpg-system delete pod -l app=barman-cloud

    仅当 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。

通过平台目录安装(推荐)

Web Console
kubectl
  1. 在左侧导航栏中,前往 Marketplace > Operator Hub。
  2. 选择目标集群。
  3. 在 platform catalog source 下搜索 Alauda Data Services Relational Database E3。
  4. 点击 安装。
  5. 在安装对话框中,接受建议的命名空间 cnpg-system(bundle 通过 operatorframework.io/suggested-namespace annotation 声明此命名空间),选择 channel stable、安装计划审批方式 Automatic,然后确认。
  6. 等待 operator 的 CSV 进入 Succeeded 阶段,且 cnpg-controller-manager deployment 状态为 1/1 Ready。

验证安装

CSV 状态为 Succeeded 后:

kubectl get csv -n cnpg-system
kubectl get deploy cnpg-controller-manager -n cnpg-system
kubectl get pods -n cnpg-system

预期结果:

  • 一个阶段为 Succeeded 的 CSV cloudnative-pg.<version>。
  • Deployment cnpg-controller-manager 有 1/1 个就绪副本。
  • 一个处于 Running 状态的 operator pod cnpg-controller-manager-<hash>。

检查 operator 环境中的 ACP 特定默认值:

kubectl get deploy cnpg-controller-manager -n cnpg-system \
  -o jsonpath='{.spec.template.spec.containers[0].env}' | python3 -c "
import json,sys
[print(e['name'], '=', e.get('value','')) for e in json.load(sys.stdin)
 if e['name'] in ('ENABLE_IMAGE_REWRITE_TOLERANCE','POSTGRES_IMAGE_NAME','PGBOUNCER_IMAGE_NAME')]"

您应看到:

  • ENABLE_IMAGE_REWRITE_TOLERANCE = true
  • POSTGRES_IMAGE_NAME = registry-dev.alauda.io/eco-oss/postgres/cnpg/postgresql:18.6-202610260653-standard-trixie
  • PGBOUNCER_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。

后续步骤

“创建 Cluster”操作指南和故障排除参考内容计划在未来的文档版本中发布。目前,架构页面介绍了 Cluster CR 模型,升级页面则包含常见安装问题的诊断操作步骤。

商标声明

CloudNativePG™ 是 The Linux Foundation 的商标。

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

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