ArgoCD : GitOps sur Kubernetes en 12 Étapes [2026]

Un déploiement Kubernetes qui dérive de son état déclaré dans Git reste l’une des causes les plus fréquentes d’incidents en production. Un ingénieur applique un correctif à chaud avec kubectl edit, oublie de le reporter dans le dépôt, et le prochain déploiement écrase silencieusement ce correctif. ArgoCD résout ce problème en forçant le cluster à rester identique à ce qui est écrit dans un dépôt Git, sans intervention manuelle. C’est le principe du GitOps, une approche que la CNCF a largement contribué à populariser à travers le projet Argo.

Ce tutoriel installe ArgoCD 3.5.2, la version stable publiée le 27 août 2026, configure un premier déploiement GitOps de bout en bout et couvre le RBAC, le SSO, la gestion des secrets et le dépannage. Comptez environ 90 minutes pour suivre les douze étapes, du cluster de test jusqu’au pipeline multi-environnement. Ce guide complète notre couverture plus large des sujets cloud et infrastructure Kubernetes déjà publiés sur shattered.io.

Qu’est-ce qu’ArgoCD et pourquoi le GitOps s’impose en 2026

ArgoCD est un outil de livraison continue déclarative pour Kubernetes, construit à l’origine chez Intuit et publié en open source sous licence Apache 2.0. Le principe tient en une phrase : le cluster Kubernetes doit toujours correspondre à ce qui est décrit dans un dépôt Git. Dès qu’un écart apparaît entre le cluster réel et l’état déclaré, ArgoCD le détecte et propose (ou applique automatiquement) la correction.

Le projet Argo, dont ArgoCD fait partie, a été accepté par la CNCF au niveau incubating en 2020 puis a atteint le niveau de maturité maximal, gradué, le 6 décembre 2022. Ce statut place ArgoCD dans la même catégorie que Kubernetes ou Prometheus en matière de gouvernance et de stabilité du projet. Le dépôt officiel argoproj/argo-cd sur GitHub affiche environ 24 100 étoiles début septembre 2026, et son fichier USERS.md liste des entreprises comme Adobe, Adyen, Alibaba Group, Amadeus IT Group ou encore Capital One parmi les organisations qui déclarent l’utiliser en production.

Cette adoption ne doit rien au hasard. Avant le GitOps, la plupart des équipes déployaient sur Kubernetes via des scripts kubectl apply lancés depuis un pipeline CI, sans garantie que l’état réel du cluster corresponde exactement à ce qui avait été validé en revue de code. ArgoCD ferme cette boucle : chaque changement passe par une pull request, chaque déploiement est traçable jusqu’à un commit précis, et un rollback revient à inverser ce commit plutôt qu’à rejouer une procédure manuelle sous pression pendant un incident.

La dernière version stable au moment de la rédaction est ArgoCD 3.5.2, publiée le 27 août 2026. Elle embarque les correctifs de sécurité accumulés depuis les versions 3.0 et 3.1, une meilleure gestion des diffs sur les grands clusters et des ajustements dans l’interface web. Le chart Helm officiel argo-cd-10.7.1, sorti le 3 septembre 2026, sert de base d’installation recommandée pour ce tutoriel. La liste complète des changements est publiée sur la page des releases GitHub du projet.

Architecture : le modèle pull et les composants du control plane

Contrairement à un pipeline CI/CD classique qui pousse des changements vers le cluster, ArgoCD fonctionne selon un modèle pull. Un agent installé à l’intérieur du cluster observe en continu le dépôt Git et applique lui-même les changements détectés. Cette inversion supprime le besoin de stocker des identifiants d’accès au cluster dans l’outil CI, une surface d’attaque classique en cybersécurité des pipelines de déploiement.

Le control plane repose sur cinq composants distincts, chacun déployé comme un pod Kubernetes indépendant. Le repo-server clone les dépôts Git et rend les manifestes (YAML brut, Helm ou Kustomize). L’application-controller compare en boucle l’état rendu à l’état réel du cluster et déclenche la réconciliation. Le server expose l’API REST et l’interface web. dex-server gère l’authentification, et redis met en cache les résultats de rendu pour éviter de recloner un dépôt à chaque cycle. Cette séparation permet de dimensionner chaque composant indépendamment selon la charge, un point détaillé dans la documentation officielle.

Prérequis : outils, versions et compte Git

