Dépannage réseau de GitLab Runner : guide pratique de terrain

Introduction

Lorsqu'un GitLab Runner cesse soudainement de traiter des tâches, la cause n'est souvent pas le runner lui-même, mais le chemin réseau entre le runner, GitLab et les services externes tels que les registres de conteneurs ou les miroirs de paquets. Ce guide propose une approche pratique, axée sur les commandes, pour diagnostiquer et corriger les problèmes réseau de GitLab Runner. Il s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui doivent passer d'un problème observé à un résultat vérifié sans deviner.

L'accent est mis sur la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des paramètres fictifs au lieu de secrets, vérifier le résultat et documenter la procédure de récupération si l'état attendu n'est pas atteint. Nous aborderons la résolution DNS, la vérification des ports, la connectivité à GitLab, la configuration des proxies, la mise en réseau de Docker et Kubernetes, et fournirons une liste de contrôle ainsi que les pièges courants.

Chaque exemple utilise des paramètres fictifs explicites comme <gitlab.example.com> ou <runner-ip> ; remplacez-les par vos valeurs réelles. Ne placez jamais de véritables identifiants, jetons, clés privées ou identifiants de production dans des scripts ou de la documentation.

Inventaire des versions et de l'environnement

Avant de toucher à quoi que ce soit, établissez avec quoi vous travaillez. Connaissez la version de GitLab Runner, le système d'exploitation hôte, l'exécuteur (shell, Docker, Kubernetes, etc.) et l'emplacement du runner dans la topologie réseau. Un mauvais diagnostic commence souvent par supposer une version ou une topologie qui n'est pas présente.

Étape 1 : Identifier la version installée

Exécutez cette commande sur la machine où le runner est installé :

gitlab-runner --version

Exemple de sortie attendue :

Version:      16.4.0
Git revision: 1a2b3c4d
Git branch:   16-4-stable
GO version:   go1.20.5
Built:        2023-09-22T14:30:00Z
OS/Arch:      linux/amd64

Si la commande n'est pas trouvée, le runner n'est pas installé ou n'est pas dans le PATH. Vérifiez les emplacements courants : /usr/local/bin/gitlab-runner, /usr/bin/gitlab-runner, ou le répertoire d'installation que vous avez utilisé.

Étape 2 : Déterminer la topologie de déploiement

Demandez-vous : ce runner est-il installé directement sur une VM ou un hôte bare-metal, ou s'exécute-t-il dans un conteneur ? Est-ce un runner partagé géré par GitLab, un runner de groupe ou un runner spécifique à un projet ? Le chemin réseau est différent dans chaque cas.

Pour un runner basé sur Docker, exécutez :

docker ps --filter "name=gitlab-runner" --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

Cela affiche le nom du conteneur du runner, l'image et l'état. Si le conteneur redémarre en boucle, c'est un signal pour inspecter les journaux : docker logs <nom-du-conteneur>.

Pour un runner basé sur Kubernetes, vérifiez l'état du pod :

kubectl get pods -n gitlab-runner -o wide

Recherchez les pods en CrashLoopBackOff, Pending, ou avec des redémarrages. L'option -o wide affiche l'IP du nœud et l'IP du pod, utiles pour diagnostiquer la connectivité entre nœuds.

Étape 3 : Capturer l'état observable actuel avec des commandes en lecture seule

Utilisez des commandes qui ne modifient pas la configuration :

• ip addr show ou ifconfig pour lister les interfaces réseau et les IP.
• ip route show pour afficher la table de routage.
• cat /etc/resolv.conf pour voir les serveurs DNS.
• ss -tulpn | grep gitlab-runner pour voir les ports en écoute (le cas échéant).
• systemctl status gitlab-runner (systemd) ou service gitlab-runner status (SysV) pour voir l'état du service.

Enregistrez la sortie et l'horodatage. Si vous devez partager des journaux avec le support, expurgez les informations sensibles.

Étape 4 : Définir le résultat attendu et le signal d'échec

Avant d'apporter des modifications, écrivez ce à quoi ressemble un runner sain dans votre environnement. Par exemple :

• Attendu : gitlab-runner verify renvoie Verifying runner... is alive.
• Signal d'échec : ERROR: Failed to register this runner. Perhaps you are having network problems.

Cette étape vous oblige à réfléchir à l'état cible, pas seulement à l'erreur immédiate.

Chemin de configuration sûr

Les modifications de configuration doivent être petites, limitées et réversibles. Avant de modifier config.toml, connaissez ses valeurs actuelles et disposez d'une sauvegarde.

