## Introduction GitLab Runner est le cheval de trait de l’intégration et du déploiement continus (CI/CD) de GitLab. Il exécute les tâches sur votre infrastructure, qu’il s’agisse d’un serveur bare-metal, d’une machine virtuelle, d’un conteneur Docker ou d’un cluster Kubernetes. Lorsque les runners échouent silencieusement, se comportent mal sous charge ou se désynchronisent de l’instance GitLab, les pipelines se cassent et les équipes perdent confiance en leur automatisation. La surveillance et les alertes pour GitLab Runner comblent cette lacune. Elles transforment l’activité brute des runners en signaux observables : quels runners sont occupés, combien de temps les tâches attendent, si le runner peut joindre GitLab et si le bon exécuteur fait réellement le travail. Avec les bonnes métriques, les bons tableaux de bord et les bonnes alertes, un opérateur peut passer de « une tâche a échoué » à « ce runner sur cet hôte a épuisé son disque à 14 h 32 et a récupéré après le nettoyage » en quelques minutes. Ce guide s’adresse aux développeurs, aux consultants DevOps et aux équipes techniques de startups qui exploitent un ou plusieurs GitLab Runners. Il se concentre sur la surveillance et les alertes pratiques : les commandes à exécuter, les métriques à collecter, les tableaux de bord à construire et les alertes à configurer. Chaque exemple est concret et versionné, avec la sortie attendue et un chemin de récupération. Aucun secret ni identifiant de production n’apparaît dans aucun exemple. Tout au long de ce guide, l’objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d’impact, vérifier le résultat et documenter la récupération avant qu’un incident ne force la décision. ## Inventaire de la version et de l’environnement Avant de pouvoir surveiller efficacement un runner, vous devez savoir exactement ce que vous exécutez. Le comportement d’un runner dépend de sa version, de son type d’exécuteur et de sa topologie de déploiement. Un exécuteur Docker sur Kubernetes se comporte différemment d’un exécuteur shell sur une VM autonome, et les deux diffèrent des runners intégrés de l’instance GitLab. Commencez par une découverte en lecture seule. Sur l’hôte du runner, exécutez : gitlab-runner --version Exemple de sortie sur une installation typique : Version: 16.5.0 Git revision: 8b1f2e3d Git branch: 16-5-stable GO version: go1.21.3 Built: 2023-10-20T14:00:00Z OS/Arch: linux/amd64 Cela vous indique la version du runner, ce qui est important pour des fonctionnalités comme FF_USE_LEGACY_VOLUMES_MOUNTING ou le helper_image de l’exécuteur Kubernetes. Consultez la documentation de GitLab Runner pour connaître les clés de configuration prises en charge par la version avant d’apporter des modifications. Ensuite, listez tous les runners configurés sur cet hôte : gitlab-runner list La sortie attendue inclut le nom de chaque runner, son exécuteur et le préfixe du jeton. Par exemple : Listing configured runners ConfigFile=/etc/gitlab-runner/config.toml my-docker-runner Executor=docker Token=glrt-xxxx URL=https://gitlab.example.com my-shell-runner Executor=shell Token=glrt-yyyy URL=https://gitlab.example.com Si un runner n’apparaît pas ici, il peut être enregistré sur un autre hôte ou géré par l’instance GitLab (runners partagés). Pour voir tous les runners du côté GitLab, un administrateur peut utiliser l’API : curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/runners/all?per_page=100" Cela renvoie un JSON avec l’ id , la description , le statut active , online , status et ip_address de chaque runner. Le champ online est critique : un runner peut être enregistré mais hors ligne. Capturez cette sortie avant tout changement pour établir une référence. Exemple d’extrait de réponse : [ { "id": 42, "description": "docker-runner-prod-01", "active": true, "online": true, "status": "online", "ip_address": "10.0.1.15" } ] Documentez la topologie de déploiement : combien de runners, quels exécuteurs, où ils s’exécutent et quels tags ils exposent. Stockez cet inventaire dans un système de contrôle de version ou un wiki afin qu’il soit disponible pendant un incident. Revoyez-le mensuellement ou chaque fois qu’un runner est ajouté, supprimé ou mis à niveau. Prérequis pour la surveillance : assurez-vous que le processus du runner est en cours d’exécution sur l’hôte, que le point de terminaison des métriques Prometheus est activé (voir la section suivante) et que vous disposez d’un accès SSH ou équivalent à l’hôte du runner. Le rayon d’impact de toute commande en lecture seule est nul ; aucun chemin de récupération n’est nécessaire. ## Chemin de configuration sûr Pour surveiller GitLab Runner avec Prometheus, activez l’écouteur de métriques intégré. Il s’agit d’une petite modification de configuration dans /etc/gitlab-runner/config.toml . Tout d’abord, vérifiez la configuration actuelle : sudo cat /etc/gitlab-runner/config.toml Recherchez une entrée [session_server] ou listen_address . Par défaut, l’écouteur de métriques est désactivé. Pour l’activer, modifiez le fichier et ajoutez ou décommentez la ligne listen_address sous la section globale : concurrent = 4 check_interval = 0 [session_server] session_timeout = 1800 listen_address = "0.0.0.0:9252" La directive listen_address définit l’adresse et le port du point de terminaison des métriques Prometheus. L’utilisation de 0.0.0.0 expose le point de terminaison sur toutes les interfaces ; restreignez-le à une adresse IP spécifique si l’hôte est multi-réseau. Le port 9252 est conventionnel mais peut être n’importe quel port libre. Rayon d’impact : cette modification expose les métriques sur le réseau. Si l’hôte est accessible publiquement, restreignez l’accès avec un pare-feu ou liez-le à localhost ( 127.0.0.1:9252 ) et utilisez un proxy inverse avec authentification. Vérifiez toujours la configuration avant de redémarrer le runner pour éviter une erreur de syntaxe qui mettrait le runner hors ligne. Après modification, validez la syntaxe de la configuration : gitlab-runner verify Sortie attendue : Verifying runner... is alive Si la syntaxe est invalide, la commande signale une erreur et le runner ne démarrera pas. Dans ce cas, annulez la modification avant de continuer. Redémarrez ensuite le runner pour appliquer les modifications : sudo systemctl restart gitlab-runner Vérifiez que le point de terminaison des métriques répond : curl -s http://localhost:9252/metrics | head La sortie attendue inclut des lignes # HELP et # TYPE pour les métriques gitlab_runner_* . Par exemple : # HELP gitlab_runner_jobs_total Total number of jobs handled by the runner # TYPE gitlab_runner_jobs_total counter gitlab_runner_jobs_total{runner="my-docker-runner",state="success"} 123 Si vous voyez connection refused , le runner n’a pas lié le port. Vérifiez /var/log/gitlab-runner/ pour les erreurs et revérifiez la syntaxe de listen_address . Récupération : si le runner ne démarre pas après la modification, restaurez le config.toml précédent à partir de la sauvegarde ou commentez la ligne listen_address , puis redémarrez. Comme cette modification est additive et limitée, la récupération est simple. ## Vérification et diagnostics Avec les métriques disponibles, vous pouvez diagnostiquer la santé et les performances du runner. Commencez par les métriques les plus importantes : le nombre de tâches, la durée des tâches et les taux d’échec. Utilisez curl pour interroger le point de terminaison et grep pour filtrer les métriques pertinentes. Par exemple, pour voir toutes les métriques de compteur pour les tâches échouées : curl -s http://localhost:9252/metrics | grep 'gitlab_runner_jobs_total{.*state="failed"' Sortie attendue : gitlab_runner_jobs_total{runner="my-docker-runner",state="failed"} 7 Cela vous indique que 7 tâches ont échoué sur ce runner depuis son démarrage. Comparez avec le total des tâches et le nombre de réussites pour calculer un taux d’échec. Utilisez le libellé id ou name du runner pour isoler un runner spécifique dans un hôte multi-runners. Une autre métrique clé est la durée des tâches. GitLab Runner expose gitlab_runner_job_duration_seconds sous forme d’histogramme. Pour voir le nombre total de tâches et la durée cumulée, interrogez : curl -s http://localhost:9252/metrics | grep 'gitlab_runner_job_duration_seconds' Exemple de sortie : gitlab_runner_job_duration_seconds_bucket{runner="my-docker-runner",le="60"} 10 gitlab_runner_job_duration_seconds_bucket{runner="my-docker-runner",le="300"} 15 gitlab_runner_job_duration_seconds_bucket{runner="my-docker-runner",le="+Inf"} 23 gitlab_runner_job_duration_seconds_sum{runner="my-docker-runner"} 4500 gitlab_runner_job_duration_seconds_count{runner="my-docker-runner"} 23 Pour calculer la durée moyenne des tâches, divisez _sum par _count . Dans cet exemple, 4500 / 23 = environ 195 secondes. Si vos tâches durent généralement 2 minutes et que la moyenne grimpe à 10 minutes, vous pouvez avoir une contention de ressources ou une latence réseau. Pour un statut en temps réel, utilisez la commande gitlab-runner status sur l’hôte : sudo gitlab-runner status Exemple de sortie : gitlab-runner: Service is running Si le service ne fonctionne pas, vérifiez les journaux systemd : sudo journalctl -u gitlab-runner -n 50 --no-pager Recherchez des entrées ERROR répétées, des délais de connexion à l’instance GitLab ou des échecs d’exécuteur. Vérifiez également que le runner peut joindre GitLab : curl -I https://gitlab.example.com Attendu : HTTP/2 200 ou similaire. Si vous obtenez une erreur de connexion, le runner ne récupérera pas de tâches. Les problèmes réseau sont souvent liés au DNS, au pare-feu ou à une mauvaise configuration du proxy. Les diagnostics doivent toujours inclure un journal horodaté des commandes exécutées et des sorties observées. Utilisez script ou la journalisation du terminal pour conserver des preuves pour l’examen post-incident. ## Modes de défaillance et récupération Les runners échouent de manière prévisible. Voici les modes de défaillance courants, comment les détecter et comment récupérer. ### Runner hors ligne Symptômes : Les tâches attribuées au runner restent en attente. L’interface GitLab affiche le runner comme hors ligne. L’hôte du runner peut toujours être actif. Détection : Sur l’instance GitLab, vérifiez le statut du runner via l’API : curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/runners/all?per_page=100" | jq '.[] | select(.description=="my-docker-runner") | {online, status}' Si online est faux, le runner n’est pas connecté. Sur l’hôte du runner, vérifiez le service : sudo systemctl status gitlab-runner Récupération : Redémarrez le service : sudo systemctl restart gitlab-runner Vérifiez ensuite qu’il est de nouveau en ligne via l’API. Si le runner passe régulièrement hors ligne, vérifiez la connectivité réseau et la validité du jeton d’enregistrement du runner. Un runner peut perdre sa connexion si l’URL de l’instance GitLab change ou si le jeton est révoqué. ### Disque plein sur l’hôte du runner Symptômes : Les tâches échouent avec no space left on device , en particulier pour l’exécuteur Docker où les images et les caches s’accumulent. Détection : Sur l’hôte du runner : df -h /var/lib/docker Recherchez un taux d’utilisation de 100 %. Vérifiez également le répertoire de construction de GitLab Runner : du -sh /home/gitlab-runner/builds Récupération : Nettoyez les ressources Docker inutilisées : docker system prune -af --volumes Avertissement : Cela supprime tous les conteneurs arrêtés, les réseaux inutilisés, les images en attente et les volumes inutilisés. Pour GitLab Runner, cela supprime également le cache de construction. À utiliser avec prudence en production. Une première étape plus sûre consiste à élaguer uniquement les images en attente : docker image prune -f Après le nettoyage, surveillez l’utilisation du disque et envisagez d’ajouter une tâche cron ou logrotate pour éviter la récurrence. Définissez une alerte sur une utilisation du disque supérieure à 80 %. ### Le runner récupère des tâches mais elles attendent dans la file Symptômes : Les tâches restent à l’état en attente même si le runner est en ligne et inactif. La limite concurrent du runner peut être atteinte, ou le runner est mal étiqueté. Détection : Dans l’interface GitLab, vérifiez les tags du runner. Si la tâche a des tags qui ne correspondent pas à ce runner, elle ne sera pas récupérée. Vérifiez également le paramètre concurrent du runner : grep 'concurrent' /etc/gitlab-runner/config.toml Si concurrent = 1 et que plusieurs tâches attendent, le runner traite une tâche à la fois. Récupération : Augmentez concurrent à un nombre plus élevé (par exemple, 4) si l’hôte a la capacité. Modifiez config.toml , vérifiez et redémarrez. Pour faire correspondre les tags, ajoutez le tag requis au runner ou ajustez les tags de la tâche dans .gitlab-ci.yml . Assurez-vous que le runner n’est pas attribué à un projet spécifique s’il doit être partagé. ### Mauvaise configuration de l’exécuteur Symptômes : Les tâches échouent immédiatement avec des erreurs spécifiques à l’exécuteur, par exemple « executor not found » ou « missing docker image ». Détection : Exécutez une tâche de test ou vérifiez l’enregistrement du runner : gitlab-runner list Confirmez que l’exécuteur est correct. Pour l’exécuteur Docker, testez Docker sur l’hôte : docker run hello-world Récupération : Réenregistrez le runner avec le bon exécuteur et les bons paramètres, ou modifiez manuellement config.toml . Pour l’exécuteur Docker, assurez-vous que le démon Docker est en cours d’exécution et que le runner a accès au socket Docker. Après les modifications, vérifiez avec une tâche de pipeline triviale. ## Liste de contrôle des opérations Utilisez cette liste de contrôle comme vérification de santé récurrente pour vos GitLab Runners. Attribuez un seul responsable par élément (pas une équipe) et définissez une cadence de révision : quotidienne pour les éléments critiques, hebdomadaire pour la capacité, mensuelle pour l’inventaire.
ÉlémentResponsableCommande / SignalRésultat attenduAction en cas d’échecFréquence de révision
Service du runner en cours d’exécutionDevOps d’astreinte, par ex. Priya Shahsudo systemctl status gitlab-runnerActif (en cours d’exécution)Redémarrer le service, examiner les journauxQuotidienne
Tous les runners configurés en ligneAdministrateur CI/CD, par ex. Marcus ChenVérification API du champ onlineTous vraisVérifier le réseau, les jetonsQuotidienne
Utilisation du disque sur l’hôte du runnerIngénieur infrastructure, par ex. Lena Ortizdf -h /var/lib/dockerUtilisation < 80 %Élaguer les images, ajouter du disqueHebdomadaire
Durée moyenne des tâches dans le SLOResponsable ingénierie, par ex. David KimPrometheus : sum(gitlab_runner_job_duration_seconds_sum) / sum(gitlab_runner_job_duration_seconds_count)< 10 minExaminer les tâches lentes, la contention des ressourcesHebdomadaire
Taux d’échec des tâches sous le seuilResponsable QA, par ex. Aisha PatelPrometheus : sum(rate(gitlab_runner_jobs_total{state="failed"}[5m])) / sum(rate(gitlab_runner_jobs_total[5m]))< 5 %Examiner les tâches échouées, identifier les tests instables ou l’infrastructureHebdomadaire
Version du runner à jourPropriétaire de la plateforme, par ex. Tom Novakgitlab-runner --versionDans les 2 dernières versions mineuresPlanifier la mise à niveauMensuelle
Exécutez ces vérifications manuellement ou automatisez-les avec une tâche cron qui envoie les résultats à un tableau de bord. Le responsable est chargé d’agir en cas d’échec et de mettre à jour la liste de contrôle si l’environnement change. ## Pièges courants et comment les éviter Plusieurs erreurs récurrentes nuisent à la surveillance de GitLab Runner. Comprendre pourquoi elles se produisent vous aide à les éviter. ### Ignorer complètement le point de terminaison des métriques Pourquoi cela arrive : Les équipes supposent que l’interface GitLab montre suffisamment d’informations. L’interface affiche le statut des tâches et l’état en ligne/hors ligne du runner, mais pas les métriques de performance comme la durée des tâches, le temps d’attente ou les tendances du taux d’échec. Comment éviter : Activez le point de terminaison des métriques Prometheus comme décrit précédemment, même si vous n’avez pas de pile de surveillance complète. Les métriques brutes sont précieuses pour le débogage ad hoc. Récupération : Si vous êtes déjà en situation d’échec, activez les métriques, redémarrez le runner et grattez immédiatement le point de terminaison pour voir les compteurs et histogrammes actuels. ### Alerter sur les mauvaises métriques Pourquoi cela arrive : Les équipes définissent des alertes sur des métriques comme gitlab_runner_jobs_total (un compteur qui augmente toujours) sans appliquer de taux, ou alertent sur un seul runner au lieu d’un agrégat. Cela crée des alertes bruyantes ou sans signification. Comment éviter : Utilisez des expressions PromQL avec rate() pour les compteurs, et réfléchissez à ce qui indique un vrai problème : taux d’échec soutenu au-dessus du seuil, durée des tâches au-dessus du SLO, ou runner hors ligne. Testez les alertes en staging avant la production. Récupération : Si une alerte est trop bruyante, ajustez le seuil ou mettez-la en veille temporairement pendant que vous corrigez la cause racine. Documentez le but et le propriétaire de l’alerte. ### Ne pas surveiller l’hôte du runner lui-même Pourquoi cela arrive : Les équipes surveillent le processus du runner mais oublient le CPU, la mémoire, le disque et le réseau de l’hôte. Un runner peut être en ligne mais privé de ressources, ce qui entraîne des tâches lentes ou des délais d’attente. Comment éviter : Installez un exportateur de nœud (par exemple, node_exporter de Prometheus) sur chaque hôte de runner et incluez les métriques de l’hôte dans vos tableaux de bord et alertes. Récupération : Si l’hôte est déjà contraint, réduisez la concurrence, déplacez certains runners vers d’autres hôtes ou augmentez les ressources. Surveillez l’effet sur la durée des tâches. ### Exécuter des versions obsolètes du runner Pourquoi cela arrive : La mise à niveau des runners est souvent négligée car elle semble à faible risque. Cependant, les anciens runners peuvent manquer de corrections de bogues ou de fonctionnalités qui affectent les performances et la sécurité. Comment éviter : Abonnez-vous aux annonces de version de GitLab et planifiez des mises à niveau trimestrielles. Gardez un environnement de test pour valider les nouvelles versions avant la production. Récupération : Si un runner est obsolète et cause des problèmes, mettez-le à niveau en suivant le guide officiel de mise à niveau. Sauvegardez toujours config.toml d’abord. ### Négliger les problèmes spécifiques à l’exécuteur Pourquoi cela arrive : La surveillance des métriques génériques du runner ne détecte pas les problèmes propres aux exécuteurs Docker, Kubernetes ou shell, comme les échecs du démon Docker, la planification des pods Kubernetes ou la dérive de l’environnement shell. Comment éviter : Incluez des vérifications spécifiques à l’exécuteur dans votre surveillance. Pour Docker, surveillez docker info et les temps de tirage des images. Pour Kubernetes, surveillez le cycle de vie des pods et l’utilisation des ressources. Récupération : Lorsqu’un exécuteur spécifique échoue, vérifiez ses dépendances et ses journaux avant de redémarrer le runner. Pour Docker, redémarrez le démon Docker si nécessaire. Pour Kubernetes, vérifiez la capacité des nœuds et les événements des pods. ## Conclusion La surveillance et les alertes GitLab Runner transforment une boîte noire en système transparent. En versionnant votre inventaire, en activant les métriques en toute sécurité, en diagnostiquant avec des commandes concrètes et en vous préparant aux modes de défaillance courants, vous réduisez les temps d’arrêt des pipelines et augmentez la confiance de l’équipe dans la CI/CD. Ce guide a fourni un processus reproductible : découvrir l’environnement, activer l’observabilité avec un changement minimal, vérifier avec les sorties attendues et documenter les chemins de récupération. La liste de contrôle des opérations et les pièges courants vous donnent un point de départ pour vos propres procédures. Comme prochaine étape, choisissez une vérification à faible risque dans cet article, comme l’activation du point de terminaison des métriques sur un seul runner de test. Enregistrez l’état actuel, appliquez le changement, vérifiez que le point de terminaison répond et observez les métriques. Ensuite, étendez à tous les runners et construisez des tableaux de bord et des alertes adaptés aux SLO de votre équipe. Un flux de travail de surveillance fiable rend les défaillances visibles, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de la récupération avant qu’un incident ne force la décision. Avec ces pratiques, vos GitLab Runners seront une base fiable pour la livraison continue.