🔁 GitOps – Guide Complet (Argo CD / Flux / Kubernetes)

1.1 GitOps – Définition, mental model & diagramme global

Définition “opérationnelle”

GitOps est une pratique où Git est la source de vérité pour décrire l’état désiré (applications + configuration + parfois infrastructure). Un ou plusieurs contrôleurs (dans le cluster) tirent la configuration depuis Git, la comparent à l’état réel, puis réconcilient.

Source of truth = Git Deploy = commit / PR Reconcile loop Drift detection Rollback = git revert

Ce que GitOps “remplace”

Les accès manuels au cluster (ex: kubectl apply en prod).
Les scripts ad-hoc de déploiement non traçables.
Les “modifs de config” hors Git (drift silencieux).

Pourquoi ça marche si bien ?

Parce que Git est déjà un outil de gouvernance : revue, historisation, diff, signatures, branches, contrôles d’accès, CI, approbations.

Propriété	GitOps apporte
Audit	Traçabilité parfaite : qui a changé quoi et quand.
Reproductibilité	Un cluster vide peut être “reconstruit” depuis Git.
Sécurité	Moins de secrets “humains” + RBAC + pull-only.
Stabilité	Le drift est détecté et corrigé (auto-heal).

Diagramme GitOps (mental model)

Développeur / SRE
   │
   │  (PR / Merge / Tag)
   ▼
[ GIT Repository ]
   │     ├─ manifests (Kustomize/Helm/YAML)
   │     ├─ policies (OPA / Kyverno)
   │     └─ env overlays (dev/stage/prod)
   │
   │  (pull + diff)
   ▼
[ GitOps Controller in Cluster ]
   │   - Argo CD / Flux
   │   - compare desired vs live
   │   - reconcile (apply)
   │   - detect drift + report
   ▼
[ Kubernetes Cluster ]
   │
   ├─ Deployments / Services / Ingress
   ├─ ConfigMaps / Secrets (encrypted or external)
   ├─ CRDs (operators)
   └─ Observability (events/metrics)

Idée IDEO-Lab : mets ce diagramme en “carte mentale” dans une section Overview, puis une modal dédiée “ArgoCD vs Flux”.

Cas d’usage parfaits

Kubernetes multi-environnements (dev/stage/prod) + besoin d’audit.
Équipes nombreuses : standardiser, réduire les accès prod.
Infra “immutable” : reconstruire rapidement (DRP / disaster recovery).
Besoin de compliance (SOC2/ISO) : preuves = Git + logs.

Cas “OK” mais à cadrer

Infra Terraform : GitOps est possible, mais attention aux “plans/apply” et aux verrous d’état.
Config runtime très dynamique : mieux via external config (vault/feature flags), pas en Git pur.

Anti-cas (ou risques)

Si l’équipe fait des changements “à chaud” sans les commiter → drift permanent.
Si les secrets sont committés en clair → interdit.
Si l’ordre d’application CRDs/operators n’est pas géré → sync failures.

Règle d’or

Prod ne doit pas être modifié directement. Tout passe par Git (PR), sinon tu casses la promesse GitOps.

GitOps vs CD “push” classique

Point	CD classique (push)	GitOps (pull)
Déploiement	CI pousse vers le cluster	Cluster tire depuis Git
Accès prod	Credentials dans CI	CI n’a pas besoin d’accès prod (idéalement)
Audit	Logs CI + scripts	Git = audit principal + état désiré
Drift	Souvent invisible	Détecté (diff) + corrigé (auto-heal)
Rollback	Procédure variable	`git revert` ou retour de tag

1.2 Les 4 piliers GitOps (avec checklists)

Déclaratif : “voici l’état désiré”

Tu décris ce que tu veux, pas la procédure pour y arriver. Exemple : “3 replicas”, “ingress activé”, “resource limits”.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: app
        image: registry/app:1.4.2
        resources:
          requests: { cpu: "200m", memory: "256Mi" }
          limits:   { cpu: "1",    memory: "512Mi" }

