Glossario

YAML (YAML Ain’t Markup Language)

YAML (YAML Ain't Markup Language) è un formato di testo per descrivere dati e configurazioni in modo leggibile dalle persone. Usa il rientro delle righe al posto di parentesi e tag, e supporta commenti, elenchi e coppie chiave-valore. È molto usato nei file di configurazione di Kubernetes, Docker Compose e dei sistemi di automazione.

Cos’è YAML e com’è fatto un file YAML

Un file YAML è un testo organizzato per righe. Ogni coppia chiave-valore sta su una riga, con i due punti come separatore. Gli elementi annidati si indicano con un rientro di spazi, e le tabulazioni non sono ammesse. Un elenco si scrive con un trattino davanti a ogni voce. I commenti iniziano con il simbolo cancelletto, cosa che il formato JSON non permette.

Il nome in origine significava “Yet Another Markup Language”. Poi è diventato un acronimo ricorsivo, “YAML Ain’t Markup Language”, a sottolineare che serve a descrivere dati e non documenti.

Dove si usa YAML

  • Le risorse di Kubernetes, che si descrivono in file YAML.
  • Docker Compose, per definire insiemi di container.
  • Le pipeline di integrazione continua, come GitHub Actions e GitLab CI, collegate al lavoro con Git e alle pratiche DevOps.
  • Strumenti di automazione come Ansible.
  • Descrizioni di API in formato OpenAPI e file di configurazione di molte applicazioni.

Vantaggi e rischi di YAML

Il formato si legge e si scrive con poca fatica, e consente di tenere configurazioni lunghe in modo ordinato. I rischi nascono dalla sua stessa semplicità. Un rientro sbagliato cambia il significato del file senza che compaia un errore evidente. Alcune versioni interpretano certi valori in modo inatteso: nella versione 1.1 le parole “no” e “yes” diventavano valori falsi e veri, e il codice paese della Norvegia “NO” veniva letto come falso. Conviene mettere tra virgolette i valori di testo ambigui e verificare i file con un controllo automatico.

Differenza tra YAML, JSON e XML

Dal punto di vista dei dati, YAML 1.2 comprende JSON: ogni file JSON valido è anche un file YAML valido. YAML è più leggibile e consente commenti, JSON è più semplice da elaborare ed è il formato preferito per lo scambio tra programmi via API, mentre XML offre regole di validazione più formali. Nella pratica si usa YAML per ciò che le persone devono scrivere e modificare, e JSON per ciò che i programmi si scambiano.

Sicurezza dei file YAML

Alcune librerie permettono a un file YAML di creare oggetti arbitrari nel programma che lo legge. Un file proveniente da fonti non fidate va caricato con le funzioni sicure della libreria, che accettano solo tipi semplici. Le credenziali non vanno scritte nei file YAML conservati in un repository. Per gestirle si usano strumenti dedicati.

La sintassi di YAML in dettaglio

Una mappa associa chiavi a valori, un elenco si scrive con i trattini e i due si annidano con il rientro. I testi possono stare su più righe: il blocco con il simbolo di barra verticale mantiene gli a capo, quello con il simbolo maggiore li trasforma in spazi. Le ancore e i riferimenti permettono di definire un blocco una volta e riusarlo, utile nelle configurazioni ripetitive. Più documenti possono stare nello stesso file, separati da tre trattini, come avviene nei file di Kubernetes.

YAML nelle pipeline e nelle configurazioni di sistema

Nei sistemi di integrazione continua il file YAML descrive i passaggi della pipeline: quando parte, su quale macchina gira, quali comandi esegue e in che ordine. Nei sistemi basati su container, un file dichiara quali servizi avviare, con quali immagini, porte e variabili. In Kubernetes ogni risorsa si dichiara con un documento YAML. Tenere questi file in un repository Git permette di rivedere le modifiche e di tornare a una configurazione precedente.

Come si controlla un file YAML

Un linter, come yamllint, individua errori di rientro, chiavi duplicate e righe troppo lunghe prima che il file arrivi in produzione. Quando il file ha uno scopo preciso, come la configurazione di un’applicazione, si può convalidare con uno schema, scritto in JSON Schema, che indica i campi ammessi e i loro tipi. Molti editor evidenziano gli errori mentre si scrive, e gli strumenti di integrazione continua eseguono i controlli a ogni modifica.

Storia e versioni di YAML

Il formato nasce nel 2001 per opera di Clark Evans, Ingy döt Net e Oren Ben-Kiki. La versione 1.2, pubblicata nel 2009, ha reso YAML compatibile con il JSON e ha tolto alcune ambiguità, come l’interpretazione automatica di «yes» e «no» come valori logici. La revisione 1.2.2 del 2021 chiarisce il testo della specifica senza cambiare il linguaggio. Non tutte le librerie supportano la stessa versione, quindi conviene verificare quale si usa.

Buone pratiche per scrivere YAML

Si usano due spazi per ogni livello di rientro, sempre gli stessi in tutto il file. Le tabulazioni non si usano. I valori ambigui, come «no», «on», i numeri di versione e i codici che iniziano con zero, si scrivono tra virgolette per evitare conversioni indesiderate. I commenti spiegano il motivo di una scelta, non ripetono ciò che il file già dice. I segreti restano fuori dal file e vengono letti da un gestore dedicato o da variabili d’ambiente.

Fonti e approfondimenti