CNPG Extension Images

This repository builds PostgreSQL extension images for CloudNativePG ImageVolume extensions. Images follow the CNPG convention:

• /share/extension contains extension control and SQL files
• /lib contains PostgreSQL shared libraries

The current matrix targets PostgreSQL 18 because CNPG ImageVolume extension loading relies on PostgreSQL 18+ extension_control_path. The matrix is kept as a PostgreSQL-version list so PostgreSQL 19 can be added without changing the repository layout.

Images

Images are published to forge.netserv.fr/azsiaz/cnpg-extension-image/<image>:<version>-pg<major>-<distro> — one repository per extension (the Image column of the table below), plus forge.netserv.fr/azsiaz/cnpg-extension-image/postgres-dev:pg<major>-<distro>. <version> is the SQL extension version (the value \dx reports and the version field of a CNPG Database resource expects).

Every merge to main automatically publishes the images affected by the change (per-directory triage: a Renovate bump of one extension only rebuilds and publishes that extension plus postgres-dev). Alongside the updated stable tag, each publish adds an immutable tag suffixed with a UTC timestamp (<version>-pg<major>-<distro>-YYYYMMDDhhmm). Manually triggered pipeline runs republish the stable tags only (idempotent resync, no new immutable tags).

Use the immutable tag in CloudNativePG manifests. The stable tag is kept as a convenience alias, but Kubernetes image volumes default to IfNotPresent for non-latest tags and CNPG only rolls pods when the cluster/catalog spec changes.

Supported distros:

• bookworm
• trixie

Supported architectures:

• linux/amd64
• linux/arm64

Build

make generate
docker buildx bake

Run the local smoke build and image layout inspection:

make smoke

BuildKit cache is exported to Forgejo container tags named:

forge.netserv.fr/azsiaz/cnpg-extension-image/buildcache:<image>-pg<major>-<distro>

This keeps cache state visible in Forgejo without mixing cache tags with the runtime extension image versions.

Adding Extensions

Extension metadata is the source of truth for generated build files. To add an extension, add a directory containing:

my-extension/
  Dockerfile
  README.md
  metadata.hcl

Then regenerate the derived files:

make generate

This updates:

• docker-bake.override.hcl
• extensions.generated.json
• postgres_dev/Dockerfile
• postgres_dev/postgresql.conf
• postgres_dev/init-extensions.sql

These files are ignored by Git. The generated Bake override is loaded automatically by docker buildx bake, and Woodpecker regenerates it before building or publishing images.

Use metadata.dev for local postgres-dev image behavior. For example, pg_crash is packaged but not preloaded in the dev image:

dev = {
  preload               = false
  create_extension      = false
  postgresql_parameters = false
}

CloudNativePG Usage

shared_preload_libraries is not required by ImageVolume itself. It is required only when an extension needs to be loaded at PostgreSQL startup.

Current versions live in each extension's README (Renovate keeps them up to date there); this table is the index.

Extension	Image	Preload	Usage
hll	hll	No	docs
pg_bigm	pg-bigm	shared_preload_libraries	docs
pg_crash	pg-crash	Only for explicit crash testing	docs
pg_cron	pg-cron	shared_preload_libraries + cron.database_name	docs
pg_fts	pg-fts	No	docs
pg_incremental	pg-incremental	No (needs pg_cron mounted)	docs
pg_ivm	pg-ivm	shared_preload_libraries	docs
pg_jsonschema	pg-jsonschema	No	docs
pg_textsearch	pg-textsearch	shared_preload_libraries	docs
pgaudit	pgaudit	shared_preload_libraries	docs
postgis	postgis-extension	No	docs
timescaledb	timescaledb-oss	shared_preload_libraries	docs
vector	pgvector	No	docs
vectorscale	pgvectorscale	No (needs vector mounted)	docs
wal2json	wal2json	No	docs

Local Docker Compose

For local development outside Kubernetes, build a regular PostgreSQL image that copies the extension artifacts from these ImageVolume images. See Local Docker Compose usage.

References

• CloudNativePG ImageVolume extensions: https://cloudnative-pg.io/docs/1.28/imagevolume_extensions/
• CNPG reference extension images: https://github.com/cloudnative-pg/postgres-extensions-containers
• pg_textsearch: https://github.com/timescale/pg_textsearch
• pg_ivm: https://github.com/sraoss/pg_ivm