Mise à niveau et migration de GitLab Runner avec exemples pratiques

Introduction

Mettre à niveau ou migrer GitLab Runner est rarement une seule commande. C'est une séquence d'observations, de changements ciblés et de vérifications qui protègent votre pipeline CI/CD contre les échecs évitables. Que vous exécutiez des runners sur Docker, Kubernetes ou un hôte Linux classique, la même discipline opérationnelle s'applique : connaître votre version actuelle, comprendre votre topologie de déploiement, préparer un chemin de rollback et vérifier chaque étape par rapport à un signal attendu.

Ce guide est destiné aux développeurs, consultants DevOps et équipes techniques de startups qui ont besoin d'une méthode reproductible pour faire passer GitLab Runner d'une version à une autre ou d'un environnement d'exécution à un autre. Il relie les mises à niveau de version, les changements de configuration, les étapes de migration, les procédures de rollback et la validation post-changement à des commandes concrètes, des sorties attendues et des décisions de récupération.

Les exemples utilisent des espaces réservés comme RUNNER_TOKEN et gitlab.example.com. Remplacez-les par vos propres valeurs, mais ne mettez jamais de véritables informations d'identification, jetons ou clés privées dans une documentation ou des scripts susceptibles d'être partagés.

Inventaire des versions et de l'environnement

Avant de changer quoi que ce soit, enregistrez ce que vous avez. L'objectif de cette phase est de créer un point de départ connu. Si quelque chose casse plus tard, vous pouvez comparer avec cet instantané et décider de revenir en arrière ou de corriger.

Identifier la version installée

Exécutez la commande de version sur l'hôte du runner ou dans le conteneur du runner. Pour un runner basé sur Docker, utilisez :

docker exec -it gitlab-runner gitlab-runner --version

La sortie attendue ressemble à :

Version:      16.10.0
Git revision: 1a2b3c4d
Git branch:   16-10-stable
GO version:   go1.21.5
Built:        2024-04-18T12:00:00+0000
OS/Arch:      linux/amd64

Pour un déploiement Kubernetes, localisez le pod du runner et vérifiez la version :

kubectl get pods -n gitlab-runners
kubectl exec -n gitlab-runners <nom-du-pod-runner> -- gitlab-runner --version

Notez le numéro de version dans un endroit durable. C'est votre référence pour le chemin de mise à niveau et votre cible de rollback si nécessaire.

Documenter la topologie de déploiement

GitLab Runner peut s'exécuter comme un exécuteur shell sur une VM, comme un exécuteur Docker sur un hôte, ou comme un exécuteur Kubernetes dans un cluster. Chacun a des mécanismes de mise à niveau différents.

• Exécuteur shell : Le binaire du runner est installé directement sur l'hôte (souvent via le gestionnaire de paquets). La mise à niveau signifie généralement apt upgrade gitlab-runner ou yum update gitlab-runner.
• Exécuteur Docker : Le runner lui-même s'exécute dans un conteneur, et les jobs s'exécutent dans des conteneurs séparés. La mise à niveau du conteneur du runner est souvent aussi simple que de tirer une nouvelle image et de redémarrer.
• Exécuteur Kubernetes : Le runner est déployé sous forme de pods dans un cluster. La mise à niveau est gérée par des mises à jour de chart Helm ou des modifications de manifestes.

Dessinez la topologie avant de continuer. Cela vous aide à comprendre le rayon d'impact de chaque changement.

Capturer la configuration actuelle

Sauvegardez le fichier de configuration du runner avant de changer quoi que ce soit. Pour un hôte Linux, la configuration se trouve généralement dans /etc/gitlab-runner/config.toml. Pour Docker, vous pouvez le monter depuis un volume hôte. Pour Kubernetes, il est souvent stocké dans une ConfigMap ou un Secret.

# Hôte Linux
sudo cp /etc/gitlab-runner/config.toml /etc/gitlab-runner/config.toml.bak-$(date +%Y%m%d)

# Docker (si la config est dans un volume nommé)
docker run --rm -v gitlab-runner-config:/config alpine cat /config/config.toml > config.toml.bak

# Kubernetes
kubectl get configmap gitlab-runner -n gitlab-runners -o yaml > runner-configmap.yaml

