PostgresCluster API Upgrade

With the release of v6.0, we also released the v1 version of our PostgresCluster API. This new version of the API signifies both the maturity and production-readiness of the PostgresCluster API, and comes with a variety of important updates and enhancements. It is therefore recommended that you upgrade to the v1 API at your earliest convenience.

If you are starting fresh with v6.0, you will be using the v1 API by default, unless you change the version in your PostgresCluster manifests. However, if you have upgraded PGO from an earlier version, your PostgresClusters will be using the v1beta1 API until you update the apiVersion in your PostgresCluster manifests.

Upgrading the PostgresCluster API version

To upgrade your PostgresClusters, you should start by changing the apiVersion in your manifest:

apiVersion: postgres-operator.crunchydata.com/v1
kind: PostgresCluster
metadata:
  name: hippo
spec:
  postgresVersion: 17
  ...
Copy

It is then generally a good idea to do a "dry-run" before attempting to apply. By doing a server-side dry-run, we can see how the API server would respond to applying the object, without actually persisting the resource. The command to do this would look like:

kubectl apply -k kustomize/postgres --dry-run='server'
Copy

Depending on what you have in your manifest and what is allowed in the API version you are attempting to use, you might see a failure, a warning, or a clean response. For example, in the v1 API, the spec.userInterface field still exists, but has been deprecated via validation rules (if you want to deploy pgAdmin, use the dedicated pgAdmin API!). If you were to create a brand new v1 PostgresCluster with spec.userInterface in place, the apply will fail, which would look like this:

The PostgresCluster "hippo" is invalid: spec.userInterface: Invalid value: "object": userInterface not available in v1
Copy

However, if you have an existing v1beta1 cluster with spec.userInterface, and you upgrade it to v1, you will see a warning instead, due to validation ratcheting:

Warning: spec.userInterface: Invalid value: "object": userInterface not available in v1
postgrescluster.postgres-operator.crunchydata.com/hippo configured (server dry run)
Copy

After you have reviewed and addressed all errors and warnings, remove the dry-run flag from the command:

kubectl apply -k kustomize/postgres
Copy

For more information on CRD versioning, validation, and ratcheting, see the Kubernetes documentation.