Get started
Configure alerts, install the catalog, and enable extensions in your databases.
Requirements
- CloudNativePG ≥ 1.29 (extension image catalog support)
- PostgreSQL ≥ 18 (requires the
extension_control_pathfeature) - Kubernetes 1.33+ (enable ImageVolume explicitly on 1.33 and 1.34; enabled by default on 1.35+)
- Container runtime with ImageVolume support: containerd 2.1+ or CRI-O 1.31+
See the CNPG requirements.
1. Set up alerts
Configure and test extension-update alerts before installing the catalog. Alerts remind you to run ALTER EXTENSION … UPDATE when needed.
Configure email alerts and test delivery before installing the catalog. With CNPG metrics scraped by Prometheus, use:
max by (namespace, cluster, datname, extname, installed_version, default_version) (
cnpg_pg_extensions_update_available
) == 1
- Grafana email alert: alert on values above zero and route to an email contact point. Self-hosted Grafana needs SMTP configured.
- Prometheus + Alertmanager email: use the query as the alert rule's
exprand route to an email receiver. - Grafana dashboard: use an instant table showing cluster, database, extension, installed version and default version; pair it with email alerts.
Image updates supply binaries and scripts but can leave SQL upgrades pending.
When alerted, review the extension's upgrade instructions and path, then set the
target version in Database.spec.extensions or run ALTER EXTENSION ... UPDATE
in each affected SQL-managed database. Verify the installed version and that the
alert clears. See CNPG extension management.
2. Install the catalog with automatic updates
Change schedule and timeZone to your weekly maintenance window. Apply the
ServiceAccount/RBAC, then the CronJob in default. Its first run installs the
catalog; later runs refresh it. CNPG rolls out changed PostgreSQL and selected
extension images to referencing Clusters, keeping their PostgreSQL major version.
ServiceAccount and RBAC: apply before the CronJob
Allow catalog creation and read/patch access to postgresql-minimal-trixie.
Kubernetes RBAC cannot restrict create by resource name. If changing the
namespace or catalog, update the names consistently.
apiVersion: v1
kind: ServiceAccount
metadata:
name: catalog-updater
namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: catalog-updater
rules:
- apiGroups: ["postgresql.cnpg.io"]
resources: ["clusterimagecatalogs"]
verbs: ["create"]
- apiGroups: ["postgresql.cnpg.io"]
resources: ["clusterimagecatalogs"]
resourceNames: ["postgresql-minimal-trixie"]
verbs: ["get", "patch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: catalog-updater
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: catalog-updater
subjects:
- kind: ServiceAccount
name: catalog-updater
namespace: default
CronJob YAML: set your weekly maintenance window
The example runs Tuesdays at 10 PM Los Angeles time, adjusting for daylight saving. The schedule sets a start time, not a rollout deadline, and does not prevent changes by other controllers or administrators.
apiVersion: batch/v1
kind: CronJob
metadata:
name: update-catalog
spec:
schedule: "0 22 * * 2"
timeZone: America/Los_Angeles
jobTemplate:
spec:
template:
spec:
serviceAccountName: catalog-updater
restartPolicy: OnFailure
containers:
- name: kubectl
image: alpine/kubectl:latest
command: [kubectl, apply, -f, https://raw.githubusercontent.com/cnpg-extensions/artifacts/main/image-catalogs-extensions/catalog-minimal-trixie.yaml]
Catalog changes to only environment variables or library paths do not trigger a rollout and may need an explicit restart. See CNPG runtime caveats .
For immediate installation, start a Job from the CronJob. Use a new Job name for later manual refreshes; scheduled runs continue.
kubectl create job --from=cronjob/update-catalog update-catalog-initial -n default
The CNPG Extensions catalog
is a drop-in replacement for upstream postgresql-minimal-trixie, with additional
extensions. See CNPG's catalog documentation
and the extension READMEs for usage.
New extension versions are automatically detected and rebuilt, typically appearing in the CNPG Extensions catalog in less than 30 minutes.
Signed containers built upstream by CloudNativePG are directly referenced by this catalog rather than being rebuilt. Updates to those containers (including core Postgres database patches) are reflected in this catalog within 24 hours.
3. Add an extension to your cluster
Browse the catalog and open an extension’s documentation. Follow its Cluster example to enable the extension image, including any preload settings or required dependencies. Keep your existing instance and storage configuration, and reference the installed catalog:
imageCatalogRef:
apiGroup: postgresql.cnpg.io
kind: ClusterImageCatalog
name: postgresql-minimal-trixie
major: 18For a new installation, first follow the CloudNativePG quick start to install the operator and create a database cluster.
4. Enable it in a database
Making an extension image available to the cluster does not install it into every database. You can enable an extension declaratively with a CloudNativePG Database resource, or run CREATE EXTENSION through SQL. The extension’s README provides its exact SQL name and any setup requirements.
Platform teams can make extension containers available by default while letting users enable only the extensions their databases need. For extensions that normally require superuser privileges, pgextwlist allows administrators to approve a selection for non-superuser installation.
Check: verify the installed extension with \dx in psql, and keep the update alerts configured in step 1. After container updates, use the extension’s supported SQL upgrade path where needed.
