CNPG PostgreSQL Extensions Container Images

This repository provides maintenance scripts for building immutable container images containing PostgreSQL extensions supported by CloudNativePG. These images are designed to integrate seamlessly with the image volume extensions feature in CloudNativePG.

Documentation

• Adding a New Extension: A step-by-step guide for contributors.
• Building Locally: Technical instructions for the build system (Dagger/Task).
• CloudNativePG Documentation: How to use these images in your cluster.

---

Requirements

• CloudNativePG ≥ 1.27
• PostgreSQL ≥ 18 (requires the extension_control_path feature)
• Kubernetes 1.33+ (with ImageVolume feature enabled in 1.33 and 1.34)

---

Supported Extensions

CloudNativePG actively maintains the following third-party extensions, provided they are maintained by their respective authors, and PostgreSQL Debian Group (PGDG) packages are available.

Extension	Description	Project URL
pgAudit	PostgreSQL audit extension	https://github.com/pgaudit/pgaudit
pgvector	Vector similarity search for PostgreSQL	https://github.com/pgvector/pgvector
PostGIS	Geospatial database extension for PostgreSQL	https://postgis.net/

Extensions are provided only for the OS versions already built by the cloudnative-pg/postgres-containers project, specifically Debian stable and oldstable.

---

Contribution and Maintenance Policy

Contributors are welcome to propose and maintain additional extensions.

Governance and Compliance

The project adheres to the following frameworks:

• Governance Model: complies with the CloudNativePG (CNPG) Governance Model, as defined in GOVERNANCE.md.
• Code of Conduct: follows the CNCF Code of Conduct, as defined in CODE_OF_CONDUCT.md.

Extension Requirements

When proposing a new extension, the following criteria must be met:

• Licensing and IP ownership: We redistribute unmodified third-party software as container images. We prioritize licenses explicitly allowed by the CNCF License Policy, which includes the PostgreSQL License (relevant to this project). Other open-source licenses, such as FSF-approved licenses (e.g., GNU GPL), will be considered on a case-by-case basis to ensure compliance with redistribution requirements.
• Structure: only one extension can be included within an extension folder.
• Debian Packages: Extension images must be built using a Debian package provided by a trusted source like the PostgreSQL Global Development Group (PGDG). This ensures compatibility with the base images and standard package management procedures.
• License inclusion: all necessary license agreements for the extension and its dependencies must be included within the extension folder (refer to the examples in the pgvector and postgis folders).

Submission Process

1. Request and commitment: Open a new issue requesting the extension. The contributor(s) must agree to become "component owners" and maintainers for that extension.
2. Approval: Once approved by maintainers, the component owner(s) will be added to the CODEOWNERS file for the specific folder.
3. Submission: Component owner(s) open a Pull Request (PR) to introduce the new extension. The PR is reviewed, approved, and merged.
4. Naming: The name of the extension is the registry name.

Removal Policy

If component owners decide to stop maintaining their extension, and no other contributors are found, the main project maintainers reserve the right to unconditionally remove that extension.

---

Naming & Tagging Convention

Each extension image tag follows this format:

<extension-name>:<ext_version>-<timestamp>-<pg_version>-<distro>

Example: Building pgvector version 0.8.1 on PostgreSQL 18.0 for the trixie distro, with build timestamp 202509101200, results in:

pgvector:0.8.1-202509101200-18-trixie

For convenience, rolling tags should also be published:

pgvector:0.8.1-18-trixie
pgvector:0.8.1-18-trixie

This scheme ensures:

• Alignment with the upstream postgres-containers base images
• Explicit PostgreSQL and extension versioning
• Multi-distro support

---

Image Labels

Each extension image includes OCI-compliant labels for runtime inspection and tooling integration. These metadata fields enable CloudNativePG and other tools to identify the base PostgreSQL version and OS distribution.

CloudNativePG-Specific Labels

Label	Description	Example
io.cloudnativepg.image.base.name	Base PostgreSQL container image	ghcr.io/cloudnative-pg/postgresql:18-minimal-bookworm
io.cloudnativepg.image.base.pgmajor	PostgreSQL major version	18
io.cloudnativepg.image.base.os	Operating system distribution	bookworm

Standard OCI Labels

In addition to CloudNativePG-specific labels, all images include standard OCI annotations as defined by the OCI Image Format Specification:

Label	Description
org.opencontainers.image.created	Image creation timestamp
org.opencontainers.image.version	Extension version
org.opencontainers.image.revision	Git commit SHA
org.opencontainers.image.title	Human-readable image title
org.opencontainers.image.description	Image description
org.opencontainers.image.source	Source repository URL
org.opencontainers.image.licenses	License identifier

You can inspect these labels using container tools:

# Using docker buildx imagetools
docker buildx imagetools inspect <image> --raw | jq '.annotations'

# Using skopeo
skopeo inspect docker://<image> | jq '.Labels'

Image catalogs

To simplify the deployment of PostgreSQL extensions, this project automatically generates ClusterImageCatalog resources. These catalogs provide a curated list of compatible extension images for PostgreSQL 18+ versions.

• Frequency: Built once a week.
• Location: Published in the artifacts project.
• Naming Convention: These are based on the minimal catalog and use the catalog-extensions prefix (e.g., catalog-extensions-trixie.yaml).