Migrate from Crunchy to Percona Operator for PostgreSQL by reusing persistent volumes¶
This guide shows how to migrate to Percona Operator for PostgreSQL using the primary PostgreSQL data volume from your Crunchy PostgresCluster.
In this approach, Percona PerconaPGCluster (cluster1) starts on the existing PGDATA data directory without running a backup-restore cycle over the network.
| Benefits | Trade-offs |
|---|---|
| - Avoids large data copies through object storage when the persistent volume already contains the dataset. - Provides a direct migration path when it is important to keep the exact data directory intact. - Allows migrating even if the source cluster is deleted but the PV is preserved |
- Downtime occurs from the moment you stop writes on Crunchy until the Percona cluster is brought up. - Rollback is difficult once Percona has advanced the database on that volume; take a Crunchy pgBackRest backup before destructive steps if you may need to restore Crunchy.- Requires manual management of PV reclaim policy, clearing claimRef, and setting a PVC selector to ensure the new claim binds only to the intended volume. |
If the backing PV was already deleted with the default Delete reclaim policy, use Migrate from Crunchy using backup and restore instead.
Versions used in this guide¶
For this migration tutorial, we use the following versions of the Operators:
- Crunchy PostgreSQL Operator 5.8.x
- Percona Operator for PostgreSQL 3.x.x
Before you migrate¶
Complete the Pre-migration compatibility checks. Physical methods require a matching PostgreSQL major version and CPU architecture.
Prerequisites¶
Ensure you have the following:
- A Kubernetes or OpenShift cluster with permissions to patch PersistentVolumes, delete
PostgresClusterresources, and deploy the Percona Operator. kubectloroc.- Storage where you can set the PV reclaim policy to
Retainand clearclaimRef(cluster-admin privileges are often required).
Before you start¶
-
Create or choose namespaces for Crunchy and Percona and export them as the environment variables.
export CRUNCHY_NS=postgres-operator export NAMESPACE=pgo -
Clone the Operator repository to edit the manifests during the migration setup:
git clone -b v3.1.0 https://github.com/percona/percona-postgresql-operator
Deploy Operators¶
-
Install Crunchy Operator for PostgreSQL into
$CRUNCHY_NSif it is not already installed. See the Crunchy quickstart for the steps. -
Install Percona Operator for PostgreSQL into
$NAMESPACE:kubectl apply --server-side \ -f https://raw.githubusercontent.com/percona/percona-postgresql-operator/v3.1.0/deploy/bundle.yaml \ -n "${NAMESPACE}" -
Wait for the Percona Operator Deployment to become available:
kubectl wait deployment percona-postgresql-operator \ -n "${NAMESPACE}" \ --for=condition=Available \ --timeout=120sExpected output
deployment.apps/percona-postgresql-operator condition met
Deploy the Crunchy source cluster¶
If you already have a PostgreSQL cluster running in the Crunchy namespace, make sure it is set up so that only one database server (replica) is running. This means changing the configuration so instances.replicas is set to 1.
If you are deploying Crunchy for testing or migration rehearsal, create it with one Postgres instance (replicas: 1 on the primary set) so a single data PVC represents the primary.
This is the sample PostgresCluster Custom Resource configuration:
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: crunchy-source
spec:
postgresVersion: 18
instances:
- name: instance1
replicas: 1
dataVolumeClaimSpec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
backups:
pgbackrest:
repos:
- name: repo1
volume:
volumeClaimSpec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
proxy:
pgBouncer:
replicas: 1
-
Apply the configuration to create or update the Crunchy PostgreSQL cluster.
-
Wait for the cluster to report the
Readystatus:kubectl wait pod \ -l postgres-operator.crunchydata.com/cluster=crunchy-source,postgres-operator.crunchydata.com/data=postgres \ -n "${CRUNCHY_NS}" \ --for=condition=Ready \ --timeout=300sExpected output
pod/crunchy-source-instance1-gpx4-0 condition met
Stop writes and identify the primary’s Persistent Volume¶
Stop application from writing to the database. This marks the start of downtime.
Next, identify the primary Pod, its data PVC, and backing PV
-
Identify the primary Pod:
CRUNCHY_PRIMARY=$(kubectl get pod -n "${CRUNCHY_NS}" \ --selector postgres-operator.crunchydata.com/cluster=crunchy-source,postgres-operator.crunchydata.com/role=master \ -o jsonpath='{.items[0].metadata.name}') -
Retrieve the PVC:
PVC_NAME=$(kubectl get pod -n "${CRUNCHY_NS}" "${CRUNCHY_PRIMARY}" \ -o jsonpath='{.spec.volumes[?(@.name=="postgres-data")].persistentVolumeClaim.claimName}') -
Retrieve the PV this PVC is bound to:
PV_NAME=$(kubectl get pvc -n "${CRUNCHY_NS}" "${PVC_NAME}" \ -o jsonpath='{.spec.volumeName}') -
Verify the retrieved data:
echo "Primary pod: ${CRUNCHY_PRIMARY}" echo "PVC: ${PVC_NAME}" echo "PV: ${PV_NAME}"Sample output
Primary pod: crunchy-source-instance1-gpx4-0 PVC: crunchy-source-instance1-gpx4-pgdata PV: pvc-32f7bc5d-82c7-4d36-9886-56a581124cbdIf your Crunchy Pod uses a volume name other than
postgres-data, adjust the JSONPath filter.
Retain the PV and remove the Crunchy cluster¶
The default reclaim policy for a dynamically PersistentVolume is Delete. This means that as soon as there are no Persistent Volume Claims (PVC) bound to this PV, Kubernetes deletes it and all data is lost. To prevent this, change the PV reclaim policy to Retain.
-
Set the PV reclaim policy to
Retainso the disk survives PVC deletion:kubectl patch pv "${PV_NAME}" \ -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' -
Patch the Crunchy
PostgresClusterobject to remove finalizers. Kubernetes “finalizers” block resource deletion until certain cleanup steps finish, such as the operator deleting related pods, PVCs, and secrets. Since we want to keep the PersistentVolume (PV) and avoid extra cleanup (like deleting the PV or data), we remove the finalizers to force Kubernetes to delete thePostgresClusterresource immediately. This lets us proceed with detaching the data volume for migration without waiting for the Crunchy Operator’s normal deletion behavior.kubectl patch postgrescluster crunchy-source -n "${CRUNCHY_NS}" \ --type=json \ -p='[{"op":"remove","path":"/metadata/finalizers"}]' -
Now, delete the
PostgresCluster:kubectl delete postgrescluster crunchy-source -n "${CRUNCHY_NS}" -
Uninstall Crunchy Operator from
$CRUNCHY_NSwhen noPostgresClusterresources remain. -
After the data PVC is gone, the PV enters the
Releasedstate. However, it still references the old claim and cannot be claimed by a new PVC. Therefore, you need to clear itsclaimRef:kubectl patch pv "${PV_NAME}" --type=json \ -p='[{"op":"remove","path":"/spec/claimRef"}]' -
Wait until the PV status becomes
Available:kubectl wait pv "${PV_NAME}" \ --for=jsonpath='{.status.phase}'=Available \ --timeout=60sExpected output
persistentvolume/pvc-32f7bc5d-82c7-4d36-9886-56a581124cbd condition met -
Label the PV so the Percona PVC selector binds to it exclusively, avoiding accidental binding to another released volume:
kubectl label pv "${PV_NAME}" percona-pv-migration=migrated
Create the Percona cluster bound to the retained volume¶
-
Edit the
deploy/cr.yamland specify the following settings:- Give a name to your cluster in the
metadata.name(for example,cluster1) - Align
spec.postgresVersionwith the old cluster. - For the first cutover, set one replica on the instance that should attach to the migrated disk
- Add a
selectorondataVolumeClaimSpecmatching the PV label. This ensures the controller binds the PVC to the correct PV that has the specified label.
Here is the example configuration:
apiVersion: pgv2.percona.com/v2 kind: PerconaPGCluster metadata: name: cluster1 spec: crVersion: 3.1.0 postgresVersion: 18 instances: - name: instance1 replicas: 1 dataVolumeClaimSpec: accessModes: - ReadWriteOnce resources: requests: storage: 10Gi selector: matchLabels: percona-pv-migration: migrated backups: pgbackrest: repos: - name: repo1 volume: volumeClaimSpec: accessModes: - ReadWriteOnce resources: requests: storage: 10GiTune
storage,storageClassName, and other fields to match your environment and the Operator’s usualdeploy/cr.yamlrequirements (users, images, resources). - Give a name to your cluster in the
-
Apply the manifest:
kubectl apply -f deploy/cr.yaml -n "${NAMESPACE}"The Percona Operator creates a PersistentVolumeClaim (PVC) using the selector you specified in the manifest. This PVC binds to the labelled PersistentVolume (PV) that contains the migrated PostgreSQL data. PostgreSQL then starts directly on the existing
PGDATAdirectory, so no backup restore, WAL download, or object storage is needed.By default,
pgBackRestuses a local, PVC-backed repository (repo1.volume) for backups and restores, so you do not need to configure S3 credentials or external storage for this migration path (unless you choose to use S3 for backups). -
Wait for the cluster to have the
Readystatus:kubectl wait perconapgcluster/cluster1 \ -n "${NAMESPACE}" \ --for=jsonpath='{.status.state}'=ready \ --timeout=600sExpected output
perconapgcluster.pgv2.percona.com/cluster1 condition met -
Verify that the data is intact by checking the primary pod state:
- Identify the primary pod:
PERCONA_PRIMARY=$(kubectl get pod -n "${NAMESPACE}" \ --selector postgres-operator.crunchydata.com/cluster=cluster1,postgres-operator.crunchydata.com/role=primary \ -o jsonpath='{.items[0].metadata.name}')- Check the primary pod state:
kubectl -n "${NAMESPACE}" exec "${PERCONA_PRIMARY}" -c database -- \ psql -t -c "SELECT pg_is_in_recovery();"Expect
ffor a writable primary.
Scale out the cluster¶
You started the cluster with a single replica, so the Operator created a PersistentVolumeClaim (PVC) that bound to your labelled PersistentVolume (PV) containing the migrated data. Once you have confirmed that the primary instance is healthy, scale out your cluster for high availability.
While the selector is present in the cluster configuration, it blocks the Operator to create new replica PVCs because no other PV carries percona-pv-migration=migrated. Therefore, you need to remove the selector. Doing so enables the Operator to create new PVCs for each replica using your default StorageClass.
-
Update the cluster configuration by removing the selector and increasing the number of replicas:
kubectl patch perconapgcluster cluster1 \ --namespace "${NAMESPACE}" \ --type=json \ -p='[ {"op":"remove","path":"/spec/instances/0/dataVolumeClaimSpec/selector"}, {"op":"replace","path":"/spec/instances/0/replicas","value":3} ]' -
Wait for the cluster to report the
Readystatus:kubectl wait perconapgcluster/cluster1 \ --namespace "${NAMESPACE}" \ --for=jsonpath='{.status.state}'=ready \ --timeout=300sExpected output
perconapgcluster.pgv2.percona.com/cluster1 condition met
Take a post-migration backup¶
Create a new baseline for further point-in-time restores by making a full backup. You can reuse the volume-based backup repository, such as repo1, that this guide uses to keep local backups on persistent storage within your cluster. Or see Configure backup storage to stream backups there.
-
Edit the
deploy/backup.yaml. This example configures backups to a volume-based backup repository following the cluster configuration in this guide:deploy/backup.yamlapiVersion: pgv2.percona.com/v2 kind: PerconaPGBackup metadata: name: post-migration-backup spec: pgCluster: cluster1 repoName: repo1 -
Apply the configuration to start a backup:
kubectl apply -f deploy/backup.yaml -n "${NAMESPACE}" -
Wait for the backup Job to complete:
kubectl wait perconapgbackup/post-migration-backup \ -n "${NAMESPACE}" \ --for=jsonpath='{.status.state}'=Succeeded \ --timeout=600s
Point applications to Percona¶
-
Discover the
pgBouncerService forcluster1:kubectl get service -n "${NAMESPACE}" \ -l postgres-operator.crunchydata.com/cluster=cluster1,postgres-operator.crunchydata.com/role=pgbouncer -
Update your application’s connection string to use the
pgBouncerservice name (from the previous step) as the PostgreSQL host. For example:Host: cluster1-pgbouncer.$NAMESPACE.svc.cluster.local Port: 5432
Replace ${NAMESPACE} with your cluster’s namespace. Update your application configuration to point to this service, ensuring it now connects to your Percona Operator for PostgreSQL deployment.
Cleanup¶
Remove the migration label from the PV after you no longer need to pin binding:
kubectl label pv "${PV_NAME}" percona-pv-migration-
Rollback¶
PV reuse is the least rollback-friendly path: once cluster1 runs on the old directory, the previous Crunchy timeline is no longer authoritative. If you need a fallback, take a full Crunchy pgBackRest backup before you delete crunchy-source, and treat that backup as your recovery source for a new Crunchy deployment.
Troubleshooting¶
PVC stays Pending¶
Confirm the PV label and phase:
kubectl get pv "${PV_NAME}" --show-labels
kubectl get pv "${PV_NAME}" -o jsonpath='{.status.phase}{"\n"}'
PostgreSQL fails to start¶
Inspect database container logs:
kubectl -n "${NAMESPACE}" logs "${PERCONA_PRIMARY}" -c database
Unclean shutdowns may require crash recovery; follow Patroni and PostgreSQL logs for progress.
PV was deleted¶
If the dynamic provisioner deleted the volume when the PVC disappeared, data is gone from that path. Use Migrate from Crunchy using backup and restore from your latest remote backup instead.
Created: May 22, 2026