Learn Velero - Cross-Cluster Migration

#Introduction

Up to episode 10, your backups and restores were still within "the same world" — the same cluster or the same namespace. Episode 11 removes that limit: moving a workload complete with its data from cluster A to cluster B. This is what makes Velero so beloved: cross-cluster migration without copying YAML manually and without losing volume data.

Think of the two clusters as two houses. The backup on cluster A is "a container with the entire contents of the house". Restore on cluster B is "unloading the container in the new house". The challenge isn't the move — it's making sure the container fits: the shelves (storage class), the rooms (namespace), and the electrical connections (service/ingress) in the new house must match.

#Prerequisites and Preparation

#Shared BSL

The key to migration: both clusters use the same BSL — same bucket, same region, same credentials. The backup is created on cluster A, and cluster B (with Velero installed) will see that backup:

velero backup get
velero backup describe my-backup --details

If the two clusters are on different clouds (AWS → GCP), make sure each plugin is installed and the BSL points to a bucket both clouds can access (e.g. an S3 bucket GCP reads via interop, or vice versa).

#Differences to Note Before Migration

Make a list of differences before restoring so there are no surprises:

• Storage class: gp2 (A) vs gp3 or standard-rwo (B).
• Ingress/Service type: a LoadBalancer will get a new IP/URL.
• Node selector / toleration: cluster B may have different node labels.
• Namespace: usually the same, but can be mapped (--namespace-mappings).

#Migration Workflow

#1. Backup on Cluster A

Before migration, create a final checkpoint — a fresh backup that captures the current state:

velero backup create pre-migration \
  --include-namespaces app \
  --ttl 720h

If the two clusters have different storage classes, choose file-level backup (kopia) so the volume data is portable:

velero backup create pre-migration \
  --include-namespaces app \
  --default-volumes-to-fs-backup

#2. Restore on Cluster B

velero restore create migration-restore \
  --from-backup pre-migration \
  --storage-class-mappings gp2:gp3

--storage-class-mappings gp2:gp3 maps PVCs from cluster A's storage class to cluster B's storage class (a Velero 1.17+ feature).

#3. Verify on Cluster B

kubectl get deploy,pvc -n app
kubectl exec -n app deploy/nginx -- cat /usr/share/nginx/html/index.html
kubectl get svc -n app

Important verification points: pod Running, PVC Bound, and data readable. Note the new Service IP — DNS on cluster A doesn't migrate with you.

#Migration Best Practices

#Validate in Staging First

Don't cut over directly. First restore to a staging namespace on cluster B, verify the data, then restore to the production namespace:

velero restore create staging-test \
  --from-backup pre-migration \
  --namespace-mappings app:app-staging \
  --storage-class-mappings gp2:gp3

This answers the question "will it actually run?" without risk. Once staging is proven, do the final restore to the original namespace.

#Planned Cutover

A production migration usually follows this order:

1. Freeze writes: point traffic to read-only mode or stop, then create a final backup.
2. Restore on cluster B with the correct storage class mapping.
3. Switch traffic (DNS/Ingress) to cluster B.
4. Observe for several hours before decommissioning cluster A.

velero backup create final-cutover --include-namespaces app --default-volumes-to-fs-backup

#Post-Migration Checklist

• All PVCs Bound — not Pending
• Volume data readable (not empty)
• Service/Ingress has a new address and DNS is updated
• Secret/ConfigMap available (pods run without ImagePullBackOff/CreateContainerConfigError errors)
• Old backups still intact on cluster A (don't delete before the observation period ends)

#Closing

Key takeaways:

• Migration = backup on cluster A + restore on cluster B with a shared BSL.
• File-level backup (kopia) is mandatory when storage classes/clouds differ; cloud snapshots only for same-cloud migration.
• --storage-class-mappings gp2:gp3 adapts PVCs on the destination cluster.
• Validate in staging first, then do the final restore; note the new Service IP.
• Post-migration checklist: PVC Bound, data readable, DNS updated, old backups kept temporarily.

In episode 12 next, we summarize everything at a strategic level: Disaster Recovery Plan — defining RPO/RTO, off-site backup to another region, writing the restore runbook, and running DR drills by deleting the cluster and restoring to a new one.