Avant de commencer, préparez les éléments suivants. Un poste avec au moins 4 vCPU et 8 Go de RAM disponibles suffit largement pour suivre ce tutoriel sur un cluster de test local.

Un cluster Kubernetes récent (1.28 ou supérieur), local via Minikube ou K3s, ou managé (GKE, AKS, EKS)
kubectl installé et configuré pour pointer vers ce cluster
Helm 3.14 ou supérieur, pour installer le chart officiel argo-cd
Git installé, avec un compte GitHub ou GitLab pour héberger le dépôt de manifestes
La CLI argocd en version 3.5.2, correspondant au serveur installé
Docker ou un autre moteur de conteneurs, si vous utilisez Minikube

Si vous n’avez pas encore de cluster sous la main, notre tutoriel Minikube ou notre guide K3s en 12 étapes couvrent la mise en place en moins de 40 minutes. Les utilisateurs de clouds managés peuvent aussi suivre nos tutoriels GKE ou AKS Azure avant de revenir ici. ArgoCD reste indifférent au fournisseur du cluster : il consomme l’API Kubernetes standard, décrite dans la documentation officielle des concepts Kubernetes, et fonctionne à l’identique sur un cluster managé ou auto-hébergé.

Un mot sur les versions : la CLI argocd doit idéalement correspondre à la version majeure du serveur pour éviter des erreurs de sérialisation sur les nouvelles ressources personnalisées. Un décalage d’une version mineure fonctionne généralement, mais un écart de version majeure (par exemple CLI 3.5 contre serveur 2.14) provoque des erreurs de compatibilité difficiles à diagnostiquer.

Étape 1 – Préparer un cluster Kubernetes de test

Pour ce tutoriel, un cluster K3s local suffit et démarre en moins d’une minute. Créez d’abord le namespace dédié à ArgoCD, une pratique recommandée pour isoler les composants du control plane des applications déployées.

Cluster local ou cluster managé : quel choix pour apprendre ArgoCD

Un cluster local comme K3s ou Minikube suffit largement pour suivre ce tutoriel et comprendre le fonctionnement d’ArgoCD, sans frais d’infrastructure. Passer sur un cluster managé (GKE, AKS, EKS) devient utile dès que vous testez des scénarios multi-clusters ou l’intégration avec un load balancer cloud pour exposer l’interface ArgoCD au-delà de votre poste. Les commandes de ce guide restent identiques dans les deux cas, seule la façon d’obtenir le contexte kubectl initial change.

kubectl create namespace argocd
kubectl get nodes
NAME       STATUS   ROLES                  AGE   VERSION
k3s-node1  Ready    control-plane,master   2m    v1.31.4+k3s1

Vérifiez que le namespace a bien été créé avant de passer à l’installation.

kubectl get namespaces
NAME              STATUS   AGE
argocd            Active   5s
default           Active   3m
kube-system       Active   3m

Étape 2 – Installer ArgoCD sur le cluster

Deux méthodes existent : le manifeste YAML officiel ou le chart Helm. Le chart Helm facilite les mises à jour et l’ajustement des ressources, on l’utilise donc ici avec la version 10.7.1 du 3 septembre 2026.

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update
helm install argocd argo/argo-cd \
  --namespace argocd \
  --version 10.7.1 \
  --set server.service.type=ClusterIP

L’installation crée trois composants principaux : argocd-server (API et interface web), argocd-repo-server (clonage et rendu des manifestes) et argocd-application-controller (réconciliation entre Git et le cluster). Comptez 30 à 60 secondes avant que tous les pods passent à l’état Running.

kubectl get pods -n argocd
NAME                                  READY   STATUS    RESTARTS   AGE
argocd-application-controller-0      1/1     Running   0          45s
argocd-repo-server-6d4f9c8b7-x2k9p   1/1     Running   0          45s
argocd-server-7f9b6d5c4-p8m3q        1/1     Running   0          45s
argocd-dex-server-5c8b7d9f6-t7w2x    1/1     Running   0          45s
argocd-redis-6b9d8f7c5-r4n8v         1/1     Running   0          45s

Étape 3 – Accéder à l’interface web et installer la CLI

Le mot de passe administrateur initial est généré automatiquement et stocké dans un secret Kubernetes. Récupérez-le, puis exposez temporairement le serveur en local via un port-forward.

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

kubectl port-forward svc/argocd-server -n argocd 8080:443

