Ancres et alias YAML expliqués (avec exemples à copier-coller)

Si vous avez déjà copié-collé les mêmes 10 lignes de YAML à trois endroits différents dans un fichier de config, vous avez ressenti la douleur que les ancres YAML sont conçues pour résoudre. Une ancre vous permet de définir une valeur une seule fois et d’y faire référence de n’importe où dans le même document. Changez la valeur à un seul endroit, et chaque référence se met à jour.

Cet article explique comment les ancres et alias fonctionnent, quand les utiliser et les cas limites qui piègent les gens.

La syntaxe de base

Une ancre YAML est un nom que vous donnez à un nœud :

defaults: &defaults
  retries: 3
  timeout: 30
  log_level: info

Le &defaults est l’ancre. Elle s’attache à la valeur de defaults, qui est une map. Vous pouvez mettre des ancres sur n’importe quel nœud — une chaîne, un nombre, une liste, une map, une séquence.

Un alias est une référence vers une ancre :

production:
  <<: *defaults
  region: us-east-1
  replicas: 5

staging:
  <<: *defaults
  region: us-west-2
  replicas: 2

Le <<: *defaults est la « clé de fusion ». Il dit « prends tout ce qui vient de l’ancre appelée defaults et fusionne-le dans cette map. » Le résultat est le même que si vous aviez écrit le contenu de defaults en ligne :

production:
  retries: 3
  timeout: 30
  log_level: info
  region: us-east-1
  replicas: 5

Mais si vous changez retries dans defaults, chaque endroit qui utilise l’ancre se met à jour. C’est justement le but.

Ancres sur des valeurs simples

Les ancres ne doivent pas fusionner dans une map. Vous pouvez ancrer une valeur simple et y faire référence :

api_version: &api "v2.1.0"
services:
  auth:
    version: *api
  billing:
    version: *api
  reports:
    version: *api

Maintenant, changer la version de l’API est un changement en une ligne. Les références suivent toutes.

Vous pouvez aussi ancrer une liste :

allowed_origins: &origins
  - https://app.example.com
  - https://admin.example.com
  - https://staging.example.com

cors:
  web: *origins
  api: *origins

La liste est réutilisée à l’identique.

Quand les ancres sont utiles

Les ancres brillent lorsque vous avez des valeurs par défaut partagées entre plusieurs instances. Les manifests Kubernetes, les fichiers docker-compose et les matrices CI sont pleins de ce modèle.

Une note pour 2026 : Helm et Kustomize dominent maintenant le templating Kubernetes, et ils opèrent en dehors du système d’ancres de YAML — ils génèrent du YAML, ils ne l’analysent pas. Si vous utilisez Helm ou Kustomize, vous n’avez pas besoin d’ancres (vous avez values.yaml et des patches de superposition à la place). Les ancres restent le bon choix pour les workflows kubectl apply -f simples, les matrices GitHub Actions, les fichiers docker-compose et toute configuration rédigée manuellement qui ne passe pas par un moteur de template.

Un exemple Kubernetes — trois services avec les mêmes limites de ressources :

base_resources: &base_resources
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

apiDeployment:
  spec:
    template:
      spec:
        containers:
          - name: api
            image: myapp/api:1.2.3
            resources: *base_resources

workerDeployment:
  spec:
    template:
      spec:
        containers:
          - name: worker
            image: myapp/worker:1.2.3
            resources: *base_resources

Un exemple docker-compose — même environnement pour dev et prod :

common_env: &common_env
  DATABASE_URL: postgres://db.internal/app
  REDIS_URL: redis://cache.internal:6379
  LOG_LEVEL: info

services:
  api:
    environment:
      <<: *common_env
      ENVIRONMENT: dev
  worker:
    environment:
      <<: *common_env
      ENVIRONMENT: dev

Dans les deux cas, modifier l’environnement commun est un édit en une ligne.

Les pièges

Les ancres sont puissantes mais ont quelques arêtes vives.

