Ancore e alias YAML spiegati (con esempi da copiare)

Se hai mai copiato e incollato le stesse 10 righe di YAML in tre posti diversi in un file di configurazione, hai provato il dolore che le ancore YAML sono progettate per risolvere. Un’àncora ti permette di definire un valore una volta e fare riferimento ad esso da qualsiasi punto nello stesso documento. Cambia il valore in un posto, e ogni riferimento si aggiorna.

Questo post spiega come funzionano le ancore e gli alias, quando usarli e i casi limite che prendono la gente alla sprovvista.

La sintassi di base

Un’àncora YAML è un nome che dai a un nodo:

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

&defaults è l’àncora. Si allega al valore di defaults, che è una mappa. Puoi mettere ancore su qualsiasi nodo — una stringa, un numero, una lista, una mappa, una sequenza.

Un alias è un riferimento a un’àncora:

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

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

<<: *defaults è la “chiave di merge”. Dice “prendi tutto dall’àncora chiamata defaults e fondila in questa mappa.” Il risultato è lo stesso come se avessi scritto il contenuto di defaults in linea:

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

Ma se cambi retries in defaults, ogni posto che usa l’àncora si aggiorna. Questo è tutto il punto.

Ancore su valori singoli

Le ancore non devono fondersi in una mappa. Puoi ancorare un singolo valore e fare riferimento ad esso:

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

Ora cambiare la versione dell’API è una modifica su una riga. I riferimenti seguono tutti.

Puoi anche ancorare una lista:

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

cors:
  web: *origins
  api: *origins

La lista viene riutilizzata letteralmente.

Quando le ancore aiutano

Le ancore brillano quando hai valori predefiniti condivisi tra più istanze. I manifesti Kubernetes, i file docker-compose e le matrici CI sono pieni di questo pattern.

Una nota per il 2026: Helm e Kustomize dominano il templating Kubernetes ora, e operano al di fuori del sistema di ancore di YAML — generano YAML, non lo analizzano. Se usi Helm o Kustomize, non hai bisogno delle ancore (hai values.yaml e patch overlay al posto). Le ancore sono ancora la scelta giusta per i workflow kubectl apply -f normali, le matrici GitHub Actions, i file docker-compose e qualsiasi configurazione scritta a mano che non passa da un motore di templating.

Un esempio Kubernetes — tre servizi con gli stessi limiti di risorse:

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 esempio docker-compose — stesso ambiente per dev e 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

In entrambi i casi, cambiare l’ambiente comune è una modifica su una riga.

Le trappole

Le ancore sono potenti ma hanno alcune parti taglienti.

Le ancore sono locali a un documento. Un file YAML multi-documento (con separatori ---) ha il suo scope per le ancore. Un’àncora definita nel documento uno non può essere riferita dal documento due. Se stai usando strumenti che producono YAML multi-doc (come kubectl get -o yaml con più risorse), non puoi usare le ancore per condividere valori tra di essi.

Le ancore e il merge interagiscono con le override in modi sorprendenti. Se sia l’àncora che la mappa che fa il riferimento definiscono la stessa chiave, il valore della mappa che fa il riferimento vince:

defaults: &defaults
  retries: 3
  timeout: 30

production:
  <<: *defaults
  retries: 10  # questo vince

Quindi production.retries è 10, non 3. Questo è il comportamento atteso, ma frega le persone che si aspettano “l’ultimo vince” o “il primo vince” a seconda dell’ordine.

Le chiavi nelle mappe fuse non possono essere rimosse. Se defaults ha una chiave legacy_setting: true e vuoi “disimpostarla” in production, non puoi. Il merge aggiunge solo chiavi; non le rimuove mai. Workaround: non includere la chiave nell’àncora.

Le ancore non possono referenziare se stesse. Un’àncora autoriferita crea un ciclo. La maggior parte dei parser lo rileva e lancia un errore. Se ottieni mai un errore “recursive anchor”, cerca un alias che punta all’àncora che lo contiene.

Le ancore e JSON non vanno d’accordo. JSON non ha il concetto di ancore. Se converti YAML con ancore in JSON, le ancore vengono espanse (il JSON diventa più grande) o eliminate (il JSON è più piccolo). In entrambi i casi, il risultato è più grande dell’YAML. Se hai bisogno di una versione JSON, solitamente hai bisogno di una fonte di configurazione diversa.

Alcuni linter si lamentano delle ancore. yamllint disabilita le ancore per default (anchors: disable) per ragioni di stile. Se usi le ancore, dovrai configurare il tuo linter o accettare gli avvisi. La maggior parte delle squadre che usa le ancore le considera vale la pena del fastidio del lint.

Le ancore funzionano sul grafo di oggetti analizzati, non sul testo. Se ordini le chiavi alfabeticamente con uno strumento come yq e poi riserializzi, le ancore vengono preservate per riferimento, non per l’ordine visibile delle chiavi. L’output è ancora corretto, ma può essere visivamente sorprendente — l’àncora appare in un posto, l’alias in un altro, e riferiscono lo stesso oggetto.

Verificare le ancore nella tua configurazione

Il modo più veloce per controllare che le tue ancore funzionano è caricare l’YAML in un parser che le risolva e stampare il risultato. Il validatore YAML su DevSpeedTools mostra il grafo di oggetti risolto — se le tue ancore sono collegate correttamente, vedrai gli stessi valori ovunque.

Per un’ispezione più approfondita, lo strumento statistiche YAML ti dice il numero totale di chiavi uniche rispetto a quelle duplicate, che è un buon indicatore per “le mie ancore stanno effettivamente deduplicando qualcosa?”

Per un’esperienza di editing interattiva, VS Code con l’estensione Red Hat YAML risolverà le ancore al passaggio del mouse e ti mostrerà dove punta ogni alias.

In breve

Le ancore sono la versione YAML delle variabili. Funzionano al momento dell’analisi, non della serializzazione, quindi il file che scrivi contiene l’àncora una volta e i riferimenti in molti posti. Il parser le espande allo stesso valore.

Usale per i valori predefiniti condivisi. Non usarle per cercare di condividere stato tra documenti. Non aspettare che la conversione JSON le preservi. E in caso di dubbio, esegui il file attraverso un validatore per confermare che l’espansione corrisponda alla tua intenzione — ancore che producono silenziosamente il valore sbagliato sono il tipo di bug che finisce in produzione e vive lì per un anno.