|
| 1 | +--- |
| 2 | +title: "Upgrade Method #1: Data Volumes" |
| 3 | +date: |
| 4 | +draft: false |
| 5 | +weight: 10 |
| 6 | +--- |
| 7 | + |
| 8 | +{{% notice info %}} |
| 9 | +Before attempting to upgrade from v4.x to v5, please familiarize yourself with the [prerequisites]({{< relref "upgrade/v4tov5/_index.md" >}}) applicable for all v4.x to v5 upgrade methods. |
| 10 | +{{% /notice %}} |
| 11 | + |
| 12 | +This upgrade method allows you to migrate from PGO v4 to PGO v5 using the existing data volumes that were created in PGO v4. Note that this is an "in place" migration method: this will immediately move your Postgres clusters from being managed by PGO v4 and PGO 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. |
| 13 | + |
| 14 | +### Step 1: Prepare the PGO v4 Cluster for Migration |
| 15 | + |
| 16 | +You will need to set up your PGO v4 Postgres cluster so that it can be migrated to a PGO v5 cluster. The following describes how to set up a PGO v4 cluster for using this migration method. |
| 17 | + |
| 18 | +1. Scale down any existing replicas within the cluster. This will ensure that the primary PVC does not change again prior to the upgrade. |
| 19 | + |
| 20 | +You can get a list of replicas using the `pgo scaledown --query` command, e.g.: |
| 21 | +``` |
| 22 | +pgo scaledown hippo --query |
| 23 | +``` |
| 24 | + |
| 25 | +If there are any replicas, you will see something similar to: |
| 26 | + |
| 27 | +``` |
| 28 | +Cluster: hippo |
| 29 | +REPLICA STATUS NODE ... |
| 30 | +hippo running node01 ... |
| 31 | +``` |
| 32 | + |
| 33 | +Scaledown any replicas that are running in this cluser, e.g.: |
| 34 | + |
| 35 | +``` |
| 36 | +pgo scaledown hippo --target=hippo |
| 37 | +``` |
| 38 | + |
| 39 | +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 `--keep-data` and `--keep-backups` flags: |
| 40 | + |
| 41 | +**You MUST run this command with the `--keep-data` and `--keep-backups` flag otherwise you risk deleting ALL of your data.** |
| 42 | + |
| 43 | +``` |
| 44 | +pgo delete cluster hippo --keep-data --keep-backups |
| 45 | +``` |
| 46 | + |
| 47 | +3\. The PVC for the primary Postgres instance and the pgBackRest repository should still remain. You can verify this with the command below: |
| 48 | + |
| 49 | +``` |
| 50 | +kubectl get pvc --selector=pg-cluster=hippo |
| 51 | +``` |
| 52 | + |
| 53 | +This should yield something similar to: |
| 54 | + |
| 55 | +``` |
| 56 | +NAME STATUS VOLUME ... |
| 57 | +hippo-jgut Bound pvc-a0b89bdb- ... |
| 58 | +hippo-pgbr-repo Bound pvc-25501671- … |
| 59 | +``` |
| 60 | + |
| 61 | +A third PVC used to store write-ahead logs (WAL) may also be present if external WAL volumes were enabled for the cluster. |
| 62 | + |
| 63 | +### Step 2: Migrate to PGO v5 |
| 64 | + |
| 65 | +With the PGO v4 cluster's volumes prepared for the move to PGO v5, you can now create a [`PostgresCluster`]({{< relref "references/crd.md" >}}) custom resource using these volumes. This migration method does not carry over any specific configurations or customizations from PGO v4: you will need to create the specific `PostgresCluster` configuration that you need. |
| 66 | + |
| 67 | +{{% notice warning %}} |
| 68 | + |
| 69 | +Additional steps are required to set proper file permissions when using certain storage options, |
| 70 | +such as NFS and HostPath storage, due to a known issue with how fsGroups are applied. When |
| 71 | +migrating from PGO v4, this will require the user to manually set the group value of the pgBackRest |
| 72 | +repo directory, and all subdirectories, to `26` to match the `postgres` group used in PGO v5. |
| 73 | +Please see [here](https://github.com/kubernetes/examples/issues/260) for more information. |
| 74 | + |
| 75 | +{{% /notice %}} |
| 76 | + |
| 77 | +To complete the upgrade process, your `PostgresCluster` custom resource **MUST** include the following: |
| 78 | + |
| 79 | +1\. A `volumes` data source that points to the PostgreSQL data, PostgreSQL WAL (if applicable) and pgBackRest repository PVCs identified in the `spec.dataSource.volumes` section. |
| 80 | + |
| 81 | +For example, using the `hippo` cluster: |
| 82 | + |
| 83 | +``` |
| 84 | +spec: |
| 85 | + dataSource: |
| 86 | + volumes: |
| 87 | + pgDataVolume: |
| 88 | + pvcName: hippo-jgut |
| 89 | + directory: "hippo-jgut" |
| 90 | + pgBackRestVolume: |
| 91 | + pvcName: hippo-pgbr-repo |
| 92 | + directory: "hippo-backrest-shared-repo" |
| 93 | + # Only specify external WAL PVC if enabled in PGO v4 cluster. If enabled |
| 94 | + # in v4, a WAL volume must be defined for the v5 cluster as well. |
| 95 | + # pgWALVolume: |
| 96 | + # pvcName: hippo-jgut-wal |
| 97 | +``` |
| 98 | + |
| 99 | +Please see the [Data Migration]({{< relref "guides/data-migration.md" >}}) section of the [tutorial]({{< relref "tutorial/_index.md" >}}) for more details on how to properly populate this section of the spec when migrating from a PGO v4 cluster. |
| 100 | + |
| 101 | +2\. If you customized Postgres parameters, you will need to ensure they match in the PGO v5 cluster. For more information, please review the tutorial on [customizing a Postgres cluster]({{< relref "tutorial/customize-cluster.md" >}}). |
| 102 | + |
| 103 | +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](https://github.com/CrunchyData/postgres-operator-examples/tree/main/kustomize/postgres) in the [PGO examples repo](https://github.com/CrunchyData/postgres-operator-examples), you can run the following command: |
| 104 | + |
| 105 | +``` |
| 106 | +kubectl apply -k examples/postgrescluster |
| 107 | +``` |
| 108 | + |
| 109 | +Your upgrade is now complete! You should now remove the `spec.dataSource.volumes` section from your `PostgresCluster`. For more information on how to use PGO v5, we recommend reading through the [PGO v5 tutorial]({{< relref "tutorial/_index.md" >}}). |
0 commit comments