How to back up a Kubernetes cluster with Velero

What Velero backs up

Each backup has two parts. Kubernetes objects, from Deployments to Secrets and PersistentVolumeClaims, are read through the Kubernetes API and uploaded to your bucket as a tarball. Volume data is handled in one of three ways:

On a self-managed cluster without a snapshot-capable CSI driver, File System Backup is the practical choice, and it keeps volume data in the same bucket. The examples below use it.

Install the CLI

The velero CLI runs on your workstation and uses your kubeconfig, like kubectl. On Linux, download the release and its checksums, verify, and install:

curl -fsSLO https://github.com/velero-io/velero/releases/download/v1.18.4/velero-v1.18.4-linux-amd64.tar.gz

curl -fsSLO https://github.com/velero-io/velero/releases/download/v1.18.4/CHECKSUM

sha256sum --check --ignore-missing CHECKSUM

tar -xvf velero-v1.18.4-linux-amd64.tar.gz

sudo install velero-v1.18.4-linux-amd64/velero /usr/local/bin/velero

velero version --client-only

Use arm64 in the file names on ARM machines. On macOS, brew install velero installs it.

Prepare the bucket and credentials

Velero needs a private bucket, ideally one per cluster, and an access key that can read, write, list and delete objects in it. S3-compatible services work through the AWS plugin. To create a bucket and key, see the guides for AWS S3, Cloudflare R2, Backblaze B2, Wasabi and DigitalOcean Spaces.

[default]
aws_access_key_id=YOUR_ACCESS_KEY_ID
aws_secret_access_key=YOUR_SECRET_ACCESS_KEY

velero install stores this file in a Secret named cloud-credentials in the velero namespace. Keep the keys somewhere safe outside the cluster: restoring into a new cluster needs them.

Install Velero in the cluster

velero install targets your current kubectl context, so check it with kubectl config current-context first. Then:

velero install \
  --provider aws \
  --plugins velero/velero-plugin-for-aws:v1.14.4 \
  --bucket my-cluster-backups \
  --prefix prod \
  --secret-file ./credentials-velero \
  --backup-location-config region=us-east-1,s3ForcePathStyle="true",s3Url=https://s3.example.com \
  --use-volume-snapshots=false \
  --use-node-agent \
  --wait

• --provider aws selects the AWS object store plugin, which speaks the S3 API.
• --plugins is the plugin image. Plugin v1.14.x pairs with Velero v1.18.x; check the compatibility table in the plugin's README when you upgrade.
• --bucket is the bucket. --prefix is optional and puts everything under a folder, so several clusters can share one bucket.
• --secret-file is the credentials file above.
• --backup-location-config holds the S3 settings: the region, your provider's endpoint as s3Url, and s3ForcePathStyle="true" for path-style URLs, which self-hosted services such as MinIO need.
• --use-volume-snapshots=false skips the snapshot location, since this setup copies files instead.
• --use-node-agent installs the node-agent DaemonSet that File System Backup needs.
• --wait returns only when the Velero deployment is ready.

On AWS itself, drop s3Url and s3ForcePathStyle. To use EBS snapshots there, replace --use-volume-snapshots=false with --snapshot-location-config region=us-east-1.

Check that the pods run and that Velero can reach the bucket:

kubectl -n velero get pods

velero backup-location get

The PHASE column must say Available. Unavailable means the bucket, endpoint, region or keys are wrong, and kubectl -n velero logs deployment/velero says which.

Choose which volumes to copy

File System Backup copies only the pod volumes you select. There are two ways to select them:

• Opt-in, the default: annotate pods with backup.velero.io/backup-volumes and the names of the volumes to copy, as written in the pod spec.
• Opt-out: add --default-volumes-to-fs-backup to velero backup create, or to velero install to make it the default. Every pod volume is copied except service account tokens, Secrets, ConfigMaps, hostPath volumes, and volumes you list in backup.velero.io/backup-volumes-excludes.

An annotation added to a running pod disappears when its Deployment or StatefulSet replaces the pod, so put it in the pod template. Changing the template restarts the pods:

spec:
  template:
    metadata:
      annotations:
        backup.velero.io/backup-volumes: data

For a database, add a pre-backup hook that writes a dump into the volume, so Velero copies a clean file alongside the live data files. The command is a JSON array and runs without a shell unless you start one, and hooks time out after 30 seconds unless you set a timeout:

spec:
  template:
    metadata:
      annotations:
        backup.velero.io/backup-volumes: data
        pre.hook.backup.velero.io/container: postgres
        pre.hook.backup.velero.io/command: '["/bin/sh", "-c", "pg_dump -U postgres -Fc -f /var/lib/postgresql/data/velero.dump postgres"]'
        pre.hook.backup.velero.io/timeout: 10m

Back up

