Sauvegarde et restauration de GitLab Runner : guide pratique avec exemples

Introduction

GitLab Runner est le cheval de trait des pipelines CI/CD de GitLab. Il exécute les tâches définies dans vos fichiers .gitlab-ci.yml sur l'infrastructure que vous spécifiez, que ce soit un shell sur une machine virtuelle, un conteneur Docker ou un pod Kubernetes. Lorsqu'un runner tombe en panne, les pipelines s'arrêtent, les déploiements se figent et la productivité des développeurs en souffre. Pour récupérer rapidement et éviter de perdre des artefacts de build, des caches et des configurations critiques, vous avez besoin d'un plan de sauvegarde et de restauration solide. Ce guide présente des stratégies de sauvegarde pratiques pour les trois types de déploiement GitLab Runner les plus courants : installation binaire sur Linux, déploiement en conteneur Docker et déploiement Kubernetes. Vous apprendrez à sauvegarder les fichiers de configuration, les volumes Docker et les ressources Kubernetes ; à vérifier ces sauvegardes ; à diagnostiquer et à récupérer après des pannes ; et à maintenir un calendrier de sauvegarde reproductible. Les exemples utilisent des commandes réalistes et un environnement type afin que vous puissiez les adapter directement à votre propre infrastructure.

Inventaire des versions et de l'environnement

Avant de sauvegarder quoi que ce soit, vous devez savoir exactement ce que vous avez. Le processus de sauvegarde diffère considérablement selon la manière dont le runner est installé et dont il exécute les tâches. Les trois modes de déploiement principaux sont :

• Installation binaire sur Linux/macOS : Le runner est installé directement sur le système d'exploitation hôte, souvent en tant que service système. C'est courant pour les exécuteurs shell et Docker sur des machines autonomes.
• Déploiement en conteneur Docker : Le runner lui-même s'exécute dans un conteneur Docker. Le conteneur peut utiliser l'exécuteur Docker (en lançant des conteneurs frères) ou un autre exécuteur.
• Déploiement Kubernetes : Le runner est installé dans un cluster Kubernetes, généralement via un chart Helm, et utilise l'exécuteur Kubernetes pour exécuter chaque tâche dans un pod dédié.

Prérequis

Vous devez disposer des éléments suivants avant de mettre en place une routine de sauvegarde :

• Stockage de sauvegarde : Un emplacement sécurisé avec suffisamment d'espace pour vos archives. Utilisez un disque séparé, un compartiment S3, un partage réseau ou un serveur de sauvegarde dédié. Ne stockez pas les sauvegardes sur le même disque physique que le runner ; une panne de disque détruirait alors à la fois le runner et sa sauvegarde.
• Identifiants d'accès : Autorisations de lecture des fichiers de configuration du runner, d'accès aux volumes Docker et d'exécution des commandes kubectl et helm si vous avez des runners Kubernetes.
• Outils : tar, rsync, docker, kubectl et helm, selon votre environnement.

Liste de contrôle de l'inventaire

Créez un tableau répertoriant chaque runner, son nom d'hôte, son exécuteur, le chemin du fichier de configuration et les volumes de données ou le stockage persistant qu'il utilise. Le tableau ci-dessous montre un inventaire type pour trois runners. Remplacez les entrées par vos propres valeurs et tenez le tableau à jour au fur et à mesure que des runners sont ajoutés, supprimés ou modifiés. Attribuez un propriétaire unique responsable (SAO) pour l'inventaire, généralement l'ingénieur infrastructure CI/CD. Cette personne est chargée de mettre à jour l'inventaire dans un délai d'un jour ouvrable après tout changement et de le réviser mensuellement avec l'équipe.

Pour chaque runner, notez si le fichier de configuration est la seule chose que vous devez sauvegarder, ou s'il existe également des volumes Docker, des répertoires de cache ou des volumes persistants. Par exemple, runner-1 possède un volume Docker nommé runner-cache qui stocke les artefacts de build et les caches de couches ; si ce volume est perdu, les builds devront re-télécharger les dépendances et recompiler, mais le runner lui-même peut être restauré à partir de config.toml seul.