Stockez ces sauvegardes en toute sécurité. Elles sont votre mécanisme de rollback le plus rapide pour les changements de configuration uniquement.

Vérification des prérequis

La mise à niveau de GitLab Runner peut nécessiter une version minimale de l'instance GitLab. Consultez le tableau de compatibilité de GitLab Runner pour confirmer que votre serveur GitLab prend en charge la version du runner que vous prévoyez d'installer. Si vous exécutez un GitLab auto-hébergé, vous pouvez vérifier la version de l'instance :

# Sur le serveur GitLab (ou via l'interface web d'administration)
sudo gitlab-rake gitlab:env:info

Recherchez GitLab version et comparez-la aux exigences du runner. Si votre instance GitLab est plus ancienne que la version minimale prise en charge par le runner, mettez d'abord à niveau GitLab ou choisissez une version plus ancienne du runner.

Chemin de configuration sûr

Les changements de configuration comportent des risques cachés. Une petite faute de frappe dans config.toml peut empêcher le runner de démarrer, ce qui arrête tous les jobs CI qui lui sont assignés. Suivez un chemin sûr : sauvegardez, changez une chose à la fois, vérifiez et soyez prêt à restaurer.

Avant de changer la configuration

Faites une sauvegarde de config.toml comme indiqué précédemment. Enregistrez également l'état actuel du runner :

sudo gitlab-runner status

Sortie attendue sur un hôte basé sur systemd :

