ArgoCD est un outil de livraison continue déclaratif basé sur GitOps pour Kubernetes qui maintient l’état du cluster en permanence synchronisé avec les configurations stockées dans Git. Si vous avez déjà passé du temps à exécuter manuellement kubectl apply après chaque modification de code ou à traquer des dérives de configuration entre environnements, ArgoCD résout ce problème en faisant de Git l’unique source de vérité pour chaque ressource déployée. Ce guide vous accompagne dans l’installation d’ArgoCD, la connexion de dépôts, la création de ressources Application et la configuration de politiques de synchronisation pour des déploiements de niveau production.

Prérequis

  • Un cluster Kubernetes en cours d’exécution (v1.22+) avec kubectl configuré
  • Permissions d’administrateur du cluster pour créer des namespaces et des CRDs
  • Un dépôt Git contenant des manifestes Kubernetes, des charts Helm ou des overlays Kustomize
  • CLI ArgoCD (argocd) installée localement (optionnel mais recommandé)
  • Familiarité de base avec les Deployments, Services et namespaces Kubernetes

Qu’est-ce que GitOps et pourquoi ArgoCD ?

GitOps est un modèle opérationnel où l’état désiré de l’infrastructure et des applications est déclaré dans Git. Un opérateur s’exécutant dans le cluster compare en permanence l’état réel avec l’état désiré et réconcilie les différences. ArgoCD est l’opérateur GitOps natif Kubernetes le plus adopté, avec le statut de projet diplômé de la CNCF depuis 2022.

Les principaux avantages par rapport aux pipelines CI/CD traditionnels basés sur le push :

FonctionnalitéArgoCD (GitOps pull)Jenkins / GitLab CI (push)
Stockage des identifiantsUniquement dans le clusterDans les secrets du système CI
Détection de dériveContinue, automatiqueUniquement au moment du déploiement
Mécanisme de retour arrièreRevert Git vers n’importe quel commitRé-exécuter l’ancien pipeline
Piste d’auditHistorique GitLogs CI
Support multi-clusterNatif, par ApplicationConfiguration manuelle du pipeline
Auto-réparationBoucle de synchronisation intégréeNon disponible

Le modèle pull est une amélioration significative de la sécurité : votre pipeline CI n’a plus besoin des identifiants du cluster. ArgoCD s’exécute dans le cluster et tire les changements de Git, toujours en sortant uniquement.

Installer ArgoCD

Créez le namespace dédié et appliquez le manifeste d’installation officiel :

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Attendez que tous les pods atteignent l’état Running :

kubectl wait --for=condition=available deployment --all -n argocd --timeout=120s
kubectl get pods -n argocd

Accéder à l’Interface Web

Par défaut, le service argocd-server est de type ClusterIP. Pour un accès local, utilisez le port-forwarding :

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

Récupérez le mot de passe admin généré automatiquement :

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

Connectez-vous via la CLI :

argocd login localhost:8080 --username admin --password <mot-de-passe> --insecure

Pour la production, configurez un Ingress avec TLS et intégrez le SSO (Dex avec GitHub/OIDC) plutôt que d’utiliser le compte admin.

Connecter un Dépôt Git

ArgoCD a besoin d’accéder à votre dépôt Git pour récupérer les manifestes. Pour les dépôts publics, aucun identifiant n’est requis. Pour les dépôts privés :

argocd repo add https://github.com/votre-org/votre-repo-k8s \
  --username git \
  --password <token>

Pour SSH :

argocd repo add git@github.com:votre-org/votre-repo-k8s.git \
  --ssh-private-key-path ~/.ssh/id_rsa

Vous pouvez également gérer les dépôts de façon déclarative en tant que Secrets Kubernetes avec le label argocd.argoproj.io/secret-type: repository si vous préférez une gestion GitOps complète d’ArgoCD lui-même.

Créer des Applications ArgoCD

Une Application est la ressource centrale d’ArgoCD. Elle définit quoi déployer, depuis où et vers quel cluster et namespace.

Manifeste Application déclaratif

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: mon-web-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/votre-org/votre-repo-k8s
    targetRevision: main
    path: manifests/mon-web-app
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      selfHeal: true
      prune: true
    syncOptions:
      - CreateNamespace=true

Appliquez-le :

kubectl apply -f mon-web-app-application.yaml

Applications avec Helm

ArgoCD supporte Helm nativement sans nécessiter Helm sur les systèmes CI :

source:
  repoURL: https://github.com/votre-org/votre-repo-k8s
  targetRevision: main
  path: charts/mon-web-app
  helm:
    valueFiles:
      - values-production.yaml
    parameters:
      - name: image.tag
        value: "v1.4.2"

Applications avec Kustomize

source:
  repoURL: https://github.com/votre-org/votre-repo-k8s
  targetRevision: main
  path: kustomize/overlays/production

ArgoCD détecte automatiquement le kustomization.yaml et exécute kustomize build de façon transparente.

Politiques de Synchronisation et Auto-Réparation

La politique de synchronisation est la décision de configuration la plus importante dans ArgoCD.

Synchronisation manuelle — ArgoCD détecte la dérive mais nécessite une personne (ou une étape CI) pour déclencher la synchronisation. Utile pour les environnements de production où une approbation explicite est souhaitée avant de déployer des changements.

