Modificare file di configurazione YAML con yq

yq è un processore YAML portabile da riga di comando, analogo a jq per la gestione del JSON. Consente di leggere, filtrare e modificare i file YAML senza scrivere uno script in Python o Ruby.

Esistono due strumenti popolari denominati yq:

• mikefarah/yq (Go) — mantenuto attivamente, supporta YAML, JSON, XML e TOML. Questa lezione usa questa versione.
• kislyuk/yq (Python) — un wrapper di jq per YAML; la sintassi è diversa.

Installate la versione Go:

• brew install yq su macOS
• snap install yq su Linux
• Oppure scaricate il binario: wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq

Verificate l'installazione: yq --version dovrebbe stampare v4.x.x. La versione 4 usa una sintassi delle espressioni diversa dalla versione 3, quindi la versione è importante.

Prima di modificare qualsiasi cosa, imparate a leggere i campi YAML. Dato un Deployment Kubernetes, potete estrarre qualsiasi valore annidato usando percorsi con notazione a punti.

Esempio di deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: production
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: app
          image: my-app:1.0.0

Comandi principali per la lettura:

• yq '.metadata.name' deployment.yaml — stampa my-app
• yq '.spec.replicas' deployment.yaml — stampa 3
• yq '.spec.template.spec.containers[0].image' deployment.yaml — stampa my-app:1.0.0

Per impostazione predefinita, l'output è testo semplice, senza virgolette. Aggiungete il flag -r oppure usate | yq -r se vi servono stringhe non elaborate negli script.

Il flag più importante nell'uso reale è -i (in-place). Senza di esso, yq stampa i risultati nello stdout e lascia invariato il file.

Sintassi:

• Sola lettura (stdout): yq '.spec.replicas' file.yaml
• Modifica in-place: yq -i '.spec.replicas = 5' file.yaml

L'operatore di assegnazione = imposta un valore. L'espressione è un filtro yq completo, quindi potete combinare lettura e scrittura in un unico passaggio.

Importante: yq -i riscrive completamente il file. I commenti inseriti sulla stessa riga di un campo vengono generalmente conservati, ma i blocchi di commenti autonomi possono essere spostati. Eseguite sempre il commit del file YAML nel sistema di controllo versione prima di applicare modifiche in-place in blocco.

Testate prima senza -i, poi aggiungetelo quando siete soddisfatti dell'output.

Un'attività CI molto comune consiste nell'aggiornare il tag dell'immagine Docker in un manifest Kubernetes dopo la creazione di una nuova immagine. Con yq diventa un comando su una sola riga.

Lo schema è il seguente:

• Individuate il container per nome usando select(), evitando di fissare l'indice dell'array a 0.
• Usate |= (operatore di aggiornamento) oppure = per impostare il nuovo valore.

