Umut TEKIN：探索：CNPG 扩展（ImageVolume）
内容提要
PostgreSQL 18 新增 extension_control_path 参数，Kubernetes 1.33 引入 ImageVolume 功能，二者结合使 CloudNativePG 能在 Pod 启动时动态加载扩展，无需构建自定义镜像。文章以 pgvector 和 PostGIS 为例，演示了在集群创建时或之后通过修改清单添加扩展并设置 LD_LIBRARY_PATH，实现扩展与 PostgreSQL 运行时解耦。
延伸解读
扩展加载机制的变化
PostgreSQL 18 引入 extension_control_path 参数，用于指定扩展控制文件的搜索路径；Kubernetes 1.33 的 ImageVolume 功能允许将 OCI 镜像作为只读卷挂载到 Pod 的指定路径。两者结合后，CloudNativePG 能在 Pod 启动时动态加载扩展，不再需要将扩展预先构建到 PostgreSQL 容器镜像中。这改变了扩展与运行时紧密耦合的传统模式。
操作方式与注意事项
在 CNPG 集群清单中，可通过 postgresql.extensions 字段声明扩展及其镜像引用，例如 pgvector 和 PostGIS。扩展既可在集群创建时添加，也可在集群运行后通过修改清单动态加入。但需注意，若扩展的共享库不在默认路径，必须设置 ld_library_path，如 PostGIS 需要指向 system 目录。实际挂载路径会变为 /extensions/$EXTENSION_NAME/$DIRECTORY_PATH，因此 LD_LIBRARY_PATH 也会相应调整。
实际效果与验证
文章以 pgvector 和 PostGIS 为例，演示了通过 kubectl apply 更新清单后，在 app 数据库中查询 \dx 可看到扩展已安装。对于 PostGIS，还通过 pg_available_extensions 确认了可用扩展列表。验证 LD_LIBRARY_PATH 时发现其被设置为 /extensions/postgis/system，而非清单中写的 /system，这反映了 CNPG 挂载镜像时的路径转换规则。
优势与适用条件
这种解耦方式让基础 PostgreSQL 镜像保持最小化、不可变且官方维护，同时减少了为不同扩展组合构建自定义镜像的需求，提升了运维灵活性。但使用前提是 PostgreSQL 18 和 Kubernetes 1.33 及以上版本，并且需要为每个扩展准备符合 OCI 标准的镜像。扩展的版本管理仍通过清单中的版本字段控制。
Q&A
CNPG 现在如何动态加载 PostgreSQL 扩展？
CNPG 利用 PostgreSQL 18 的 extension_control_path 参数和 Kubernetes 1.33 的 ImageVolume 功能，在 Pod 启动时动态加载扩展。ImageVolume 将 OCI 容器镜像作为只读卷挂载到指定路径，extension_control_path 则指定扩展的搜索路径，从而无需构建自定义镜像。
使用 CNPG 动态扩展需要满足哪些前提条件？
需要 PostgreSQL 18（提供 extension_control_path 参数）和 Kubernetes 1.33（提供 ImageVolume 功能）。此外，需要准备包含扩展镜像引用的 Cluster 和 Database 清单文件。
如何在 CNPG 集群创建时添加 pgvector 扩展？
在 Cluster 清单的 postgresql.extensions 字段中指定扩展名称和镜像引用，例如 name: pgvector, image.reference: ghcr.io/cloudnative-pg/pgvector:0.8.1-18-trixie。然后在 Database 清单的 extensions 字段中指定扩展名称和版本，应用清单后即可在数据库中看到扩展已安装。
集群启动后还能添加新的扩展吗？如何操作？
可以。编辑 Cluster 清单，在 postgresql.extensions 下添加新的扩展（如 postgis），并设置 ld_library_path 为 system。同时更新 Database 清单添加对应扩展和版本，重新应用清单即可。
为什么 PostGIS 扩展需要设置 LD_LIBRARY_PATH？
因为 PostGIS 的共享库位于容器镜像的 /system 目录下，而 CNPG 将扩展镜像挂载到 /extensions/$EXTENSION_NAME/$DIRECTORY_PATH_IN_EXTENSION_CONTAINER_IMAGE，所以实际路径为 /extensions/postgis/system。需要设置 LD_LIBRARY_PATH 指向该路径，以便 PostgreSQL 找到共享库。
CNPG 动态加载扩展带来了哪些好处？
消除了将扩展直接构建到 PostgreSQL 容器镜像中的长期需求，使基础 PostgreSQL 镜像保持最小化、不可变和官方维护。扩展可以在集群创建时或之后通过简单的清单更新添加，实现了扩展与 PostgreSQL 运行时的解耦，提高了操作灵活性并减少了镜像泛滥。