Ouvrez ensuite https://localhost:8080 et connectez-vous avec l’identifiant admin et le mot de passe récupéré. Installez aussi la CLI, indispensable pour scripter les déploiements et automatiser le pipeline CI/CD par la suite.

curl -sSL -o argocd-linux-amd64 \
  https://github.com/argoproj/argo-cd/releases/download/v3.5.2/argocd-linux-amd64
sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
argocd login localhost:8080 --username admin --insecure

Changez immédiatement le mot de passe par défaut avec argocd account update-password. C’est une étape que beaucoup d’équipes oublient avant de mettre le cluster en production.

Étape 4 – Structurer un dépôt Git pour le GitOps

ArgoCD ne remplace pas votre dépôt applicatif, il consomme un dépôt de manifestes distinct. Séparer le code applicatif des manifestes de déploiement évite qu’un simple commit de code déclenche accidentellement une synchronisation. Une structure courante ressemble à ceci.

gitops-repo/
├── apps/
│   ├── api-service/
│   │   ├── base/
│   │   │   ├── deployment.yaml
│   │   │   ├── service.yaml
│   │   │   └── kustomization.yaml
│   │   └── overlays/
│   │       ├── staging/
│   │       └── production/
└── argocd/
    └── applicationset.yaml

Kustomize s’intègre nativement à ArgoCD sans plugin supplémentaire, contrairement à certains templates Helm plus complexes qui demandent une configuration explicite du repo-server. Poussez cette structure vers votre dépôt GitHub avant l’étape suivante.

Deux stratégies s’opposent pour organiser ce dépôt : le mono-repo, où toutes les applications d’une organisation vivent dans un seul dépôt GitOps, et le multi-repo, où chaque équipe possède son propre dépôt de manifestes. Le mono-repo simplifie la gouvernance et la visibilité globale, mais un dépôt qui grossit trop ralentit le clonage effectué par le repo-server à chaque cycle de synchronisation. Le multi-repo isole mieux les équipes mais multiplie le nombre d’Applications à déclarer côté ArgoCD. La plupart des organisations de taille moyenne démarrent en mono-repo et migrent vers un modèle multi-repo une fois que le nombre d’équipes dépasse la dizaine.

Étape 5 – Déployer votre première application

Une Application ArgoCD est une ressource personnalisée (CRD) qui décrit quel dépôt Git surveiller, quel chemin lire et dans quel cluster/namespace déployer. Créez le fichier suivant dans votre dépôt de manifestes.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: api-service
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/votre-org/gitops-repo.git
    targetRevision: main
    path: apps/api-service/overlays/staging
  destination:
    server: https://kubernetes.default.svc
    namespace: staging
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

Appliquez la ressource puis vérifiez son état via la CLI. Le champ SYNC STATUS indique si le cluster correspond à Git, et HEALTH STATUS reflète l’état des pods déployés.

kubectl apply -f argocd/api-service-app.yaml
argocd app list
NAME         CLUSTER     NAMESPACE  PROJECT  STATUS   HEALTH
api-service  in-cluster  staging    default  Synced   Healthy

Étape 6 – Activer la synchronisation automatique et le self-healing

Par défaut, ArgoCD détecte les écarts mais attend une validation manuelle avant d’appliquer un changement. En production, activez plutôt la synchronisation automatique combinée au self-healing, qui annule toute modification faite directement sur le cluster hors de Git.

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

Le paramètre prune: true supprime les ressources retirées du dépôt Git, tandis que selfHeal: true restaure automatiquement toute ressource modifiée manuellement, par exemple via un kubectl edit effectué par erreur. Testez ce comportement en modifiant une réplique directement dans le cluster, ArgoCD la remet à sa valeur déclarée en quelques secondes. Ce délai de correction dépend de l’intervalle de réconciliation configuré sur l’application-controller, généralement fixé à quelques secondes par défaut mais ajustable pour réduire la charge sur de très gros clusters.

Le self-healing change fondamentalement la façon dont une équipe résout les incidents. Un correctif d’urgence appliqué directement au cluster sera annulé au prochain cycle si le dépôt Git n’a pas été mis à jour en parallèle, ce qui force une discipline saine mais peut surprendre une équipe habituée à intervenir directement sur la production.

Étape 7 – Gérer plusieurs environnements avec ApplicationSet

