Upgrade Method #1: Data Volumes

This upgrade method allows you to migrate from CPK v4 to CPK v5 using the existing data volumes that were created in CPK v4. Note that this is an "in place" migration method: this will immediately move your Postgres clusters from being managed by CPK v4 to being managed by CPK v5. If you wish to have some failsafes in place, please use one of the other migration methods.

Please also note that you will need to perform the cluster upgrade in the same namespace as the original cluster in order for your v5 cluster to access the existing PVCs.

Step 1: Prepare the CPK v4 Cluster for Migration

You will need to set up your CPK v4 Postgres cluster so that it can be migrated to a CPK v5 cluster. The following describes how to set up a CPK v4 cluster for using this migration method.

1. Scale down any existing replicas within the cluster. This will ensure that the primary PVC does not change again prior to the upgrade.

You can get a list of replicas using the pgo scaledown --query command, e.g.:

pgo scaledown hippo --query
Copy

If there are any replicas, you will see something similar to:

Cluster: hippo
REPLICA                 STATUS          NODE ...
hippo                   running         node01 ...
Copy

Scaledown any replicas that are running in this cluser, e.g.:

pgo scaledown hippo --target=hippo
Copy

2. Once all replicas are removed and only the primary remains, proceed with deleting the cluster while retaining the data and backups. You can do this with the --keep-data and --keep-backups flags:

You MUST run this command with the --keep-data and --keep-backups flag otherwise you risk deleting ALL of your data.

pgo delete cluster hippo --keep-data --keep-backups
Copy

3. The PVC for the primary Postgres instance and the pgBackRest repository should still remain. You can verify this with the command below:

kubectl get pvc --selector=pg-cluster=hippo
Copy

This should yield something similar to:

NAME STATUS   VOLUME ...
hippo-jgut        Bound    pvc-a0b89bdb- ...
hippo-pgbr-repo   Bound    pvc-25501671- ...
Copy

A third PVC used to store write-ahead logs (WAL) may also be present if external WAL volumes were enabled for the cluster.

Step 2: Migrate to CPK v5

With the CPK v4 cluster's volumes prepared for the move to CPK v5, you can now create a PostgresCluster custom resource using these volumes. This migration method does not carry over any specific configurations or customizations from CPK v4: you will need to create the specific PostgresCluster configuration that you need.

To complete the upgrade process, your PostgresCluster custom resource MUST include the following:

1. A spec.dataSource.volumes section that points to the PostgreSQL data, PostgreSQL WAL (if applicable) and pgBackRest repository PVCs from the v4 cluster.

For example, using the hippo cluster:

spec:
  dataSource:
    volumes:
      pgDataVolume:
        pvcName: hippo-jgut
        directory: "hippo-jgut"
      pgBackRestVolume:
        pvcName: hippo-pgbr-repo
        directory: "hippo-backrest-shared-repo"
      # Only specify external WAL PVC if enabled in CPK v4 cluster. If enabled
      # in v4, a WAL volume must be defined for the v5 cluster as well.
      # pgWALVolume:
      #  pvcName: hippo-jgut-wal
Copy

Please see the Data Migration section for more details on how to properly populate this section of the spec when migrating from a CPK v4 cluster.

2. If you customized Postgres parameters, you will need to ensure they match in the CPK v5 cluster. For more information, please review the tutorial on customizing a Postgres cluster.

3. Once the PostgresCluster spec is populated according to these guidelines, you can create the PostgresCluster custom resource. For example, if the PostgresCluster you're creating is a modified version of the postgres example in the CPK examples repo, you can run the following command:

kubectl apply -k kustomize/postgres
Copy

Your upgrade is now complete! You should now remove the spec.dataSource.volumes section from your PostgresCluster. For more information on how to use CPK v5, we recommend reading through the CPK v5 tutorial.