Velero est l'outil de référence pour la sauvegarde, la restauration et la migration de clusters Kubernetes. Il sauvegarde deux choses distinctes : les ressources Kubernetes (Deployments, Services, ConfigMaps, Secrets, etc.) en les sérialisant dans un object storage, et les données des volumes persistants via des snapshots cloud ou via Kopia (agent de sauvegarde fichier inclus).

Velero est développé par VMware (Broadcom) et est un projet CNCF. Il s'utilise via sa CLI et expose des CRDs (Backup, Restore, Schedule) pour automatiser les sauvegardes.

Informations essentielles

Origine : VMware / Heptio → CNCF · Licence : Apache 2.0 · Architectures : x86_64, ARM64

Liens : Site officiel · Documentation · GitHub · Releases

Support : Les 3 dernières versions mineures sont maintenues.

Stack par défaut

Composant	Valeur
Sauvegarde ressources K8s	Object storage (S3, Azure Blob, GCS, MinIO…)
Sauvegarde volumes PV	Kopia (agent fichier) ou snapshots cloud natifs
Format de sauvegarde	Tar compressé dans l'object storage
Planification	CRD Schedule (cron) ou CLI
Restauration	Sélective par namespace, label, ressource

Concepts clés

Concept	Description
BackupStorageLocation (BSL)	Où stocker les sauvegardes (bucket S3, conteneur Azure…)
VolumeSnapshotLocation (VSL)	Où stocker les snapshots de volumes (AWS EBS, GCE PD…)
Backup	Ressource CRD représentant une sauvegarde à un instant T
Restore	Ressource CRD pour restaurer depuis un Backup
Schedule	Sauvegarde récurrente (format cron)
BackupRepository	Stockage Kopia pour les données des volumes

Sauvegarde des volumes PV

Deux approches :

Approche	Mécanisme	Usage
Kopia (file-system backup)	Agent copie les fichiers du volume	Tout stockage, indépendant du cloud
Snapshots natifs	API snapshot du provider cloud (AWS EBS, GCE PD, Azure Disk)	Cloud uniquement
CSI Snapshots	VolumeSnapshot Kubernetes (CSI)	Clusters avec CSI driver compatible

Prérequis

Ressource	Valeur
Kubernetes	1.20+
kubectl	Compatible avec le cluster
Object storage	Bucket S3, Azure Blob, GCS ou MinIO
velero CLI	À installer sur le poste de travail

Installation

1. Installer la CLI Velero

# Linux
VELERO_VERSION=v1.13.0
curl -Lo velero.tar.gz \
  https://github.com/vmware-tanzu/velero/releases/download/${VELERO_VERSION}/velero-${VELERO_VERSION}-linux-amd64.tar.gz
tar -xzf velero.tar.gz
sudo mv velero-*/velero /usr/local/bin/
velero version --client-only

2. Installer Velero sur le cluster (backend S3 / MinIO)

# Créer le fichier de credentials S3
cat > credentials-velero <<EOF
[default]
aws_access_key_id=<ACCESS_KEY>
aws_secret_access_key=<SECRET_KEY>
EOF

# Installer Velero avec le plugin AWS
velero install \
  --provider aws \
  --plugins velero/velero-plugin-for-aws:v1.9.0 \
  --bucket velero-backups \
  --secret-file ./credentials-velero \
  --backup-location-config region=eu-west-1 \
  --snapshot-location-config region=eu-west-1 \
  --use-node-agent                          # Active Kopia pour les volumes PV

# Vérifier
kubectl get pods -n velero
velero backup-location get

Avec MinIO (self-hosted S3)

velero install \
  --provider aws \
  --plugins velero/velero-plugin-for-aws:v1.9.0 \
  --bucket velero \
  --secret-file ./credentials-velero \
  --use-node-agent \
  --backup-location-config \
    region=minio,s3ForcePathStyle=true,s3Url=http://minio.minio.svc.cluster.local:9000

Via Helm

helm repo add vmware-tanzu https://vmware-tanzu.github.io/helm-charts
helm install velero vmware-tanzu/velero \
  --namespace velero --create-namespace \
  -f velero-values.yaml

Vérification de l'installation

# 1. Pods Velero
kubectl get pods -n velero
# velero-* (1/1) et node-agent-* (1/1 sur chaque nœud si --use-node-agent)

# 2. Vérifier la connexion au backend de stockage
velero backup-location get
# PHASE doit être Available, LAST VALIDATED récent (< 1 min)
# Si Unavailable : credentials incorrects ou bucket inaccessible

# 3. Tester avec un backup de validation rapide (namespace kube-system léger)
velero backup create install-check \
  --include-namespaces kube-system \
  --exclude-resources pods,events
velero backup get install-check
# STATUS doit passer InProgress → Completed (quelques secondes)

# 4. Vérifier les logs en cas de problème
kubectl logs -n velero -l component=velero --tail=50

# 5. Nettoyer le backup de test
velero backup delete install-check --confirm

Pièges courants à l'installation

Symptôme	Cause	Correction
`BackupStorageLocation Unavailable`	Bucket inexistant ou credentials incorrects	Vérifier le bucket + le secret credentials-velero
`BackupStorageLocation Unavailable`	Endpoint S3 inaccessible depuis le cluster	Vérifier la connectivité réseau K8s → S3
Backup `PartiallyFailed`	Ressources cluster-scoped sans permission	Ajouter `--exclude-resources` pour les ressources problématiques
Volumes PV non sauvegardés	`--default-volumes-to-fs-backup` manquant	Ajouter le flag ou annoter les pods
`node-agent` non présent sur un nœud	Nœud ajouté après installation	Redéployer : `kubectl rollout restart ds/node-agent -n velero`