Lire la configuration actuelle

Le fichier de configuration principal est généralement /etc/gitlab-runner/config.toml. Affichez-le avec :

sudo cat /etc/gitlab-runner/config.toml

Notez les sections [[runners]], en particulier url, token, executor, et les éventuelles entrées pre_clone_script, environment ou extra_hosts. Pour l'exécuteur Docker, les paramètres network_mode et dns sont importants.

Effectuer une sauvegarde

Avant toute modification :

sudo cp /etc/gitlab-runner/config.toml /etc/gitlab-runner/config.toml.bak.$(date +%Y%m%d%H%M%S)

Cela vous donne un chemin de récupération rapide : restaurez la sauvegarde et redémarrez le runner.

Exemple de modification : ajouter un serveur DNS personnalisé pour l'exécuteur Docker

Si les tâches du runner échouent à résoudre des noms d'hôtes internes, vous pouvez ajouter un serveur DNS dans la configuration Docker du runner. Dans config.toml, trouvez la section [[runners]] et ajoutez ou modifiez dns :

[[runners]]
  name = "my-docker-runner"
  url = "https://gitlab.example.com/"
  token = "REDACTED"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    dns = ["10.0.0.2", "8.8.8.8"]

Après modification, validez la syntaxe TOML :

gitlab-runner verify

Ou utilisez un analyseur TOML si disponible. Ensuite, redémarrez le runner :

sudo systemctl restart gitlab-runner

Vérifiez que le runner se reconnecte :

sudo gitlab-runner status

Attendu : gitlab-runner: Service is running.

Si le runner ne démarre pas, restaurez la sauvegarde et consultez les journaux : journalctl -u gitlab-runner -n 50 --no-pager.

Exemple de modification : ajuster le mode réseau pour l'exécuteur Docker

Parfois, les tâches ne peuvent pas atteindre les services sur le réseau de l'hôte car le réseau bridge par défaut les isole. Passer network_mode à host peut résoudre le problème, mais soyez conscient des implications de sécurité. Dans config.toml :

[runners.docker]
  network_mode = "host"

Rayon d'impact : l'utilisation du réseau hôte signifie que les conteneurs partagent la pile réseau de l'hôte, ce qui peut exposer des ports hôtes ou entrer en conflit avec d'autres services. À utiliser uniquement après avoir vérifié que le réseau ponté n'est pas nécessaire pour l'isolation. Documentez la décision et la date de révision.

Vérification et retour en arrière

Après toute modification de configuration, exécutez une tâche de test ou au moins un gitlab-runner verify. Si la modification ne produit pas le résultat attendu, revenez en arrière :

sudo cp /etc/gitlab-runner/config.toml.bak.<horodatage> /etc/gitlab-runner/config.toml
sudo systemctl restart gitlab-runner

Ne modifiez jamais config.toml à la main sur un runner de production actif sans sauvegarde et sans fenêtre de maintenance.

Vérification et diagnostics

Les problèmes réseau se manifestent souvent par : le runner ne peut pas s'enregistrer, le runner ne peut pas se connecter à GitLab, les tâches échouent à cloner le dépôt, ou les tâches ne peuvent pas atteindre les services externes. Utilisez ces vérifications ciblées.

1. Tester la connectivité à GitLab