Checklist “déclaratif propre”

Manifests générés (Helm/Kustomize) mais “reviewables”.
Pas de valeurs runtime dans Git (tokens, passwords, clés).
Ressources et probes définies (readiness/liveness).
Namespaces & labels cohérents (ownership, app, env).

Objectif : que “diff Git vs cluster” soit lisible (sinon GitOps devient bruyant).

Versionné : Git = historique officiel

Chaque changement d’infra/config/app est un commit, idéalement via PR avec revue & CI.

# Exemple: promotion stage -> prod
- PR: bump image tag 1.4.2 -> 1.4.3
- CI: lint manifests + policy checks
- Merge: Argo/Flux sync prod
- Observability: alert if sync fails

Checklist “gouvernance”

Branches protégées + approbations obligatoires.
Conventional commits / changelog (optionnel mais utile).
CODEOWNERS (SRE owners sur dossiers prod).
Signatures commits/tags (si exigences compliance).

Pull-based : le cluster tire, la CI ne pousse pas

Le contrôleur GitOps vit dans le cluster et récupère les manifests depuis Git. Cela réduit l’exposition : plus besoin de donner au CI des droits admin sur prod.

CI (build/test) ✅
- build image
- scan image
- publish image

CD GitOps ✅
- commit manifests (tag image)
- controller pulls + applies

Points d’attention

Accès Git : token read-only par environnement si possible.
Rotation des secrets (repo credentials) + scopes minimaux.
Webhooks optionnels : accélèrent la sync, mais le polling suffit.

Réconciliation continue : drift → correction

Le contrôleur compare en boucle desired (Git) vs live (cluster). Si divergence : il applique, alerte, ou bloque selon policy.

Loop:
- fetch Git revision
- render manifests
- diff vs cluster live
- if drift:
    - sync/apply
    - emit events
    - update health status

Modes de sync

Mode	Effet	Quand ?
Manual sync	Opérateur déclenche	Début / contrôle strict
Auto sync	Déploiement automatique	Pipeline mature
Auto-heal	Corrige drift live	Prod, anti “kubectl drift”
Prune	Supprime ressources retirées de Git	Quand Git = vérité totale

1.3 Outils GitOps – Argo CD vs Flux + composants

Stack GitOps “standard” en entreprise

- Git provider: GitHub / GitLab
- Registry: GHCR / ECR / GCR / Harbor
- Kubernetes: EKS / GKE / AKS / on-prem
- GitOps controller: Argo CD (GUI) ou Flux (Kubernetes-native)
- Manifests: Helm charts + values / Kustomize overlays
- Secrets: SOPS + KMS (AWS/GCP) ou External Secrets (Vault/SM)
- Policy: Kyverno ou OPA Gatekeeper
- Observability: Prometheus/Grafana + Alertmanager + logs (Loki/ELK)

Argo CD (pattern courant)

UI très pratique (diff, sync status, app tree).
Pattern App of Apps pour organiser des centaines d’apps.
Intégration RBAC et multi-clusters.

Flux (pattern courant)

Très “Kubernetes-native” (CRDs : GitRepository, Kustomization…).
Composants modulaires, excellent pour GitOps “pur”.
Souvent préféré si on veut moins de UI et plus d’infra-as-code.

Table décisionnelle : Argo CD vs Flux

Critère	Argo CD	Flux
UI / visibilité	✅ Très forte	➖ (extensions possibles)
Modèle	Applications (App CRD)	CRDs “K8s-first” (Kustomization…)
Onboarding	Rapide (GUI + concepts clairs)	Plus technique (CRDs, controllers)
Scale multi-app	Très bon (App-of-apps)	Très bon (Kustomizations)
Flux + Helm	✅	✅ (Helm Controller)
Opinionated	Plutôt “App-centric”	Plutôt “K8s-centric”

