ArgoCD, Déployer votre première application

Vous avez ArgoCD installé. Il est maintenant temps de lui confier votre première application. Ce guide vous fait créer un dépôt de manifestes, déclarer une Application ArgoCD, déclencher une synchronisation et comprendre tous les statuts affichés dans le dashboard. Public : débutants en GitOps qui ont déjà une instance ArgoCD et veulent déployer leur premier workload. À la fin, une application tourne dans votre cluster et ArgoCD la surveille en continu.

Prérequis

ArgoCD doit être installé et la CLI argocd doit être connecté. Si ce n'est pas encore fait, suivez le guide Installer ArgoCD en premier.

Ce que vous allez apprendre

• Préparer un dépôt de manifestes Kubernetes minimal pour ArgoCD
• Déclarer une Application ArgoCD via CLI et via YAML (méthode GitOps)
• Déclencher et suivre une synchronisation manuelle
• Interpréter les statuts Sync (Synced, OutOfSync) et Health (Healthy, Degraded)
• Activer le self-heal (réconciliation automatique) et le prune (suppression des ressources orphelines)
• Inspecter les diffs et diagnostiquer un échec de synchronisation
• Déployer aussi depuis un chart Helm avec spec.source.helm

Préparer un dépôt de manifestes

ArgoCD déploie ce qu'il trouve dans un dépôt Git. Il vous faut donc un dépôt contenant des manifestes Kubernetes. Si vous n'en avez pas, créez-en un minimal.

Pour cet exemple, nous allons déployer une application Nginx simple. Créez un dépôt Git (GitHub, GitLab ou autre) avec cette structure :

config-repo/
└── nginx-demo/
    ├── deployment.yaml
    ├── service.yaml
    └── namespace.yaml

Contenu des fichiers :

nginx-demo/namespace.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: demo

nginx-demo/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27@sha256:6784fb0834aa7dbbe12e3d7471e69c290df3e6ba810dc38b34ae33d3c1c05f7d
          ports:
            - containerPort: 80

nginx-demo/service.yaml

apiVersion: v1
kind: Service
metadata:
  name: nginx
  namespace: demo
spec:
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80

Commitez ces trois fichiers et poussez sur la branche main. Notez l'URL de votre dépôt.

Créer une Application ArgoCD

Une Application ArgoCD lie une source Git à une destination Kubernetes. Il y a deux façons de la créer : via la CLI ou via un fichier YAML appliqué avec kubectl. Nous allons utiliser les deux pour bien comprendre.

Via le CLI

argocd app create nginx-demo \
  --repo https://github.com/votre-org/config-repo \
  --path nginx-demo \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace demo \
  --revision main

Vérification :

argocd/nginx-demo

argocd app get nginx-demo
# Sync Status:        OutOfSync from main (abc1234)
# Health Status:      Missing
# Source:
# - Repo:             https://github.com/votre-org/config-repo
#   Target:           main
#   Path:             nginx-demo

Le statut OutOfSync est normal : ArgoCD a lu le dépôt Git mais n'a pas encore appliqué les ressources sur le cluster. Missing signifie que les ressources n'existent pas encore.

Flag --grpc-web pour les installations HTTP

Si ArgoCD est exposé en HTTP pur (mode server.insecure=true avec NodePort ou Ingress sans TLS), ajoutez --grpc-web à toutes les commandes argocd :

argocd app get nginx-demo --grpc-web

Cela n'est pas nécessaire quand vous utilisez kubectl port-forward en local.

Via un fichier YAML (méthode GitOps)

La méthode recommandée en production : déclarer les Applications elles-mêmes dans Git.

argocd-app.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx-demo
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/votre-org/config-repo
    targetRevision: main
    path: nginx-demo
  destination:
    server: https://kubernetes.default.svc
    namespace: demo
  syncPolicy:
    syncOptions:
      - CreateNamespace=true  # Crée le namespace si absent

