YAML per principianti: Padroneggiare i file di configurazione

Se lavori con Docker, Kubernetes, GitHub Actions o praticamente qualsiasi strumento DevOps moderno, stai già usando YAML, che te ne renda conto o no. YAML (che sta per "YAML Ain't Markup Language" — sì, è un acronimo ricorsivo) è stato progettato per essere il formato dati più leggibile possibile per gli esseri umani.

Impariamolo insieme, un concetto alla volta.

Perché YAML esiste

JSON è ottimo per le macchine, ma hai mai provato a scrivere un file di configurazione di 200 righe in JSON? Nessun commento, virgolette doppie obbligatorie ovunque, cinque livelli di parentesi graffe annidate... diventa doloroso in fretta. YAML è stato creato per risolvere questo problema. Usa l'indentazione al posto delle parentesi, il che rende le configurazioni pulite e facili da leggere.

Ecco gli stessi dati in JSON e YAML. Vedi la differenza?

JSON:

YAML:

Le basi da conoscere

Le coppie chiave-valore sono il pane quotidiano di YAML. Basta usare due punti e uno spazio: name: John Doe. Tutto qui — non servono virgolette per la maggior parte delle stringhe.

L'indentazione è tutto. YAML usa gli spazi (mai i tab!) per mostrare la struttura. Lo standard è 2 spazi per livello. Sbaglialo e il tuo file si rompe. Sul serio — la specifica YAML è rigorosa su questo.

Ecco un esempio di dati annidati:

Le liste usano un trattino e uno spazio. Ecco una lista della spesa in YAML:

Stringhe: più insidiose di quanto pensi

La maggior parte delle stringhe non ha bisogno di virgolette in YAML. Ma dovresti usarle quando contengono due punti, cancelletti o potrebbero essere mal interpretate. Ad esempio, country: NO viene interpretato come country: false in YAML 1.1 perché NO è trattato come booleano. Questo è il famigerato "problema Norvegia" e ha causato bug reali in produzione.

Nel dubbio, mettilo tra virgolette: country: "NO"

Le stringhe multi-riga sono fantastiche

Qui è dove YAML brilla davvero. Il pipe | preserva gli a capo (perfetto per gli script), mentre > li converte in spazi (perfetto per le descrizioni lunghe):

Ancore e alias: file di configurazione DRY

Una delle funzionalità più belle di YAML. Definisci qualcosa una volta con &, riferisciti ad esso dopo con *:

Il blocco production eredita retries: 3 dai defaults ma sovrascrive timeout. Questo è incredibilmente utile nei workflow di GitHub Actions e nei file Docker Compose dove altrimenti ripeteresti gli stessi blocchi di configurazione più e più volte.

I 4 errori YAML più comuni

• Tab al posto degli spazi — Il tuo editor potrebbe inserire tab di default. Configuralo per usare spazi nei file YAML. Sul serio, fallo adesso.
• Trappole booleane — yes, no, on, off, true, false sono TUTTI booleani in YAML 1.1. Usa le virgolette se intendi la stringa.
• Due punti nei valori — message: Error: file not found si romperà perché YAML vede un secondo separatore chiave-valore. Usa le virgolette: message: "Error: file not found"
• Spazi finali — Spazi invisibili alla fine delle righe possono causare comportamenti di parsing strani. Usa un editor che evidenzi gli spazi finali.

Dove userai YAML ogni giorno

YAML è il linguaggio di configurazione per Docker Compose, manifesti Kubernetes, GitHub Actions, GitLab CI, playbook Ansible e decine di altri. Se fai qualsiasi cosa in DevOps o cloud, la padronanza di YAML è irrinunciabile.

Hai un file YAML che si comporta in modo strano? Incollalo nel nostro YAML Validator per trovare il problema istantaneamente.

YAML nel mondo reale: Esempio Docker Compose

Diamo un'occhiata a un file Docker Compose realistico — il tipo di file che scriveresti davvero per un'applicazione web:

Nota alcune cose: le variabili d'ambiente possono essere scritte come lista (- KEY=value) o come mapping (KEY: value). Entrambi funzionano in Docker Compose — ma scegli uno stile e mantienilo per coerenza.

YAML nel mondo reale: Pipeline CI di GitHub Actions

Ecco un workflow GitHub Actions che esegue i test ad ogni push:

Questo è pulito, leggibile e autoesplicativo. Immagina di scrivere lo stesso workflow in JSON — sarebbe il doppio più lungo e molto più difficile da leggere visivamente.

YAML vs JSON vs TOML: Confronto rapido

YAML non è l'unica alternativa a JSON per i file di configurazione. TOML è un'altra scelta popolare (usata da Cargo.toml di Rust e pyproject.toml di Python). Ecco come si confrontano:

YAML avanzato: Più documenti in un file

YAML supporta più documenti in un singolo file, separati da ---. Questo è comunemente usato in Kubernetes per distribuire più risorse contemporaneamente:

Il separatore --- dice al parser YAML "questo è un nuovo documento." Puoi eseguire kubectl apply -f su un file così e Kubernetes creerà entrambe le risorse.

Sicurezza YAML: L'attacco Billion Laughs

Ecco qualcosa che la maggior parte dei principianti non sa: YAML può essere un rischio di sicurezza se non stai attento. L'attacco "Billion Laughs" usa ancore e alias per creare un'espansione esponenziale dei dati:

Questo minuscolo file può espandersi a gigabyte in memoria e mandare in crash la tua applicazione. La lezione? Non fare mai il parsing di input YAML non fidato. Usa funzioni di caricamento sicure come yaml.safe_load() in Python invece di yaml.load(), e imposta limiti di memoria sul tuo parser YAML.

Convertire tra YAML e JSON

Dato che YAML è un superset di JSON (sì, JSON valido è anche YAML valido!), convertire tra i due è semplice. Questo è utile quando vuoi usare la leggibilità di YAML per scrivere le configurazioni ma hai bisogno di JSON per un'API o uno strumento che lo richiede.

Il nostro Convertitore da YAML a JSON lo gestisce istantaneamente — incolla semplicemente il tuo YAML e ottieni un output JSON pulito. Nella direzione opposta? Qualsiasi JSON tu abbia è già YAML valido.

Provalo tu stesso

Che tu stia debuggando un manifesto Kubernetes rotto o configurando una nuova pipeline CI, questi strumenti ti faranno risparmiare tempo:

• YAML Formatter — Correggi l'indentazione e rendi i tuoi file YAML puliti e coerenti.
• YAML Validator — Individua gli errori di sintassi prima che rompano il tuo deployment.
• Convertitore da YAML a JSON — Converti tra formati quando devi interoperare con strumenti che accettano solo JSON.

YAML ha le sue particolarità, ma una volta che ti sentirai a tuo agio con la sintassi basata sull'indentazione, apprezzerai quanto più puliti appaiono i tuoi file di configurazione rispetto all'alternativa JSON.