Configuring Cluster Images

Crunchy Postgres for Kubernetes installers provide default images to use in your Postgres clusters. These defaults make a patch update to your cluster as easy as upgrading your version of Crunchy Postgres for Kubernetes. To see how this works, let’s take a look at how Crunchy Postgres for Kubernetes determines the images you want to use and how to configure PGO’s defaults when you want to change them.

Specifying a Crunchy Postgres Version

All Crunchy Postgres for Kubernetes installers come with default images defined in PGO’s Pod spec. You can either rely on these defaults or override them by setting image fields manually.

To tell PGO which major version of Crunchy Postgres you want installed in your cluster, you can use a manifest with spec.postgresVersion set to the major version and PGO will use its defaults to fulfill your request, like this:

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
spec:
  postgresVersion: 15
  instances:
    - name: instance1
      dataVolumeClaimSpec:
        accessModes:
        - "ReadWriteOnce"
        resources:
          requests:
            storage: 1Gi
  backups:
    pgbackrest:
      image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbackrest:ubi8-2.45-2
      repos:
      - name: repo1
        volume:
          volumeClaimSpec:
            accessModes:
            - "ReadWriteOnce"
            resources:
              requests:
                storage: 1Gi

In this case, spec.postgresVersion is set to Postgres major version 15. But how does PGO know which version 15 image to pull? PGO knows because its installer provides environment variables during the installation process. A typical installer will include configuration like this:

spec:
  containers:
  - name: operator
    image: postgres-operator
    env:
    - name: RELATED_IMAGE_POSTGRES_15
      value: "registry.developers.crunchydata.com/crunchydata/crunchy-postgres:ubi8-15.3-0"

The spec.postgresVersion field declares a major version which PGO can satisfy by looking at RELATED_IMAGE_POSTGRES_15. So long as the version set by spec.postgresVersion has a corresponding related image, PGO will know what to do. If a required image has not been set, PGO's functionality will be limited and you can expect to see a MissingRequiredImages event.

All PGO installers come with related images for the supported images you can run in your cluster, but you aren't required to use them. Notice that backups.pgbackrest has an image field explicitly set. Setting the image field overrides the related image. To override the default for Crunchy Postgres, you would set spec.image to the specific container image you want, like this:

spec:
  image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres:ubi8-15.3-0
  postgresVersion: 15

In the above case, the image field is set to run Crunchy Postgres 15.3, built on the Red Hat 8 Universal Base Image.

The Postgres minor version, the 3 in 15.3, will increment when security patches and other improvements are added to Postgres. Crunchy Postgres for Kubernetes makes it easy to update your cluster to the latest minor version by giving you the latest supported images in each installer release. Just upgrade Crunchy Postgres for Kubernetes and you’ll update to the latest supported minor versions of your cluster components.

Configuring Installers

While PGO installers ship with preset related image references, you can also customize those settings to point at images of your choosing. Related images can be customized for all installer types, including Kustomize (via manager.yaml), Helm (via values.yaml) and OperatorHub (via spec.config.env in the Subscription).

To configure the image references in your Kustomize installer, look for kustomize/install/manager/manager.yaml to find the related images the operator’s environment variables.

To configure the image references in your Helm installer, look for helm/install/values.yaml.

After Crunchy Postgres for Kubernetes has been installed from OperatorHub, you can edit image references by clicking on Installed Operators and selecting Crunchy Postgres for Kubernetes. From there, select Subscription and from the Actions dropdown menu select Edit Subscription. Scroll to the spec section and you can create a config block to set environment variables like this:

spec:
  config:
    env:
    - name: RELATED_IMAGE_POSTGRES_15
      value: 'registry.developers.crunchydata.com/crunchydata/crunchy-postgres:ubi8-15.3-2'

By specifying a value for RELATED_IMAGE_POSTGRES_15 in the above, we’ve overridden the value that comes from the OperatorHub installation package. After you’ve adjusted the Subscription to meet your needs, save it and observe that the environment variables in your PGO pod have updated.

Special Considerations for Upgrades on OperatorHub

Crunchy Postgres for Kubernetes (CPK) provides an OperatorHub experience with seamless updates for Crunchy Postgres minor versions. Automatic updates to minor Postgres versions are made possible through the list of related images packaged with the Crunchy Postgres for Kubernetes installer. Installing a new version of Crunchy Postgres for Kubernetes will trigger these updates.

Upgrading to a new major version of Crunchy Postgres is not automatic, but related images are still involved. When it's time to upgrade the Crunchy Postgres major version, PGO will run the image defined under RELATED_IMAGE_PGUPGRADE to do the work. The upgrade container holds binaries for different versions of Crunchy Postgres. Successful upgrades depend on the upgrade container holding a binary for the version of Crunchy Postgres you’re presently running, as well as the version of Crunchy Postgres targeted in your upgrade. When you upgrade your installation of Crunchy Postgres for Kubernetes, the newer package will include the latest supported versions of Crunchy Postgres and will not include versions no longer supported.

Note that minor and major version upgrades are only possible for as long as your major version of Crunchy Postgres is supported. This makes it important to perform major upgrades in a timely fashion. If the latest upgrade image does not include your current major version of Crunchy Postgres, a Postgres upgrade might be difficult.