Sauvegardes

Sauvegarde manuelle

# Sauvegarde complète du cluster
velero backup create cluster-backup-$(date +%Y%m%d)

# Sauvegarde d'un namespace uniquement
velero backup create prod-backup \
  --include-namespaces production

# Sauvegarde avec volumes (Kopia)
velero backup create prod-backup-with-pv \
  --include-namespaces production \
  --default-volumes-to-fs-backup

# Exclure des ressources
velero backup create prod-backup \
  --include-namespaces production \
  --exclude-resources secrets,events

# Vérifier
velero backup get
velero backup describe prod-backup
velero backup logs prod-backup

Sauvegarde planifiée (Schedule)

# Sauvegarde quotidienne à 3h
velero schedule create daily-backup \
  --schedule="0 3 * * *" \
  --include-namespaces production \
  --default-volumes-to-fs-backup \
  --ttl 720h0m0s             # Rétention 30 jours

# Lister les schedules
velero schedule get

# Déclencher manuellement depuis un schedule
velero backup create --from-schedule daily-backup

Via CRD

apiVersion: velero.io/v1
kind: Schedule
metadata:
  name: daily-production
  namespace: velero
spec:
  schedule: "0 3 * * *"
  template:
    includedNamespaces:
    - production
    defaultVolumesToFsBackup: true
    ttl: 720h0m0s
    storageLocation: default

Restauration

# Lister les backups disponibles
velero backup get

# Restaurer un namespace dans le cluster actuel
velero restore create --from-backup prod-backup \
  --include-namespaces production

# Restaurer dans un namespace différent
velero restore create --from-backup prod-backup \
  --include-namespaces production \
  --namespace-mappings production:production-restored

# Restaurer uniquement certaines ressources
velero restore create --from-backup prod-backup \
  --include-resources deployments,services,configmaps

# Vérifier l'état de la restauration
velero restore get
velero restore describe <restore-name>
velero restore logs <restore-name>

Migration de cluster

Velero permet de migrer des workloads d'un cluster source vers un cluster cible via un object storage partagé.

# --- Sur le cluster SOURCE ---

# 1. Configurer Velero avec le même bucket que le cluster cible
# 2. Lancer une sauvegarde du namespace à migrer
velero backup create migration-backup \
  --include-namespaces production \
  --default-volumes-to-fs-backup

# Attendre la fin
velero backup get migration-backup

# --- Sur le cluster CIBLE ---

# 3. Installer Velero avec les mêmes credentials bucket
# 4. Synchroniser les backups (auto-sync toutes les minutes)
velero backup-location get          # Doit voir le backup du cluster source

# 5. Restaurer
velero restore create --from-backup migration-backup

Hooks pre/post sauvegarde

Pour assurer la cohérence des bases de données, exécuter un flush avant la sauvegarde :

# Annotation sur le pod (ex: MySQL)
metadata:
  annotations:
    pre.hook.backup.velero.io/command: '["/bin/bash", "-c", "mysql -u root -p$MYSQL_ROOT_PASSWORD -e \"FLUSH TABLES WITH READ LOCK\""]'
    pre.hook.backup.velero.io/timeout: "60s"
    post.hook.backup.velero.io/command: '["/bin/bash", "-c", "mysql -u root -p$MYSQL_ROOT_PASSWORD -e \"UNLOCK TABLES\""]'

Mise à jour

# Mettre à jour la CLI
curl -Lo velero.tar.gz \
  https://github.com/vmware-tanzu/velero/releases/download/v1.13.0/velero-v1.13.0-linux-amd64.tar.gz
tar -xzf velero.tar.gz && sudo mv velero-*/velero /usr/local/bin/

# Mettre à jour le déploiement cluster
velero install --upgrade \
  --provider aws \
  --plugins velero/velero-plugin-for-aws:v1.9.0 \
  ...

Troubleshooting

# Logs du serveur Velero
kubectl logs -n velero -l component=velero --tail=100

# Logs de l'agent node-agent (Kopia)
kubectl logs -n velero -l name=node-agent --tail=100

# Vérifier la connexion au backend de stockage
velero backup-location get
velero backup-location check

# Backup en erreur
velero backup describe <nom>
velero backup logs <nom>

Backup en état PartiallyFailed

# Voir les ressources qui ont échoué
velero backup describe <nom> --details

# Souvent : permission manquante sur une ressource cluster-scoped
# Ajouter --exclude-resources sur les ressources problématiques

Volume PV non sauvegardé

# Vérifier que --default-volumes-to-fs-backup est utilisé
# OU que l'annotation est présente sur le pod
kubectl get pod <pod> -o yaml | grep backup.velero.io

# Vérifier que node-agent tourne sur tous les nœuds
kubectl get pods -n velero -l name=node-agent

Commandes utiles

velero backup get                          # Lister les sauvegardes
velero backup describe <nom> --details     # Détail complet d'une sauvegarde
velero backup delete <nom>                 # Supprimer une sauvegarde
velero schedule get                        # Lister les schedules
velero restore get                         # Lister les restaurations
velero backup-location get                 # Vérifier les backends de stockage
velero version                             # Version client + serveur

Ressources

Documentation officielle : https://velero.io/docs/
Plugins providers : https://velero.io/docs/latest/supported-providers/
Sauvegarde des volumes (Kopia) : https://velero.io/docs/latest/file-system-backup/
Migration de clusters : https://velero.io/docs/latest/migration-case/
GitHub : https://github.com/vmware-tanzu/velero
Releases : https://github.com/vmware-tanzu/velero/releases