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_path feature)
  • 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 expr and 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: 18

For 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.