Usando l'indice dell'array (fragile se cambia l'elenco dei container):

• yq -i '.spec.template.spec.containers[0].image = "my-app:2.1.0"' deployment.yaml

Usando select() (robusto):

• yq -i '(.spec.template.spec.containers[] | select(.name == "app")).image = "my-app:2.1.0"' deployment.yaml

In una pipeline CI passereste il tag come variabile shell:

Oltre ad aggiornare i campi esistenti, yq può aggiungere nuove chiavi o eliminare quelle esistenti.

Aggiunta di un campo:

• Assegnate semplicemente un valore a un percorso inesistente: yq -i '.metadata.labels.version = "v2"' file.yaml
• Se manca la chiave padre (labels), yq la crea automaticamente.

Eliminazione di un campo:

• Usate la funzione del(): yq -i 'del(.metadata.annotations)' file.yaml
• Eliminate un elemento dell'array tramite indice: yq -i 'del(.spec.template.spec.containers[1])' file.yaml

Aggiunta di un elemento a un array:

• yq -i '.spec.template.spec.containers += [{"name": "sidecar", "image": "envoy:latest"}]' file.yaml

I manifest Kubernetes raggruppano spesso più risorse in un unico file, separate da ---. Per impostazione predefinita, yq elabora tutti i documenti presenti nel file.

Tecniche principali:

• Elencare tutti i tipi di documento: yq '.[].kind' multi.yaml — notate il prefisso .[] per iterare sui documenti.
• Individuare un documento specifico per tipo: yq 'select(.kind == "Service")' multi.yaml
• Modificare in-place solo i documenti corrispondenti:

yq -i 'select(.kind == "Deployment").spec.replicas = 2' multi.yaml

I documenti che non soddisfano il predicato select() vengono lasciati invariati, quindi le risorse Service, ConfigMap e le altre rimangono intatte.

Per dividere un file con più documenti in singoli file, potete iterare sull'output di yq oppure usare:

• yq -s '.kind' multi.yaml — scrive un file per documento, denominato in base al valore di .kind.

Anche i file di configurazione CI (.github/workflows/*.yml, .gitlab-ci.yml) sono file YAML. Gli stessi comandi yq funzionano, anche se i percorsi possono essere profondamente annidati.

Attività comuni di modifica della CI:

• Fissare la versione del runner: aggiornate runs-on in tutti i job.
• Aggiornare la versione di un'action: individuate i passaggi che usano una determinata action e incrementate il relativo campo uses.
• Attivare o disattivare un flag: abilitate o disabilitate un'impostazione a livello di workflow.

Esempio: aggiornare alla versione 4 tutti i passaggi che usano actions/checkout:

yq -i '(.jobs[].steps[] | select(.uses == "actions/checkout@v3")).uses = "actions/checkout@v4"' .github/workflows/ci.yml

Questo idioma — iterare con [], restringere con select(), assegnare con = — è lo schema fondamentale per qualsiasi modifica a YAML strutturato.

Inserire valori direttamente nelle espressioni yq rende gli script fragili. yq supporta l'iniezione di variabili shell usando la funzione env() o la forma abbreviata strenv().

• env(VAR_NAME) — legge la variabile d'ambiente e la converte nel tipo YAML appropriato (un numero rimane un numero, una stringa rimane una stringa).
• strenv(VAR_NAME) — restituisce sempre una stringa, utile per i tag delle immagini.

In questo modo si evita l'incubo delle virgolette causato dall'interpolazione di variabili all'interno di stringhe shell tra virgolette doppie contenenti percorsi YAML.

Schema:

export IMAGE_TAG="my-app:3.0.0"
yq -i '.spec.template.spec.containers[0].image = strenv(IMAGE_TAG)' deployment.yaml

Usate env() quando impostate campi numerici come replicas, così il tipo YAML viene preservato (intero, non stringa tra virgolette).

A volte è necessario applicare un file di patch (un piccolo YAML di override) a una configurazione di base, ad esempio per gestire override specifici dell'ambiente nei workflow in stile Kustomize.

yq può unire due file usando l'operatore di merge *:

• yq '. *= load("patch.yaml")' base.yaml — esegue un merge profondo della patch nella base e scrive il risultato su stdout.
• Aggiunga -i per aggiornare direttamente il file di base: yq -i '. *= load("patch.yaml")' base.yaml

Comportamento del merge:

• I valori scalari nella patch sovrascrivono quelli della base.
• Le mappe vengono unite con un merge profondo (le chiavi non presenti nella patch vengono mantenute).
• Le sequenze (array) vengono sostituite per impostazione predefinita, non accodate. Utilizzi *+ per accodarle.

Questo approccio sostituisce gli script sed fragili, che si rompono quando cambiano gli spazi bianchi.

Prima di applicare un YAML con patch a un cluster, è buona norma convalidarlo e, se necessario, convertirlo in JSON per altri strumenti.

Convalidare la sintassi:

• yq '.' file.yaml && echo "Valid" — yq termina con il codice 1 in caso di errori di analisi, quindi questo comando è adatto ai controlli CI.

Convertire YAML in JSON:

• yq -o=json '.' file.yaml — restituisce JSON formattato.
• Invii l'output a jq per ulteriori elaborazioni JSON: yq -o=json '.' file.yaml | jq '.metadata.name'

Convertire JSON in YAML:

• yq -P '.' file.json — il flag -P forza l'output in formato YAML (formattato) quando l'input è JSON.

Queste conversioni fanno di yq un ponte tra gli strumenti nativi YAML (Helm, kubectl) e quelli nativi JSON (Terraform, AWS CLI, jq).

Riuniamo tutte le tecniche in uno script CI reale che applica patch a un manifest Kubernetes Deployment nell'ambito di una pipeline GitOps.

Lo script:

1. Convalida il YAML di input prima di modificarlo.
2. Utilizza env() / strenv() per tutte le sostituzioni di variabili.
3. Aggiorna il tag dell'immagine del container usando un select() basato sul nome.
4. Aumenta il numero di repliche.
5. Imposta un'annotazione deploy-time con il timestamp corrente.
6. Convalida nuovamente l'output prima del commit.

Questo approccio garantisce che, anche se la pipeline viene eseguita simultaneamente, ogni passaggio sia atomico e verificabile.

Verifichi la Sua comprensione della modifica di file YAML Kubernetes composti da più documenti con yq.

Ha completato la lezione sulla modifica dei file di configurazione YAML con yq. Ecco un riepilogo conciso di tutti gli argomenti trattati:

• Installazione: utilizzi il binario Go mikefarah/yq (v4). Verifichi l'installazione con yq --version.
• Lettura: percorsi con notazione puntata come .spec.replicas; accesso agli array con [0] o iterazione con [].
• Modifica sul posto: il flag -i riscrive il file. Visualizzi sempre prima il risultato senza -i.
• Selezione robusta: preferisca select(.name == "app") agli indici hard-coded degli array.
• Aggiunta / eliminazione: assegni un valore a un nuovo percorso per crearlo; utilizzi del() per rimuovere i campi.
• File composti da più documenti: utilizzi select(.kind == "...") per selezionare una risorsa e lasciare inalterate le altre.
• Variabili CI: utilizzi strenv(VAR) per le stringhe e env(VAR) per i valori tipizzati, evitando i problemi di quoting della shell.
• Merge: . *= load("patch.yaml") esegue un merge profondo di un file di override senza perdere le chiavi non incluse nella patch.
• Convalida e conversione: utilizzi yq '.' come controllo lint; -o=json e -P per convertire il formato.

Il modello di base per qualsiasi patch YAML in CI è: convalidare → selezionare → assegnare → convalidare. Lo combini con strenv() e select() e non avrà più bisogno di ricorrere a one-liner sed fragili.