Skip to content

Comprendre la promotion multi-environnements

Ce guide explique comment une version d'image avance de dev vers staging puis prod, sur un cluster unique découpé en trois environnements.

ADR lié : Stratégie multi-environnements (Décision 2). Voir aussi Comprendre ArgoCD et GitOps avec ArgoCD.

En une phrase

Le tag de l'image vit dans l'overlay de chaque env (pas dans base) : dev est bumpé automatiquement à chaque merge sur develop, staging et prod avancent uniquement par une MR qui recopie le tag validé de l'env amont. Aucun rebuild : on fait avancer la même image, déjà construite et scannée.

Où vit la version déployée

Chaque environnement a son propre newTag dans son kustomization.yaml :

k8s/overlays/
  fastapi/{dev,staging,prod}/kustomization.yaml   → images[].newTag
  frontend/{dev,staging,prod}/kustomization.yaml  → images[].newTag

« Quelle version tourne où » se lit donc dans trois fichiers, dans le même commit. Les trois envs peuvent tourner sur trois versions différentes en même temps (dev en avance, prod stable) : c'est tout l'intérêt d'un pipeline de promotion.

Le flux global

flowchart LR
    merge["merge sur develop<br/>(build + scan + push ECR)"]
    merge -->|"write-back CI<br/>(automatique)"| dev["overlays/*/dev<br/>newTag = sha"]
    dev -->|"MR de promotion<br/>(promote.sh dev staging)"| stg["overlays/*/staging<br/>newTag = sha"]
    stg -->|"MR de promotion + review<br/>(promote.sh staging prod)"| prod["overlays/*/prod<br/>newTag = sha"]
    dev -.->|sync| ad[(ArgoCD dev)]
    stg -.->|sync| as[(ArgoCD staging)]
    prod -.->|sync| ap[(ArgoCD prod)]

1. dev = automatique

À chaque merge sur develop, le job CI update-image-tag (write-back GitOps) réécrit le newTag de overlays/fastapi/dev et overlays/frontend/dev, commit en [skip ci] et push sur develop. ArgoCD détecte le diff et déploie dev seul. staging et prod ne bougent pas.

sequenceDiagram
    participant Dev as Développeur
    participant CI as CI (develop)
    participant Git as Git (overlays/dev)
    participant Argo as ArgoCD
    Dev->>CI: merge sur develop
    CI->>CI: build + scan + push ECR (deployed-sha)
    CI->>Git: kustomize edit set image (dev) + commit [skip ci]
    Git-->>Argo: diff détecté sur overlays/*/dev
    Argo->>Argo: sync → déploie dev

2. staging et prod = MR de promotion

Promouvoir = recopier le tag de l'env amont vers l'aval, sur une branche, puis MR vers develop. Le script scripts/promote.sh fait la recopie et prépare la branche (il ne pousse pas, ne merge pas) :

# dev → staging
scripts/promote.sh dev staging
git push -u origin promote/staging-<sha>
# → ouvrir une MR vers develop, relire, merger

# staging → prod (après validation de staging)
scripts/promote.sh staging prod
git push -u origin promote/prod-<sha>
# → MR vers develop, review obligatoire avant merge

Une fois la MR mergée, ArgoCD voit le nouveau newTag dans l'overlay cible et déploie l'env correspondant. Le saut direct dev → prod est interdit par le script : staging est un palier obligatoire.

Le gate de promotion prod

La promotion vers prod est le moment sensible. Deux garde-fous :

  • La MR de promotion elle-même : sur develop (branche protégée, merge réservé Maintainer), tu relis le diff — un simple changement de tag — et tu merges. Pour ce projet, c'est le point de contrôle humain.
  • .gitlab/CODEOWNERS déclare overlays/*/prod comme possédé, ce qui auto-suggère le reviewer. L'enforcement d'une approbation obligatoire par code owner est une fonctionnalité GitLab Premium+ : sur un plan Free il ne bloque pas, il documente et suggère.
  • E2E staging vert deviendra la condition automatique (job CI) avant promotion prod — c'est le gate « dur » et gratuit, livré en #140.

Rollback

Revenir en arrière = promouvoir un ancien tag. On recopie manuellement le tag connu-bon dans l'overlay cible (ou kustomize edit set image à la main), MR, merge. Comme chaque promotion est une MR, l'historique Git donne la liste des tags par env : retrouver le dernier tag sain est trivial.

Et après ? Vers une promotion outillée (Kargo & alternatives)

Le flux actuel est manuel par choix pédagogique : on manipule toute la mécanique à la main pour la comprendre. Il évoluera vers de l'outillage dédié (noté en « Évolution possible » de l'ADR 029) :

  • Kargo — l'évolution cible. Modélise la promotion en Stages et Freight : il détecte une nouvelle image, la promeut automatiquement dev → staging après vérification (tests, health), et garde prod en promotion manuelle approuvée. C'est le pattern d'entreprise « auto jusqu'à staging, gate humaine avant prod », sans le geste promote.sh à la main.
  • Argo Rollouts — progressive delivery dans un env : canary / blue-green + analyse automatique des métriques avant de basculer 100 % du trafic.
  • ArgoCD Image Updater — écarté : il bumpe le tag automatiquement partout, contraire à une promotion contrôlée vers prod.
flowchart LR
    subgraph Aujourdhui["Aujourd'hui — manuel (promote.sh)"]
        d1[dev] -->|MR à la main| s1[staging] -->|MR à la main| p1[prod]
    end
    subgraph Cible["Cible — Kargo"]
        d2[dev] -->|"auto après<br/>vérification"| s2[staging] -->|"gate humaine<br/>approuvée"| p2[prod]
    end

Le socle multi-env (namespaces, overlays, promotion par MR) est le prérequis : Kargo s'installe par-dessus cette structure, il ne la remplace pas.