Choix simple : Argo CD si tu veux une UI et un modèle “application”. Flux si tu veux un modèle “Kubernetes controllers” ultra IaC.

Helm (templating)

Bon pour packager une app (chart) + paramètres par environnement (values).

# values-prod.yaml
replicaCount: 3
image:
  repository: ghcr.io/acme/app
  tag: "1.4.3"
ingress:
  enabled: true

Attention : trop de logique Helm rend le diff illisible → rester sobre.

Kustomize (overlays)

Excellent pour overlays env (patches) et composition.

# overlays/prod/kustomization.yaml
resources:
  - ../../base
patches:
  - path: patch-replicas.yaml
  - path: patch-ingress.yaml

Astuce : base = commun ; overlays = uniquement deltas (réduit la duplication).

Terraform + GitOps : 2 patterns

Pattern A (classique)

Terraform gère l’infra (VPC, cluster, IAM, DB), puis GitOps gère les apps sur le cluster. C’est le plus simple et le plus robuste.

Terraform:
- VPC, EKS/GKE, nodegroups
- ingress controller, cert-manager (option)
GitOps:
- apps + configs + policies

Pattern B (Terraform “GitOps”)

Le contrôleur GitOps déclenche des “apply” Terraform (moins courant). Risques : lock state, ordering, drift infra complexe.

OK si “Terraform controllers” matures + states bien gérés.
Sinon : garde Terraform dans CI dédiée avec approvals.

2.1 Architecture GitOps – environnements, app-of-apps & policies

Topologie recommandée (lisible & scalable)

Git Repos:
- app-source/         (code + Dockerfile)  -> produit une image
- platform-config/    (manifests GitOps)   -> décrit l'état désiré

Clusters:
- dev cluster
- stage cluster
- prod cluster

Controllers:
- 1 controller GitOps par cluster (souvent)
- ou 1 controller central multi-clusters (selon RBAC)

Pourquoi séparer code et config ?

Le repo “config” devient le journal de l’état prod.
Les droits d’accès sont différents (prod = plus strict).
Tu peux promouvoir une image sans toucher au code.

Quand garder un monorepo ?

Petite équipe, peu d’apps.
Si tu veux des PR “tout-en-un” (code+deploy).
Mais attention : governance prod plus difficile.

Gestion des environnements

Approche	Principe	Avantage	Risque
Branches	dev/stage/prod = branches	Simple	Merge conflicts + drift branch
Dossiers	/env/dev /env/prod	Lisible	Gros repo à scaler
Repos séparés	1 repo par env	RBAC strict	Duplication si mal structuré

Recommandation : dossiers env + overlays (Kustomize) ou values (Helm) + PR de promotion.

Policies : empêcher les “mauvaises configs”

Exemples de règles utiles

Interdire :latest en prod (images non immutables).
Exiger resources.limits et probes.
Interdire privileged: true.
Forcer labels (team, env, app).

Outils

Kyverno : policies YAML “K8s friendly”.
OPA Gatekeeper : policies Rego (puissant).
CI lint : kubeconform, kubeval, helm lint.

Pattern “App-of-Apps” (Argo CD)

