Le sync vient de réussir. L’Application repasse OutOfSync dans la foulée, sur un champ que personne n’a touché, et le diff affiche une différence d’un seul entier ou d’une chaîne encodée. Relancer le sync ne change rien : la boucle se reforme à l’identique.

Ce n’est ni un bug ni une dérive. C’est l’état normal d’un système qui compare Git à un cluster dans lequel quelque chose d’autre écrit aussi. La question utile n’est pas comment faire taire l’alerte, mais comment déclarer que cette divergence-là est attendue sans perdre la détection sur tout le reste.

Ce qui écrit dans l’objet en plus de vous

La documentation Argo CD énumère les causes connues d’un OutOfSync immédiatement après un sync réussi, et elles se rangent en trois familles.

La première, ce sont les contrôleurs et les webhooks mutants : l’objet est modifié après avoir été soumis à l’API, il ne ressemble donc plus à ce que Git décrit. Le cas d’école documenté est l’objet HPA, dont le contrôleur réordonne spec.metrics dans un ordre à lui — le contournement recommandé n’est même pas d’ignorer le champ, c’est d’écrire spec.metrics dans Git dans l’ordre que le contrôleur préfère.

La deuxième, ce sont les manifestes non déterministes. Un chart Helm qui utilise une fonction de template comme randAlphaNum produit une valeur différente à chaque invocation de helm template. L’état désiré change tout seul, à commit constant.

La troisième est plus vexante : le manifeste contient un champ inconnu ou en trop au regard de la spec Kubernetes réelle. Ce champ est supprimé quand Argo CD interroge le cluster pour lire l’état live, ce qui produit un OutOfSync signalant un champ manquant. Le diff pointe alors vers une faute de frappe, pas vers un contrôleur.

S’ajoute un cas qui n’est pas une mutation du tout : un sync effectué avec l’élagage désactivé laisse des ressources qui devraient être supprimées, et l’Application reste OutOfSync pour cette raison. Chercher le champ coupable est alors une perte de temps, il n’y en a pas.

Trois manières de désigner ce qu’on ignore

spec.ignoreDifferences est une liste d’entrées, chacune ciblant un group et un kind. Le group est le groupe d’API sans la version — écrire apps/v1 ne matche rien.

Le sélecteur le plus courant est le pointeur JSON, au sens de la RFC 6902 :

# Ignore the replicas field for every Deployment of this Application
spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas

L’entrée se restreint à un objet nommé, avec un namespace facultatif, ce qui vaut mieux que de neutraliser un champ pour tous les Deployments d’un coup :

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      name: guestbook
      namespace: default
      jsonPointers:
        - /spec/replicas

Un piège de syntaxe attend celui qui ignore un label : le pointeur JSON utilise / comme séparateur, donc un / présent dans la clé se remplace par ~1.

# node-role.kubernetes.io/worker -> node-role.kubernetes.io~1worker
spec:
  ignoreDifferences:
    - kind: Node
      jsonPointers:
        - /metadata/labels/node-role.kubernetes.io~1worker

Le deuxième sélecteur, jqPathExpressions, sert quand la cible est un élément de liste identifié par son contenu et non par son index. C’est le cas d’un conteneur d’init injecté par un maillage de services ou par un opérateur : sa position dans la liste n’est pas garantie.

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jqPathExpressions:
        - .spec.template.spec.initContainers[] | select(.name == "injected-init-container")

Une limite à connaître avant d’écrire une expression compliquée : l’évaluation d’une jqPathExpression est plafonnée à une seconde. Le message JQ patch execution timed out se corrige en relevant ignore.normalizer.jq.timeout dans la ConfigMap argocd-cmd-params-cm, mais une expression qui dépasse une seconde mérite d’abord d’être simplifiée.

Le troisième sélecteur est le plus intéressant, et le moins utilisé. managedFieldsManagers ignore tous les champs appartenant à un gestionnaire donné, lus dans metadata.managedFields de la ressource live. On ne décrit plus les champs un par un, on décrit qui a le droit de les posséder.

# Ignore whatever kube-controller-manager owns, whatever the field is
spec:
  ignoreDifferences:
    - group: '*'
      kind: '*'
      managedFieldsManagers:
        - kube-controller-manager

C’est la formulation à privilégier quand la cause est « un contrôleur écrit dans cet objet ». Elle décrit le mécanisme réel au lieu d’énumérer ses symptômes, et elle ne dérive pas quand le contrôleur se met à toucher un champ de plus.

Le niveau système, pour les divergences qui ne sont pas les vôtres

Certaines divergences n’appartiennent à aucune Application en particulier : elles viennent du type de ressource. Elles se règlent dans la clé resource.customizations de la ConfigMap argocd-cm, indexée par groupe et par kind.

