Dépannage ArgoCD : OutOfSync, erreurs de synchro, santé dégradée

Une Application reste OutOfSync sans que vous compreniez pourquoi, une synchronisation échoue, ou une ressource passe en Degraded. Ce guide de dépannage donne la méthode de diagnostic ArgoCD et les correctifs des pannes les plus fréquentes, avec des sorties réelles capturées sur un cluster k3d (ArgoCD v3.4.5). Public : toute personne qui exploite ArgoCD au quotidien et doit débloquer une situation vite. Prérequis : avoir déployé une première application et connaître les concepts.

Ce que vous allez apprendre

Lire l'état d'une Application pour localiser le problème
Débloquer une Application coincée en OutOfSync
Corriger une ComparisonError (ArgoCD ne peut pas comparer)
Traiter une synchronisation qui échoue ou une ressource Degraded
Résoudre les erreurs d'accès au dépôt Git

Diagnostic rapide

Avant de plonger, ce tableau relie un symptôme à sa cause probable et à la section qui le traite en détail.

Symptôme	Cause probable	Où regarder
Statut OutOfSync permanent	Dérive réelle, ou champ ignoré manquant	OutOfSync qui persiste
ComparisonError (rouge)	ArgoCD ne peut pas rendre les manifestes	ComparisonError
Sync qui échoue immédiatement	Hook en erreur, RBAC, ressource invalide	Sync qui échoue
Ressource Degraded / Progressing sans fin	Le pod ne démarre pas, sonde qui échoue	Santé dégradée
Unable to connect to repository	Identifiants ou URL du dépôt	Accès au dépôt
App bloquée à la suppression	Finalizer en attente	Suppression bloquée

La méthode : lire l'état avant d'agir

ArgoCD expose tout l'état nécessaire au diagnostic. Le réflexe est de regarder avant de forcer. Trois angles complémentaires : le résumé de l'Application, le détail par ressource, les événements.

# Résumé : statut de synchro et de santé
kubectl -n argocd get app guestbook \
  -o custom-columns="NAME:.metadata.name,SYNC:.status.sync.status,HEALTH:.status.health.status"

NAME        SYNC        HEALTH
guestbook   OutOfSync   Healthy

Ici l'Application est saine (les pods tournent) mais OutOfSync : l'état du cluster diverge de Git. Pour savoir quelle ressource dérive, on descend au niveau des ressources :

kubectl -n argocd get app guestbook \
  -o jsonpath='{range .status.resources[*]}{.kind}/{.name}: sync={.status}{"\n"}{end}'

Service/guestbook-ui: sync=Synced
Deployment/guestbook-ui: sync=OutOfSync

Le Deployment est le coupable. Dans l'interface, le même diagnostic saute aux yeux : la carte de l'application affiche l'état, et la vue arbre pointe la ressource concernée.

Dashboard ArgoCD v3.4.5 : l'application guestbook en Healthy + OutOfSync, filtres de synchronisation à gauche

Une Application reste OutOfSync

C'est la situation la plus fréquente. OutOfSync signifie que le cluster ne correspond pas à Git, rien de plus. Trois causes distinctes, trois traitements.

Cause 1 : une dérive réelle

Quelqu'un a modifié le cluster à la main (kubectl scale, kubectl edit). La correction dépend de votre politique :

# Voir précisément ce qui diffère (Git vs cluster)
argocd app diff guestbook

# Réappliquer Git par-dessus le cluster
argocd app sync guestbook

Si l'Application a selfHeal: true, ArgoCD annule automatiquement ce genre de dérive. Si elle reste OutOfSync malgré selfHeal, c'est que la dérive porte sur un champ qu'ArgoCD ignore (cas suivant).

Cause 2 : un champ géré par un contrôleur

Un HorizontalPodAutoscaler ajuste replicas, un webhook injecte un sidecar : ArgoCD voit une différence permanente entre Git (replicas: 2) et le cluster (replicas: 5). La solution n'est pas de synchroniser en boucle, mais de dire à ArgoCD d'ignorer ce champ :

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas   # géré par le HPA, pas par Git

Cause 3 : un ordre de champs ou une valeur par défaut

Kubernetes réécrit certains manifestes (ajout de status, normalisation). Depuis la 3.0, activer ServerSideDiff=true dans les syncOptions rend le diff bien plus fidèle en s'appuyant sur le dry-run côté serveur, ce qui élimine beaucoup de faux OutOfSync.

ComparisonError : ArgoCD ne peut pas comparer

Un statut Unknown avec un bandeau rouge ComparisonError veut dire qu'ArgoCD n'arrive même pas à générer l'état désiré depuis Git. Le message exact est dans les conditions de l'Application :