Chemin de configuration sûr

Le principal fichier de configuration de GitLab Runner est config.toml. Sur les installations binaires Linux, il se trouve généralement dans /etc/gitlab-runner/config.toml. Ce fichier contient le jeton d'enregistrement du runner, les paramètres de l'exécuteur, les limites de concurrence et d'autres options. Le sauvegarder est essentiel mais pas suffisant pour les runners qui utilisent des exécuteurs de conteneurs avec des images ou des volumes en cache. Les sections ci-dessous montrent comment sauvegarder le fichier de configuration pour chaque type de déploiement, ainsi que les données associées.

Sauvegarde du fichier de configuration (installation binaire)

Pour une installation binaire Linux, exécutez la commande suivante en tant qu'utilisateur disposant des privilèges sudo. Elle crée une archive compressée du fichier de configuration et du répertoire certs (s'il existe) :

sudo tar -czf gitlab-runner-config-$(date +%Y%m%d).tar.gz \
  /etc/gitlab-runner/config.toml \
  /etc/gitlab-runner/certs/ 2>/dev/null || true

Sortie attendue : un fichier nommé gitlab-runner-config-AAAAMMJJ.tar.gz dans le répertoire courant. Par exemple, si nous sommes le 15 janvier 2025, le fichier est gitlab-runner-config-20250115.tar.gz. L'archive contient le config.toml et tous les fichiers du répertoire certs. Si le répertoire certs n'existe pas, la commande réussit quand même grâce à 2>/dev/null || true ; l'archive ne contiendra alors que config.toml.

Après avoir créé l'archive, générez une somme de contrôle afin de pouvoir vérifier l'intégrité plus tard :

sha256sum gitlab-runner-config-20250115.tar.gz > gitlab-runner-config-20250115.tar.gz.sha256

Conservez le fichier de somme de contrôle à côté de l'archive et vérifiez-le avant la restauration.

Sauvegarde du fichier de configuration (conteneur Docker)

Si le runner s'exécute dans un conteneur Docker, extrayez config.toml du conteneur en cours d'exécution :

docker cp <nom_du_conteneur>:/etc/gitlab-runner/config.toml ./config.toml

Remplacez <nom_du_conteneur> par le nom ou l'ID réel du conteneur, par exemple gitlab-runner. Sortie attendue : un fichier local config.toml dans le répertoire courant sans message d'erreur. Vous devez ensuite archiver ce fichier ainsi que tous les volumes montés ou autres données pertinentes. Si le conteneur a été démarré avec un montage de volume pour la configuration, par exemple -v /srv/gitlab-runner/config:/etc/gitlab-runner, vous pouvez sauvegarder directement le répertoire hôte au lieu d'utiliser docker cp.

Sauvegarde des volumes Docker

Les runners utilisant l'exécuteur Docker stockent souvent le cache et les artefacts de build dans des volumes Docker nommés. Pour sauvegarder un volume, identifiez d'abord les volumes utilisés :

docker volume ls

Exemple de sortie :

DRIVER    VOLUME NAME
local     runner-cache
local     runner-artifacts

Sauvegardez chaque volume en exécutant un conteneur Alpine temporaire qui monte le volume et un répertoire hôte, puis crée une archive tar :

docker run --rm -v runner-cache:/data -v $(pwd):/backup alpine \
  tar czf /backup/runner-cache.tar.gz -C /data .

Sortie attendue : un fichier runner-cache.tar.gz dans le répertoire courant. Cette archive contient tous les fichiers du volume. Répétez l'opération pour chaque volume, en remplaçant runner-cache par le nom approprié. Pour les gros volumes, vous pouvez exclure certains répertoires (par exemple .cache) afin de réduire la taille de la sauvegarde ; pour ce faire, ajoutez des options tar telles que --exclude='.cache' avant le drapeau -C. Après la sauvegarde, créez une somme de contrôle pour chaque archive et conservez-la en lieu sûr.