root-app (Argo CD Application)
└── apps/
    ├── monitoring.yaml   (Prometheus, Grafana)
    ├── ingress.yaml      (Ingress controller)
    ├── app1.yaml         (Business app #1)
    └── app2.yaml         (Business app #2)

Avantages:
- 1 point d'entrée (root-app)
- onboarding simple: ajouter un fichier appX.yaml
- scale: des centaines d'apps gérables

2.2 Structure Git – monorepo vs multi-repo + templates

Layout “propre” pour platform-config

platform-config/
├── clusters/
│   ├── dev/        # ce cluster suit env/dev
│   ├── stage/
│   └── prod/
├── env/
│   ├── base/       # manifests communs
│   ├── dev/        # overlays dev
│   ├── stage/
│   └── prod/
├── apps/
│   ├── app-web/
│   ├── app-api/
│   └── app-worker/
└── policies/
    ├── kyverno/
    └── opa/

Objectif : séparer “où ça tourne” (clusters) de “ce qui tourne” (apps).

Mono-repo vs multi-repo (décision rapide)

Option	Quand	+ / -
Monorepo	petite équipe, peu d’apps	✅ simple / ❌ gouvernance prod difficile
Repo config dédié	moyen/grand SI	✅ audit & RBAC / ❌ 2 repos à gérer
1 repo par env	compliance forte	✅ cloisonnement / ❌ duplication si mal géré

Promotion (dev → stage → prod)

Pattern simple

CI build + push image app:1.4.3.
PR sur env/dev (ou dev overlay) pour mettre le tag.
Validation (tests, policies) → merge.
PR de promotion vers stage puis prod.

Anti-pattern

Écraser le tag prod directement sans passer par stage.
Modifier live cluster “pour dépanner” puis oublier de commiter.
Utiliser :latest (rollback impossible, drift non maîtrisé).

Exemples de fichiers (templates)

Kustomize base

# env/base/kustomization.yaml
resources:
  - deployment.yaml
  - service.yaml
  - ingress.yaml

Overlay prod

# env/prod/kustomization.yaml
resources:
  - ../base
patches:
  - path: patch-prod.yaml
images:
  - name: ghcr.io/acme/app
    newTag: "1.4.3"

2.3 Workflow CI → GitOps CD (de bout en bout)

Pipeline “golden path”

(1) Dev pushes code
(2) CI:
    - tests
    - build image
    - scan (SCA/SAST)
    - publish image (tag immutable)
(3) CI (ou bot) ouvre PR sur repo config:
    - bump image tag + config changes
(4) Merge PR
(5) GitOps Controller:
    - detect new commit
    - render manifests
    - sync
(6) Observability:
    - health checks
    - alert if sync error / degraded

CI : ce que tu veux absolument

Tests unitaires + intégration.
Build image reproductible (Dockerfile propre).
Scan dépendances + image (vulnérabilités).
Publish image immuable (tag version, digest).

# Exemple de tags
app:1.4.3
app:1.4.3+build.21
app@sha256:abcdef...

Deux options “update manifests”

Option	Principe	Note
Bot commit	CI commit direct dans repo config	Rapide mais attention gouvernance
PR auto	CI ouvre PR, humain valide	Le plus “enterprise-friendly”

CD GitOps : ce que fait le contrôleur

Récupère la dernière révision Git (poll/webhook).
Render Helm/Kustomize.
Calcule diff.
Sync (apply) selon la policy.
Surveille health (degraded, progressing…)

Desired (Git) vs Live (cluster)
- if OutOfSync: apply
- if Degraded: alert + maybe rollback

Contrôle du “blast radius”

Déployer par namespaces (ownership clair).
Limiter permissions du controller (RBAC).
Approvals sur dossiers prod (CODEOWNERS).
Progressive delivery (canary) pour changements risqués.

Guardrails (filtres anti-cata)

Couche	Contrôle	Exemples
Git	Approvals & protections	branch protection, CODEOWNERS
CI	Lint & policy checks	kubeconform, helm lint, kyverno test
Cluster	Admission policies	OPA/Kyverno bloque configs non conformes
Runtime	Observability & SLO	alerts, rollback automatique

2.4 Drift & auto-heal – comprendre les écarts et les “diffs bruyants”

Définition

Le drift apparaît quand l’état réel du cluster diverge de l’état désiré stocké dans Git. Exemple : quelqu’un fait un kubectl edit en prod, ou un operator modifie un champ.

Git says: replicas=3
Cluster live: replicas=5
=> OutOfSync / drift

Causes humaines

Hotfix “juste pour dépanner” → non committé.
Accès prod trop large (beaucoup d’admins).
Absence de process PR / approbations.

Causes techniques

Operators/CRDs qui “mutent” des champs.
Defaulting API server (valeurs injectées).
Controllers qui ajoutent annotations/labels dynamiques.

Auto-heal : la “vraie” valeur GitOps

Auto-heal ON : le controller remet le cluster comme Git le décrit.
Auto-heal OFF : drift détecté, mais correction manuelle (ou PR) requise.

Stratégie recommandée

Dev/stage : auto-heal ON (itérations rapides)
Prod : auto-heal ON + RBAC strict + policy checks

Si tu dois hotfix en prod

Faire la modif (si urgence).
Créer immédiatement PR “align Git avec live”.
Une fois PR mergée : re-sync GitOps.

Réduire le bruit de diff

Éviter champs “auto” dans Git (timestamps, status fields).
Configurer “ignore differences” sur champs mutés (selon outil).
Standardiser labels/annotations.
Limiter la logique Helm (diff plus stable).

3.1 Rollouts – Blue/Green, Canary, progressive delivery & rollback

Stratégies de déploiement

Stratégie	Principe	Quand
Rolling update	Remplacement progressif pods	Par défaut, changements simples
Blue/Green	Deux versions, switch traffic	Quand tu veux un cutover net
Canary	Trafic progressif vers nouvelle version	Quand risque élevé / perf

Canary mental model:
- 5% traffic -> observe
- 25% traffic -> observe
- 50% traffic -> observe
- 100% -> promote
If errors -> abort / rollback

Argo Rollouts (exemple “conceptuel”)

kind: Rollout
spec:
  strategy:
    canary:
      steps:
      - setWeight: 10
      - pause: { duration: 2m }
      - setWeight: 25
      - pause: { duration: 5m }
      - setWeight: 50
      - pause: { duration: 10m }

L’idée : ton GitOps déploie un objet Rollout (déclaratif), puis la stratégie fait le reste.

Quality gates

Gates metrics : taux d’erreur HTTP, latence P95, saturation CPU/mem.
Gates logs : spikes d’exceptions, timeouts DB.
Gates fonctionnels : smoke tests sur endpoints critiques.

“Progressive delivery” = GitOps + métriques + décisions automatiques.

Rollback : 3 niveaux

Rollback Git : git revert du commit manifests (le plus propre).
Rollback rollout : abort canary / promote ancienne version.
Rollback infra : plus rare, via Terraform + approvals.

# Règle pratique:
Rollback = revenir à un état Git connu "green"

3.2 Sécurité GitOps – RBAC, secrets, signatures, policies

Principe : least privilege

Le controller GitOps a des droits limités (namespaces ciblés).
Les humains n’ont pas besoin d’être admins prod.
Le repo prod est protégé (CODEOWNERS + approvals).

RBAC quick rules:
- 1 namespace = 1 équipe (idéal)
- interdire cluster-admin au controller
- limiter verbs: get/list/watch/apply sur ressources nécessaires

Git Access

Token repo read-only (si possible) côté controller.
Rotation périodique.
Scopes minimaux (pas “admin repo”).

Secrets : ce qu’il faut faire

Option A : SOPS (recommandé GitOps)

Secrets chiffrés dans Git, déchiffrés dans le cluster via KMS.

secret.enc.yaml (in Git)  ✅ encrypted
controller decrypts with KMS (AWS/GCP)
applies Secret to cluster

Option B : External Secrets

Git ne contient pas le secret, seulement une référence (Vault/Secret Manager).

Git: ExternalSecret manifest
Runtime: operator fetches value from Vault/SM

Interdit : committer des secrets en clair (même “temporairement”).

Supply chain security

Signatures images (cosign) + vérification en admission.
SBOM (cyclonedx/spdx) généré en CI.
Scan vulnérabilités (deps + images).
Pin par digest (@sha256) pour immutabilité stricte.

Golden rule:
- image tags = ok
- digests = best (immutable)
- "latest" = never in prod

Policies (admission control)

But : rendre impossible un déploiement dangereux, même si quelqu’un pousse un mauvais manifest.

Règle	Exemple
Interdire containers privileged	`securityContext.privileged != true`
Forcer limits	`resources.limits` obligatoires
Interdire latest	`image != *:latest`
Forcer labels	team/env/app requis

3.3 Observabilité GitOps – health, events, metrics & alerting

Ce que tu dois monitorer

Sync status : in sync / out of sync
Health : healthy / degraded / progressing
Latency de sync : temps entre commit et déploiement
Erreurs répétées : retry loops, hooks failing

Alerts recommandées:
- app OutOfSync > X min
- app Degraded
- sync failures spikes
- drift frequency high (symptôme d'accès manuel)

Signal vs bruit

Si tes dashboards sont rouges tout le temps, l’équipe les ignore. Fixe le “diff noise” (champs dynamiques), standardise les manifests, et définis des SLO simples.

Quick SLO (exemples)

95% des déploiements “Healthy” en < 10 minutes
0 déploiement prod via accès manuel (objectif)

4.1 Troubleshooting GitOps – erreurs fréquentes & solutions

Sync errors : pattern de diagnostic

Lire l’erreur exacte (resource + message).
Valider que la ressource existe (namespace, CRD, API version).
Vérifier permissions (RBAC du controller).
Vérifier rendus Helm/Kustomize (templating).

Cas typiques:
- "namespace not found" -> créer namespace en amont
- "forbidden" -> RBAC du controller
- "no matches for kind X" -> CRD manquante

CRDs : le piège n°1

Si tu appliques un objet custom avant sa CRD, ça échoue.

Ordre recommandé:
1) CRDs
2) Operators/controllers
3) Custom resources (CRs)

