Gabriele Bartolini：CNPG 配方 26 - 扩展镜像目录
内容提要
CloudNativePG 1.29 新增通过ClusterImageCatalog管理扩展镜像的功能，用户只需在Cluster中指定扩展名，无需硬编码镜像引用。社区目录提供pgvector、PostGIS等7种扩展，按PostgreSQL主版本统一解析镜像、路径和依赖。此机制简化了扩展分发和升级，支持滚动更新和私有目录定制，成为推荐的管理方式。
延伸解读
目录机制的核心价值
CloudNativePG 1.29 将扩展镜像纳入 ClusterImageCatalog，使得 Cluster 清单只需指定扩展名，无需硬编码镜像引用。这解决了扩展升级时需逐个修改 Cluster 的问题，实现了镜像与扩展的单一事实来源，并支持滚动更新，简化了扩展分发与升级流程。
适用版本与限制
该机制依赖 PostgreSQL 18 的 extension_control_path 特性，因此社区目录目前仅对 PostgreSQL 18 提供扩展支持。对于仍在使用旧版 PostgreSQL 的组织，若需提前采用此机制，社区不提供支持，但 EDB 企业版可为 PostgreSQL 15 及以上版本提供扩展镜像。
私有目录定制与离线部署
社区目录并非唯一选择，组织可以复制并定制自己的 ClusterImageCatalog，固定扩展构建和摘要，以满足特定需求。对于离线环境，可将镜像同步到私有仓库并调整引用，而使用 imageCatalogRef 的 Cluster 清单无需改动，这为受限网络环境提供了便利。
Q&A
CloudNativePG 1.29 中，Cluster 如何通过镜像目录指定扩展？
在 CloudNativePG 1.29 中，Cluster 只需在 postgresql.extensions 中指定扩展名称，并通过 imageCatalogRef 引用 ClusterImageCatalog 和 PostgreSQL 主版本，无需硬编码镜像引用。例如，引用 postgresql-minimal-trixie 目录并指定 major: 18，然后添加扩展 pgvector。
CloudNativePG 的社区扩展目录包含哪些扩展？
社区扩展目录目前包含 7 个扩展：pg-crash、pg-ivm、pgaudit、pgvector、postgis、timescaledb-oss 和 wal2json。
为什么 CloudNativePG 推荐使用镜像目录管理扩展？
因为镜像目录提供了每个 PostgreSQL 主版本的单一事实来源，确保扩展与操作数镜像兼容，避免 ABI 不匹配；同时实现了关注点分离，平台团队维护目录，应用团队只需按名称引用；还支持滚动更新和跨主版本的干净升级路径。
如何部署 CloudNativePG 的社区扩展目录？
使用 kubectl apply -k https://github.com/cloudnative-pg/artifacts/image-catalogs-extensions?ref=main 命令，该命令会应用一个 kustomize 目标，将扩展数组添加到 Debian Trixie 和 Bookworm 最小目录的相关主版本条目中。
CloudNativePG 的扩展镜像目录支持哪些 Kubernetes 版本？
需要 Kubernetes 1.35 或更高版本（ImageVolume 默认启用），或者 1.33/1.34 版本并启用 ImageVolume 特性门控。容器运行时需要 containerd 2.1.0+ 或 CRI-O 1.31+。
在 CloudNativePG 中，如何验证扩展是否从目录正确解析？
可以通过检查 Cluster 的状态字段 status.pgDataImageInfo，使用 kubectl get cluster pgvector -o jsonpath='{.status.pgDataImageInfo}' | jq 命令，该输出会显示从目录解析出的操作数和扩展的有效镜像引用。
CloudNativePG 的扩展镜像目录是否支持私有定制？
支持。社区目录只是一个 ClusterImageCatalog 示例，组织可以 fork 它，固定自己的扩展构建和摘要，并维护一个私有目录。对于气隙部署，可以镜像镜像到自己的注册表并调整 image.reference 条目，而使用 imageCatalogRef 的 Cluster 清单无需更改。
