Redigering af YAML-konfigurationsfiler med yq

yq er en portabel YAML-processor til kommandolinjen, på samme måde som jq håndterer JSON. Den lader dig læse, filtrere og redigere YAML-filer uden at skrive et script i Python eller Ruby.

Der findes to populære værktøjer med navnet yq:

• mikefarah/yq (Go) — vedligeholdes aktivt og understøtter YAML, JSON, XML og TOML. Denne lektion bruger denne version.
• kislyuk/yq (Python) — en jq-wrapper til YAML; syntaksen er anderledes.

Installér Go-versionen:

• brew install yq på macOS
• snap install yq på Linux
• Eller download binærfilen: wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq

Kontrollér installationen: yq --version bør udskrive v4.x.x. Version 4 bruger en anden udtrykssyntaks end v3, så versionen er vigtig.

Før du redigerer noget, skal du lære at læse YAML-felter. Med en Kubernetes-Deployment kan du udtrække enhver indlejret værdi ved hjælp af stiadressering med punktnotation.

Eksempel på 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

Vigtige læsekommandoer:

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

Outputtet er som standard almindelig tekst (uden anførselstegn). Tilføj flaget -r, eller brug | yq -r, hvis du har brug for rå strenge i scripts.

Det vigtigste flag til praktisk brug er -i (på stedet). Uden det udskriver yq resultaterne til stdout og lader filen være uændret.

Syntaks:

• Læsning alene (stdout): yq '.spec.replicas' file.yaml
• Redigering på stedet: yq -i '.spec.replicas = 5' file.yaml

Tildelingsoperatoren = angiver en værdi. Udtrykket er et komplet yq-filter, så du kan kombinere læsning og skrivning i én gennemkørsel.

Vigtigt: yq -i omskriver hele filen. Kommentarer på samme linje som et felt bevares normalt, men selvstændige kommentarblokke kan blive flyttet. Commit altid din YAML til versionsstyring, før du kører massevise redigeringer på stedet.

Test først uden -i, og tilføj det derefter, når du er tilfreds med outputtet.

En meget almindelig CI-opgave er at opdatere Docker-imagetagget i et Kubernetes-manifest, efter at et nyt image er blevet bygget. Med yq bliver det til én linje.

Mønsteret er:

• Find containeren efter navn ved hjælp af select(), så du undgår at hardkode array-indeks 0.
• Brug |= (opdateringsoperatoren) eller = til at angive den nye værdi.

Brug af array-indeks (skrøbeligt, hvis containerlisten ændres):

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

Brug af select() (robust):

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

I en CI-pipeline ville du sende tagget som en shell-variabel:

Ud over at opdatere eksisterende felter kan yq tilføje nye nøgler eller slette eksisterende.

Tilføjelse af et felt:

• Tildel blot en værdi til en sti, der ikke findes: yq -i '.metadata.labels.version = "v2"' file.yaml
• Hvis den overordnede nøgle (labels) mangler, opretter yq den automatisk.

Sletning af et felt:

• Brug funktionen del(): yq -i 'del(.metadata.annotations)' file.yaml
• Slet et array-element efter indeks: yq -i 'del(.spec.template.spec.containers[1])' file.yaml

Tilføjelse af et element til et array:

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

Kubernetes-manifester samler ofte flere ressourcer i én fil, adskilt af ---. Som standard behandler yq alle dokumenter i sådan en fil.

Vigtige teknikker:

• Vis alle dokumenttyper: yq '.[].kind' multi.yaml — bemærk det indledende .[], der gennemløber dokumenterne.
• Vælg et bestemt dokument efter type: yq 'select(.kind == "Service")' multi.yaml
• Redigér kun matchende dokumenter på stedet:

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

Dokumenter, der ikke matcher prædikatet i select(), sendes uændret videre, så din Service, ConfigMap og andre ressourcer forbliver intakte.

Hvis du vil opdele en fil med flere dokumenter i individuelle filer, kan du gennemløbe yq-outputtet eller bruge:

• yq -s '.kind' multi.yaml — skriver én fil pr. dokument med navn efter dokumentets .kind-værdi.