kubectl apply -f argocd-app.yaml

CreateNamespace=true

Sans cette option, si le namespace demo n'existe pas, la synchronisation échoue. Avec elle, ArgoCD crée automatiquement le namespace manquant.

Déclencher une synchronisation

Par défaut, cette Application est en mode synchronisation manuelle : ArgoCD surveille Git mais ne déploie pas tant que vous ne le demandez pas. C'est le comportement sécurisé pour commencer.

# Synchronisation manuelle via CLI
argocd app sync nginx-demo

Sortie attendue :

TIMESTAMP                  GROUP  KIND        NAMESPACE  NAME   STATUS     HEALTH
2026-03-30T12:00:00+02:00         Namespace              demo   OutOfSync  Missing
2026-03-30T12:00:01+02:00         Namespace              demo   Synced     Healthy
2026-03-30T12:00:01+02:00  apps   Deployment  demo       nginx  OutOfSync  Missing
2026-03-30T12:00:02+02:00         Service     demo       nginx  Synced     Healthy
2026-03-30T12:00:03+02:00  apps   Deployment  demo       nginx  Synced     Progressing

Name:               argocd/nginx-demo
Sync Status:        Synced to main (abc1234)
Health Status:      Progressing

Operation:          Sync
Sync Revision:      abc1234
Phase:              Succeeded

Health passe de Progressing à Healthy en quelques secondes, le temps que le pod démarre.

Vérification sur le cluster :

kubectl get pods -n demo
# NAME                     READY   STATUS    RESTARTS
# nginx-xxxxxxxxxx-xxxxx   1/1     Running   0

Le résultat dans le dashboard

Le dashboard ArgoCD donne la même information d'un coup d'œil. Chaque Application est une carte qui affiche le dépôt source, le chemin, la destination et surtout les deux statuts clés en couleur : Healthy (santé) et Synced (synchronisation).

La barre latérale de gauche filtre par statut : sur un cluster qui compte des dizaines d'Applications, elle permet de repérer immédiatement celles qui sont OutOfSync ou Degraded.

Comprendre les statuts

Après la synchronisation, ArgoCD affiche deux statuts pour chaque Application.

Sync Status

Statut	Signification	Que faire
Synced	Le cluster est identique à Git	Rien, tout va bien
OutOfSync	Des différences existent	Inspecter le diff, synchroniser si voulu
Unknown	Impossible de vérifier	Vérifier les droits ArgoCD sur le cluster

Glissez pour voir

Pour voir ce qui diffère :

argocd app diff nginx-demo

Health Status

Statut	Signification
Healthy	Tous les pods tournent correctement
Progressing	Un déploiement est en cours
Degraded	Un pod est en erreur (CrashLoopBackOff, ImagePullBackOff...)
Suspended	Un CronJob est pausé
Missing	La ressource est dans Git mais pas dans le cluster
Unknown	ArgoCD ne peut pas évaluer la santé

Glissez pour voir

Pour inspecter en détail :

argocd/nginx-demo

argocd app get nginx-demo
# Sync Status:        Synced to main (abc1234)
# Health Status:      Healthy
# Source:
# - Repo:             https://github.com/votre-org/config-repo
#   Target:           main
#   Path:             nginx-demo

argocd app resources nginx-demo
# GROUP  KIND        NAMESPACE  NAME   ORPHANED
#        Namespace              demo   No
#        Service     demo       nginx  No
# apps   Deployment  demo       nginx  No

Déployer depuis un chart Helm

Jusqu'ici, la source de l'Application était un dossier de manifestes YAML bruts. ArgoCD sait aussi déployer un chart Helm directement, sans que vous lanciez helm install : c'est le repo-server qui effectue le rendu (helm template) et applique le résultat. C'est la source la plus courante en entreprise.