Sauvegarde des manifestes et des données Kubernetes

Pour GitLab Runner déployé sur Kubernetes, la configuration principale se trouve dans le fichier de valeurs Helm et dans les ressources personnalisées que vous avez créées. Les données d'exécution du runner peuvent être stockées dans des PersistentVolumeClaims (PVC) pour le cache et les artefacts. Sauvegardez les valeurs de la release Helm avec :

helm get values <nom-de-release> -n <namespace> > values-backup.yaml

Par exemple, si la release s'appelle gitlab-runner dans le namespace gitlab, exécutez :

helm get values gitlab-runner -n gitlab > values-backup.yaml

Sortie attendue : un fichier YAML values-backup.yaml contenant toutes les valeurs personnalisées utilisées pour installer ou mettre à niveau la release. Ce fichier préserve vos paramètres non par défaut.

Pour sauvegarder les ressources Kubernetes à l'exécution (ConfigMaps, Secrets, Deployments et Pods), exécutez :

kubectl get configmap, secret, deployment, pod -n <namespace> -o yaml > k8s-resources-backup.yaml

Exemple :

kubectl get configmap, secret, deployment, pod -n gitlab -o yaml > k8s-resources-backup.yaml

Sortie attendue : un fichier YAML contenant les définitions de toutes ces ressources dans le namespace. Notez que les ressources Secret contiennent des données encodées en base64 ; lors de leur restauration, elles seront recréées exactement telles qu'elles étaient. Pour les données des PVC, vous devez sauvegarder le volume de stockage sous-jacent. La méthode dépend de votre fournisseur de stockage. Si vous utilisez un fournisseur cloud, prenez des instantanés des PVC. Si vous utilisez un provisionneur local, vous devrez peut-être copier les données depuis le pod à l'aide de kubectl cp ou d'un outil similaire. Nous abordons la sauvegarde des PVC plus en détail dans la section sur la reprise après sinistre.

Vérification et diagnostics

La sauvegarde n'est que la moitié du travail. Vous devez vérifier que les sauvegardes sont valides et restaurables. Des tests réguliers évitent le scénario classique où l'on découvre en cas d'urgence que la sauvegarde est vide, corrompue ou incomplète.

Vérifier les fichiers de sauvegarde

Commencez par lister le contenu de l'archive pour vous assurer qu'elle n'est pas vide et qu'elle contient les fichiers attendus. Pour une archive de configuration :

tar -tzf gitlab-runner-config-20250115.tar.gz

Sortie attendue : une liste de fichiers, dont etc/gitlab-runner/config.toml. Si le répertoire certs a été inclus, ces fichiers apparaissent également. Si l'archive est vide ou si le listage échoue, la sauvegarde ne s'est pas terminée correctement ; réexécutez la commande de sauvegarde.

Pour les sauvegardes de volumes Docker :

tar -tzf runner-cache.tar.gz | head

Sortie attendue : les dix premiers chemins de fichiers du volume. Si le volume était vide, il n'y aura aucune sortie ; dans ce cas, vérifiez que le volume n'avait effectivement aucune donnée ou que le montage était correct.

Vérifiez toujours la somme de contrôle de l'archive par rapport à la somme stockée :

sha256sum -c gitlab-runner-config-20250115.tar.gz.sha256

Sortie attendue : gitlab-runner-config-20250115.tar.gz: OK. Si la sortie indique FAILED, l'archive est corrompue ou a été modifiée ; créez une nouvelle sauvegarde.

Tester la restauration dans un environnement isolé

Avant de vous fier à une sauvegarde, testez le processus de restauration dans un environnement isolé. Pour une configuration de runner binaire, extrayez l'archive dans un répertoire temporaire et comparez le fichier restauré avec l'original :

mkdir /tmp/restore-test
tar -xzf gitlab-runner-config-20250115.tar.gz -C /tmp/restore-test
diff /etc/gitlab-runner/config.toml /tmp/restore-test/etc/gitlab-runner/config.toml

