ArgoCD — Concepts et architecture

ArgoCD fonctionne comme un gardien permanent de votre cluster Kubernetes : il compare en continu l’état souhaité (décrit dans Git) avec l’état réel (ce qui tourne dans le cluster), et corrige automatiquement les écarts. Ce guide explique comment ce mécanisme fonctionne, pourquoi il est plus fiable qu’un kubectl apply en fin de pipeline, et quels objets ArgoCD introduce dans votre cluster.

Guide précédent recommandé

Ce guide suppose que vous connaissez les principes GitOps. Si ce n’est pas encore le cas, lisez d’abord Comprendre le GitOps.

Ce que vous allez apprendre

• Le modèle de réconciliation : desired state, live state, control loop et drift
• Les composants internes d’ArgoCD (argocd-server, repo-server, application-controller, Redis, Dex) et le rôle de chacun
• L’objet Application : source Git, destination Kubernetes, politiques de sync
• Les AppProject : périmètres d’autorisation pour isoler les équipes
• L’ApplicationSet : génération automatique d’Applications depuis un template

Qu’est-ce qu’ArgoCD ?

ArgoCD est un opérateur GitOps — c’est-à-dire un programme qui tourne dans votre cluster Kubernetes et qui est spécialisé dans une seule tâche : garder le cluster synchronisé avec un dépôt Git.

L’analogie : Imaginez un contremaître sur un chantier. Il reçoit les plans de l’architecte (votre dépôt Git) et s’assure que les ouvriers (Kubernetes) construisent exactement ce qui est dessiné. Si quelqu’un modifie quelque chose sur le terrain sans passer par les plans, le contremaître le remet dans l’état prévu.

Ce qui distingue ArgoCD d’un simple kubectl apply dans un pipeline :

Approche	Ce qui se passe	Risque
kubectl apply en CI	Le cluster est modifié une fois, puis oublié	Drift : le cluster peut dériver sans que personne ne le sache
ArgoCD	ArgoCD surveille en permanence, réconcilie en continu	Drift détecté et corrigé automatiquement

Glissez pour voir

Le modèle de réconciliation

Le cœur d’ArgoCD est une boucle de contrôle (control loop), qui effectue ces étapes en permanence :

1. OBSERVE  → Lire l'état actuel du cluster (live state)
2. DIFF     → Comparer avec l'état souhaité dans Git (desired state)
3. ACT      → Si différents, appliquer les manifestes Git sur le cluster
4. REPEAT   → Reprendre depuis le début

Ce cycle s’appelle la réconciliation. Par défaut, ArgoCD le déclenche toutes les 3 minutes (polling Git) et immédiatement à chaque webhook Git.

Desired state vs Live state

Terme	Définition	Où ça vit
Desired state	Ce que vous voulez (décrit dans Git)	Dépôt Git
Live state	Ce qui tourne réellement	Cluster Kubernetes
Drift	Écart entre desired et live	Détecté par ArgoCD

Glissez pour voir

Le drift, c'est dangereux

Un drift non détecté signifie que votre cluster ne correspond plus à ce qui est dans Git. Quelqu’un a peut-être appliqué un correctif d’urgence directement avec kubectl, et personne ne le sait. ArgoCD détecte ce genre de situation et peut automatiquement la corriger.

Les composants internes d’ArgoCD

ArgoCD est lui-même une application Kubernetes composée de plusieurs pods, chacun avec un rôle précis :

argocd-server

C’est le point d’entrée d’ArgoCD. Il expose :

• L’interface web (dashboard) accessible depuis votre navigateur
• L’API gRPC/REST que la CLI argocd et les outils externes utilisent

Il ne touche jamais directement au cluster de destination — c’est l’application-controller qui fait les synchronisations.

repo-server

Son rôle : cloner vos dépôts Git et générer les manifestes Kubernetes finaux. C’est lui qui sait lire du Helm, du Kustomize, ou du YAML brut, et qui produit la liste de toutes les ressources à appliquer.

application-controller

Le chef d’orchestre. Il :

1. Appelle le repo-server pour obtenir le desired state
2. Interroge l’API Kubernetes pour obtenir le live state
3. Compare les deux
4. Déclenche les synchronisations si nécessaire

C’est le composant le plus critique — si vous avez plusieurs clusters gérés, c’est lui qui doit scaler.

Redis

Un cache utilisé par l’application-controller pour stocker le résultat des comparaisons récentes et éviter de surcharger l’API Kubernetes.

Dex (optionnel)

Un service d’authentification OIDC qui permet à ArgoCD de déléguer la connexion à un fournisseur d’identité externe : GitHub, GitLab, LDAP, Active Directory, etc. Obligatoire en production dans une équipe.