● gitlab-runner.service - GitLab Runner
   Loaded: loaded (/etc/systemd/system/gitlab-runner.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2024-04-23 10:00:00 UTC; 1h ago

Notez si le service est actif et depuis combien de temps il tourne. Une durée de fonctionnement courte peut indiquer un crash ou un redémarrage récent.

Effectuer un changement ciblé

Supposons que vous deviez changer l'image Docker utilisée pour les jobs de ruby:3.2 à ruby:3.3. Ouvrez config.toml et localisez la section [[runners]] pertinente :

[[runners]]
  name = "shared-docker-runner"
  url = "https://gitlab.example.com/"
  token = "RUNNER_TOKEN"
  executor = "docker"
  [runners.docker]
    image = "ruby:3.2"

Changez image en ruby:3.3, enregistrez et redémarrez le runner :

sudo gitlab-runner restart

Ensuite, vérifiez que le changement a pris effet sans casser le runner :

sudo gitlab-runner verify

Sortie attendue :

Verifying runner... is alive

Si la vérification échoue, restaurez immédiatement la sauvegarde :

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

Utiliser les variables d'environnement en toute sécurité

Ne codez jamais en dur des secrets dans config.toml si vous pouvez l'éviter. GitLab Runner prend en charge les variables d'environnement pour de nombreux paramètres. Pour Docker, vous pouvez passer le jeton d'enregistrement comme variable d'environnement :

docker run -d --name gitlab-runner \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e CI_SERVER_URL=https://gitlab.example.com/ \
  -e REGISTRATION_TOKEN=VOTRE_JETON \
  gitlab/gitlab-runner:latest

Pour Kubernetes, utilisez un Secret et référencez-le dans les valeurs Helm ou le manifeste de déploiement.

Vérification et diagnostics

Après toute mise à niveau ou migration, prouvez que le runner fonctionne. La vérification va au-delà de gitlab-runner verify ; elle doit inclure une exécution réelle d'un job et une inspection minutieuse des journaux.

Vérification de l'enregistrement du runner

Confirmez que le runner est toujours enregistré auprès de votre instance GitLab. Dans l'interface GitLab, allez dans Paramètres > CI/CD > Runners pour le projet ou le groupe concerné. Le runner doit apparaître avec un cercle vert (en ligne) ou un cercle gris (hors ligne mais enregistré). Vous pouvez également utiliser l'API :

curl --header "PRIVATE-TOKEN: <votre_jeton_d'accès>" \
  "https://gitlab.example.com/api/v4/runners/all?scope=active"

Recherchez l'ID du runner et "active": true. Si le runner est manquant ou inactif, enquêtez sur le jeton d'enregistrement et la configuration du runner.

Pipeline de test

Créez un .gitlab-ci.yml trivial à exécuter sur le runner. Pour un exécuteur Docker, un job simple comme celui-ci fonctionne :

test-runner:
  script:
    - echo "Runner is alive"
    - docker --version

Si le job réussit, vous avez un niveau de confiance de base. Pour l'exécuteur shell, la commande docker peut ne pas exister, ajustez donc le script en conséquence.

Pour un test plus approfondi, exécutez un job qui exerce les changements spécifiques que vous avez effectués. Si vous avez mis à niveau l'image Docker, utilisez une commande qui vérifie la version de l'image :

test-ruby-version:
  image: ruby:3.3
  script:
    - ruby -v

La sortie attendue inclut ruby 3.3.x.

Inspecter les journaux

Les journaux du runner sont essentiels pour diagnostiquer les problèmes. Pour Linux basé sur systemd :

sudo journalctl -u gitlab-runner -n 50 --no-pager

Recherchez des erreurs comme ERROR: Failed to start, Registering runner... failed, ou des messages spécifiques à l'exécuteur. Pour Docker :

docker logs gitlab-runner --tail 50

Pour Kubernetes :

kubectl logs -n gitlab-runners <nom-du-pod-runner> --tail=50

Si un job échoue, vérifiez le journal du job dans l'interface GitLab pour l'erreur spécifique. Les problèmes courants incluent des permissions manquantes sur le socket Docker, des paramètres d'exécuteur incompatibles ou des délais réseau.

Modes d'échec et récupération

Les mises à niveau et les migrations ne se passent pas toujours bien. Préparez-vous aux modes d'échec les plus probables et sachez comment récupérer.

Le runner ne démarre pas après la mise à niveau

Symptôme : gitlab-runner status affiche failed ou activating, et journalctl signale des erreurs concernant des bibliothèques manquantes ou une configuration incompatible.

Cause : La nouvelle version du runner peut nécessiter une bibliothèque système plus récente, ou votre config.toml contient des paramètres obsolètes.

Récupération : Restaurez la version précédente du runner si vous avez utilisé un gestionnaire de paquets et conservé l'ancien paquet. Sur Debian/Ubuntu :

sudo apt install gitlab-runner=<ancienne_version>

Si vous avez utilisé Docker, tirez l'image du tag précédent :

docker pull gitlab/gitlab-runner:<ancienne_version>
docker stop gitlab-runner
docker rm gitlab-runner
docker run -d --name gitlab-runner \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:<ancienne_version>

Ensuite, restaurez votre config.toml sauvegardé si nécessaire.

Le runner ne récupère pas les jobs

Symptôme : Le runner apparaît comme en ligne dans l'interface GitLab, mais les jobs restent en attente.

Cause : Les tags du runner ne correspondent pas aux tags des jobs, ou le runner n'est pas activé pour le projet, ou le runner est en pause.

Récupération : Vérifiez les tags des jobs dans .gitlab-ci.yml et la liste des tags du runner. Vérifiez que le runner est activé pour le projet : dans l'interface GitLab, allez dans Paramètres > CI/CD > Runners, trouvez le runner et assurez-vous que le projet est listé sous Activer pour ce projet. Utilisez gitlab-runner list pour voir les runners configurés et leurs paramètres :

sudo gitlab-runner list

Recherchez les lignes Executor et Tags. Si des tags manquent, ajoutez-les à config.toml et redémarrez.

Erreurs de permission de l'exécuteur Docker

Symptôme : Les jobs échouent avec permission denied en essayant d'accéder à /var/run/docker.sock.

Cause : L'utilisateur du runner n'a pas la permission d'accéder au socket Docker, souvent en raison d'une appartenance de groupe manquante.

Récupération : Pour un runner shell, ajoutez l'utilisateur gitlab-runner au groupe docker :

sudo usermod -aG docker gitlab-runner
sudo gitlab-runner restart

Pour l'exécuteur Docker, assurez-vous que le conteneur du runner est démarré avec -v /var/run/docker.sock:/var/run/docker.sock et que les permissions du socket permettent à l'utilisateur du conteneur.

Rollback de configuration

Gardez toujours une sauvegarde connue et fonctionnelle de config.toml. Si un changement provoque un dysfonctionnement du runner, restaurez la sauvegarde et redémarrez :

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

Ensuite, vérifiez avec gitlab-runner verify et un pipeline de test.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour toute mise à niveau ou migration. Chaque élément inclut un responsable (une personne ou un rôle spécifique) et une fréquence de révision.

Pièges courants et comment les éviter

Sauter la vérification de compatibilité des versions

Piège : Vous mettez à niveau le runner vers une version qui nécessite un serveur GitLab plus récent que celui que vous utilisez. Le runner peut ne pas s'enregistrer ou se comporter de manière imprévisible.

Pourquoi cela arrive : L'enthousiasme pour les nouvelles fonctionnalités du runner ou l'application de correctifs de sécurité sans lire les notes de version.

Comment éviter : Avant toute mise à niveau, ouvrez la page des releases de GitLab Runner et confirmez la version minimale de GitLab. Si votre instance GitLab est plus ancienne, mettez d'abord à niveau GitLab, ou choisissez un runner plus ancien qui prend en charge votre version de GitLab.

Écraser le fichier de configuration sans sauvegarde

Piège : Vous modifiez directement config.toml, faites une erreur de syntaxe et le runner ne démarre pas. Sans sauvegarde, vous devez reconstruire la configuration de mémoire ou à partir des paramètres de l'interface GitLab.

Pourquoi cela arrive : Les administrateurs s'appuient souvent sur le contrôle de version pour le code mais oublient que la configuration du runner n'est pas toujours versionnée.

Comment éviter : Faites une sauvegarde horodatée avant chaque changement. Mieux encore, validez config.toml (avec les secrets expurgés) dans un dépôt Git privé et utilisez un outil de gestion de configuration.

Changer plusieurs variables à la fois

Piège : Vous mettez à jour la version du runner, changez l'image Docker et modifiez les tags dans une seule fenêtre de maintenance. Un job échoue et vous ne pouvez pas dire quel changement en est la cause.

Pourquoi cela arrive : Essayer d'être efficace en regroupant les changements.

Comment éviter : Changez une chose à la fois. Si vous devez regrouper, assurez-vous de pouvoir appliquer et annuler chaque changement indépendamment. Dans un déploiement Kubernetes, utilisez le rollback Helm ou kubectl pour annuler des changements spécifiques.

Ignorer les tags du runner et l'activation du projet

Piège : Après la migration, le runner est en ligne mais ne récupère jamais de jobs. Vous passez des heures à vérifier les journaux alors que le problème est simplement que les tags des jobs ne correspondent pas ou que le runner n'est pas activé pour le projet.

Pourquoi cela arrive : Les tags et l'activation sont faciles à négliger lorsqu'on se concentre sur l'exécution technique.

Comment éviter : Après toute migration, examinez les tags du runner et l'activation du projet dans l'interface GitLab. Mettez à jour config.toml si des tags manquent et activez explicitement le runner pour les projets cibles.

Ne pas tester d'abord avec un pipeline non critique

Piège : Vous mettez à niveau le runner et y acheminez immédiatement les jobs CI de production. Un échec interrompt le pipeline de livraison de l'équipe.

Pourquoi cela arrive : La pression pour terminer rapidement la mise à niveau ou le manque d'environnement de staging.

Comment éviter : Exécutez d'abord un pipeline de test sur un runner de rechange ou un projet à faible trafic. Déplacez progressivement le trafic de production après le succès du test. De nombreuses équipes utilisent des tags de runner comme staging et production pour contrôler le routage des jobs.

Conclusion

La valeur d'une approche structurée de la mise à niveau et de la migration de GitLab Runner ne réside pas dans les commandes elles-mêmes mais dans la discipline d'observer avant de changer, de limiter le rayon d'impact, de vérifier chaque étape et de savoir comment récupérer. Copier une commande sans vérifier les prérequis et la sortie attendue n'est pas une procédure opérationnelle ; c'est une supposition.

Comme prochaine étape, choisissez une vérification à faible risque de ce guide, comme vérifier votre version actuelle du runner et la comparer à la plage prise en charge. Enregistrez l'état actuel, exécutez la vérification documentée et examinez les dépendances comme Docker ou Kubernetes avant d'effectuer un changement plus important. Appliquez ensuite le chemin de configuration sûr à un seul changement ciblé et confirmez le résultat avec un pipeline de test.

Un flux de travail technique fiable rend les échecs visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision. Avec cette base, vous pouvez mettre à niveau et migrer GitLab Runner en toute confiance.