Dépanner le réseau GitLab CI/CD avec des exemples pratiques

Intro

Cette version française explique GitLab CI/CD networking troubleshooting with practical examples avec le même objectif pratique que l article source : aider le lecteur à comprendre le contexte, les décisions à prendre et les points à vérifier avant de passer à l action.

Quand des jobs GitLab CI/CD échouent à joindre des dépôts de paquets, des stockages d'artéfacts, des registres de conteneurs ou des API internes, la cause provient souvent du réseau. À l'intérieur d'un Runner, DNS, ports, routage, proxies, TLS et pare-feu ne se comportent pas toujours comme sur un poste développeur. Ce guide fournit des étapes pratiques, sûres et reproductibles pour diagnostiquer ces différences. Vous allez créer un petit job de diagnostic en lecture seule, comparer ses sorties à des résultats attendus et appliquer des changements ciblés sans risquer d'autres parties du pipeline.

L'approche est simple: établir un inventaire clair, exécuter un test pilote étroit, observer le chemin réseau, puis corriger uniquement ce que les preuves indiquent. En gardant le pilote petit et mesurable, vous itérez vite et limitez les retours arrière.

Inventaire des versions et de l'environnement

Avant toute modification, capturez les éléments suivants. Un inventaire constant évite de viser la mauvaise couche.

À consigner

Comment le collecter (exemples Linux)

• Version du Runner et exécuteur (sur l'hôte Runner):

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

• Configuration DNS visible dans les jobs (dans le job):

cat /etc/resolv.conf || true
getent hosts gitlab.com || true

• Environnement lié au proxy (dans le job):

( env | grep -iE '^(http|https|no)_proxy=' || true ) | sort

• Chemins réseau (sur l'hôte Runner ou dans le job si permis):

ip addr show
ip route show
ss -tupan | head -n 50

Extraits Windows Runner

• Résolution DNS:

Resolve-DnsName example.com

• Accessibilité d'un port:

Test-NetConnection example.com -Port 443

Documentez ces constats avec les IDs de job pour comparer runs sains et défaillants.

Chemin de configuration sûr

Le moyen le plus sûr pour dépanner consiste à introduire un petit job de diagnostic en lecture seule qui ne sonde que les endpoints visés. Évitez les changements globaux tant que ce job n'a pas montré la couche fautive.

1) Ajouter un job de diagnostic

Le job suivant utilise des outils Linux standard. Il ne modifie pas l'état du système et échoue clairement en cas de problèmes.

# .gitlab-ci.yml (exemple construit)
stages:
  - verify

net-verify:
  stage: verify
  image: alpine:3.19 # pour l'exécuteur docker; supprimez 'image' en shell
  variables:
    # Définissez les proxies ici uniquement si nécessaire
    # http_proxy: "http://proxy.local:3128"
    # https_proxy: "http://proxy.local:3128"
    # NO_PROXY: ".svc,.cluster.local,10.0.0.0/8,127.0.0.1, localhost"
  before_script:
    - apk add --no-cache bind-tools curl openssl iproute2 busybox-extras
  script:
    - set -euxo pipefail
    - echo "== DNS =="
    - cat /etc/resolv.conf || true
    - dig +short example.com || true
    - echo "== TCP 443 reachability =="
    - nc -vz -w5 example.com 443 || true
    - echo "== TLS handshake and SNI =="
    - echo | openssl s_client -connect example.com:443 -servername example.com -brief 2>/dev/null || true
    - echo "== HTTP HEAD with timing =="
    - curl -fsSILv https://example.com -o /dev/null -w 'code=%{http_code} connect=%{time_connect} ttfb=%{time_starttransfer}\n'
    - echo "== Route and addresses =="
    - ip addr show || true
    - ip route show || true

Notes:

• Remplacez example.com par votre cible réelle (store d'artéfacts, registry, API).
• En exécuteur shell sur hôte verrouillé, installez les outils via le gestionnaire de paquets de l'OS et lancez-les dans le script du job.
• Gardez les secrets hors des lignes de commande. Utilisez des variables CI masquées quand une authentification HTTP(S) est requise.

2) Vérifier le DNS d'abord

Une grande part des échecs de connectivité en CI vient de la résolution de noms. Validez:

• Le job résout les mêmes noms que votre poste.
• Les types de réponse (A vs AAAA) sont cohérents avec votre réseau.
• Le domaine de recherche ne réécrit pas vos noms.

Diagnostics:

getent hosts internal.api.local || true
dig +search internal.api A AAAA +timeout=2 +tries=1 || true

Si des réponses IPv6 arrivent mais que votre réseau ne porte pas IPv6 de bout en bout, privilégiez IPv4 le temps de l'enquête:

curl -4 -fsSIL https://internal.api.local

3) Valider ports et TLS

• Ports: Confirmez que le port cible est ouvert depuis le job.

nc -vz -w3 registry.internal 443 || true

• TLS: Confirmez SNI, chaîne de certificats et protocole. Repérez les erreurs de vérification ou un émetteur inattendu (ex: proxy d'interception d'entreprise).

echo | openssl s_client -connect registry.internal:443 -servername registry.internal -showcerts 2>/dev/null | awk '/Server certificate/ {p=1} p{print}'

Si une CA d'entreprise signe les certificats, installez-la dans l'environnement Runner plutôt que de désactiver la vérification. Sur Debian/Ubuntu, par exemple:

# Écrivez corporate-ca.crt via une variable CI protégée ou une image
sudo cp corporate-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Évitez de désactiver la vérification TLS globalement. Si vous devez la contourner brièvement pour confirmer que seule la confiance pose problème, limitez au strict nécessaire et revenez immédiatement après installation de la CA.

4) Inspecter le routage et le NAT

