Image Catalog
=============
.. raw:: html
``ImageCatalog`` and ``ClusterImageCatalog`` are Custom Resource
Definitions (CRDs) that allow you to decouple the PostgreSQL image
lifecycle from the ``Cluster`` definition. By using a catalog, you can
manage image updates centrally; when a catalog entry is updated, all
associated clusters automatically :ref:`roll out the new image ` .
While you can build custom catalogs, CloudNativePG provides
:ref:`CloudNativePG Catalogs ` as ``ClusterImageCatalog`` resources, covering all
official Community PostgreSQL container images.
Catalog scoping
---------------
The primary difference between the two resources is their scope:
.. csv-table::
:header: Resource,Scope,Best use case
:widths: 12,15,20
:align: left
:class: longtable
`ImageCatalog`,Namespaced,Application-specific versions or team-level restrictions.
`ClusterImageCatalog`,Cluster-wide,Global standards across all namespaces for an organization.
Catalog structure
-----------------
Both resources share a common schema:
- **Major versioning**: A list of images keyed by the ``major``
PostgreSQL version.
- **Uniqueness**: The ``major`` field must be unique within a single
catalog.
- **Extensions**: Support for certified extension container images
(available for PostgreSQL 18+ via ``extension_control_path`` ).
.. Warning::
While the operator trusts the user-defined `major` version without performing image detection, the official CloudNativePG catalogs are pre-validated by the community to ensure that every extension and operand image entry correctly matches the declared major version. If you are creating a custom catalog, you must ensure the declared major version matches the actual PostgreSQL images to maintain compatibility.
Configuration examples
----------------------
Defining a catalog
^^^^^^^^^^^^^^^^^^
You can define multiple major versions within a single catalog.
The following example defines a namespaced ``ImageCatalog`` :
.. code:: yaml
apiVersion: postgresql.cnpg.io/v1
kind: ImageCatalog
metadata:
name: postgresql
namespace: default
spec:
images:
- major: 15
image: ghcr.io/cloudnative-pg/postgresql:15.14-system-trixie
- major: 16
image: ghcr.io/cloudnative-pg/postgresql:16.10-system-trixie
- major: 17
image: ghcr.io/cloudnative-pg/postgresql:17.6-system-trixie
- major: 18
image: ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie
The following example defines a cluster-wide ``ClusterImageCatalog`` :
.. code:: yaml
apiVersion: postgresql.cnpg.io/v1
kind: ClusterImageCatalog
metadata:
name: postgresql-global
spec:
images:
- major: 15
image: ghcr.io/cloudnative-pg/postgresql:15.14-system-trixie
- major: 16
image: ghcr.io/cloudnative-pg/postgresql:16.10-system-trixie
- major: 17
image: ghcr.io/cloudnative-pg/postgresql:17.6-system-trixie
- major: 18
image: ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie
Referencing a Catalog in a Cluster
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A ``Cluster`` resource uses the ``imageCatalogRef`` to select its
images:
.. code:: yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
instances: 3
imageCatalogRef:
apiGroup: postgresql.cnpg.io
kind: ClusterImageCatalog # Or ImageCatalog
name: postgresql-global
major: 18
storage:
size: 1Gi
Image Catalog with Image Volume Extensions
------------------------------------------
:ref:`Image Catalog with Image Volume Extensions ` allow you to bundle containers for extensions directly
within the catalog entry:
.. code:: yaml
apiVersion: postgresql.cnpg.io/v1
kind: ImageCatalog
metadata:
name: postgresql
spec:
images:
- major: 18
image: ghcr.io/cloudnative-pg/postgresql:18.3-minimal-trixie
extensions:
- name: foo
image:
reference: # registry path for your `foo` extension image
The ``extensions`` section follows the :ref:`ExtensionConfiguration `
API schema and structure. Clusters referencing an image catalog can load
any of its associated extensions by name.
.. Note::
Refer to the :ref:`documentation of image volume extensions `
for details on the internal image structure, configuration options, and
instructions on how to select or override catalog extensions within a
cluster.
CloudNativePG Catalogs
----------------------
The CloudNativePG project maintains ``ClusterImageCatalog`` manifests
for all supported images.
These catalogs are regularly updated and published in the `artifacts repository `_
.
Each catalog corresponds to a specific combination of image type
(e.g. ``minimal`` ) and Debian release (e.g. ``trixie`` ). It lists the
most up-to-date container images for every supported PostgreSQL major
version.
.. Important::
To ensure maximum security and immutability, all images within official CloudNativePG catalogs are identified by their **SHA256 digests** rather than just tags.
Version Compatibility
^^^^^^^^^^^^^^^^^^^^^
While standard catalogs work with older versions of the operator,
**catalogs containing an ``extensions`` section are only compatible with
CloudNativePG 1.29 or later**. Using a catalog with extension
definitions on an older operator will result in those definitions being
rejected.
Installation and Usage
^^^^^^^^^^^^^^^^^^^^^^
By installing these catalogs, cluster administrators can ensure that
their PostgreSQL clusters are automatically updated to the latest patch
release within a given PostgreSQL major version, for the selected Debian
distribution and image type.
For example, to install the latest catalog for the ``minimal``
PostgreSQL container images on Debian ``trixie`` , run:
.. code:: shell
kubectl apply -f \
https://raw.githubusercontent.com/cloudnative-pg/artifacts/refs/heads/main/image-catalogs/catalog-minimal-trixie.yaml
You can install all the available catalogs by using the
``kustomization`` file present in the ``image-catalogs`` directory:
.. code:: shell
kubectl apply -k https://github.com/cloudnative-pg/artifacts//image-catalogs?ref=main
You can then view all the catalogs deployed with:
.. code:: shell
kubectl get clusterimagecatalogs.postgresql.cnpg.io
Example: Using a Catalog in a Cluster
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To create a cluster that always tracks the latest ``minimal`` image for
PostgreSQL 18 on ``trixie`` , define your ``Cluster`` as follows:
.. code:: yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: angus
spec:
instances: 3
imageCatalogRef:
apiGroup: postgresql.cnpg.io
kind: ClusterImageCatalog
name: postgresql-minimal-trixie
major: 18
storage:
size: 1Gi