kubectl -n argocd get app guestbook \
  -o jsonpath='{range .status.conditions[*]}{.type}: {.message}{"\n"}{end}'

Les causes classiques et leur correctif :

Erreur de template Helm ou Kustomize : le rendu échoue. Reproduisez en local (helm template, kustomize build) pour voir l'erreur brute.
path inexistant dans le dépôt : le chemin déclaré dans l'Application ne pointe plus vers rien (dossier renommé). Corrigez le spec.source.path.
Version d'outil : depuis la 3.0, ArgoCD embarque Helm 3.17.1, plus strict sur les valeurs nulles. Un chart qui passait avant peut échouer ; épinglez ou corrigez les valeurs concernées.

Une synchronisation échoue

La synchro démarre puis passe en Failed. L'operationState porte le détail de l'échec :

kubectl -n argocd get app guestbook \
  -o jsonpath='{.status.operationState.phase}: {.status.operationState.message}{"\n"}'

Les pistes à suivre dans l'ordre :

Un hook en erreur : un Job PreSync qui échoue bloque toute la synchro. Inspectez le Job (kubectl logs) ; rendez le hook idempotent. Voir la synchronisation.
RBAC insuffisant : le compte de service d'ArgoCD n'a pas le droit de créer la ressource. Le message mentionne forbidden. Ajustez le rôle sur le cluster cible.
Ressource invalide : le manifeste est refusé par l'API (ou par un admission controller comme Kyverno). Le message reprend l'erreur d'admission.

Une ressource reste Degraded

L'Application est synchronisée mais Degraded ou Progressing sans fin : le problème n'est plus dans ArgoCD, il est dans le cluster. ArgoCD ne fait que refléter la santé Kubernetes.

# Descendre à la ressource et au pod
kubectl -n guestbook get pods
kubectl -n guestbook describe pod <pod-en-erreur>

Les causes habituelles sont celles de tout déploiement Kubernetes : image introuvable (ImagePullBackOff), sonde de vivacité qui échoue, ressources insuffisantes, secret manquant. Corrigez la cause dans Kubernetes : ArgoCD repassera Healthy tout seul dès que le pod sera sain.

Erreur d'accès au dépôt

Le message Unable to connect to repository ou authentication required signale un problème d'identifiants Git, pas de déploiement.

Dépôt privé : depuis la 3.0, les dépôts ne se déclarent plus dans argocd-cm mais dans des Secrets étiquetés argocd.argoproj.io/secret-type: repository. Vérifiez que le Secret existe et porte le bon label.
Clé SSH ou token expiré : régénérez et mettez à jour le Secret.
URL erronée : https:// contre git@, la forme doit correspondre au type d'authentification déclaré.

Une Application refuse de se supprimer

Une Application coincée à la suppression a presque toujours un finalizer en attente : ArgoCD veut supprimer les ressources filles d'abord (cascade), mais l'une d'elles résiste.

# Voir le finalizer
kubectl -n argocd get app guestbook -o jsonpath='{.metadata.finalizers}'

Traitez d'abord la ressource fille bloquée (souvent un namespace ou un volume avec son propre finalizer). Retirer le finalizer de l'Application à la main est un dernier recours : cela laisse les ressources filles orphelines dans le cluster.

Prévention

Beaucoup de pannes se règlent en amont par des réglages robustes :

ServerSideDiff=true pour un diff fidèle et moins de faux OutOfSync.
ignoreDifferences déclaré pour tout champ possédé par un contrôleur (HPA, webhooks).
Hooks idempotents et bornés par hook-delete-policy.
Surveillance de la métrique argocd_app_info pour être alerté d'un statut anormal avant l'utilisateur. Voir superviser ArgoCD.
Notifications sur les synchros échouées pour ne pas découvrir la panne trop tard. Voir notifications.

À retenir

OutOfSync n'est pas une erreur : c'est un écart entre Git et le cluster. Demandez qui possède le champ avant d'agir.
Un champ géré par un contrôleur (HPA) se déclare dans ignoreDifferences, on ne le synchronise pas en boucle.
ComparisonError = ArgoCD ne peut pas rendre Git (template cassé, path absent, Helm 3.17.1 plus strict).
Une sync qui échoue vient souvent d'un hook, du RBAC ou d'un admission controller ; le message est dans operationState.
Une ressource Degraded est un problème Kubernetes qu'ArgoCD ne fait que refléter : corrigez le pod.
Depuis la 3.0 : dépôts en Secrets (plus dans argocd-cm) et logs soumis au RBAC.

Pour aller plus loin

Admission Controllers : Valider les déploiements GitOps avec Kyverno et policy-as-code pour bloquer les manifestes fautifs en amont.