Troubleshooting backup

Logs and description of backup #

List of backups #

kubectl get backup -n velero

Backup events and errors #

kubectl describe backup <backup-name> -n velero

Velero server logs #

kubectl logs -n velero deployment/velero --tail=500

Job backup logs (if Job is created) #

kubectl logs -n velero job/<job-name> -f

For backups that failed at an early stage, the log file may be missing - look at kubectl describe backup and deployment/velero logs (Troubleshooting (v1.17)).

Restore #

Description of restore (kubectl) #

kubectl describe restore <name> -n velero

Description of restore (Velero CLI) #

velero restore describe <name>

Restore log (Velero CLI) #

velero restore logs <name>

Collecting a debug archive #

Help for the velero debug command #

velero debug --help

The velero debug command creates an archive with versions, server and plugin logs and resources managed by Velero (Troubleshooting (v1.17)).

Increasing logging level #

In the manifest Deployment velero in the namespace velero for the server container, add the arguments --log-level and debug (Troubleshooting (v1.17)).

Why backup may be unavailable in the GUI #

Typical errors and situations #

Error checking repository for stale locks #

Data in object storage (restic/kopia directories) has been deleted or corrupted, but BackupRepository objects in the cluster remain. Either delete the data together with BackupRepository, or do not touch the data in the bucket manually.

error checking if volume is a hostPath volume #

Velero does not include hostPath volumes in the file system backup. The message does not stop the rest of the backup. To remove the warning, exclude the volumes with an annotation on the pod:

backup.velero.io/backup-volumes-excludes: name1,name2,name3

pod volume backup failed: getting pod trivy-system/scan-vulnerabilityreport-* #

Trivy scanner pods are often short-lived; By the time the volume was copied, the pod could have already disappeared. This is usually expected and does not mean a complete failure of the backup.

SignatureDoesNotMatch with velero backup logs #

Artifacts are downloaded via temporary signed URLs. Some S3-compatible storages may deviate from the AWS API. Check the signature version (Signature V4), account type (Troubleshooting (v1.17)).

Backup stuck in InProgress phase after a failure #

Velero does not continue interrupted backups. A backup in InProgress without data in storage can be deleted (Troubleshooting (v1.17)):

Deleting a Backup entry in Kubernetes #

kubectl delete backup <name> -n velero

Restoring Service type LoadBalancer #

After restore, Service has a new UID → the name of the cloud balancer may change. Update DNS CNAME or use spec.loadBalancerIP if your provider supports (Troubleshooting (v1.17), Kubernetes documentation).

Admission webhooks block resource creation during restore #

Webhook can reject or change the object. Options: temporarily disable webhook, use restore item action plugin (Troubleshooting (v1.17)).

Kopia: repository owner conflict (maintenance must be run by designated user) #

When manually working with the Kopia repository, you must respect the default user/host for the Velero repository; in case of a conflict, set the owner to maintenance via the Kopia CLI (Troubleshooting (v1.17)).

Errors when restoring from the GUI #

• PVs occupied by running pods are not restored.
• Name conflict: Update policy or deleting the conflicting resource to a new Restore.

Checking status #

BackupStorageLocation list #

kubectl get backupstoragelocation -n velero

BackupRepository list #

kubectl get backuprepository -n velero

Events in the velero namespace #

kubectl get events -n velero --sort-by='.lastTimestamp' | tail -20

Credentials for BackupStorageLocation and associated secrets - steps in Troubleshooting (v1.17).