• Confirmez l'existence d'une route par défaut cohérente:

ip route show

• Tracez le chemin et détectez les trous noirs:

traceroute -n registry.internal || true

• En cas de NAT, demandez à l'équipe NetSec l'IP d'egress du Runner pour vérifier les logs pare-feu. Conservez ce processus hors du job CI; n'utilisez pas de services externes « what is my IP » depuis le pipeline.

5) Gérer les proxies avec discernement

Si vos jobs doivent passer par un proxy, définissez les variables au périmètre minimal qui fonctionne:

variables:
  http_proxy: "http://proxy.local:3128"
  https_proxy: "http://proxy.local:3128"
  NO_PROXY: ".local,.svc,.cluster.local,10.0.0.0/8,127.0.0.1, localhost"

Conseils:

• NO_PROXY accepte des suffixes (.example.com). Listez les hôtes internes et 127.0.0.1 pour éviter de proxyfier les services locaux.
• Si seuls certains jobs ont besoin du proxy, définissez ces variables au niveau du job, pas globalement.
• Certains outils lisent variantes minuscules/majuscules; mettez les deux si doute.

6) Notes spécifiques aux exécuteurs

• Shell executor: le job partage le réseau hôte. Les pare-feu (ufw, nftables, Windows Firewall) impactent directement la connectivité.
• Docker executor: le job tourne derrière un pont user-defined. La résolution de noms, le MTU et le NAT sortant sont contrôlés par le pont Docker et l'hôte. Pour ajouter des autorités de confiance ou des mappings hosts, privilégiez l'image ou la configuration du Runner plutôt que des flags ad hoc.
• Kubernetes executor: des NetworkPolicies peuvent bloquer l'egress. Confirmez les règles d'egress du namespace, les politiques DNS, et la présence éventuelle d'un proxy ou egress gateway.

Vérification et diagnostics

Après chaque changement, relancez le job de diagnostic et comparez ses sorties aux attentes ci-dessous. Gardez des diffs petits et centrés sur l'endpoint testé.

Résultats attendus par couche

Exemples de sorties saines (exemples construits)

• DNS:

$ dig +short registry.internal
10.50.12.34

• TCP:

$ nc -vz -w3 registry.internal 443
registry.internal (10.50.12.34:443) open

• TLS:

$ echo | openssl s_client -connect registry.internal:443 -servername registry.internal -brief
Protocol  : TLSv1.3
Ciphersuite: TLS_AES_256_GCM_SHA384
Server certificate
 subject=CN = registry.internal
 issuer=CN = Corp-Root-CA
 Verification: OK

• Timing HTTP:

$ curl -fsSILv https://registry.internal -o /dev/null -w 'code=%{http_code} connect=%{time_connect} ttfb=%{time_starttransfer}\n'
< HTTP/1.1 200 OK
code=200 connect=0.020 ttfb=0.085

Si les sorties ne correspondent pas, revenez au Chemin de configuration sûr et ne corrigez que la couche concernée.

Modes de panne et remédiation

Retour arrière et reprise

• .gitlab-ci.yml:
• Conservez les changements de diagnostic dans un job verify dédié.
• Pour revenir en arrière, retirez uniquement ce job ou les variables ajoutées.
• Store de confiance du Runner:
• Avant d'ajouter une CA d'entreprise, sauvegardez /etc/ssl/certs et /usr/local/share/ca-certificates (Debian/Ubuntu).
• Pour revenir en arrière, supprimez la CA ajoutée et relancez update-ca-certificates.
• Proxies:
• Retirez les variables de job pour revenir au comportement antérieur.
• Réglages Docker/Kubernetes:
• Sauvegardez la configuration du Runner avant modification.
• Restaurez le fichier précédent et redémarrez le Runner si besoin.

Relancez toujours le job de diagnostic après rollback pour confirmer le retour à la ligne de base.

Checklist d'exploitation

1. Inventaire

• Noter versions GitLab et Runner, exécuteur, OS, résolveurs DNS et variables proxy.
• Capturer l'IP d'egress attendue auprès du NetSec si applicable.

1. Préparer le diagnostic

• Ajouter un job verify exécutant dig, nc, openssl s_client, curl, ip route.
• Limiter la portée aux endpoint(s) ciblés. Pas de secrets en clair.

1. Exécuter et observer

• Sauvegarder les logs de job. Comparer réponses DNS, statut TCP, chaîne TLS, codes HTTP et temps.
• Noter les différences entre Runners ou environnements.

1. Correctifs ciblés

• DNS: corriger les résolveurs ou la politique DNS du Runner.
• Ports: demander les règles d'egress; tester avec nc.
• TLS: installer la CA d'entreprise dans le store du Runner.
• Proxies: définir http_proxy/https_proxy/NO_PROXY au niveau du job.
• Routage: corriger la route par défaut ou le pare-feu hôte; relancer traceroute.

1. Vérifier et documenter

• Relancer le job verify; confirmer que les sorties répondent aux attentes.
• Consigner ce qui a changé et garder le job pour de futurs contrôles.

1. Revenir en arrière si besoin

• Revert uniquement les changements introduits.
• Confirmer la ligne de base en relançant le job verify.

Conclusion

Le réseau dans GitLab CI/CD diffère des postes développeurs de manière subtile mais significative. En consignant un inventaire clair, en introduisant un job de diagnostic étroit et en validant chaque couche dans l'ordre (DNS, ports, TLS, routage, proxies, pare-feu), vous isolez rapidement les causes et corrigez avec un risque minimal. Conservez ce job dans votre dépôt pour valider de nouveaux environnements, Runners ou endpoints. En cas de récidive, suivez la checklist pour reproduire, appliquer des corrections ciblées et confirmer les résultats.