Le commit est mergé. On clique sur Refresh, l’Application reste Synced sur l’ancienne révision. On clique sur Sync, et il déploie quand même quelque chose — pas forcément ce qu’on vient de pousser.

Les deux boutons sont côte à côte dans l’interface et portent des noms proches. Ils ne font ni la même chose, ni sur les mêmes données, et l’un des deux n’écrit rien du tout dans le cluster. Le troisième bouton, celui qui se cache dans le menu déroulant du premier, existe précisément parce que le premier ne suffit pas toujours.

Refresh recalcule, sync écrit

Un refresh est une opération de lecture. Argo CD relit l’état désiré — les manifestes générés depuis la source — et l’état live via l’API Kubernetes, recalcule le diff, et met à jour le statut Synced / OutOfSync. Rien n’est appliqué au cluster.

Un sync est une opération d’écriture. C’est celle qui exécute kubectl apply (ou replace, ou apply --server-side, selon les options de synchronisation), qui joue les hooks et les vagues, et qui s’inscrit dans l’historique de l’Application.

En CLI, la distinction est visible dans les commandes elles-mêmes : argocd app get my-app --refresh rafraîchit les données de l’Application au moment de la lecture, tandis que argocd app sync my-app déclenche une opération.

# Read-only: recompute the diff, write nothing to the cluster
argocd app get my-app --refresh

# Read-only, and also invalidate the target manifests cache
argocd app get my-app --hard-refresh

# Write: run the sync operation
argocd app sync my-app

La conséquence pratique est simple : un refresh ne peut rien casser, et il ne peut rien réparer non plus. Un OutOfSync obtenu après refresh est un diagnostic, pas un début de correction.

Le cache qui explique le hard refresh

Reste la question qui amène tout le monde ici : pourquoi un refresh ne voit-il parfois pas un changement pourtant présent dans le dépôt ?

Parce qu’Argo CD ne régénère pas les manifestes à chaque refresh. Le argocd-repo-server met en cache les manifestes générés — 24 heures par défaut, réglables par --repo-cache-expiration. L’hypothèse derrière ce cache est explicite dans la documentation : les manifestes ne changent que quand le dépôt change.

Cette hypothèse est fausse dans au moins deux situations courantes. Une base Kustomize distante peut évoluer sans que le dépôt de l’Application bouge. Et un chart Helm modifié sans incrément de son numéro de version produit d’autres manifestes à URL et version identiques. Dans les deux cas, le refresh normal constate — correctement — que la révision n’a pas changé, et sert le cache.

C’est ce que débloque le hard refresh : il rafraîchit les données de l’Application et le cache des manifestes cibles. La documentation de la CLI le formule exactement ainsi pour --hard-refresh.

Deux autres cas justifient le bouton, et ils sont documentés pour eux-mêmes. Le premier est l’erreur Manifest generation error (cached) : quand la génération de manifestes échoue, le message d’erreur est mis en cache pour éviter des retentatives en boucle. Un hard refresh ignore l’erreur cachée et permet de passer outre un incident transitoire — mais s’il existe une cause persistante, il n’y changera rien, et la documentation renvoie alors aux logs du repo-server en cherchant le nom de l’application. Le second cas est le développement d’un plugin de gestion de configuration : les erreurs du plugin sont mises en cache dans Redis, et redémarrer le pod repo-server ne vide pas ce cache. C’est le réflexe naturel, et il ne marche pas.

À l’inverse, si vous vous surprenez à faire un hard refresh de manière routinière sur une Application donnée, ce n’est plus un dépannage : c’est le signe qu’un cache de 24 heures ne convient pas à cette source. Réduire --repo-cache-expiration est la réponse prévue — la documentation suggère une heure en environnement à faible volume, en rappelant qu’une valeur trop basse annule le bénéfice du cache.

Qui déclenche un refresh sans que vous cliquiez

Trois mécanismes provoquent un refresh, et aucun ne provoque un sync.

La boucle périodique. Le contrôleur d’applications relit la source à intervalle régulier. La valeur est timeout.reconciliation dans la ConfigMap argocd-cm, à 120 secondes par défaut, à laquelle s’ajoute un timeout.reconciliation.jitter d’une minute par défaut. D’où le « toutes les trois minutes » qu’on lit ailleurs dans la documentation : c’est la borne haute. Le jitter n’est pas décoratif — il étale les rafraîchissements pour éviter que toutes les Applications ne tapent le repo-server en même temps.

Les changements de ressources. Par défaut, une Application est rafraîchie chaque fois qu’une ressource lui appartenant change. C’est aussi la raison pour laquelle des contrôleurs bavards peuvent maintenir un contrôleur d’applications sous charge en continu, et ce qu’ignoreResourceUpdates sert à calmer.

Le webhook. Un webhook Git pointant vers /api/webhook supprime le délai de sondage. Ce qu’il déclenche est un refresh, pas un déploiement — la documentation le dit en toutes lettres pour justifier que le secret partagé soit facultatif : un événement non authentifié ne peut provoquer qu’un rafraîchissement, opération qui se produit déjà toute seule toutes les trois minutes. Le déploiement, lui, ne part que si une politique automatisée existe derrière.

Un détail à connaître avant de brancher le webhook : le gestionnaire ne distingue pas un événement de branche d’un événement de tag portant le même nom. Un push sur la branche x rafraîchit une Application pointant sur refs/tags/x du même dépôt.

Ce qu’un sync automatique fait, et ne refait pas

Quand spec.syncPolicy.automated est actif, le sync suit un refresh — mais pas systématiquement, et les règles documentées expliquent la plupart des « pourquoi il ne redéploie pas ».

Un sync automatique n’est tenté que si l’Application est OutOfSync ; en état Synced ou en erreur, rien ne part. Surtout, il n’est tenté qu’une fois par combinaison unique de SHA de commit et de paramètres. Si le dernier sync réussi de l’historique portait déjà ce couple, il n’y a pas de seconde tentative — sauf si selfHeal est activé, auquel cas la tentative est rejouée après le délai d’auto-guérison, cinq secondes par défaut. Et un sync automatique qui a échoué sur un couple donné n’est pas retenté sur ce même couple.

C’est ici que le cache et l’automatisme se rejoignent en un mode de défaillance propre : un chart modifié sans changement de version ne produit ni nouvelle révision, ni nouveaux paramètres. Rien ne bouge, et rien ne le signale. Le hard refresh est alors le seul geste qui remet le système en mouvement.

# The reconciliation cadence, in argocd-cm
# timeout.reconciliation: 120s
# timeout.reconciliation.jitter: 60s
kubectl -n argocd get cm argocd-cm -o yaml | grep -A1 'timeout.reconciliation'

Dernier point qui surprend : un rollback ne peut pas être effectué sur une Application dont le sync automatique est activé. Ce n’est pas une limite arbitraire, c’est la conséquence directe du modèle — l’état désiré est Git, et revenir en arrière sans passer par Git remettrait immédiatement le contrôleur en désaccord avec lui-même. Le retour arrière d’un système GitOps est un commit, pas un bouton, ce qui n’a rien d’évident quand on vient du kubectl rollout undo.

Pour la mécanique de réconciliation elle-même : le déploiement déclaratif avec ArgoCD, et le parcours la chaîne CI/CD pour la place de tout ceci dans le pipeline.