Dupliquer manuellement une Application pour chaque environnement devient vite ingérable. L’ApplicationSet Controller, intégré à ArgoCD, génère automatiquement une Application par entrée d’un générateur, ici une simple liste d’environnements.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: api-service-envs
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - env: staging
            namespace: staging
          - env: production
            namespace: production
  template:
    metadata:
      name: 'api-service-{{env}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/votre-org/gitops-repo.git
        targetRevision: main
        path: 'apps/api-service/overlays/{{env}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{namespace}}'

Cette approche évite la duplication de fichiers et centralise la logique multi-environnement dans un seul générateur. Des générateurs plus avancés existent, basés sur les clusters enregistrés, les dépôts Git ou une requête vers une API externe. Le générateur Git, par exemple, scanne automatiquement un dépôt à la recherche de dossiers correspondant à un motif donné et crée une Application pour chacun, une approche pratique quand de nouveaux microservices sont ajoutés régulièrement sans vouloir modifier l’ApplicationSet à chaque fois. Le générateur de matrice combine deux générateurs entre eux, par exemple une liste de clusters croisée avec une liste d’applications, pour couvrir tous les déploiements possibles en une seule ressource.

Étape 8 – Configurer le RBAC et le SSO avec Dex ou OIDC

ArgoCD embarque Dex, un fournisseur d’identité qui fait le lien entre vos utilisateurs (GitHub, Google, LDAP, SAML) et le système RBAC interne d’ArgoCD. Une alternative consiste à connecter directement un fournisseur OIDC (Keycloak, Okta, Azure AD) via la ConfigMap argocd-cm. Une fois l’authentification en place, mappez les groupes reçus vers des rôles ArgoCD.