Solution : séparer en apps (infra) et apps (workloads), ou utiliser sync waves/hooks.

Diff “bruyant”

Champs mutés par operators → ignorer certains champs.
Annotations dynamiques (ex: checksum config) → standardiser.
Helm trop “smart” → réduire logique.

Recovery playbook (rapide)

Stop the bleeding : pause auto-sync si nécessaire.
Rollback : revert commit / revenir au dernier état green.
Fix root cause : CRD ordering / RBAC / policy.
Re-enable : auto-sync + monitor health.

4.2 Cheat-sheet GitOps – règles d’or, checklists, commandes

Règles d’or

1) Git = source de vérité (prod ne se modifie pas à la main)
2) Secrets jamais en clair
3) Images immutables (tag version / digest) — jamais :latest
4) Policy checks avant merge (lint + admission)
5) Observabilité: alerte sur OutOfSync/Degraded

Checklist “PR prod”

Diff lisible (pas de bruit)
Resource limits + probes
Rollback plan simple
Change log / description claire
App health check ok

Commandes (conceptuelles)

# Workflow
git checkout -b feat/bump-app-1.4.3
# modifier image tag / values / overlay
git commit -am "chore(prod): bump app to 1.4.3"
git push

# Rollback
git revert 
git push

Anti-patterns

“kubectl apply” en prod sans PR
Config runtime (secrets) dans Git en clair
Helm chart illisible (trop de logique)
Pas de policies → drift + déploiements dangereux

Si tu veux, je peux te générer une modal “Argo CD install + config de base” (RBAC, repo credentials, apps-of-apps) exactement au même style.

🔁 GitOps – Guide complet (Kubernetes / Argo CD / Flux)

Définition & promesse

Les 4 piliers GitOps

Outils & écosystème

Architecture type

Structure Git recommandée

Workflow CI → GitOps CD

2.4 Drift & auto-heal

Rollouts & stratégies

Sécurité & secrets

Observabilité

Troubleshooting

Cheat-sheet GitOps