ArgoCD, Déploiement multi-environnements avec Kustomize

Déployer une application dans un seul environnement est simple. La vraie difficulté commence quand vous gérez dev, staging et production avec des configurations différentes (replicas, ressources CPU/mémoire, URLs, feature flags...). Ce guide vous montre comment structurer votre config-repo avec Kustomize pour ArgoCD et comment automatiser les déploiements multi-clusters avec les ApplicationSet. Kustomize est l'outil natif de Kubernetes qui compose des manifestes par base plus surcouches (overlays), sans dupliquer la configuration. Si vous débutez avec lui, lisez d'abord le guide prérequis Kustomize.

Ce que vous allez apprendre

• Comparer les trois stratégies multi-environnements (branches, dossiers, overlays Kustomize)
• Structurer un config-repo avec Kustomize : base commune + overlays par environnement
• Créer un ApplicationSet avec générateur List pour déployer sur plusieurs clusters
• Implémenter un workflow de promotion : dev → staging → production via Pull Request
• Effectuer un rollback ciblé avec git revert sur un environnement sans affecter les autres

Stratégies de gestion multi-environnements

Il existe trois approches pour gérer plusieurs environnements dans Git :

Stratégie	Description	Avantage	Inconvénient
Branches	Une branche par env (dev, staging, main)	Workflow familier	Divergence difficile à gérer, merges complexes
Dossiers	Un dossier par env (envs/dev/, envs/prod/)	Simple	Duplication des manifestes
Kustomize overlays	Base commune + sur-couches par env	Pas de duplication, diff clair	Courbe d'apprentissage

Glissez pour voir

Les overlays Kustomize sont la méthode recommandée. C'est celle décrite dans ce guide.

Structure de dépôt avec Kustomize

La logique de Kustomize repose sur deux niveaux. La base rassemble les manifestes communs à tous les environnements. Les overlays (un par environnement) ne décrivent que les différences à appliquer sur cette base. Cette organisation évite de recopier un même Deployment trois fois : vous ne maintenez qu'un seul socle, et chaque environnement le personnalise par petits patches.

config-repo/
└── nginx-demo/
    ├── base/                        # Manifestes communs à tous les envs
    │   ├── kustomization.yaml
    │   ├── deployment.yaml
    │   └── service.yaml
    └── overlays/                    # Sur-couches par environnement
        ├── dev/
        │   ├── kustomization.yaml
        │   └── patch-replicas.yaml  # 1 replica en dev
        ├── staging/
        │   ├── kustomization.yaml
        │   └── patch-replicas.yaml  # 2 replicas en staging
        └── production/
            ├── kustomization.yaml
            ├── patch-replicas.yaml  # 5 replicas en production
            └── patch-resources.yaml # Limites CPU/mémoire plus élevées

La base

La base contient les manifestes partagés, sans valeurs spécifiques à un environnement :

nginx-demo/base/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml

nginx-demo/base/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1    # Valeur par défaut, écrasée dans chaque overlay
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27@sha256:6784fb0834aa7dbbe12e3d7471e69c290df3e6ba810dc38b34ae33d3c1c05f7d
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 200m
              memory: 256Mi

L'overlay production

L'overlay production est le plus chargé, car la production a les exigences les plus strictes. Il patche la base sur trois points : il monte à 5 replicas pour la haute disponibilité, relève les ressources CPU/mémoire pour encaisser la charge réelle, et épingle le tag d'image sur une version précise plutôt que de suivre une cible mouvante.

nginx-demo/overlays/production/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base   # Hérite de la base
patches:
  - path: patch-replicas.yaml
  - path: patch-resources.yaml
images:
  - name: nginx
    newTag: "1.27.4"   # Version épinglée en production

nginx-demo/overlays/production/patch-replicas.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 5

nginx-demo/overlays/production/patch-resources.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  template:
    spec:
      containers:
        - name: nginx
          resources:
            requests:
              cpu: 500m
              memory: 512Mi
            limits:
              cpu: 1000m
              memory: 1Gi

L'overlay dev

L'overlay dev vise l'inverse : un environnement léger où l'on veut toujours tester la dernière build. Il garde donc 1 replica (inutile de gaspiller des ressources sur un environnement de travail) et suit le tag latest pour récupérer automatiquement la version la plus récente de l'image.

nginx-demo/overlays/dev/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patches:
  - path: patch-replicas.yaml
images:
  - name: nginx
    newTag: "latest"   # Toujours la dernière version en dev

nginx-demo/overlays/dev/patch-replicas.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1

Vérifier localement avant de pousser

Avant de pousser un overlay dans Git, prenez l'habitude de rendre le résultat en local. Comme ArgoCD déploiera exactement ce que Kustomize génère, mieux vaut inspecter ce YAML final vous-même : vous confirmez que le bon nombre de replicas et le bon tag d'image sont appliqués, et vous détectez une erreur de patch avant qu'elle n'atteigne le cluster.