Synchronisation automatique — ArgoCD synchronise automatiquement dès qu’il détecte une différence entre Git et le cluster. Combinez avec l’auto-réparation et l’élagage pour une automatisation complète :

syncPolicy:
  automated:
    selfHeal: true   # annule les modifications kubectl manuelles
    prune: true      # supprime les ressources effacées de Git
  retry:
    limit: 5
    backoff:
      duration: 5s
      maxDuration: 3m
      factor: 2

selfHeal: true signifie que si quelqu’un modifie manuellement une ressource avec kubectl, ArgoCD la rétablira en quelques secondes. Cela impose une discipline GitOps stricte.

prune: true signifie que les ressources supprimées du dépôt Git sont également supprimées du cluster. Sans élagage, les ressources orphelines s’accumulent avec le temps.

Scénario Réel : Promotion Multi-Environnement

Vous avez trois environnements — dev, staging et production — chacun dans un namespace séparé, avec des overlays Kustomize spécifiques par environnement. Votre pipeline CI construit et pousse une image Docker, puis met à jour le tag d’image dans le fichier dev/kustomization.yaml et effectue un commit dans Git.

repo/
  kustomize/
    base/           ← manifestes partagés
    overlays/
      dev/          ← App ArgoCD pour namespace dev
      staging/      ← App ArgoCD pour namespace staging
      production/   ← App ArgoCD pour namespace production (sync manuel)

ArgoCD pour dev utilise automated: {} (déploiement automatique à chaque commit). ArgoCD pour staging et production utilise la synchronisation manuelle : un ingénieur examine le diff dans l’UI et clique sur synchroniser, ou une approbation de PR déclenche un appel argocd app sync dans le pipeline CI.

Ce modèle maintient la promotion contrôlée et auditable via l’historique Git, et non via les logs de build Jenkins.

Pièges et Cas Particuliers

Problèmes d’ordre avec les CRDs — Si votre application installe des Custom Resource Definitions avec des ressources qui les utilisent, ArgoCD peut échouer à la première synchronisation car les CRDs ne sont pas encore établies. Utilisez les sync waves avec argocd.argoproj.io/sync-wave: "-1" sur les manifestes CRD pour garantir leur application en premier.

Élagage et Jobs — L’élagage ArgoCD supprimera les Jobs terminés et leurs Pods s’ils sont retirés de Git. Utilisez argocd.argoproj.io/hook: PostSync et argocd.argoproj.io/hook-delete-policy: HookSucceeded pour les Jobs de migration à exécution unique.

Stratégie de tags d’image — Évitez d’utiliser latest comme tag. ArgoCD compare les manifestes, pas les digests d’image, donc un nouveau push vers latest ne déclenchera pas de synchronisation. Utilisez des tags immuables (SHA git ou semver). Le projet ArgoCD Image Updater peut automatiser la mise à jour des tags dans Git.

RBAC et Projects — Le projet default autorise tous les dépôts et clusters. Pour les configurations multi-équipes, créez des AppProjects avec une portée limitée aux dépôts source, namespaces cibles et types de ressources autorisés.

Gestion des secrets — Ne stockez jamais de manifestes Secrets Kubernetes avec des données en clair dans Git. Utilisez Sealed Secrets, External Secrets Operator ou des secrets chiffrés avec SOPS commités dans Git.

Délai de synchronisation — Les hooks Helm à longue exécution peuvent dépasser le délai de synchronisation par défaut (300s). Augmentez-le avec --timeout en CLI ou configurez timeout.reconciliation dans le ConfigMap argocd-cm.

Problèmes Courants

Application bloquée en Progressing — Vérifiez la sortie de argocd app get <nom> pour les ressources dégradées. C’est généralement un rollout de Deployment échoué ou un PVC en attente. Exécutez kubectl describe pod -n <namespace> sur le Pod concerné.

ComparisonError ou santé Unknown — ArgoCD ne peut pas récupérer les manifestes. Vérifiez la connectivité du dépôt avec argocd repo list et les identifiants.

Boucle d’auto-réparation — Si ArgoCD continue de rétablir une ressource, un webhook de validation ou un opérateur modifie la ressource après qu’ArgoCD l’a appliquée. Utilisez ignoreDifferences dans la spec de l’Application pour ignorer des champs spécifiques.

L’élagage supprime des ressources inattendues — Assurez-vous que toutes les ressources que vous voulez qu’ArgoCD gère ont le label correct app.kubernetes.io/instance.

Résumé

  • ArgoCD implémente GitOps en réconciliant en permanence l’état du cluster avec l’état désiré défini dans Git
  • S’installe avec un seul kubectl apply dans le namespace argocd ; accès via port-forward ou Ingress
  • Les Applications sont définies de façon déclarative et supportent les manifestes bruts, charts Helm et Kustomize
  • Utilisez la synchronisation automatique avec selfHeal et prune pour dev/staging ; synchronisation manuelle pour les approbations en production
  • Organisez les configurations multi-environnements avec des overlays Kustomize ou des fichiers de valeurs Helm par environnement
  • Protégez les secrets avec Sealed Secrets ou External Secrets Operator — jamais en clair dans Git
  • Utilisez les sync waves pour l’ordre des CRDs et ArgoCD Image Updater pour la promotion automatique des tags
  • Les RBAC Projects limitent l’accès aux dépôts et clusters dans les déploiements multi-équipes

Articles Connexes