# argocd-rbac-cm ConfigMap
policy.csv: |
  p, role:staging-deployer, applications, sync, default/*, allow
  p, role:staging-deployer, applications, get, default/*, allow
  g, platform-team, role:staging-deployer
  g, org:votre-org:sre-team, role:admin

Cette configuration limite l’équipe plateforme aux actions de synchronisation sans lui donner les droits d’administration complets, réservés à l’équipe SRE. Combiné aux ServiceAccounts et ClusterRoles Kubernetes classiques côté cluster, ce double niveau de RBAC, interne à ArgoCD puis Kubernetes natif, réduit la surface d’erreur humaine.

Dex ou OIDC natif : lequel choisir

Dex convient bien aux organisations qui doivent fédérer plusieurs sources d’identité hétérogènes, par exemple un LDAP interne pour les équipes historiques et un compte GitHub pour les contributeurs externes, le tout derrière un seul point d’entrée. La connexion OIDC native, elle, évite un composant intermédiaire quand l’entreprise dispose déjà d’un fournisseur d’identité central comme Keycloak ou Azure AD. Elle réduit le nombre de pods à maintenir et simplifie le débogage en cas d’échec d’authentification, au prix d’une flexibilité moindre si plusieurs fournisseurs doivent cohabiter.

Étape 9 – Protéger les secrets avec Sealed Secrets ou External Secrets Operator

Un dépôt Git GitOps ne doit jamais contenir de secret en clair, même dans un dépôt privé. Deux approches dominent l’écosystème ArgoCD. Sealed Secrets chiffre le secret côté client avant de le committer, et seul le contrôleur installé sur le cluster peut le déchiffrer. External Secrets Operator (ESO) fait l’inverse : le dépôt Git référence uniquement le nom d’un secret stocké dans un coffre externe (Vault, AWS Secrets Manager, Azure Key Vault), et ESO le synchronise dans Kubernetes au moment du déploiement.

ESO convient mieux aux organisations qui centralisent déjà leurs secrets dans un coffre géré, tandis que Sealed Secrets reste plus simple à mettre en place pour une petite équipe sans infrastructure de secret management existante. Les deux s’intègrent nativement au modèle de synchronisation d’ArgoCD, sans plugin ni script additionnel. Notre tutoriel dédié aux secrets Kubernetes détaille la configuration complète des deux approches.

Un piège fréquent avec Sealed Secrets consiste à perdre la clé privée du contrôleur lors d’une reconstruction du cluster, ce qui rend tous les secrets scellés illisibles. Sauvegardez systématiquement cette clé en dehors du cluster, dans un coffre séparé, avant toute opération de maintenance lourde. Avec External Secrets Operator, le risque se déplace plutôt vers la disponibilité du coffre externe : si Vault ou AWS Secrets Manager devient injoignable, les secrets déjà synchronisés dans le cluster restent valides, mais toute rotation ou nouvelle application ne pourra pas récupérer sa valeur tant que la connexion n’est pas rétablie.

Étape 10 – Mettre en place les notifications et la supervision

Le composant argocd-notifications permet d’envoyer une alerte sur Slack, Microsoft Teams ou par webhook dès qu’une synchronisation échoue ou qu’une application devient dégradée. Un déclencheur type ressemble à ceci.

trigger.on-sync-failed: |
  - when: app.status.operationState.phase in ['Error', 'Failed']
    send: [app-sync-failed]
template.app-sync-failed: |
  message: "Echec de synchronisation sur {{.app.metadata.name}}"

Pour la supervision, l’endpoint Prometheus exposé nativement par argocd-application-controller fournit des métriques comme le nombre d’applications désynchronisées ou la durée moyenne de réconciliation. Un tableau de bord Grafana basé sur ces métriques repère en un coup d’œil les applications qui dérivent le plus souvent de leur état déclaré, un signal souvent révélateur d’un processus de déploiement manuel qui contourne encore Git.

Au-delà de Slack et Teams, argocd-notifications supporte aussi les webhooks génériques, ce qui permet de brancher un système de tickets comme Jira ou un outil d’astreinte comme PagerDuty. Pour une équipe qui gère plusieurs dizaines d’applications, il vaut mieux limiter les alertes aux échecs de synchronisation et aux applications dégradées plutôt que de notifier chaque synchronisation réussie, sous peine de noyer le signal utile dans un flux constant de messages ignorés au bout de quelques jours.

Étape 11 – Durcir la sécurité et suivre les CVE d’ArgoCD

Comme tout composant central du pipeline de déploiement, ArgoCD est une cible logique. Plusieurs vulnérabilités ont été publiées entre 2025 et 2026, toutes corrigées dans les versions récentes. La 3.5.2 utilisée dans ce tutoriel embarque déjà tous ces correctifs.

CVE	Nature	Versions affectées	Corrigé dans
CVE-2025-55190	Fuite d’identifiants de dépôt via l’API projet	2.13.0–2.13.8, 2.14.0–2.14.15, 3.0.0–3.0.12	2.13.9, 2.14.16, 3.0.14, 3.1.2
CVE-2025-55191	Vulnérabilité documentée NVD	2.1.0 et ultérieures, jusqu’à 2.14.x et 3.x	2.14.20, 3.0.19, 3.1.8, 3.2.0-rc2
CVE-2025-59538	Déni de service (DoS)	2.9.0 et ultérieures, jusqu’à 2.14.20	2.14.20, 3.0.19, 3.1.8, 3.2.0-rc2
CVE-2026-45737	Sévérité moyenne (score 6.3)	Branche 2.14.x et suivantes	Images durcies Akuity
CVE-2026-45738	Sévérité élevée	argo-cd/v2, jusqu’à 2.14.21	2.14.21

Trois réflexes limitent l’exposition. D’abord, restreignez l’accès réseau au serveur ArgoCD à votre VPN ou à un tunnel Zero Trust plutôt que de l’exposer publiquement, une approche détaillée dans notre tutoriel Cloudflare Tunnel. Ensuite, activez les alertes de sécurité du dépôt GitHub pour être notifié dès qu’une nouvelle CVE touche ArgoCD, en suivant par exemple les avis publiés sur la National Vulnerability Database. Enfin, planifiez une mise à jour mensuelle plutôt que d’attendre un incident pour patcher.

Dimensionner le control plane ArgoCD

Le dimensionnement par défaut du chart Helm convient à un cluster de test, mais il mérite d’être ajusté avant une mise en production. Les besoins augmentent surtout avec le nombre d’applications synchronisées et la taille des dépôts Git surveillés, pas avec le trafic applicatif lui-même puisque ArgoCD ne se trouve jamais dans le chemin de requête des utilisateurs finaux.

Composant	CPU recommandé	RAM recommandée	Facteur de dimensionnement
argocd-server	0,5 à 1 vCPU	512 Mio à 1 Gio	Nombre de sessions API/UI simultanées
argocd-repo-server	1 à 2 vCPU	1 à 2 Gio	Taille des dépôts Git et fréquence de clonage
argocd-application-controller	1 à 2 vCPU	1 à 2 Gio	Nombre total d’applications gérées
argocd-redis	0,25 vCPU	256 Mio	Volume de rendu de manifestes mis en cache

Pour un cluster qui dépasse quelques centaines d’applications, le repo-server et l’application-controller deviennent les premiers goulots d’étranglement. Le contrôleur d’applications peut être répliqué horizontalement en mode sharding, où chaque réplique prend en charge un sous-ensemble de clusters enregistrés, une configuration décrite dans la documentation officielle du projet. Surveillez en particulier la latence de réconciliation via les métriques Prometheus exposées par défaut : une hausse continue de ce temps signale généralement qu’il est temps d’augmenter le nombre de répliques plutôt que la taille de chaque pod.

ArgoCD vs FluxCD : quel outil GitOps choisir

FluxCD reste le concurrent direct d’ArgoCD sur le terrain du GitOps pour Kubernetes. Les deux projets sont gradués CNCF depuis 2022 et partagent le même principe de réconciliation continue depuis Git. Les différences se jouent surtout sur l’expérience utilisateur et l’architecture.

Critère	ArgoCD	FluxCD
Statut CNCF	Gradué (décembre 2022)	Gradué (2022)
Interface web	Incluse nativement	Absente, nécessite Weave GitOps ou un tableau de bord tiers
Multi-environnement	ApplicationSet Controller	Kustomize + générateurs GitOps Toolkit
Modèle d’authentification	Dex intégré ou OIDC natif	Délégué à Kubernetes RBAC, pas d’UI d’auth native
Notifications	Composant argocd-notifications intégré	Via Alerts/Provider du GitOps Toolkit
Licence	Apache 2.0	Apache 2.0
Modèle managé	Akuity Platform	Solutions tierces

L’interface web intégrée d’ArgoCD explique une grande partie de son adoption par les équipes qui débutent en GitOps, car elle offre une vue graphique immédiate de l’état de synchronisation sans outil supplémentaire. FluxCD, plus modulaire, s’intègre mieux dans une chaîne d’outils GitOps Toolkit déjà en place, mais demande davantage de configuration initiale pour obtenir une visibilité équivalente.

Dans la pratique, le choix dépend surtout de l’existant. Une équipe qui a déjà investi dans Flux pour du chiffrement de secrets natif ou une intégration poussée avec Flagger pour le déploiement progressif a peu d’intérêt à migrer. À l’inverse, une équipe qui démarre son adoption du GitOps et veut une interface immédiatement lisible pour convaincre le reste de l’organisation tire davantage parti de l’expérience clé en main d’ArgoCD. Les deux outils peuvent d’ailleurs cohabiter sur des clusters distincts sans conflit technique.

Projet complet : pipeline GitOps de bout en bout

Assemblons maintenant toutes les étapes en un pipeline fonctionnel. Le scénario : un commit sur la branche main du dépôt applicatif déclenche une image Docker construite par CI, l’image est poussée avec un tag basé sur le SHA du commit, puis un second commit automatisé met à jour le manifeste dans le dépôt GitOps, qu’ArgoCD synchronise ensuite sans intervention humaine.

# Etape CI (extrait d'un workflow GitHub Actions)
- name: Build and push image
  run: |
    docker build -t ghcr.io/votre-org/api-service:$GITHUB_SHA .
    docker push ghcr.io/votre-org/api-service:$GITHUB_SHA

- name: Update GitOps manifest
  run: |
    git clone https://github.com/votre-org/gitops-repo.git
    cd gitops-repo/apps/api-service/overlays/production
    kustomize edit set image \
      ghcr.io/votre-org/api-service:$GITHUB_SHA
    git commit -am "deploy: api-service@$GITHUB_SHA"
    git push

ArgoCD détecte le nouveau commit en moins de trois minutes grâce à son polling par défaut, ou instantanément si un webhook Git est configuré vers argocd-server. Avec syncPolicy.automated activé, l’application se met à jour sans qu’aucun humain ne touche au cluster. Cet enchaînement, du commit de code jusqu’au pod redémarré, constitue la valeur centrale du GitOps : chaque déploiement est tracé, réversible par un simple git revert, et audité.

Pour valider que ce pipeline complet fonctionne avant de le brancher sur une vraie CI, testez chaque maillon isolément. Poussez d’abord un commit manuel modifiant le tag d’image dans le dépôt GitOps et vérifiez qu’ArgoCD le détecte et synchronise sans intervention. Simulez ensuite un échec, par exemple en pointant vers une image inexistante, pour observer comment le health status et les notifications réagissent. Ce n’est qu’une fois ces deux scénarios validés manuellement que le pipeline CI complet doit être connecté en production, avec un déploiement progressif sur staging avant production.

Erreurs fréquentes à éviter

Mélanger dépôt applicatif et dépôt GitOps. Un commit de code source ne doit jamais déclencher directement une synchronisation ArgoCD, sous peine de déployer du code non testé.
Activer le self-healing avant d’avoir des tests de rollback. Sans stratégie de retour arrière claire, une erreur dans Git se propage automatiquement sur tout un environnement.
Exposer l’interface ArgoCD publiquement sans authentification renforcée. Le serveur ArgoCD porte des droits étendus sur le cluster, il mérite le même niveau de protection qu’un accès kubectl.
Laisser le mot de passe admin par défaut. Beaucoup d’installations de test finissent en production sans que ce mot de passe initial soit jamais changé.
Ignorer les mises à jour de sécurité. Les CVE listées plus haut montrent qu’ArgoCD reçoit des correctifs réguliers, une version figée depuis plus de six mois accumule un risque inutile.
Stocker des secrets en clair dans le dépôt GitOps. Même un dépôt privé peut fuiter via un token mal configuré ou un fork accidentel.
Négliger le dimensionnement du repo-server sur un mono-repo volumineux. Un clonage répété d’un dépôt de plusieurs centaines de Mo à chaque cycle de réconciliation sature vite la RAM allouée par défaut.
Ne pas séparer les projets ArgoCD par équipe. Sans AppProject dédié, toutes les applications partagent implicitement les mêmes permissions par défaut, ce qui complique l’application du principe du moindre privilège.

Dépannage : 8 problèmes courants et leurs solutions

Application bloquée en état OutOfSync malgré une synchronisation manuelle. Vérifiez les hooks de synchronisation avec argocd app diff, un webhook mal configuré peut réappliquer un changement en boucle.
Erreur “repository not accessible” au moment d’ajouter un dépôt. Ajoutez les identifiants du dépôt via argocd repo add avec un token d’accès personnel plutôt qu’un mot de passe, GitHub a désactivé l’authentification par mot de passe depuis plusieurs années.
Le pod argocd-repo-server redémarre en boucle (CrashLoopBackOff). C’est souvent un manque de mémoire sur de gros dépôts monorepo, augmentez la limite RAM du composant dans les values Helm.
Les changements Git ne sont pas détectés. Le polling par défaut tourne toutes les trois minutes, configurez un webhook Git vers argocd-server pour une détection quasi instantanée.
Health status bloqué sur “Progressing” indéfiniment. Vérifiez les probes de readiness du déploiement concerné, ArgoCD attend que Kubernetes signale les pods prêts avant de marquer l’application comme saine.
Erreur de certificat TLS lors de la connexion CLI. Utilisez temporairement le flag --insecure en développement, mais configurez un certificat valide via cert-manager avant la production.
Conflit RBAC : un utilisateur ne voit aucune application. Vérifiez le mapping des groupes dans argocd-rbac-cm, une faute de frappe dans le nom du groupe OIDC est la cause la plus fréquente.
ApplicationSet ne génère aucune Application. Contrôlez la syntaxe du générateur avec kubectl describe applicationset, les erreurs de templating apparaissent dans les events de la ressource.
La commande argocd login échoue avec un timeout. Vérifiez que le port-forward ou l’Ingress vers argocd-server reste actif, et que le port utilisé (443 par défaut en gRPC-Web) n’est pas bloqué par un pare-feu local.
Les credentials Git expirent régulièrement. Préférez une clé de déploiement SSH dédiée ou un token à durée de vie longue avec des permissions limitées à la lecture du dépôt de manifestes, plutôt qu’un token personnel lié à un compte individuel.

Astuces avancées pour aller plus loin

Une fois les bases maîtrisées, plusieurs fonctionnalités avancées méritent d’être explorées. Les App of Apps permettent de gérer un ensemble d’applications ArgoCD via une seule Application racine, pratique pour démarrer un nouveau cluster en une seule commande. Les Sync Waves ordonnent le déploiement de ressources dépendantes, par exemple une base de données avant l’application qui la consomme, via une simple annotation argocd.argoproj.io/sync-wave.

Pour les organisations qui gèrent des dizaines de clusters, le générateur de clusters d’ApplicationSet évite de dupliquer les manifestes à chaque nouvel environnement. Enfin, pour les équipes qui veulent déléguer l’exploitation du control plane sans renoncer à l’open source, Akuity Platform propose une offre managée facturée par nombre d’applications, avec un forfait de 50 applications incluses et des packs supplémentaires de 10 applications à 99 dollars par mois, jusqu’à 1 500 applications au total.

Pensez aussi aux Resource Hooks, qui exécutent des jobs Kubernetes à des moments précis du cycle de synchronisation (PreSync, Sync, PostSync), utiles pour lancer une migration de base de données avant de basculer le trafic vers une nouvelle version. Le mode diff personnalisé (ignoreDifferences) évite enfin les faux positifs de désynchronisation quand un contrôleur tiers, comme un autoscaler horizontal, modifie légitimement le nombre de réplicas en dehors de Git.

Foire aux questions

ArgoCD est-il gratuit ?
Oui, ArgoCD est un projet open source sous licence Apache 2.0, gratuit à installer et exploiter sur votre propre infrastructure. Seules les offres managées comme Akuity Platform sont payantes.

ArgoCD fonctionne-t-il avec Helm et Kustomize en même temps ?
Oui, une Application peut pointer vers un chart Helm, un dossier Kustomize ou de simples manifestes YAML bruts. ArgoCD détecte automatiquement le format à partir du contenu du dépôt.

Faut-il activer le self-healing dès le départ ?
Non, il est recommandé de commencer en mode manuel pour observer le comportement de synchronisation, puis d’activer automated et selfHeal une fois la confiance établie avec le pipeline.

Quelle est la différence entre ArgoCD et un pipeline CI/CD classique ?
Un pipeline CI/CD classique pousse activement les changements vers le cluster. ArgoCD fonctionne à l’inverse : un agent installé dans le cluster tire (pull) les changements depuis Git, ce qui évite de stocker des identifiants de cluster dans l’outil CI.

ArgoCD peut-il gérer plusieurs clusters Kubernetes depuis une seule installation ?
Oui, un serveur ArgoCD central peut piloter plusieurs clusters enregistrés via argocd cluster add, une architecture courante pour les organisations qui séparent staging et production sur des clusters distincts.

Comment revenir en arrière après un déploiement problématique ?
Deux options : argocd app rollback pour revenir à une révision précédente enregistrée par ArgoCD, ou un simple git revert sur le dépôt GitOps, qu’ArgoCD synchronisera automatiquement si le mode automated est actif.

ArgoCD remplace-t-il Terraform ou OpenTofu ?
Non, ces outils opèrent à des niveaux différents. Terraform et OpenTofu provisionnent l’infrastructure (clusters, réseaux, bases de données managées), tandis qu’ArgoCD gère ce qui tourne à l’intérieur du cluster Kubernetes déjà existant. Notre guide sur la migration Terraform vers OpenTofu détaille la partie infrastructure.

Combien de ressources consomme ArgoCD sur un petit cluster ?
Pour un cluster gérant quelques dizaines d’applications, comptez environ 0,5 à 1 vCPU et 512 Mio à 1 Gio de RAM pour argocd-server, et 1 à 2 vCPU avec 1 à 2 Gio de RAM pour le repo-server et le contrôleur d’applications. Ces besoins augmentent avec le nombre d’applications synchronisées.

ArgoCD fonctionne-t-il en dehors de Kubernetes ?
Non, ArgoCD est conçu spécifiquement pour Kubernetes et s’appuie sur ses ressources personnalisées (CRD) pour fonctionner. Pour orchestrer des workflows plus larges, comme des pipelines de traitement de données, le même projet Argo propose un outil distinct, Argo Workflows, qui reste toutefois hors du périmètre de ce tutoriel.

Peut-on migrer progressivement vers ArgoCD sans tout casser ?
Oui, la méthode la plus sûre consiste à commencer par une seule application non critique, en mode manuel plutôt qu’automatisé, le temps que l’équipe se familiarise avec le flux de synchronisation. Une fois ce premier cas d’usage validé, l’extension aux autres applications se fait application par application, sans coupure du pipeline de déploiement existant. Beaucoup d’équipes gardent d’ailleurs l’ancien pipeline en parallèle pendant quelques semaines, le temps de comparer les deux méthodes de déploiement sur les mêmes applications avant de couper définitivement l’ancien chemin.

ArgoCD : GitOps sur Kubernetes en 12 Étapes, 90 Min [2026]