Sortie attendue : aucune différence (sortie diff vide). Si diff affiche des différences, vérifiez si la sauvegarde a été prise après que l'original a changé, ou si le chemin d'extraction est incorrect.

Pour les sauvegardes de volumes Docker, créez un nouveau volume, restaurez l'archive dedans, puis exécutez un conteneur pour vérifier que les fichiers sont présents :

docker volume create restore-test-volume
docker run --rm -v restore-test-volume:/data -v $(pwd):/backup alpine \
  tar xzf /backup/runner-cache.tar.gz -C /data

Ensuite, exécutez un conteneur temporaire utilisant le volume et listez les fichiers :

docker run --rm -v restore-test-volume:/data alpine ls -la /data

Sortie attendue : une liste de fichiers et de répertoires qui doit correspondre au contenu du volume d'origine. Si la liste est vide ou incomplète, la sauvegarde n'a pas capturé les données correctement.

Pour les sauvegardes Kubernetes, testez en restaurant dans un namespace séparé. Utilisez les fichiers YAML de sauvegarde pour recréer les ressources, mais faites attention aux Secrets et aux ConfigMaps ; ils devront peut-être être recréés avec les mêmes noms avant de restaurer les Deployments. Un test complet de restauration de PVC dépend de la capacité d'instantané de votre fournisseur de stockage.

Modes de défaillance et récupération

Les processus de sauvegarde et de restauration peuvent échouer pour de nombreuses raisons. Comprendre les modes de défaillance courants vous aide à planifier des mesures d'atténuation et à récupérer plus rapidement. Le tableau ci-dessous résume les défaillances typiques, les symptômes et les atténuations. Pour chaque mode de défaillance, le responsable de la récupération est la personne ou le rôle chargé de rétablir le service. Dans la plupart des organisations, il s'agit de l'ingénieur infrastructure CI/CD ou de l'ingénieur SRE de garde. Le responsable de la récupération doit documenter l'incident, y compris la cause, les étapes de récupération effectuées et le temps de restauration, dans les 24 heures suivant la résolution.

Stratégie de retour en arrière

Si une restauration introduit des problèmes, vous devez pouvoir revenir à l'état précédent. Pour les fichiers de configuration, conservez toujours le fichier actuel comme sauvegarde avant de l'écraser :

sudo cp /etc/gitlab-runner/config.toml /etc/gitlab-runner/config.toml.bak

Ensuite, restaurez le nouveau fichier. Si le runner ne démarre pas ou se comporte de manière incorrecte, revenez en arrière :

sudo cp /etc/gitlab-runner/config.toml.bak /etc/gitlab-runner/config.toml
sudo gitlab-runner restart

