ArgoCD : maîtriser la synchronisation (waves, hooks, options)

Par défaut, ArgoCD applique toutes les ressources d'une Application en même temps. Dès qu'une ressource dépend d'une autre, il faut reprendre la main sur l'ordre et le comportement de la synchronisation. C'est le rôle des sync-waves (ordonner), des resource hooks (exécuter des tâches avant ou après) et des sync options (ajuster le comportement). Ce guide les met en pratique, avec des sorties réelles capturées sur un cluster k3d (ArgoCD v3.4.5). Prérequis : avoir déployé une première application.

Ce que vous allez apprendre

Comprendre les trois phases d'une synchronisation ArgoCD
Ordonner le déploiement de ressources dépendantes avec les sync-waves
Exécuter des tâches avant ou après la synchro avec les resource hooks
Ajuster le comportement avec les sync options (ServerSideApply, prune, replace...)
Synchroniser partiellement une Application

Les trois phases d'une synchronisation

Une synchronisation ArgoCD n'est pas un simple kubectl apply. Elle se déroule en trois phases successives, ce qui permet d'intercaler des actions :

PreSync : avant d'appliquer les manifestes (par exemple, une migration de base de données).
Sync : l'application proprement dite des ressources.
PostSync : après que tout est appliqué et sain (par exemple, un test de fumée).

Une quatrième phase, SyncFail, ne se déclenche qu'en cas d'échec, pour nettoyer ou alerter. Comprendre ces phases est la clé pour orchestrer un déploiement complexe.

Ordonner avec les sync-waves

Quand des ressources dépendent les unes des autres (un CRD avant la ressource qui l'utilise, une base avant l'application), les appliquer en même temps échoue. Les sync-waves donnent à chaque ressource un numéro d'onde via une annotation, et ArgoCD les applique par ordre croissant, en attendant que chaque vague soit saine avant la suivante.

metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "1"   # appliqué avant la wave 2

Une ressource sans annotation est en wave 0. On n'annote donc que ce qui doit venir après. Les valeurs peuvent être négatives (pour ce qui doit passer en tout premier).

Les resource hooks : agir avant ou après

Un resource hook est une ressource Kubernetes (souvent un Job) qu'ArgoCD exécute à une phase précise, repérée par l'annotation argocd.argoproj.io/hook. Typiquement : un Job de migration en PreSync, un Job de test en PostSync.

apiVersion: batch/v1
kind: Job
metadata:
  name: migration-bdd
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: mon-org/migrate:1.4.0
      restartPolicy: Never

L'annotation hook-delete-policy contrôle quand le hook est nettoyé : HookSucceeded (à la réussite), HookFailed (à l'échec), ou BeforeHookCreation (juste avant de le recréer au prochain sync, ce qui garde le dernier pour inspection).

Voir waves et hooks à l'œuvre

Déployons l'exemple officiel sync-waves, qui combine un hook PreSync (migration de schéma), des hooks Sync (page de maintenance) et des déploiements ordonnés. En lisant l'ordre de création des pods, on voit la mécanique réelle :

NAME (dans l'ordre de création)                     STATUT
upgrade-sql-schema...presync...                     Succeeded   ← hook PreSync (1er)
backend                                             Running     ← wave
maint-page-up                                       Succeeded   ← hook Sync
frontend                                            Running     ← wave suivante
maint-page-down                                     Succeeded   ← hook Sync

La migration de schéma (PreSync) s'exécute avant tout le reste. Puis la phase Sync applique les ressources dans l'ordre des ondes, en intercalant les hooks Sync (page de maintenance montée puis descendue autour du déploiement). Les annotations réelles portées par ces ressources :

upgrade-sql-schema...presync   hook=PreSync
maint-page-up                  hook=Sync   hook-delete-policy=BeforeHookCreation
maint-page-down                hook=Sync   hook-delete-policy=BeforeHookCreation

En une Application, on a orchestré un déploiement réaliste : monter une page de maintenance, migrer la base, déployer, redescendre la page. Impossible avec un simple apply.

Les sync options

Les sync options ajustent le comportement de la synchro, au niveau de l'Application ou d'une ressource. Les plus utiles :

Option	Effet
`CreateNamespace=true`	Crée le namespace de destination s'il n'existe pas
`ServerSideApply=true`	Applique côté serveur : indispensable pour les gros CRDs (> 262 Ko)
`ApplyOutOfSyncOnly=true`	N'applique que les ressources réellement dérivées, pas toutes
`Prune=false` (sur une ressource)	Empêche la suppression de cette ressource même si retirée de Git
`Replace=true`	Remplace la ressource (`kubectl replace`) au lieu de la patcher
`RespectIgnoreDifferences=true`	Respecte les `ignoreDifferences` pendant la synchro, pas seulement le diff

Elles se déclarent dans la syncPolicy de l'Application :

syncPolicy:
  syncOptions:
    - CreateNamespace=true
    - ServerSideApply=true

Synchroniser partiellement

Toutes les ressources d'une Application ne doivent pas toujours être synchronisées d'un coup. La sync sélective cible une ou quelques ressources, utile pour débloquer une situation sans tout réappliquer :

# Synchroniser uniquement le Deployment "backend" de l'Application
argocd app sync mon-app --resource apps:Deployment:backend

À l'inverse, argocd app sync mon-app --prune force la suppression des ressources retirées de Git lors de ce sync. Ces commandes manuelles complètent la sync automatique pour les cas particuliers.

Bonnes pratiques et pièges

Toujours borner les hooks avec une hook-delete-policy. Sans elle, les Job de hook s'accumulent dans le cluster à chaque sync.
Garder les hooks idempotents. Un hook PreSync peut se rejouer ; une migration doit pouvoir tourner deux fois sans casser.
Ne pas abuser des waves. Trop d'ondes rend le déploiement lent (ArgoCD attend chaque vague) et difficile à suivre. Réservez-les aux vraies dépendances.
ServerSideApply pour les gros objets. Le client-side apply échoue silencieusement au-delà de 262 Ko : c'est le piège classique des CRDs.

Dépannage

Symptôme	Cause probable	Solution
Ressource créée avant sa dépendance	Pas de sync-wave	Annoter la dépendance en wave inférieure
Hooks `Job` qui s'accumulent	`hook-delete-policy` absente	Ajouter `HookSucceeded` ou `BeforeHookCreation`
`request entity too large`	CRD > 262 Ko en client-side apply	`ServerSideApply=true` dans les syncOptions
Sync bloquée sur une wave	Une ressource de la vague reste non saine	Inspecter cette ressource (`kubectl describe`), corriger avant que la suite ne parte
Migration rejouée à chaque sync	Hook PreSync non idempotent	Rendre le hook idempotent ou le conditionner

À retenir

Une synchronisation ArgoCD a trois phases : PreSync, Sync, PostSync (plus SyncFail en cas d'échec).
Les sync-waves ordonnent les ressources dépendantes ; wave 0 par défaut, on annote ce qui vient après.
Les resource hooks exécutent des Job à une phase donnée (migration en PreSync, test en PostSync), à borner avec hook-delete-policy.
Les sync options ajustent le comportement : ServerSideApply pour les gros CRDs, CreateNamespace, Prune, Replace.
La sync sélective (--resource) débloque une ressource sans tout réappliquer.
Waves et hooks permettent d'orchestrer un déploiement réaliste (page de maintenance, migration, déploiement) en une seule Application.

Pour aller plus loin

Notifications ArgoCD : être alerté du résultat de vos synchronisations sur Slack ou Teams.
Dépannage ArgoCD : résoudre les OutOfSync bloqués et les erreurs de synchronisation.