VM Backup and Restore

This guide backs up a virtual machine to S3-compatible object storage and restores it as a new VM. Every step shows the dashboard first, then the equivalent YAML for kubectl.

Running KubeV inside a KDP project? Read VM Backups and Restores in KDP instead: the steps are the same, but the restore and the endpoint rules differ.

Before you start

• A cluster installed with kubermatic-virtualization apply. The installer enables KubeVirt snapshots and installs the snapshot controller, so a running VM can be backed up on Longhorn storage. On other storage, add a VolumeSnapshotClass for your CSI driver, or stop the VM before backing it up.
• An S3-compatible bucket and an access key for it: AWS S3, MinIO, Ceph RGW or similar.
• A VM with at least one disk backed by a DataVolume. VMs created in the dashboard qualify. Container disks are left out of a backup, and a disk that references a PersistentVolumeClaim directly cannot be backed up.

All three live in the VM’s namespace. A backup can only use a target in its own namespace. The three pages sit under Data Protection in the sidebar.

Step 1: Create a backup target

Go to Data Protection > Backup Targets and choose New Backup Target.

The target turns Ready once its Secret is found; a target whose Secret is missing turns Failed and is checked again every five minutes. KubeV checks the target’s settings, not the bucket: a wrong key or bucket name shows up when the first backup runs.

The same with YAML

apiVersion: v1
kind: Secret
metadata:
  name: prod-backups-creds
  namespace: kubermatic-virtualization
stringData:
  accessKeyId: AKIAEXAMPLE
  secretKey: example-secret
---
apiVersion: virtualization.k8c.io/v1alpha1
kind: BackupStorageLocation
metadata:
  name: prod-backups
  namespace: kubermatic-virtualization
spec:
  provider: s3
  bucket: kubev-backups
  endpoint: https://s3.example.com:9000
  region: us-east-1
  prefix: vms
  credentialsSecretRef: prod-backups-creds

kubectl get backupstoragelocations -n kubermatic-virtualization

Private certificate authorities

An https endpoint signed by a private CA needs two settings, because backups and restores take different paths:

• Backups upload with the cluster’s trusted CAs only. Turn on Skip TLS verification.
• Restores import through CDI, which cannot skip verification. Put the CA certificate in a ConfigMap in the target’s namespace and name it in spec.caBundleConfigMapRef, with Edit YAML on the target or kubectl.

A target that skips verification without a CA bundle can be backed up to, but not restored from. Plain http endpoints need neither.

Step 2: Back up a VM

Open the VM, switch to its Backups tab and choose Create Backup. The VM’s actions menu offers it too.

Pick a Backup Target in the VM’s namespace, keep or change the Backup Name (at most 50 characters) and choose Start Backup.

The backup shows Pending or Provisioning while it runs, then Ready or Failed. Both are final: to retry a failed backup, delete it and create a new one. Follow it on the VM’s Backups tab or under Data Protection > VM Backups.

What KubeV does:

1. Saves the VM’s definition, so a restore can rebuild the VM.
2. Reads the disks from a volume snapshot when every disk’s storage supports snapshots. The VM keeps running. Otherwise it reads the disks directly, and the VM must be stopped.
3. Streams each disk, compressed, to <prefix>/<namespace>/<backup name>/ in the bucket, next to a manifest.yaml of the VM.

Open a backup to see its message, the uploaded volumes with their sizes, the names of its snapshot, export and manifest object, and the events of the run. The upload must finish within an hour.

The same with YAML

apiVersion: virtualization.k8c.io/v1alpha1
kind: VMBackup
metadata:
  name: web-01-20261019
  namespace: kubermatic-virtualization
spec:
  vmName: web-01
  storageLocation: prod-backups

kubectl get vmbackups -n kubermatic-virtualization

Step 3: Restore a VM

A restore always creates a new VM in the backup’s namespace. The original VM is never changed.

Go to Data Protection > VM Backups, open a Ready backup and choose Restore. Enter a New VM Name (at most 63 characters) that no VM in the namespace uses yet, and choose Restore.

Follow the restore under Data Protection > VM Restores. KubeV creates the VM stopped and imports each disk from the bucket. Once the restore is Ready, open the restored VM and start it.

The same with YAML

apiVersion: virtualization.k8c.io/v1alpha1
kind: VMRestore
metadata:
  name: web-01-restore
  namespace: kubermatic-virtualization
spec:
  backupName: web-01-20261019
  targetVMName: web-01-restored
  # Optional. Keeps each disk's original storage class when empty.
  storageClassName: longhorn

kubectl get vmrestores -n kubermatic-virtualization
virtctl start web-01-restored -n kubermatic-virtualization

Deleting a restore removes only the record. The restored VM stays.

Delete backups and targets

• Deleting a backup also deletes its data in the bucket.
• Deleting a target leaves the bucket alone; the dashboard also deletes its credentials Secret. Delete its backups first: a backup deleted after its target cannot reach the bucket, and its data stays there.

Troubleshooting

The message is on the target’s, backup’s or restore’s page, and in kubectl get backupstoragelocations, vmbackups and vmrestores.