Le runner doit atteindre le point de terminaison HTTP(S) de l'instance GitLab. Depuis l'hôte du runner (ou à l'intérieur du conteneur du runner), exécutez :

curl -I https://gitlab.example.com

Attendu : HTTP/1.1 200 OK ou redirection 302 vers la connexion. Si vous obtenez Could not resolve host, le DNS échoue. Si la connexion expire, un problème de pare-feu ou de routage est probable. Si vous obtenez une erreur de certificat SSL, l'autorité de certification n'est pas approuvée.

Pour une vérification TLS plus détaillée :

echo | openssl s_client -connect gitlab.example.com:443 -servername gitlab.example.com 2>/dev/null | openssl x509 -noout -dates -subject

Cela affiche les dates de validité du certificat et le sujet, aidant à détecter les certificats expirés ou les incohérences de nom d'hôte.

2. Tester la résolution DNS

Depuis l'hôte du runner, résolvez le nom d'hôte de GitLab :

nslookup gitlab.example.com

Ou avec dig :

dig +short gitlab.example.com

En l'absence de réponse, vérifiez /etc/resolv.conf et /etc/hosts. Pour l'exécuteur Docker, le DNS utilisé dans les tâches peut différer ; testez à l'intérieur d'une tâche ou d'un conteneur temporaire :

docker run --rm alpine nslookup gitlab.example.com

Si l'hôte résout mais pas le conteneur, la configuration DNS du démon Docker est incorrecte. Corrigez en ajustant dns dans config.toml ou les paramètres du démon Docker.

3. Tester l'accessibilité des ports

GitLab Runner a généralement besoin d'un accès HTTPS sortant (443) et éventuellement SSH (22) si l'URL SSH est utilisée pour le dépôt. Utilisez nc (netcat) ou telnet :

nc -zv gitlab.example.com 443

Attendu : Connection to gitlab.example.com 443 port [tcp/https] succeeded!

Sinon, testez avec telnet gitlab.example.com 443. Un pare-feu peut bloquer. Utilisez traceroute pour voir où les paquets s'arrêtent :

traceroute -n -T -p 443 gitlab.example.com

4. Vérifier l'enregistrement du runner et le jeton

Le jeton du runner est utilisé pour s'authentifier auprès de GitLab. Si le jeton est invalide ou si le runner n'est pas enregistré, il ne se connectera pas. Exécutez :

sudo gitlab-runner verify

Attendu : Verifying runner... is alive. Si vous voyez ERROR: Verifying runner... failed, vérifiez le jeton dans config.toml et comparez avec l'interface GitLab sous Paramètres > CI/CD > Runners. Ne partagez pas le jeton.

5. Inspecter les journaux

Les journaux du runner sont essentiels. Pour systemd :

journalctl -u gitlab-runner -f

Pour un runner Docker :

docker logs -f gitlab-runner

Recherchez des lignes comme :

ERROR: Failed to register this runner. Perhaps you are having network problems
ERROR: Registering runner... failed runner=xxxx status=couldn't execute POST

Celles-ci indiquent des problèmes de connectivité ou d'authentification. Pour les erreurs réseau au niveau des tâches, consultez les journaux des tâches ; ils peuvent montrer des échecs de résolution de noms, des erreurs TLS ou des délais d'attente.

6. Tester depuis une tâche

Créez une tâche de test simple dans .gitlab-ci.yml pour exécuter des diagnostics réseau dans l'environnement CI :

network-test:
  script:
    - nslookup gitlab.example.com
    - curl -I https://gitlab.example.com
    - nc -zv registry.example.com 443

Exécutez la tâche et examinez la sortie. Cela révèle rapidement si le problème est au niveau du runner ou de la tâche.

Modes de défaillance et récupération

Voici les modes de défaillance réseau courants avec les symptômes, les causes et les étapes de récupération.

A. Échec de résolution DNS

Symptôme : curl: (6) Could not resolve host: gitlab.example.com ; nslookup renvoie server can't find gitlab.example.com: NXDOMAIN.

Causes possibles :

• Serveurs DNS incorrects dans /etc/resolv.conf ou le démon Docker.
• Serveur DNS injoignable à cause d'un pare-feu.
• Nom d'hôte absent du DNS ou entrée manquante dans /etc/hosts.

Récupération :

• Vérifiez les IP des serveurs DNS et leur accessibilité : ping <dns-ip> (si ICMP autorisé) ou nc -zv <dns-ip> 53.
• Ajoutez le bon serveur de noms dans /etc/resolv.conf ou la configuration Docker.
• Pour une correction temporaire, ajoutez dans /etc/hosts :

  192.0.2.10 gitlab.example.com

Mais ce n'est pas évolutif ; préférez un DNS approprié.

• Documentez le responsable de la configuration DNS et révisez trimestriellement.

B. Délai de connexion à GitLab

Symptôme : curl: (7) Failed to connect to gitlab.example.com port 443: Connection timed out.

Causes possibles :

• Pare-feu/groupe de sécurité bloquant le port sortant 443.
• Pas de route vers l'hôte (route manquante, mauvaise passerelle).
• Service GitLab en panne ou écoutant sur un port différent.

Récupération :

• Vérifiez les règles du groupe de sécurité (cloud) ou iptables/firewalld sur l'hôte.
• Vérifiez la table de routage : ip route show ; assurez-vous qu'une route par défaut existe.
• Testez avec telnet gitlab.example.com 443 depuis une machine qui peut se connecter pour isoler.
• Si GitLab est derrière un proxy, assurez-vous que le runner a les paramètres de proxy.

C. Erreurs de certificat TLS

Symptôme : curl: (60) SSL certificate problem: unable to get local issuer certificate.

Causes possibles :

• Autorité de certification auto-signée ou interne non approuvée.
• Certificat expiré ou incohérence de nom d'hôte.

Récupération :

• Pour un certificat auto-signé, ajoutez l'autorité de certification au magasin de confiance du système ou configurez le runner pour utiliser ca_file dans config.toml :

  [[runners]]
    url = "https://gitlab.example.com/"
    tls-ca-file = "/etc/gitlab-runner/certs/ca.crt"

Puis redémarrez le runner.

• Vérifiez les dates du certificat : openssl s_client -connect gitlab.example.com:443 | openssl x509 -noout -dates.
• Ne désactivez pas la vérification TLS (tls-skip-verify) sauf en cas de nécessité absolue et avec un plan pour corriger la cause racine.

D. Mauvaise configuration du proxy

Symptôme : Le runner se connecte à GitLab, mais les tâches échouent à atteindre les sites externes ; les journaux du runner montrent des erreurs de proxy.

Causes possibles :

• Variables d'environnement HTTP_PROXY, HTTPS_PROXY, NO_PROXY non définies ou incorrectement définies.
• Le proxy nécessite une authentification non fournie.

Récupération :

• Définissez le proxy dans le config.toml du runner sous [[runners]] :

  environment = ["HTTP_PROXY=http://proxy.example.com:3128", "HTTPS_PROXY=http://proxy.example.com:3128", "NO_PROXY=localhost,127.0.0.1,.example.com"]

Ou définissez-le dans l'exécuteur Docker via env ou pre_build_script.

• Assurez-vous que NO_PROXY inclut le nom d'hôte de GitLab si GitLab est interne.
• Testez avec curl -x http://proxy.example.com:3128 https://gitlab.example.com.

E. Problèmes de réseau Docker

Symptôme : Les tâches ne peuvent pas atteindre les services de l'hôte ou d'autres conteneurs ; le DNS dans les conteneurs échoue.

Causes possibles :

• Isolation du réseau ponté par défaut.
• Paramètres DNS du démon Docker.
• Mappage de port non défini pour les conteneurs de service.

Récupération :

• Utilisez network_mode = "host" (avec prudence) ou définissez un réseau personnalisé dans la configuration de l'exécuteur Docker :

  [runners.docker]
    network_mode = "bridge"
    dns = ["10.0.0.2"]

• Pour les services, utilisez links ou définissez un réseau dans docker-compose si utilisé.
• Testez depuis un conteneur temporaire : docker run --rm --network=host alpine nslookup gitlab.example.com.

F. Pare-feu sur l'hôte du runner

Symptôme : Le runner ne peut pas établir de connexions sortantes, mais d'autres hôtes le peuvent.

Causes possibles : des règles de pare-feu locales bloquent la sortie.

Récupération :

• Pour iptables : sudo iptables -L -n -v pour voir les règles ; ajoutez des règles sortantes autorisées.
• Pour firewalld : sudo firewall-cmd --list-all ; assurez-vous que les services http et https sont autorisés.
• Pour les groupes de sécurité cloud, examinez les règles de sortie.
• Documentez les modifications dans la gestion des changements.

Chaque étape de récupération doit être suivie d'une vérification : réexécutez la commande échouée ou la tâche de test pour confirmer que le problème est résolu.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle avant, pendant et après le dépannage. Attribuez un responsable unique pour chaque élément et définissez une fréquence de révision.

Utilisez ce tableau comme modèle ; adaptez les responsables et les fréquences à votre équipe. L'essentiel est d'avoir une personne nommée responsable de chaque domaine et une révision régulière pour détecter les dérives.

Pièges courants et comment les éviter

De nombreux problèmes réseau persistent à cause d'erreurs évitables. Voici les plus fréquents, pourquoi ils surviennent et comment les prévenir ou s'en remettre.

Piège 1 : Supposer que le problème vient du runner alors qu'il vient du réseau

Pourquoi cela arrive : les équipes voient une tâche échouée et redémarrent immédiatement le runner ou le réinstallent, sans vérifier la connectivité de base. Cela fait perdre du temps et peut masquer temporairement le vrai problème.

Comment l'éviter : commencez toujours par les diagnostics réseau : DNS, curl, tests de ports et journaux. Seulement après avoir écarté le réseau, touchez à la configuration du runner.

Récupération : si vous avez déjà redémarré et que le problème persiste, parcourez systématiquement la section Vérification et diagnostics ; ne sautez pas d'étapes.

Piège 2 : Modifier config.toml sans sauvegarde

Pourquoi cela arrive : dans l'urgence, les opérateurs modifient le fichier directement et ne peuvent ensuite pas revenir en arrière, ou ils introduisent des erreurs de syntaxe qui cassent complètement le runner.

Comment l'éviter : copiez toujours le fichier vers une sauvegarde horodatée avant de le modifier. Utilisez un linter TOML ou gitlab-runner verify après les modifications. Conservez les sauvegardes pendant au moins 30 jours.

Récupération : si le runner ne démarre pas après une modification, restaurez la sauvegarde et redémarrez. Examinez l'erreur dans les journaux pour comprendre ce qui n'a pas fonctionné.

Piège 3 : Ignorer les paramètres de proxy dans les tâches CI

Pourquoi cela arrive : l'hôte du runner peut avoir des variables d'environnement de proxy définies, mais les tâches de l'exécuteur Docker n'en héritent souvent pas. Les développeurs s'attendent à ce que les tâches se comportent comme leur shell local.

Comment l'éviter : définissez explicitement les variables de proxy dans la configuration du runner ou les scripts de tâche. Utilisez NO_PROXY pour exclure les adresses internes. Testez depuis une tâche, pas seulement depuis l'hôte.

Récupération : vérifiez les journaux des tâches pour les échecs de téléchargement ou les erreurs DNS. Ajoutez l'environnement de proxy au config.toml du runner ou utilisez un before_script pour les définir.

Piège 4 : Ne pas isoler les problèmes DNS entre l'hôte et le conteneur

Pourquoi cela arrive : nslookup fonctionne sur l'hôte, donc les opérateurs concluent que le DNS est correct, mais les conteneurs utilisent le DNS du démon Docker (souvent 8.8.8.8 ou le DNS interne de Docker) et ne peuvent pas résoudre les noms internes.

Comment l'éviter : testez le DNS depuis un conteneur qui imite l'environnement du runner. Utilisez docker run --rm alpine nslookup ... ou exécutez une tâche de test.

Récupération : configurez dns dans [runners.docker] pour utiliser des serveurs DNS internes, ou définissez le DNS du démon Docker globalement.

Piège 5 : Trop de changements à la fois

Pourquoi cela arrive : sous pression, les opérateurs modifient les règles de pare-feu, le DNS, le proxy et la configuration du runner en même temps ; si le problème est résolu, ils ne savent pas quel changement l'a corrigé, et si ça casse, ils ne savent pas lequel annuler.

Comment l'éviter : faites un changement à la fois, vérifiez après chacun et documentez. Utilisez la liste de contrôle pour suivre.

Récupération : si vous êtes dans un imbroglio de changements multiples, revenez à la dernière bonne sauvegarde connue de chaque composant modifié un par un, en testant après chaque retour en arrière.

Piège 6 : Coder en dur les adresses IP au lieu d'utiliser le DNS

Pourquoi cela arrive : pour « corriger rapidement » les problèmes DNS, quelqu'un ajoute une IP dans /etc/hosts ou dans le code. Plus tard, l'IP change et tout casse mystérieusement.

Comment l'éviter : corrigez correctement le DNS ; utilisez des noms d'hôte dans la configuration. Si vous devez utiliser /etc/hosts temporairement, ajoutez un commentaire avec la date et la raison, et planifiez une correction permanente.

Récupération : recherchez les IP codées en dur dans config.toml, les scripts CI et /etc/hosts ; remplacez-les par des noms d'hôte et assurez-vous que le DNS fonctionne.

Conclusion

Un dépannage réseau efficace de GitLab Runner est un processus discipliné, pas une collection de commandes aléatoires. Il nécessite de connaître votre environnement, d'observer l'état actuel avec des commandes en lecture seule, d'apporter des modifications petites et réversibles, de vérifier chaque étape et de documenter les chemins de récupération.

Les compétences et les listes de contrôle de ce guide s'appliquent à GitLab auto-hébergé, aux runners cloud et aux configurations hybrides. En suivant l'inventaire des versions et de l'environnement, les pratiques de configuration sûres, les diagnostics ciblés et un plan de récupération clair, vous réduisez les temps d'arrêt et gagnez en confiance dans votre infrastructure CI/CD.

Comme prochaine étape, choisissez une vérification à faible risque dans la liste de contrôle opérationnelle et exécutez-la aujourd'hui. Enregistrez l'état actuel, exécutez la vérification, comparez la sortie au résultat attendu et notez les écarts. Ensuite, attribuez un responsable et définissez une date de révision. Avec le temps, cette pratique rendra les problèmes réseau rares et rapides à résoudre.