Les objets Kubernetes qu’ArgoCD introduce

ArgoCD étend Kubernetes avec des Custom Resource Definitions (CRD) qui représentent les concepts ArgoCD en tant que ressources Kubernetes.

Application

L’objet Application est la pièce centrale. Il déclare :

• Où est la source (dépôt Git + chemin + révision)
• Où déployer (cluster + namespace)
• Comment synchroniser (manuel ou automatique)

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: mon-app
  namespace: argocd
spec:
  # La source : quel dépôt Git et quel chemin
  source:
    repoURL: https://github.com/mon-org/config-repo
    targetRevision: main
    path: mon-app/overlays/production

  # La destination : quel cluster et quel namespace
  destination:
    server: https://kubernetes.default.svc  # cluster local
    namespace: production

  # La politique de synchronisation
  syncPolicy:
    automated:           # synchronisation automatique
      selfHeal: true     # correction du drift automatique
      prune: true        # suppression des ressources retirées de Git

Le cluster local

https://kubernetes.default.svc est l’adresse de l’API Kubernetes depuis l’intérieur du cluster. Quand ArgoCD gère le cluster dans lequel il est installé, c’est cette adresse qu’on utilise. Pour des clusters distants, on utilise l’adresse externe de l’API + des credentials.

AppProject

Un AppProject est un périmètre de sécurité autour d’un groupe d’Applications. Il répond à la question : “Qui a le droit de déployer quoi, où ?”

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: equipe-backend
  namespace: argocd
spec:
  # Dépôts Git autorisés
  sourceRepos:
    - https://github.com/mon-org/config-repo

  # Clusters et namespaces de destination autorisés
  destinations:
    - namespace: backend-*
      server: https://kubernetes.default.svc

  # Types de ressources Kubernetes autorisés
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace

Sans AppProject explicite, les Applications utilisent le projet default qui n’a aucune restriction. En production, chaque équipe doit avoir son propre AppProject.

ApplicationSet

Un ApplicationSet est un générateur d’Applications. Plutôt que de créer 20 objets Application à la main (un par environnement, ou un par dépôt), on crée un ApplicationSet qui les génère depuis un template :

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: apps-par-env
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - env: dev
            namespace: app-dev
          - env: staging
            namespace: app-staging
          - env: production
            namespace: app-production
  template:
    metadata:
      name: 'mon-app-{{env}}'
    spec:
      source:
        repoURL: https://github.com/mon-org/config-repo
        path: 'mon-app/overlays/{{env}}'
        targetRevision: main
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{namespace}}'
      syncPolicy:
        automated:
          selfHeal: true
          prune: true

Ce fichier crée automatiquement 3 Application ArgoCD : mon-app-dev, mon-app-staging, mon-app-production.

Les ApplicationSets seront détaillés dans le module Multi-environnements.

Les statuts à comprendre

Quand vous regardez l’interface ArgoCD ou que vous utilisez le CLI, deux dimensions de statut s’affichent toujours :

Sync Status

Statut	Signification
Synced	Le cluster correspond exactement à Git
OutOfSync	Il y a des différences — une synchro est nécessaire
Unknown	Impossible de déterminer (problème de connexion, permissions)

Glissez pour voir

Health Status

Statut	Signification
Healthy	Toutes les ressources sont saines (Pods Running, Services OK…)
Progressing	Déploiement en cours (rollout, Job en attente…)
Degraded	Erreur détectée (Pod CrashLoopBackOff, PVC non monté…)
Suspended	Ressource intentionnellement pausée (CronJob suspendu…)
Missing	La ressource est dans Git mais n’existe pas dans le cluster
Unknown	ArgoCD ne peut pas déterminer l’état de santé

Glissez pour voir

Healthy + Synced = tout va bien

L’état parfait pour une application en production est Synced + Healthy. Si vous voyez OutOfSync sans déploiement en cours, il y a eu du drift. Si vous voyez Degraded, un pod ou une ressource est en erreur.

SyncPolicy avancée : sync-waves et syncOptions

La partie syncPolicy d’une Application ne se limite pas à automated: true. ArgoCD propose des mécanismes avancés pour contrôler l’ordre et le comportement des synchronisations.

Sync-waves : ordonner les déploiements

Quand une Application contient plusieurs ressources (un CRD, un Namespace, un Deployment…), ArgoCD les applique toutes en même temps par défaut. C’est un problème quand une ressource dépend d’une autre — par exemple, une ClusterPolicy Kyverno ne peut pas être créée si le CRD Kyverno n’existe pas encore.

Les sync-waves résolvent ce problème. Chaque ressource reçoit un numéro d’onde via une annotation — ArgoCD les applique dans l’ordre croissant :

