用 CNPG Extension Image Catalog 管理 PostgreSQL 扩展镜像

预计阅读时间：7 分钟

CloudNativePG 的 ClusterImageCatalog 不只可以携带 PostgreSQL operand 镜像，也可以统一描述扩展镜像。这样，Cluster 清单只需要声明想使用的扩展名称，扩展对应的镜像、文件路径和依赖关系都由按 PostgreSQL 大版本维护的 catalog 解析。

这项能力的价值不在于少写几行 YAML，而在于把扩展分发从每个集群的手工配置，提升为可版本化、可复用的基础设施能力。

扩展配置从 Cluster 清单中消失

传统做法通常要求每个 Cluster 自己填写扩展镜像，甚至还要补充扩展文件位置、依赖库或镜像标签。这样的配置很快会产生重复：同一个 pgvector 版本需要在多个集群中重复声明，升级时也必须逐个修改 manifest。

Extension image catalog 改变了这个边界：

catalog 按 PostgreSQL major version 管理可用镜像；
catalog 记录扩展名称与对应的镜像信息；
Cluster 只引用 catalog，并声明需要的扩展名称；
catalog 更新后，后续引用它的 Cluster 可以继承新的扩展定义。

因此，扩展的发布信息集中在一个有版本的来源中，而不是散落在每个应用团队维护的 Cluster manifest 里。

一个 catalog 服务所有 Cluster

社区提供的扩展 catalog 可以作为集群平台的一部分部署。一个实际的组织方式是：平台团队维护 catalog，应用团队只消费 catalog 中已经审核的扩展。

下面是一个最小化的示意配置。具体字段应以正在使用的 CloudNativePG 版本和社区 catalog CRD 为准；部署前可以先检查本地 CRD schema：

kubectl explain clusterimagecatalog.spec --recursive
kubectl explain clusterimagecatalog.spec.images --recursive

随后，根据当前 CRD 版本调整并应用 catalog：

apiVersion: postgresql.cnpg.io/v1
kind: ClusterImageCatalog
metadata:
  name: community-extensions
spec:
  images:
    # 示例：为 PostgreSQL 16 提供包含 pgvector 的扩展镜像。
    # image、extensions 及其子字段请以当前 catalog 版本的 CRD 为准。
    - major: 16
      image: ghcr.io/example/postgresql-extension-pgvector:16-0.7.4
      extensions:
        - name: pgvector
          version: 0.7.4

kubectl apply -f community-extensions.yaml
kubectl get clusterimagecatalog community-extensions -o yaml

上面的镜像地址是示例值，不代表社区 catalog 的固定镜像命名规则。实际使用时，应部署社区维护的 catalog manifest，或将其内容纳入自己的 GitOps 仓库，并固定可审计的版本。

Cluster 只声明扩展名称

假设 catalog 已经为 PostgreSQL 16 注册了 pgvector，Cluster 侧可以保持非常小的配置：

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: vector-db
spec:
  instances: 3
  imageCatalogRef:
    apiGroup: postgresql.cnpg.io
    kind: ClusterImageCatalog
    name: community-extensions
    major: 16
  postgresql:
    extensions:
      - name: pgvector

这段配置表达的是“这个 Cluster 需要 pgvector”，而不是“请使用某个具体镜像、某个路径和某组依赖”。解析细节由 operator 和 catalog 共同完成。

不同 CloudNativePG 版本或 catalog 发行版可能对 imageCatalogRef、扩展列表字段和扩展名称使用略有不同的 schema。实际改造时，建议以安装的 CRD、对应版本文档以及社区 catalog 示例为准，并在测试集群中先验证：

kubectl apply --dry-run=server -f vector-db.yaml
kubectl get cluster vector-db -o yaml
kubectl describe cluster vector-db

真正的收益是扩展生态

当一个扩展进入 catalog 后，所有引用该 catalog 并声明该扩展的 Cluster 都可以复用这份定义。应用团队不需要为每个集群重新编写镜像配置，平台团队也可以集中处理以下工作：

为每个 PostgreSQL major version 选择兼容的扩展镜像；
固定扩展版本，避免镜像标签漂移；
检查扩展与 PostgreSQL、操作系统库之间的兼容性；
在预发布环境中验证后，再发布新的 catalog 版本；
通过 GitOps 或镜像签名策略审计扩展来源。

这也带来一个重要边界：catalog 更新并不等于所有现有数据库会无条件完成升级。镜像替换、实例滚动更新、数据库扩展升级和数据迁移仍然需要按照 CloudNativePG 版本策略及扩展自身的升级要求执行。catalog 解决的是“扩展如何被发现和分发”，不是自动替代数据库变更管理。

落地时的检查清单

采用 Extension image catalog 前，可以确认以下事项：

PostgreSQL major version 与 catalog 中的镜像条目匹配；
pgvector 等扩展的名称符合 catalog 和 PostgreSQL 中的实际名称；
catalog manifest 已固定版本，并纳入代码审查；
镜像仓库、签名、漏洞扫描和拉取凭据已经准备好；
在测试 Cluster 上验证扩展镜像、路径和依赖是否能被 operator 正确解析；
catalog 版本升级有明确的回滚和实例更新方案。

如果组织中有多个 PostgreSQL 集群，优先把 catalog 当作平台级产品维护：Cluster manifest 只表达业务需要的扩展，镜像选择和兼容性则集中在 catalog 生命周期中管理。这样，新增一个扩展通常只需要更新一次 catalog，后续集群便能通过声明名称直接复用它。