Add docs on removing PVC labels

benjaminjb · andrewlecuyer · commit 0bbe41584a3b · 2022-05-17T09:48:55.000-05:00
When migrating from v4 to v5, some legacy labels
may remain and cause unintended behavior. This PR
adds documentation around that issue and the manual
fix (done manually to avoid PGO having to remove
labels).

Issue [sc-14477]
diff --git a/docs/content/guides/data-migration.md b/docs/content/guides/data-migration.md
@@ -54,7 +54,26 @@ With the above configuration in place, your existing PVC will be used when creat
 
 ## Considerations
 
-- Additional steps are required to set proper file permissions when using certain storage options, such as NFS and HostPath storage due to a known issue with how fsGroups are applied. When migrating from PGO v4, this will require the user to manually set the group value of the pgBackRest repo directory, and all subdirectories, to `26` to match the `postgres` group used in PGO v5. Please see [here](https://github.com/kubernetes/examples/issues/260) for more information.
+### Removing legacy labels
+
+When migrating data volumes from v4 to v5, PGO will add new required labels to the PVCs, but **it will not remove existing labels**. The result is that a PVC might have labels that identify it as both a v4 and a v5 product, which can lead to unintended behavior.
+
+To avoid that, you must manually remove the `pg-cluster` and `vendor` labels, which you can do with a `kubectl` command. For instance, given a cluster named `hippo` with a dedicated pgBackRest repo, the PVC will be `hippo-pgbr-repo`, and the legacy labels can be remove with the below command:
+
+```
+kubectl label pvc hippo-pgbr-repo \
+  pg-cluster- \
+  vendor-
+```
+
+### Proper file permissions for certain storage options
+
+Additional steps are required to set proper file permissions when using certain storage options, such as NFS and HostPath storage due to a known issue with how fsGroups are applied.
+
+When migrating from PGO v4, this will require the user to manually set the group value of the pgBackRest repo directory, and all subdirectories, to `26` to match the `postgres` group used in PGO v5. Please see [here](https://github.com/kubernetes/examples/issues/260) for more information.
+
+### Additional Considerations
+
 - An existing pg_wal volume is not required when the pg_wal directory is located on the same PVC as the pgData directory.
 - When using existing pg_wal volumes, an existing pgData volume **must** also be defined to ensure consistent naming and proper bootstrapping.
 - When migrating from PGO v4 volumes, it is recommended to use the most recently available version of PGO v4.
diff --git a/docs/content/upgrade/v4tov5/upgrade-method-1-data-volumes.md b/docs/content/upgrade/v4tov5/upgrade-method-1-data-volumes.md
@@ -98,6 +98,12 @@ spec:
 
 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.
 
+{{% notice info %}}
+Note that when migrating data volumes from v4 to v5, PGO will add new required labels to the PVCs, but **it will not remove existing labels**. The result is that a PVC might have labels that identify it as both a v4 and a v5 product, which can lead to unintended behavior.
+<br><br>
+To avoid that behavior, follow the instructions in the section on [removing legacy labels]({{< ref "guides/data-migration.md#removing-legacy-labels" >}}).
+{{% /notice %}}
+
 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" >}}).
 
 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:
diff --git a/docs/content/upgrade/v4tov5/upgrade-method-2-backups.md b/docs/content/upgrade/v4tov5/upgrade-method-2-backups.md
@@ -132,7 +132,6 @@ kubectl apply -k examples/postgrescluster
 
 If you wish to protect against this, first remove the reference to the pgBackRest PVC in the PostgresCluster spec:
 
-
 ```
 kubectl patch postgrescluster hippo-pgbr-repo --type='json' -p='[{"op": "remove", "path": "/spec/dataSource/volumes"}]'
 ```