Les ancres sont locales à un document. Un fichier YAML multi-documents (avec des séparateurs ---) a sa propre portée pour les ancres. Une ancre définie dans le document un ne peut pas être référencée depuis le document deux. Si vous utilisez des outils qui produisent du YAML multi-documents (comme kubectl get -o yaml avec plusieurs ressources), vous ne pouvez pas utiliser des ancres pour partager des valeurs entre eux.

Les ancres et les fusionnements interagissent avec les remplacements de façon surprenante. Si l’ancre et la map qui la référence définissent toutes deux la même clé, la valeur de la map qui référence l’emporte :

defaults: &defaults
  retries: 3
  timeout: 30

production:
  <<: *defaults
  retries: 10  # c'est cette valeur qui l'emporte

Donc production.retries est 10, pas 3. C’est le comportement attendu, mais cela piègent les gens qui s’attendent à « la dernière l’emporte » ou « la première l’emporte » selon l’ordre.

Les clés dans les maps fusionnées ne peuvent pas être supprimées. Si defaults a une clé legacy_setting: true et que vous voulez la « désactiver » dans production, vous ne pouvez pas. La fusion n’ajoute que des clés ; elle ne les supprime jamais. Solution de contournement : n’incluez pas la clé dans l’ancre.

Les ancres ne peuvent pas se référencer elles-mêmes. Une ancre auto-référencée crée un cycle. La plupart des analyseurs détectent cela et lancent une erreur. Si vous obtenez jamais une erreur « recursive anchor », cherchez un alias qui pointe vers l’ancre qui le contient.

Les ancres et JSON ne font pas bon ménage. JSON n’a pas de concept d’ancres. Si vous convertissez du YAML avec des ancres en JSON, les ancres sont étendues (le JSON devient plus grand) ou supprimées (le JSON est plus petit). Dans les deux cas, le résultat est plus gros que le YAML. Si vous avez besoin d’une version JSON, vous avez généralement besoin d’une source de config différente.

Certains linters se plaignent des ancres. yamllint désactive les ancres par défaut (anchors: disable) pour des raisons de style. Si vous utilisez des ancres, vous devrez soit configurer votre linter soit accepter les avertissements. La plupart des équipes qui utilisent des ancres les considèrent comme valant le coût du linter.

Les ancres fonctionnent sur le graphe d’objets analysé, pas sur le texte. Si vous triez les clés par ordre alphabétique avec un outil comme yq puis resérialisez, les ancres sont préservées par référence, pas par l’ordre visible des clés. La sortie est toujours correcte, mais elle peut être visuellement surprenante — l’ancre apparaît à un endroit, l’alias à un autre, et ils pointent vers le même objet.

Vérifier les ancres dans votre configuration

Le moyen le plus rapide de vérifier que vos ancres fonctionnent est de charger le YAML dans un analyseur qui les résout et d’afficher le résultat. Le validateur YAML de DevSpeedTools affiche le graphe d’objets résolu — si vos ancres sont correctement câblées, vous verrez les mêmes valeurs partout.

Pour une inspection plus approfondie, l’outil statistiques YAML vous indique le nombre total de clés uniques vs. dupliquées, ce qui est un bon indicateur de « est-ce que mes ancres dédupliquent réellement quelque chose ? »

Pour une expérience d’édition interactive, VS Code avec l’extension Red Hat YAML résoudra les ancres au survol et vous montrera où pointe chaque alias.

Le résumé

Les ancres sont la version YAML d’une variable. Elles fonctionnent au moment de l’analyse, pas au moment de la sérialisation, donc le fichier que vous écrivez contient l’ancre une seule fois et les références à de nombreux endroits. L’analyseur les étend vers la même valeur.

Utilisez-les pour les valeurs par défaut partagées. Ne les utilisez pas pour essayer de partager un état entre documents. Ne vous attendez pas à ce que la conversion JSON les préserve. Et en cas de doute, passez le fichier par un validateur pour confirmer que l’extension correspond à votre intention — des ancres qui produisent silencieusement la mauvaise valeur sont le type de bogue qui arrive en production et y reste pendant un an.