# Le CRD s'installe en premier (wave 0)
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kyverno
  annotations:
    argocd.argoproj.io/sync-wave: "1"
# ...

# Les politiques s'installent après (wave 2)
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kyverno-policies
  annotations:
    argocd.argoproj.io/sync-wave: "2"
# ...

ArgoCD attend que chaque vague soit Healthy avant de passer à la suivante. C’est essentiel pour le pattern App-of-Apps avec des dépendances d’infrastructure.

Wave	Ce qu’on y met	Exemple
0	Namespaces, CRDs système	cert-manager, CRDs Kyverno
1–3	Opérateurs, contrôleurs	Kyverno, Prometheus Operator
4–6	Politiques, configurations	ClusterPolicy, PrometheusRule
7–9	Applications métier	Vos microservices

Glissez pour voir

Wave par défaut = 0

Si vous ne mettez pas d’annotation sync-wave, la ressource est dans la wave 0. Vous n’avez donc besoin d’annoter que les ressources qui doivent venir après les autres.

SyncOptions : contrôler le comportement de la synchro

Les syncOptions se configurent dans le champ spec.syncPolicy.syncOptions de l’Application. Voici les options les plus utiles :

Option	Effet	Quand l’utiliser
CreateNamespace=true	Crée le namespace cible s’il n’existe pas	Toute Application qui cible un namespace dédié
ServerSideApply=true	Utilise le server-side apply de Kubernetes	Obligatoire pour les CRDs volumineux (Kyverno, Prometheus, cert-manager) qui dépassent la limite de 262 Ko des annotations last-applied-configuration
Validate=false	Désactive la validation côté client	Utile avec des CRDs custom mal déclarés
RespectIgnoreDifferences=true	Respecte les ignoreDifferences même en sync auto	Quand un opérateur modifie certains champs post-apply
PruneLast=true	Supprime les ressources obsolètes seulement après toutes les créations	Réduit le risque de disruption lors du pruning

Glissez pour voir

spec:
  syncPolicy:
    automated:
      selfHeal: true
      prune: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true

Compare options : éviter les faux OutOfSync

Certains contrôleurs d’admission (comme Kyverno ou Gatekeeper) mutent les ressources après leur création — ils ajoutent des labels, des annotations ou modifient des champs. ArgoCD voit ces mutations comme un drift et marque l’Application OutOfSync en permanence.

Deux annotations sur l’Application corrigent ce problème :

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kyverno
  annotations:
    argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true

Option	Effet
ServerSideDiff=true	Calcule les diffs côté serveur au lieu du client — prend en compte l’état réel après mutation
IncludeMutationWebhook=true	Intègre les modifications des webhooks mutants dans le calcul des diffs, évitant les faux positifs OutOfSync

Glissez pour voir

Sans ces options, Kyverno provoque du drift permanent

Si vous déployez Kyverno (ou tout contrôleur qui mute des ressources) sans ServerSideDiff et IncludeMutationWebhook, ArgoCD affichera un état OutOfSync permanent sur les Applications concernées. Le self-heal re-appliquera les manifestes en boucle sans résoudre le problème.

Résumé des concepts fondamentaux

Avant de passer à l’installation, assurez-vous de maîtriser ces termes :

Concept	Définition simple
Opérateur GitOps	Programme K8s qui synchronise le cluster depuis Git
Réconciliation	Boucle de contrôle : observe → compare → agit
Desired state	Ce que Git dit (les manifestes)
Live state	Ce qui tourne réellement dans le cluster
Drift	Écart entre desired et live
Application	Objet K8s ArgoCD : source Git → destination cluster
AppProject	Périmètre de sécurité autour d’Applications
ApplicationSet	Générateur automatique d’Applications
Sync Status	Le cluster est-il identique à Git ?
Health Status	Les workloads déployés sont-ils sains ?

Glissez pour voir

À retenir

• ArgoCD est un opérateur Kubernetes qui tourne dans votre cluster et surveille Git en permanence.
• La réconciliation est une boucle : observe → compare → agit. Elle tourne en continu, toutes les 3 minutes par défaut.
• L’Application est l’objet central : elle lie une source Git à une destination Kubernetes.
• L’AppProject ajoute des garde-fous de sécurité (qui peut déployer quoi où).
• L’ApplicationSet génère des Applications automatiquement depuis des templates — indispensable pour gérer plusieurs environnements.
• Deux statuts à surveiller : Sync Status (Git vs cluster) et Health Status (santé des workloads).

Prochaines étapes

Installer ArgoCD Installation Helm, accès initial, CLI argocd

Première application Déployer et synchroniser votre première Application ArgoCD

Retour vue d'ensemble Tous les modules de la formation

×

📖 Voir la documentation →