On la déclare dans spec.source.helm : le chart (ici un sous-dossier du dépôt), les fichiers de valeurs et des paramètres qui surchargent des valeurs à la volée.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: helm-guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps
    targetRevision: HEAD
    path: helm-guestbook          # dossier contenant le Chart.yaml
    helm:
      valueFiles:
        - values.yaml
      parameters:
        - name: replicaCount       # surcharge une valeur du chart
          value: "2"
  destination:
    server: https://kubernetes.default.svc
    namespace: helm-guestbook
  syncPolicy:
    automated: { prune: true, selfHeal: true }
    syncOptions:
      - CreateNamespace=true

Après synchronisation, ArgoCD a rendu le chart et appliqué le paramètre replicaCount=2 :

helm-guestbook: sync=Synced health=Healthy

NAME             READY   UP-TO-DATE   AVAILABLE
helm-guestbook   2/2     2            2

Le paramètre replicaCount a bien produit deux réplicas, sans modifier le chart : ArgoCD garde Git comme source de vérité et injecte vos valeurs au rendu. La même mécanique existe pour Kustomize (spec.source.kustomize), détaillée dans Multi-environnements.

Activer la synchronisation automatique

La synchronisation manuelle est bien pour comprendre. En pratique, on active l'auto-sync pour que le cluster se rapproche de Git dès qu'un commit est poussé.

argocd app set nginx-demo \
  --sync-policy automated \
  --auto-prune \
  --self-heal

Ou par YAML en modifiant la syncPolicy :

syncPolicy:
  automated:
    prune: true      # Supprime les ressources retirées de Git
    selfHeal: true   # Corrige le drift automatiquement
  syncOptions:
    - CreateNamespace=true

Que fait exactement selfHeal ?

Self-heal : si quelqu'un modifie une ressource directement avec kubectl (un kubectl edit deployment nginx -n demo par exemple), ArgoCD détecte l'écart et remet la ressource dans l'état décrit dans Git. Votre cluster ne peut plus dériver en dehors de ce que Git dit.

Prune : si vous supprimez un fichier YAML du dépôt Git et poussez, ArgoCD supprime la ressource correspondante dans le cluster. Sans prune, la ressource reste en place silencieusement.

Tester le self-heal

Pour voir le self-heal en action, modifiez directement le Deployment dans le cluster :

kubectl scale deployment nginx -n demo --replicas=3

Attendez environ 20 secondes, puis vérifiez :

kubectl get deployment nginx -n demo
# NAME    READY   UP-TO-DATE   AVAILABLE   AGE
# nginx   1/1     1            1           5m

ArgoCD a détecté l'écart et remis le Deployment à 1 replica, comme décrit dans Git.

Tester la synchronisation automatique

Modifiez maintenant un fichier dans votre dépôt Git, la source de vérité, sans toucher au cluster. Par exemple, changez replicas: 1 en replicas: 2 dans deployment.yaml et poussez.

En quelques secondes (ou au prochain polling de 3 minutes), ArgoCD passe à OutOfSync, puis se synchronise et déploie la nouvelle version.

# Surveiller en temps réel
watch argocd app get nginx-demo

À retenir

• Une Application ArgoCD lie une source Git (dépôt + chemin + branche) à une destination Kubernetes (cluster + namespace).
• OutOfSync = des différences existent entre Git et le cluster. Synced = le cluster correspond à Git.
• Healthy = les workloads déployés fonctionnent. Degraded = erreur sur un pod ou une ressource.
• Auto-sync déclenche automatiquement les déploiements sur chaque push Git.
• Self-heal corrige automatiquement toute modification manuelle du cluster.
• Prune supprime du cluster les ressources retirées de Git.
• La commande argocd app diff montre exactement ce qui diffère avant de synchroniser.

Pour aller plus loin

• Multi-environnements : gérer dev, staging et production avec Kustomize et ApplicationSet.
• Intégration CI/CD : connecter votre pipeline CI à ArgoCD sans accès direct au cluster.

×

📖 Voir la documentation →