Upgrade Method #3: Standby Cluster

This upgrade method allows you to migrate from CPK v4 to CPK v5 by creating a new CPK v5 Postgres cluster in a "standby" mode, allowing it to mirror the CPK v4 cluster and continue to receive data updates in real time. This has the advantage of being able to fully inspect your CPK v5 Postgres cluster while leaving your CPK v4 cluster up and running, thus minimizing downtime when you cut over. The tradeoff is that you will temporarily use more resources while this migration is occurring.

This method only works if your CPK v4 cluster uses S3 or an S3-compatible storage system, or GCS. For more information on standby clusters, please refer to the standby cluster tutorial.

Step 1: Migrate to CPK v5

Create a PostgresCluster custom resource. 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. Configure your pgBackRest to use an object storage system such as S3/GCS. You will need to configure your spec.backups.pgbackrest.repos.volume to point to the backup storage system. For instance, if AWS S3 storage is being utilized, the repo would be defined similar to the following:

spec:
  backups:
    pgbackrest:
      repos:
        - name: repo1
          s3:
            bucket: hippo
            endpoint: s3.amazonaws.com
            region: us-east-1
Copy

Any required secrets or desired custom pgBackRest configuration should be created and configured as described in the backup tutorial.

You will also need to ensure that the “pgbackrest-repo-path” configured for the repository matches the path used by the CPK v4 cluster. The default repository path follows the pattern /backrestrepo/<clusterName>-backrest-shared-repo. Note that the path name here is different than migrating from a PVC-based repository.

Using the hippo Postgres cluster as an example, you would set the following in the spec.backups.pgbackrest.global section:

spec:
  backups:
    pgbackrest:
      global:
        repo1-path: /backrestrepo/hippo-backrest-shared-repo
Copy

2. A spec.standby cluster configuration within the spec that is populated according to the name of pgBackRest repo configured in the spec. For example:

spec:
  standby:
    enabled: true
    repoName: repo1
Copy

3. If you customized other 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.

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

5. Once the standby cluster is up and running and you are satisfied with your set up, you can promote it.

First, you will need to shut down your CPK v4 cluster. You can do so with the following command, e.g.:

pgo update cluster hippo --shutdown
Copy

You can then update your CPK v5 cluster spec to promote your standby cluster:

spec:
  standby:
    enabled: false
Copy

Note: When the v5 cluster is running in non-standby mode, you will not be able to restart the v4 cluster, as that data is now being managed by the v5 cluster.

Once the v5 cluster is up and running, you will need to run the following SQL commands as a PostgreSQL superuser. For example, you can login as the postgres user, or exec into the Pod and use psql:

-- add the managed replication user
CREATE ROLE _crunchyrepl WITH LOGIN REPLICATION;

-- allow for the replication user to execute the functions required as part of "rewinding"
GRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO _crunchyrepl;
GRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO _crunchyrepl;
GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO _crunchyrepl;
GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO _crunchyrepl;
Copy

The above step will be automated in an upcoming release.

Your upgrade is now complete! Once you verify that the CPK v5 cluster is running and you have recorded the user credentials from the v4 cluster, you can remove the old cluster:

pgo delete cluster hippo
Copy

For more information on how to use CPK v5, we recommend reading through the CPK v5 tutorials.