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 introduit 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.

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

Ces trois termes reviennent en permanence dans ArgoCD, il faut les distinguer avant d'aller plus loin. Lisez le tableau comme une correspondance entre chaque état et l'endroit où il se matérialise : le desired state vit dans Git, le live state dans le cluster, et leur écart s'appelle le drift.

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.

Comment ArgoCD reconnaît ses ressources

Pour réconcilier, ArgoCD doit savoir quelles ressources lui appartiennent. Il marque chacune avec un identifiant de suivi (tracking id). Depuis ArgoCD 3.0, ce marquage se fait par annotation et non plus par label comme en 2.x, ce qui évite d'entrer en collision avec les labels applicatifs. Sur une ressource déployée, l'annotation ressemble à ceci :

argocd.argoproj.io/tracking-id: guestbook:apps/Deployment:guestbook/guestbook-ui

Elle relie la ressource à son Application (guestbook) et à son type. Si vous migrez depuis la 2.x, notez ce changement de défaut : pour conserver l'ancien suivi par label, positionnez application.resourceTrackingMethod: label dans argocd-cm.

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 introduit

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 : n'importe quelle Application peut déployer n'importe où. 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

Le Sync Status répond à une seule question : le cluster est-il conforme à Git ? Il ne dit rien de la santé des workloads, seulement de l'écart entre le desired state et le live state. Voici les trois valeurs que vous croiserez.

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

Le Health Status est indépendant du Sync Status : il évalue la santé réelle des ressources déployées, pas leur conformité à Git. Une Application peut être Synced mais Degraded si un pod tombe en erreur. Chaque valeur ci-dessous correspond à un état de vie des workloads.

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.

La vue arbre de ressources

C'est la vue la plus utile de l'interface. Elle affiche l'arbre des ressources d'une Application : l'objet Application à gauche, puis ce qu'il génère en cascade. Chaque nœud porte son état de santé et de synchronisation, ce qui rend le diagnostic immédiat.

On lit la filiation Kubernetes de gauche à droite : l'Application guestbook pilote un Service et un Deployment, le Deployment crée un ReplicaSet, qui crée le Pod running 1/1. Le bouton HISTORY AND ROLLBACK en haut donne accès à l'historique des déploiements, utile pour revenir en arrière.

Aller plus loin sur la synchronisation

La synchronisation peut être finement ordonnée (sync-waves), ajustée (sync options comme CreateNamespace ou ServerSideApply) et fiabilisée face aux contrôleurs d'admission qui mutent les ressources après leur création. Ces mécanismes avancés sont détaillés dans la leçon dédiée Maîtriser la synchronisation, et le cas particulier des admission controllers (Kyverno, Gatekeeper) dans Admission Controllers.

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).

Pour aller plus loin

• Première application : déployer et synchroniser votre première Application ArgoCD.
• Multi-environnements : générer une Application par environnement avec ApplicationSet et Kustomize.
• Rollback et reprise : revenir en arrière depuis l'historique des déploiements.

×

📖 Voir la documentation →