# argocd-cm — the caBundle of a MutatingWebhookConfiguration is injected
# by a cert manager, never by Git.
data:
  resource.customizations.ignoreDifferences.admissionregistration.k8s.io_MutatingWebhookConfiguration: |
    jqPathExpressions:
    - '.webhooks[]?.clientConfig.caBundle'

La même configuration accepte .all pour viser toutes les ressources de toutes les Applications de l’instance. C’est puissant et c’est exactement là qu’on se tire dans le pied : une entrée .all qui ignore /spec/replicas retire la détection de dérive sur le nombre de réplicas pour l’ensemble de la plateforme, y compris là où ce nombre est réellement géré par Git.

Deux réglages spécifiques valent la peine d’être connus, parce qu’ils traitent des cas très fréquents. ignoreResourceStatusField désactive le diff sur le champ status, avec all pour valeur par défaut — le status est écrit par les contrôleurs et ne peut pas être appliqué comme configuration désirée. La documentation recommande crd plutôt que none pour ceux qui commitent le status de leurs CRD dans Git. Et ignoreAggregatedRoles: true évite qu’Argo CD lise comme une dérive les règles injectées dans un ClusterRole agrégé.

data:
  resource.compareoptions: |
    ignoreResourceStatusField: crd
    ignoreAggregatedRoles: true

Le point que tout le monde manque : ignorer n’empêche pas d’écrire

C’est la subtilité qui fait qu’ignoreDifferences semble « ne pas marcher » alors qu’il fonctionne exactement comme documenté.

ignoreDifferences n’agit que sur le calcul du diff. Il décide si l’Application est affichée comme synchronisée. Pendant le sync, l’état désiré est appliqué tel quel, et le patch est calculé par un merge à trois voies entre l’état live, l’état désiré et l’annotation last-applied-configuration — le merge que personne ne regarde vraiment.

Traduit en conséquence : ignorer /spec/replicas fait taire l’écran, puis le prochain sync réécrit quand même la valeur de Git par-dessus celle du HPA. L’écran ne ment plus, mais le cluster se fait bien remettre le compteur à zéro.

L’option de sync RespectIgnoreDifferences=true est ce qui étend ignoreDifferences à l’étape de sync : l’état désiré est pré-patché avant d’être appliqué.

spec:
  ignoreDifferences:
    - group: 'apps'
      kind: 'Deployment'
      jsonPointers:
        - /spec/replicas
  syncPolicy:
    syncOptions:
      - RespectIgnoreDifferences=true

Elle vient avec une réserve documentée qui compte à la création : l’option n’est effective que si la ressource existe déjà dans le cluster. Quand l’Application est créée et qu’aucun état live n’existe, l’état désiré est appliqué tel quel. Le premier déploiement pose donc bien la valeur de Git ; ce sont les suivants qui la laissent tranquille.

Deux mécanismes voisins qu’on confond avec celui-ci

argocd.argoproj.io/compare-options: IgnoreExtraneous ne traite pas un champ mais une ressource entière en trop, typiquement un ConfigMap généré par un outil. Elle l’exclut du statut de synchronisation de l’application, et la documentation précise la limite : seul le statut de sync est affecté, la santé dégradée de la ressource dégrade quand même l’application.

ignoreResourceUpdates ressemble à ignoreDifferences jusque dans sa syntaxe, mais il répond à une question de performance, pas d’affichage. Par défaut, une Application est rafraîchie à chaque changement d’une ressource qui lui appartient ; des contrôleurs qui mettent à jour périodiquement leurs objets déclenchent des réconciliations en continu et font monter le CPU du contrôleur d’applications. ignoreResourceUpdates dit « ce changement-là ne justifie pas une réconciliation ». Il n’a aucun effet sur le diff.

# argocd-cm — the refreshTime of an ExternalSecret changes constantly and
# never justifies a reconcile.
data:
  resource.customizations.ignoreResourceUpdates.external-secrets.io_ExternalSecret: |
    jsonPointers:
    - /status/refreshTime

Les deux se croisent sur un point à connaître : par défaut, les ignoreDifferences définis au niveau système sont aussi appliqués aux mises à jour de ressources, comportement qu’on désactive avec ignoreDifferencesOnResourceUpdates: false dans resource.compareoptions.

Le critère pour savoir jusqu’où ignorer

Une règle d’ignorance bien écrite décrit qui possède le champ, pas quelle valeur on tolère. C’est la différence entre managedFieldsManagers: [kube-controller-manager], qui reste vraie quand le contrôleur évolue, et une liste de pointeurs JSON qu’il faudra rallonger à chaque montée de version.

Et la formulation qui doit déclencher une relecture, c’est jsonPointers: [/spec] ou une entrée .all sans group ni kind. À ce niveau-là, on n’a plus déclaré une divergence attendue : on a débranché la détection de dérive, qui est la seule raison d’exécuter un contrôleur GitOps en premier lieu.

Suite logique côté opérations : ArgoCD ou Flux et le parcours la chaîne CI/CD.