CI-konfigurationsfiler (.github/workflows/*.yml, .gitlab-ci.yml) er også YAML. De samme yq-kommandoer virker, selvom stierne kan være dybt indlejrede.

Almindelige CI-rettelser:

• Fastlås en runner-version: opdatér runs-on på tværs af alle jobs.
• Opdatér en action-version: find trin, der bruger en bestemt action, og opdatér feltet uses.
• Slå et flag til eller fra: aktivér eller deaktivér en indstilling på workflow-niveau.

Eksempel: opdatér alle trin, der bruger actions/checkout, til v4:

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

Dette idiom — gennemløb med [], indsnævr med select(), tildel med = — er grundmønstret for enhver struktureret YAML-redigering.

Hardkodning af værdier i yq-udtryk gør scripts skrøbelige. yq understøtter indsættelse af shell-variabler ved hjælp af env()-funktionen eller forkortelsen strenv().

• env(VAR_NAME) — læser miljøvariablen og konverterer den til den passende YAML-type (et tal forbliver et tal, og en streng forbliver en streng).
• strenv(VAR_NAME) — returnerer altid en streng og er nyttig til imagetags.

Det undgår citeringsmareridtet ved interpolation af variabler i shell-strenge med dobbelte anførselstegn og indlejrede YAML-stier.

Mønster:

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

Brug env() ved angivelse af numeriske felter som replicas, så YAML-typen bevares (heltal i stedet for en citeret streng).

Nogle gange skal du anvende en patchfil (en lille YAML-fil med tilsidesættelser) på en grundkonfiguration — f.eks. miljøspecifikke tilsidesættelser i arbejdsforløb i stil med Kustomize.

yq kan sammenflette to filer ved hjælp af *-operatoren til sammenfletning:

• yq '. *= load("patch.yaml")' base.yaml — sammenfletter patchen rekursivt ind i grundkonfigurationen og skriver resultatet til standardoutput.
• Tilføj -i for at opdatere grundkonfigurationen direkte: yq -i '. *= load("patch.yaml")' base.yaml

Sådan fungerer sammenfletningen:

• Skalære værdier i patchen overskriver grundkonfigurationen.
• Kortlægninger sammenflettes rekursivt (nøgler, der ikke findes i patchen, bevares).
• Sekvenser (tabeller) erstattes som standard og føjes ikke til. Brug *+ for i stedet at føje dem til.

Dette mønster erstatter skrøbelige sed-skripter, der går i stykker ved ændringer i mellemrum.

Før du anvender en patchet YAML-fil på en klynge, er det god praksis at validere den og eventuelt konvertere den til JSON til andre værktøjer.

Validér syntaksen:

• yq '.' file.yaml && echo "Valid" — yq afslutter med kode 1 ved parsefejl, så dette fungerer i CI-gates.

Konvertér YAML til JSON:

• yq -o=json '.' file.yaml — skriver formateret JSON.
• Send resultatet gennem jq for yderligere JSON-behandling: yq -o=json '.' file.yaml | jq '.metadata.name'

Konvertér JSON til YAML:

• yq -P '.' file.json — flaget -P tvinger YAML-output (med pæn formatering), når inputtet er JSON.

Disse konverteringer gør yq til en bro mellem YAML-baserede værktøjer (Helm, kubectl) og JSON-baserede værktøjer (Terraform, AWS CLI, jq).

Her samler vi alle teknikkerne i et rigtigt CI-script, der patcher et Kubernetes-udrulningsmanifest som en del af et GitOps-arbejdsforløb.

Scriptet:

1. Validerer YAML-inputtet, før det ændres.
2. Bruger env() / strenv() til alle variabelsubstitutioner.
3. Opdaterer containerens billedtag ved hjælp af et navnebaseret select().
4. Forøger antallet af replikaer.
5. Tilføjer en deploy-time-annotation med det aktuelle tidsstempel.
6. Validerer outputtet igen før commit.

Dette mønster sikrer, at hvert trin er atomisk og kan revideres, selv hvis arbejdsforløbet kører samtidigt.

Du har gennemført lektionen om redigering af YAML-konfigurationsfiler med yq. Her er en kort opsummering af alt det, vi har gennemgået:

• Installation: Brug mikefarah/yq Go-binærfilen (v4). Kontrollér med yq --version.
• Læsning: Stier med punktnotation som .spec.replicas; adgang til tabeller med [0] eller iteration med [].
• Redigering direkte i filen: Flaget -i omskriver filen. Forhåndsvis altid uden -i først.
• Robust målretning: Foretræk select(.name == "app") frem for fast definerede tabelindekser.
• Tilføjelse og sletning: Tildel en værdi til en ny sti for at oprette den; brug del() til at fjerne felter.
• Filer med flere dokumenter: Brug select(.kind == "...") til at målrette én ressource og lade de andre være urørte.
• CI-variabler: Brug strenv(VAR) til strenge og env(VAR) til værdier med type — det undgår problemer med shell-citater.
• Sammenfletning: . *= load("patch.yaml") sammenfletter en tilsidesættelsesfil rekursivt uden at miste nøgler, der ikke er patchet.
• Validering og konvertering: Brug yq '.' som lint-gate samt -o=json og -P til formatkonvertering.

Grundmønstret for enhver YAML-patch i CI er: validér → vælg → tildel → validér. Kombinér dette med strenv() og select(), så behøver du aldrig mere ty til skrøbelige sed-enkeltlinjer.