velero backup create shop-first --include-namespaces shop --default-volumes-to-fs-backup --wait

• shop-first is the backup's name.
• --include-namespaces shop limits the backup to one namespace. Leave it out to back up all namespaces and cluster-scoped objects; --exclude-namespaces skips the ones you list.
• With a namespace filter, cluster-scoped objects such as StorageClasses and ClusterRoles are left out, apart from related ones like the PersistentVolumes of included claims. Add --include-cluster-resources=true to include every cluster-scoped object.
• --default-volumes-to-fs-backup copies every pod volume. Leave it out if you annotate instead.
• --wait blocks until the backup finishes.

Then check it:

velero backup describe shop-first --details

Look for Phase: Completed; PartiallyFailed means some items or volumes failed. The pod volume backups section lists each volume Kopia copied, so a volume missing there was never selected. velero backup logs shop-first prints the full log. Both commands fetch from the bucket through temporary signed URLs, so your machine must be able to reach the bucket's endpoint.

Schedule backups with retention

velero schedule create shop-daily --schedule="0 3 * * *" --include-namespaces shop --default-volumes-to-fs-backup --ttl 168h0m0s

• --schedule takes a five-field cron expression in UTC, here 03:00 daily. @every 6h also works, and CRON_TZ=Europe/Berlin 0 3 * * * sets a time zone.
• --ttl 168h0m0s keeps each backup for seven days; the default is 30 days. Expired backups are deleted from the bucket with their snapshots, and File System Backup data is cleared later by repository maintenance.
• The velero backup create filters work here too.

Scheduled backups are named after the schedule plus a timestamp, such as shop-daily-20261003030000. Trigger one now to test the schedule, then list your schedules:

velero backup create --from-schedule shop-daily

velero schedule get

Restore

Velero never overwrites what is in the cluster: existing objects are skipped, and ServiceAccounts are merged. To test a backup on a live cluster, restore into a new namespace:

velero restore create shop-test --from-backup shop-first --namespace-mappings shop:shop-restore-test --wait

--namespace-mappings old:new renames the namespace on the way in. Claims are created fresh and provisioned by their StorageClass, and an init container holds each pod until its data is copied back. Check the result, then delete the test namespace:

velero restore describe shop-test --details

Look for Phase: Completed and read the warnings and errors; already exists only means an object was skipped. velero restore logs shop-test has the full log.

For a real recovery, delete the broken namespace, then restore it:

kubectl delete namespace shop

velero restore create --from-backup shop-first --wait

--from-schedule shop-daily restores a schedule's latest successful backup instead. --include-namespaces and --include-resources restore part of a backup, and --existing-resource-policy=update updates existing objects instead of skipping them, on a best-effort basis.

Restore into a new cluster

Point kubectl at the new cluster and run the same velero install command, with the same bucket, prefix, credentials, plugin and namespace. Then make the location read-only, so the new cluster cannot delete or add backups while you work:

kubectl patch backupstoragelocation default --namespace velero --type merge --patch '{"spec":{"accessMode":"ReadOnly"}}'

Velero syncs the backup list from the bucket every minute. When velero backup get shows your backup, restore it with velero restore create --from-backup as above. Patch accessMode back to ReadWrite once the new cluster takes over.

If the new cluster's StorageClasses have different names, restored claims stay Pending. Map old names to new ones before restoring, with a ConfigMap in the velero namespace; the labels must be exactly these:

apiVersion: v1
kind: ConfigMap
metadata:
  name: change-storage-class-config
  namespace: velero
  labels:
    velero.io/plugin-config: ""
    velero.io/change-storage-class: RestoreItemAction
data:
  local-path: do-block-storage

kubectl apply -f change-storage-class.yaml

The new cluster must run the same Kubernetes version or newer. Cloud snapshots cannot move between providers, or between regions with the AWS and Azure plugins; File System Backup data can, because it lives in the bucket. If you set your own repository password, set the same one here before restoring.

Common errors

Frequently asked questions

Does Velero back up etcd?

No. Velero reads objects through the Kubernetes API and handles volume data with snapshots or File System Backup. It does not copy etcd's data files.

How long does Velero keep backups?

30 days by default. Set --ttl on velero backup create or velero schedule create, for example --ttl 168h0m0s for seven days.

Can I restore a Velero backup to a different cluster?

Yes. Install Velero in the new cluster against the same bucket and prefix, wait for the backup list to sync, and run velero restore create. The new cluster needs the same Kubernetes version or newer.

Is Velero's file system backup safe for databases?

Not on its own. It copies live files, so a database can be caught mid-write. Add a pre-backup hook that dumps the database into the volume, or use snapshots.

Does Velero work with S3-compatible storage?

Yes, through the AWS plugin with s3Url and region in the location config. Velero's docs say these services are reported working by users, not tested regularly by the Velero team.