# Vérifier ce que Kustomize va générer pour production
kubectl kustomize nginx-demo/overlays/production

# Diff entre dev et production
diff \
  <(kubectl kustomize nginx-demo/overlays/dev) \
  <(kubectl kustomize nginx-demo/overlays/production)

ApplicationSet multi-environnements

Avec Kustomize et la structure overlays, vous pouvez créer un ApplicationSet qui déploie une Application par environnement depuis un seul template :

applicationset-multi-env.yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: nginx-envs
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - env: dev
            namespace: nginx-dev
            cluster: https://kubernetes.default.svc
          - env: staging
            namespace: nginx-staging
            cluster: https://kubernetes.default.svc
          - env: production
            namespace: nginx-production
            cluster: https://prod-cluster.example.com
  template:
    metadata:
      name: "nginx-{{env}}"
    spec:
      project: default
      source:
        repoURL: https://github.com/votre-org/config-repo
        targetRevision: main
        path: "nginx-demo/overlays/{{env}}"
      destination:
        server: "{{cluster}}"
        namespace: "{{namespace}}"
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

Cet ApplicationSet crée trois Applications : nginx-dev, nginx-staging et nginx-production, chacune pointant vers son overlay.

Multi-clusters

Dans l'exemple, prod pointe vers un cluster externe prod-cluster.example.com. Ce cluster doit être enregistré dans ArgoCD au préalable :

argocd cluster add mon-contexte-prod --name prod-cluster

Promotion entre environnements

Via PR (recommandé en production)

La promotion manuelle via Pull Request est la méthode la plus sûre : elle permet une revue humaine avant que le changement n'atteigne la production.

Workflow type :

1. La CI pousse le nouveau tag dans overlays/dev/kustomization.yaml
2. Dev se synchronise automatiquement
3. Après validation, ouvrez une PR pour mettre à jour overlays/staging/
4. Après approbation, mergez. Staging se synchronise
5. Ouvrez une PR vers overlays/production/. Approbation par l'équipe
6. Fusion → déploiement automatique en production

# Script de promotion dev → staging
CURRENT_TAG=$(yq '.images[0].newTag' nginx-demo/overlays/dev/kustomization.yaml)
yq -i ".images[0].newTag = \"${CURRENT_TAG}\"" \
  nginx-demo/overlays/staging/kustomization.yaml
git add nginx-demo/overlays/staging/kustomization.yaml
git commit -m "chore(staging): promote nginx to ${CURRENT_TAG}"
git push origin promote/staging-nginx-${CURRENT_TAG}
# Ouvrir la PR depuis cette branche

Via argocd app sync (dev/staging uniquement)

Pour des environnements non-critiques, vous pouvez forcer une synchronisation depuis la CI après le déploiement en dev :

argocd app sync nginx-staging \
  --server argocd.example.com \
  --auth-token "$ARGOCD_TOKEN" \
  --timeout 120

Rollback ciblé sur un environnement

L'intérêt du multi-environnements, c'est de pouvoir revenir en arrière sur un seul environnement sans toucher aux autres. Comme chaque environnement a son overlay dans Git, un rollback consiste simplement à annuler le commit qui a modifié cet overlay. C'est la méthode GitOps, et elle est parfaitement isolée : revenir en arrière sur overlays/production/ ne change rien à dev ou staging.

# Annuler le dernier commit qui a modifié l'overlay production
git revert <sha-du-commit-production>
git push origin main

ArgoCD détecte le nouveau commit, resynchronise uniquement nginx-production sur la version d'avant, et l'Application repasse Synced + Healthy. La traçabilité est préservée : l'historique Git montre ce qui a été annulé et pourquoi.

Rollback d'urgence : voir la leçon dédiée

Pour un retour arrière immédiat en pleine incident (avant même de toucher à Git), ArgoCD propose argocd app rollback à partir de son historique de déploiement. Cette commande a ses propres règles, notamment l'obligation de couper l'auto-sync au préalable (sinon elle est refusée), et fait diverger le cluster de Git le temps de l'urgence. Tout est détaillé dans Rollback et reprise après incident.

À retenir

• Kustomize overlays est la stratégie recommandée pour le multi-env : une base commune + sur-couches spécifiques par environnement. Pas de duplication.
• Un ApplicationSet avec le générateur List permet de déployer la même application dans N environnements depuis un seul template.
• La promotion via PR est la méthode la plus sûre pour la production : revue humaine avant déploiement.
• kubectl kustomize path/ permet de vérifier localement ce que Kustomize générera, avant de pousser.
• Préférez le git revert au argocd app rollback en production pour maintenir Git comme source de vérité.
• Épinglez les versions d'images dans les overlays de production (pas latest).

Pour aller plus loin

• Sécuriser ArgoCD : RBAC, AppProjects, SSO et gestion sécurisée des secrets.
• Admission Controllers : valider les déploiements multi-env avec Kyverno et policy-as-code.

×

📖 Voir la documentation →