🛠️ PLAN D'IMPLÉMENTATION — PD-12
📚 Navigation User Story
| Document | | | ---------- | -- | | 📋 Spécification | [PD-12-specification.md](PD-12-specification.md) | | 🛠️ **Plan d'implémentation** | *(ce document)* | | ✅ Critères d'acceptation | [PD-12-acceptability.md](PD-12-acceptability.md) | | 📝 Retour d'expérience | [PD-12-rex.md](PD-12-rex.md) | [← Retour à infrastructure-souveraine](../PD-193-epic.md) · [↑ Index User Story](index.md)
PD-12 — Configuration GitLab Runner pour CI/CD
1. Découpage en composants
1.1 Composants infrastructure
| Composant | Description | Fichiers |
| VPS Principal | Héberge les runners Docker et Shell avec accès réseau interne | 51.68.126.160 |
| VPS Internet | VPS isolé pour runner sans accès réseau interne | vps-97f12e3e.vps.ovh.net |
| Docker Engine | Runtime d'exécution des conteneurs CI/CD | Installé via Ansible |
| GitLab Runner Service | Agent d'exécution des jobs | gitlab-runner systemd |
1.2 Composants configuration
| Composant | Rôle | Fichier |
| config.toml (principal) | Configuration runners Docker + Shell | config.toml.j2 |
| config-internet-only.toml | Configuration runner isolé | config-internet-only.toml.j2 |
| Ansible Playbook principal | Déploiement runners VPS principal | setup_gitlab_complete.yml |
| Ansible Playbook internet | Déploiement runner isolé | setup_internet_runner.yml |
1.3 Composants secrets
| Composant | Stockage | Chemin |
| Runner tokens | Ansible Vault | vault.yml |
| VPS credentials | HashiCorp Vault | kv/ci/vps-internet |
| CI/CD variables | GitLab CI/CD Variables | Projet/Groupe GitLab |
2. Flux techniques
2.1 Flux d'enregistrement du Runner
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Administrateur │ → │ GitLab Web UI │ → │ Génération │
│ │ │ (Settings) │ │ token runner │
└─────────────┘ └──────────────┘ └──────┬──────┘
│
┌────────────────────────┘
▼
┌──────────────────────────────┐
│ Stockage token dans vault.yml │
│ (Ansible Vault chiffré) │
└──────────────┬───────────────┘
│
▼
┌───────────────────────┐
│ ansible-playbook │
│ setup_gitlab_complete │
└───────────┬───────────┘
│
┌─────────────┴─────────────┐
▼ ▼
┌───────────────────────┐ ┌───────────────────────┐
│ Génération config.toml │ │ systemctl restart │
│ depuis template j2 │ │ gitlab-runner │
└───────────────────────┘ └───────────────────────┘
│
▼
┌───────────────────────┐
│ gitlab-runner verify │
│ → Runner visible GitLab │
└───────────────────────┘
2.2 Flux d'exécution d'un job (Docker executor)
┌───────────┐ ┌────────────┐ ┌───────────────┐
│ git push │ → │ GitLab CI │ → │ Pipeline créé │
└───────────┘ └────────────┘ └───────┬───────┘
│
┌───────────────────────┘
▼
┌────────────────────────┐
│ Job assigné au runner │
│ (matching tags) │
└───────────┬────────────┘
│
▼
┌────────────────────────┐
│ docker pull <image> │
│ (if-not-present) │
└───────────┬────────────┘
│
▼
┌────────────────────────┐
│ docker run │
│ --network=bridge|host │
│ --volumes /cache │
│ --env CI_* │
└───────────┬────────────┘
│
┌───────────┴───────────┐
│ │
▼ ▼
┌───────────────┐ ┌───────────────┐
│ Exécution job │ │ Injection │
│ (script) │ │ secrets │
└───────┬───────┘ │ (masked) │
│ └───────────────┘
▼
┌───────────────────────┐
│ Upload artifacts/cache │
│ → GitLab │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ docker rm <container> │
│ (conteneur éphémère) │
└───────────────────────┘
2.3 Flux de gestion du cache
┌─────────────────────────────────────────────────┐
│ Job démarre avec cache: key: $CI_COMMIT_REF_SLUG │
└───────────────────────┬─────────────────────────┘
│
▼
┌───────────────────────────────┐
│ Recherche cache existant │
│ /home/gitlab-runner/cache/ │
│ ou cache S3/GCS (si configuré)│
└───────────────┬───────────────┘
│
┌─────────────┴─────────────┐
│ Cache trouvé? │
└─────────────┬─────────────┘
│ │
┌───┘ └───┐
▼ ▼
┌───────────────┐ ┌───────────────┐
│ Restauration │ │ Cache miss │
│ cache → /cache│ │ (départ vide) │
└───────┬───────┘ └───────┬───────┘
│ │
└────────┬───────────┘
▼
┌───────────────────┐
│ Exécution job │
└─────────┬─────────┘
▼
┌───────────────────┐
│ Upload cache si │
│ policy: push │
└───────────────────┘
2.4 Flux d'accès aux secrets
┌──────────────────────────────────────────────────────────┐
│ GitLab CI/CD Variables │
│ (Project/Group Settings → CI/CD → Variables) │
├──────────────────────────────────────────────────────────┤
│ Variable: SSH_PRIVATE_KEY │
│ Type: Variable │
│ Protected: ✓ (branches protégées uniquement) │
│ Masked: ✓ (masqué dans les logs) │
│ Scope: Environment: production │
└────────────────────────────┬─────────────────────────────┘
│
▼
┌───────────────────────┐
│ Job runner démarre │
│ script: │
│ echo "$SSH_KEY" │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ GitLab injecte │
│ $SSH_PRIVATE_KEY │
│ comme env var │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Si echo $SSH_KEY: │
│ → [MASKED] dans logs │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Fin du job │
│ → conteneur détruit │
│ → env vars perdues │
└───────────────────────┘
3. Mapping invariants → mécanismes
| # | Invariant | Mécanisme technique | Implémentation |
| INV-1 | Le Runner ne doit jamais exposer de secrets en clair dans les logs | GitLab CI/CD Variables masquées | Variables marquées Masked: true dans GitLab UI |
| INV-2 | Jobs CI/CD exécutés dans un environnement isolé | Docker executor avec conteneurs éphémères | executor = "docker" + conteneur détruit après chaque job |
| INV-3 | Aucun job ne peut accéder aux données persistantes d'un autre job | Volumes éphémères + network isolation | network_mode = "bridge" pour runner internet, volumes non partagés |
| INV-4 | Toute exécution de job doit être traçable | Variables CI_* automatiques de GitLab | CI_PIPELINE_ID, CI_JOB_ID, CI_COMMIT_SHA injectées automatiquement |
| INV-5 | Secrets révocables sans redéploiement du Runner | GitLab CI/CD Variables dynamiques | Modification via GitLab UI, effet immédiat au prochain job |
| INV-6 | Le Runner n'exécute que des jobs explicitement autorisés | Tags runner + run_untagged = false | Seuls les jobs avec tag correspondant sont exécutés |
| INV-7 | Toute règle vérifiable par test ou audit | Scénarios de test + journalisation | Logs journalctl -u gitlab-runner, audit GitLab |
3.1 Détail des mécanismes de sécurité
Isolation réseau (INV-2, INV-3)
# config-internet-only.toml.j2
[runners.docker]
privileged = false # Pas d'accès kernel
network_mode = "bridge" # Réseau isolé
dns = ["8.8.8.8", "1.1.1.1"] # DNS publics uniquement
extra_hosts = ["169.254.169.254:127.0.0.1"] # Bloque metadata cloud
Masquage des secrets (INV-1)
# GitLab CI/CD Variables
SSH_PRIVATE_KEY:
value: "-----BEGIN RSA..."
masked: true # → [MASKED] dans logs
protected: true # → branches protégées seulement
Traçabilité (INV-4)
Variables injectées automatiquement par GitLab :
CI_PIPELINE_ID : Identifiant unique du pipelineCI_JOB_ID : Identifiant unique du jobCI_COMMIT_SHA : Hash du commitCI_RUNNER_ID : ID du runner ayant exécutéCI_JOB_STARTED_AT : Timestamp de démarrage
4. Gestion des erreurs
| Cas d'erreur | Détection | Action | Message |
| Échec enregistrement runner | gitlab-runner verify retourne erreur | Re-générer token dans GitLab | ERROR: Verifying runner... is removed |
| Job assigné à runner indisponible | Runner offline dans GitLab UI | Vérifier systemctl status gitlab-runner | Job reste en queue "pending" |
| Échec création conteneur Docker | Job échoue avec erreur Docker | Vérifier docker info, espace disque | ERROR: Cannot connect to Docker daemon |
| Cache indisponible/corrompu | Job échoue à restore cache | Cache miss automatique, rebuild | WARNING: Cache file does not exist |
| Secret manquant | Variable non définie | Vérifier CI/CD Variables GitLab | Error: variable XXX is not defined |
| Accès non autorisé à secret | Variable protégée sur branche non protégée | Étendre scope ou protéger branche | Job échoue, variable non injectée |
| Échec communication GitLab-Runner | Timeout, runner offline | Vérifier connectivité réseau | ERROR: Fetching job failed |
Procédure de diagnostic
# 1. État du service
sudo systemctl status gitlab-runner
# 2. Logs détaillés
sudo journalctl -u gitlab-runner -f --since "10 minutes ago"
# 3. Vérification de l'enregistrement
sudo gitlab-runner verify
# 4. Test de connectivité
curl -I https://gitlab.com
# 5. État Docker
docker info
docker ps -a
df -h # Espace disque
# 6. Liste des runners configurés
sudo gitlab-runner list
5. Impacts sécurité
5.1 Surface d'attaque
| Vecteur | Risque | Mitigation |
| Conteneur Docker compromis | Escalade vers host | privileged = false, network_mode = bridge |
| Fuite de secrets dans logs | Exposition credentials | Variables masked: true obligatoires |
| Accès métadonnées cloud | Vol credentials IAM | extra_hosts = ["169.254.169.254:127.0.0.1"] |
| Accès réseau interne | Pivot vers services internes | Runner internet sur VPS séparé |
| Token runner volé | Exécution jobs malveillants | run_untagged = false, tags spécifiques |
5.2 Séparation des runners
┌─────────────────────────────────────────────────────────┐
│ VPS Principal (51.68.126.160) │
│ Accès: VPN CloudHSM, PostgreSQL, Redis, services internes │
├─────────────────────────────────────────────────────────┤
│ • ovh-docker : privileged=true, network=host │
│ → Build Docker, tests d'intégration, HSM │
│ • ovh-shell : executor=shell │
│ → Terraform, Ansible, SSH vers autres VPS │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ VPS Internet (vps-97f12e3e) │
│ Accès: Internet public UNIQUEMENT │
├─────────────────────────────────────────────────────────┤
│ • ovh-internet : privileged=false, network=bridge │
│ → Lint, docs, tests externes sans secrets internes │
└─────────────────────────────────────────────────────────┘
5.3 Checklist sécurité
6. Hypothèses techniques
6.1 Hypothèses validées
| # | Hypothèse | Statut | Validation |
| H1 | Instance GitLab.com fonctionnelle | ✅ Validé | SLA GitLab 99.95% |
| H2 | VPS OVH accessibles et opérationnels | ✅ Validé | Monitoring OVH |
| H3 | Pipelines CI/CD définis en amont | ✅ Validé | .gitlab-ci.yml existants |
| H4 | Utilisateurs GitLab avec droits nécessaires | ✅ Validé | Rôle Maintainer minimum |
6.2 Hypothèses à valider à l'implémentation
| # | Hypothèse | Impact si fausse |
| H5 | Espace disque suffisant pour cache (80GB) | Ajout volume ou nettoyage automatique |
| H6 | Bande passante suffisante pour pull images | Pre-pull des images critiques |
| H7 | Latence réseau < 200ms vers GitLab.com | Impact performance jobs |
6.3 Décisions techniques prises
| Décision | Choix | Justification |
| Executor | Docker (pas Kubernetes) | Simplicité, contrôle direct, coût |
| Stockage secrets runner | Ansible Vault | Intégration existante, chiffrement AES |
| Cache | Local filesystem | Suffisant pour volume actuel |
| Network mode (internet) | Bridge | Isolation réseau maximale |
| Network mode (principal) | Host | Accès VPN CloudHSM requis |
7. Points de vigilance
7.1 Points critiques
| Point | Risque | Mitigation |
| Rotation tokens runner | Token expiré = runner offline | Procédure documentée, monitoring |
| Espace disque cache | Remplissage = jobs en échec | Monitoring + docker system prune périodique |
| Mise à jour gitlab-runner | Breaking changes | Tester sur runner internet d'abord |
| Secrets dans logs | Exposition accidentelle | Audit régulier des variables masked |
7.2 Points de clarification (issus de la spec)
| # | Point | Réponse implémentée |
| 1 | Périmètre runner (instance/groupe/projet) | Groupe probatiovault |
| 2 | Politique durée de vie cache | Pas d'expiration automatique, nettoyage manuel |
| 3 | Volume maximal cache | 80GB (disque VPS) |
| 4 | Politique rotation secrets | Manuelle via GitLab UI, immédiat |
| 5 | Niveau de journalisation | Info par défaut, journalctl pour debug |
| 6 | Exigences conformité | Pas d'audit externe requis actuellement |
7.3 Procédures de maintenance
# Nettoyage Docker hebdomadaire (cron recommandé)
docker system prune -af --volumes
# Mise à jour runner
sudo apt update && sudo apt upgrade gitlab-runner -y
sudo systemctl restart gitlab-runner
# Rotation token runner
# 1. Générer nouveau token dans GitLab UI
# 2. Mettre à jour vault.yml
# 3. ansible-playbook setup_gitlab_complete.yml
Annexes
A. Fichiers de référence
| Fichier | Description |
ansible/setup_internet_runner.yml | Playbook runner isolé |
ansible/roles/gitlab_runner/templates/config.toml.j2 | Template config principal |
ansible/roles/gitlab_runner/templates/config-internet-only.toml.j2 | Template config isolé |
docs/reference/infra/operations/internet-runner.md | Documentation opérationnelle |
B. Commandes utiles
# Vérifier tous les runners
sudo gitlab-runner list
sudo gitlab-runner verify
# Logs en temps réel
sudo journalctl -u gitlab-runner -f
# Espace disque
df -h
docker system df
# Test pipeline manuel
# Via GitLab UI : CI/CD → Run Pipeline
Fin du plan d'implémentation PD-12.