Sortie attendue : le runner redémarre avec succès (aucun message d'erreur). Assurez-vous que le fichier de retour en arrière provient d'un état connu comme bon ; vous pouvez conserver des copies horodatées de config.toml pendant quelques jours.

Pour les volumes Docker, vous pouvez de la même manière conserver une copie du volume existant avant de restaurer à partir de la sauvegarde. Par exemple, créez une sauvegarde du volume actuel, puis restaurez la sauvegarde précédente si nécessaire.

Étapes de reprise après sinistre

En cas de sinistre complet, suivez ces étapes pour ramener un runner à partir des sauvegardes :

1. Restaurer le fichier de configuration : Copiez le config.toml sauvegardé vers /etc/gitlab-runner/config.toml (ou le chemin approprié). Assurez-vous que la propriété et les permissions sont correctes :

   sudo cp /chemin/vers/sauvegarde/config.toml /etc/gitlab-runner/config.toml
   sudo chown gitlab-runner:gitlab-runner /etc/gitlab-runner/config.toml
   sudo chmod 600 /etc/gitlab-runner/config.toml

1. Restaurer les volumes Docker : Recréez le volume si nécessaire et remplissez-le à partir de l'archive de sauvegarde :

   docker volume create runner-cache
   docker run --rm -v runner-cache:/data -v $(pwd):/backup alpine \
     tar xzf /backup/runner-cache.tar.gz -C /data

1. Réinstaller le binaire du runner si nécessaire : Si l'hôte a été reconstruit, installez GitLab Runner en utilisant le dépôt officiel ou le script d'installation :

   curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
   sudo apt-get install gitlab-runner

1. Vérifier l'enregistrement du runner : Exécutez gitlab-runner verify pour vérifier que le runner est enregistré auprès de l'instance GitLab :

   sudo gitlab-runner verify

Sortie attendue : des messages indiquant que chaque runner configuré est vivant ou nécessite une attention. Si le runner a été enregistré avec un jeton qui n'est plus valide, réenregistrez-le en utilisant gitlab-runner register avec le jeton approprié de GitLab.

1. Tester avec un pipeline simple : Déclenchez une tâche CI minimale pour confirmer le fonctionnement de bout en bout. Créez un projet de test ou utilisez-en un existant, et exécutez un pipeline avec une tâche simple, par exemple une tâche qui exécute echo. Si le runner prend la tâche et la termine avec succès, votre restauration a réussi.

Pièges courants et comment les éviter

Même avec de bonnes intentions, les équipes commettent souvent des erreurs dans les processus de sauvegarde et de restauration. Voici les pièges fréquents et comment les éviter.

1. Ne pas tester régulièrement les restaurations. Les sauvegardes peuvent être corrompues ou incomplètes sans que personne ne s'en aperçoive. Un test de restauration est le seul moyen de garantir la récupérabilité.

• Pourquoi cela arrive : Les sauvegardes s'exécutent automatiquement et personne ne les vérifie jusqu'à une urgence.
• Comment l'éviter : Planifiez un test de restauration mensuel (ou plus fréquent pour les runners critiques). Automatisez le test avec un script et demandez à l'ingénieur CI/CD de passer en revue les résultats.

1. Stocker les sauvegardes sur le même disque que le runner. Une panne de disque détruit à la fois le runner et ses sauvegardes.

• Pourquoi cela arrive : La commodité ; les sauvegardes locales sont faciles à configurer.
• Comment l'éviter : Utilisez un disque physique séparé, un partage réseau ou un stockage cloud. Au minimum, copiez régulièrement les sauvegardes hors de l'hôte.

1. Oublier de sauvegarder les secrets et les jetons. Dans Kubernetes, les Secrets sont souvent sauvegardés dans le cadre du YAML de ressources, mais dans les configurations binaires ou Docker, les jetons peuvent résider uniquement dans config.toml. Perdre le config.toml signifie perdre les jetons d'enregistrement.

• Pourquoi cela arrive : Les jetons ne sont pas visibles ; ils sont cachés dans la configuration.
• Comment l'éviter : Assurez-vous que config.toml est sauvegardé, et stockez également le jeton d'enregistrement du runner en toute sécurité dans un gestionnaire de mots de passe ou un magasin de secrets. Pour Kubernetes, assurez-vous que les Secrets sont inclus dans votre sauvegarde (ou utilisez un système de gestion des secrets externe).

1. Supposer que les volumes Docker sont sauvegardés lorsque seule la configuration est enregistrée. Le config.toml ne contient pas les données des volumes. Si vous comptez sur les caches stockés dans les volumes, vous avez besoin de sauvegardes de volumes séparées.

• Pourquoi cela arrive : Une mauvaise compréhension du contenu de config.toml.
• Comment l'éviter : Documentez quels runners ont des volumes et incluez-les dans le plan de sauvegarde. Exécutez des sauvegardes de volumes automatisées à la même fréquence que les sauvegardes de configuration.

1. Utiliser un script de sauvegarde monolithique unique qui échoue silencieusement. Si le script échoue à mi-chemin, vous pourriez vous retrouver avec des sauvegardes incomplètes mais aucune erreur signalée.

• Pourquoi cela arrive : Manque de gestion des erreurs ; le script s'exécute et se termine avec le code 0 même si certaines commandes échouent.
• Comment l'éviter : Ajoutez set -e et des vérifications explicites dans votre script de sauvegarde. Pour chaque commande, vérifiez le code de sortie et consignez les erreurs. Envoyez des notifications en cas d'échec.

1. Ne pas sécuriser le stockage des sauvegardes. Les archives de sauvegarde peuvent contenir des informations sensibles (jetons, clés SSH, artefacts de build). Si les sauvegardes sont stockées non chiffrées sur un serveur partagé, elles peuvent être compromises.

• Pourquoi cela arrive : On néglige la sécurité des sauvegardes.
• Comment l'éviter : Chiffrez les sauvegardes avant de les envoyer au stockage (par exemple, en utilisant gpg ou openssl). Limitez l'accès aux fichiers de sauvegarde et utilisez des contrôles d'accès.

Liste de contrôle opérationnelle

Utilisez les listes de contrôle suivantes pour maintenir une routine de sauvegarde cohérente. Attribuez un propriétaire de sauvegarde (généralement l'ingénieur CI/CD) qui est responsable de l'exécution de ces listes de contrôle et de l'escalade de tout échec. Le propriétaire doit passer en revue les résultats de la liste de contrôle avec l'équipe lors de la réunion hebdomadaire sur l'infrastructure.

Liste de contrôle quotidienne des sauvegardes

Exécutez ces vérifications tous les jours, de préférence automatisées et journalisées :

• [ ] Le script de sauvegarde s'est exécuté avec succès (vérifiez le journal pour les erreurs).
• [ ] Les fichiers de sauvegarde existent et ont la taille attendue (par exemple, archive de configuration > 1 Ko, archive de volume > 10 Mo).
• [ ] Le stockage de sauvegarde a suffisamment d'espace libre (par exemple, au moins 20 % de libre).
• [ ] Les fichiers de somme de contrôle sont générés et correspondent aux sommes stockées.

Liste de contrôle hebdomadaire de vérification

Effectuez ces tâches chaque semaine pour vous assurer que les sauvegardes sont utilisables :

• [ ] Testez la restauration des fichiers de configuration dans un environnement isolé et comparez avec la configuration en direct.
• [ ] Validez les sauvegardes de volumes Docker en les restaurant dans un volume de test et en vérifiant l'intégrité des fichiers.
• [ ] Vérifiez que le YAML de sauvegarde des ressources Kubernetes est complet (toutes les ressources attendues sont présentes).
• [ ] Passez en revue les journaux de sauvegarde pour détecter toute anomalie et mettez à jour la documentation si nécessaire.

Exercice trimestriel de reprise après sinistre

Effectuez un exercice complet de reprise après sinistre chaque trimestre pour tester le processus de restauration complet :

• [ ] Simulez une panne complète du runner (par exemple, arrêtez un runner de test, supprimez sa configuration et ses volumes).
• [ ] Restaurez à partir des dernières sauvegardes en utilisant les étapes documentées.
• [ ] Vérifiez l'enregistrement du runner avec gitlab-runner verify.
• [ ] Déclenchez un pipeline de test et confirmez l'exécution réussie de la tâche.
• [ ] Enregistrez le temps de récupération (objectif : moins de 30 minutes) et identifiez tout problème ou amélioration.

Conclusion

Une stratégie robuste de sauvegarde et de restauration pour GitLab Runner ne se limite pas à copier des fichiers ; elle vise à garantir que vous pouvez récupérer rapidement et complètement lorsque les choses tournent mal. Ce guide a passé en revue les principes fondamentaux : inventorier vos runners, sauvegarder les fichiers de configuration, les volumes Docker et les ressources Kubernetes, vérifier les sauvegardes et planifier les pannes. En mettant en œuvre les pratiques et les listes de contrôle décrites ici, vous pouvez minimiser les temps d'arrêt et les pertes de données. Commencez petit : choisissez un runner, créez une sauvegarde, testez la restauration, puis étendez à tous les runners. Mesurez votre temps de récupération lors des exercices et améliorez-vous continuellement. Avec un processus de sauvegarde et de restauration fiable, votre infrastructure CI/CD reste résiliente et votre équipe de développement peut continuer à livrer sans interruption.