Restore from a backup to a new Kubernetes-based environment

This page covers restoring a backup to a new cluster on a different Kubernetes cluster or environment. For example, if you migrate to another cloud provider or region. For the other restore paths, see Restore scenarios.

Because PVCs are namespace-specific Kubernetes resources tied to a specific Kubernetes cluster, restoring to a different Kubernetes cluster only works from backups stored in cloud storage, such as S3 or Azure. See Restore limitations.

For Operator version 1.17.0 and earlier

When restoring to a new Kubernetes-based environment, make sure it has a Secrets object with the same user passwords as in the source cluster. Find more details about secrets in System Users. Find the name of the required Secrets object in the spec.secretsName key in the deploy/cr.yaml. The default Secret name is cluster1-secrets.

This differs for a point-in-time restore — see Restore limitations.

To restore from a backup, you create a PerconaXtraDBClusterRestore object using a restore configuration file. The example of such file is deploy/backup/restore.yaml. You can check available options in the restore options reference.

Before you start

1. Make sure that the source cluster is running.

2. Find the correct cluster name.

   kubectl get pxc -n <namespace>
   

3. Export the cluster name and the namespace where it is running as environment variables. Replace the cluster1 and <namespace> with your values:

   export CLUSTER=cluster1
   export NAMESPACE=<namespace>
   

4. List backups on the source cluster to retrieve the desired backup name. Replace the <namespace> with your value:

   kubectl get pxc-backup -n $NAMESPACE
   

5. For point-in-time recovery, disable storing binlogs point-in-time functionality on the existing cluster. You must do it regardless of whether you made the backup with point-in-time recovery or without it. Use the following command and replace the cluster name and the <namespace> with your values:

   kubectl patch pxc $CLUSTER \
     -n $NAMESPACE \
     --type merge \
     -p '{"spec":{"backup":{"pitr":{"enabled":false}}}}'
   

Restore from a full backup

To restore from a backup Percona XtraDB Cluster must know where to take the backup from and have access to that storage. See Choose backupName or backupSource for the general rule. A new cluster has no Backup object, so the procedures in this document use backupSource.

You can define the backup storage in two ways: within the restore object configuration or pre-configure it within the target cluster’s Custom Resource manifest.

Approach 1: Define storage configuration in the Restore object

If you haven’t defined storage in the target cluster’s cr.yaml file, you can configure it directly in the restore object.

1. Configure the PerconaXtraDBClusterRestore Custom Resource. Specify the following keys:

   • set spec.pxcCluster key to the name of the target cluster to restore the backup on,

   • configure the spec.backupSource subsection to point to the cloud storage where the backup is stored.

     S3-compatible storageAzure Blob storage

     The spec.backupSource subsection should include:

     • a destination key. Take it from the output of the kubectl get pxc-backup command. The destination consists of the s3:// prefix, the S3 bucket name and the backup name.
     • the necessary storage configuration keys, just like in the deploy/cr.yaml file of the source cluster.
     • verifyTLS to verify the storage server TLS certificate
     • the custom TLS configuration if you use it for backups. Refer to the Configure TLS verification with custom certificates section for more information.

     spec:
       pxcCluster: cluster1
       backupSource:
         verifyTLS: true
         destination: s3://S3-BUCKET-NAME/BACKUP-NAME
         s3:
           bucket: S3-BUCKET-NAME
           credentialsSecret: my-cluster-name-backup-s3
           region: us-west-2
           endpointUrl: https://URL-OF-THE-S3-COMPATIBLE-STORAGE
           caBundle: #If you use custom TLS certificates for S3 storage
             name: minio-ca-bundle
             key: ca.crt
     

     Specify the following keys in the spec.backupSource subsection:

     • The destination key. Take the value from the output of the kubectl get pxc-backup command.
     • The necessary Azure storage configuration keys, just like in the deploy/cr.yaml file of the source cluster.

     spec:
       pxcCluster: cluster1
       backupSource:
         destination: azure://AZURE-CONTAINER-NAME/BACKUP-NAME
         azure:
           container: AZURE-CONTAINER-NAME
           credentialsSecret: my-cluster-azure-secret
           ...
     

2. Start the restore process:

   kubectl apply -f deploy/backup/restore.yaml -n $NAMESPACE
   

Approach 2: Storage is configured on the target cluster

You can already define the storage where the backup is stored in the backup.storages subsection of your target cluster’s deploy/cr.yaml file. In this case, reference it by name within the restore configuration.

1. Configure the PerconaXtraDBClusterRestore Custom Resource. Specify the following keys:

   • set spec.pxcCluster key to the name of the target cluster to restore the backup on

   • specify the storage name in the backupSource.storageName key. The name must match the name in the backup.storages subsection of the deploy/cr.yaml file

   • configure the spec.backupSource subsection with the backup destination

     Here are example configurations:

     S3-compatible storageAzure Blob storage

     spec:
       pxcCluster: cluster1
       backupSource:
         destination: s3://S3-BUCKET-NAME/BACKUP-NAME
         storageName: s3-us-west
     

     spec:
        pxcCluster: cluster1
        backupSource:
          destination: azure://AZURE-CONTAINER-NAME/BACKUP-NAME
          storageName: azure
     

2. Run the restore process:

   kubectl apply -f deploy/backup/restore.yaml -n $NAMESPACE
   

Verify the restore

1. Confirm the Restore object reports Succeeded:

   kubectl get pxc-restore -n $NAMESPACE
   

2. Confirm the cluster reports the ready status:

   kubectl get pxc -n $NAMESPACE
   

3. Spot-check the data you expected the backup to contain, then configure the main storage within the target cluster’s cr.yaml so you can make subsequent backups from the new cluster.

Restore the cluster with point-in-time recovery

See Restore with point-in-time recovery. The storage requirements on this page still apply — PITR to a different Kubernetes cluster needs the binlogs in cloud storage, the same as the full backup.

---

Last update: October 21, 2026
Created: July 4, 2023