YAML-Konfigurationsdateien mit yq bearbeiten

yq ist ein portabler YAML-Prozessor für die Kommandozeile, ähnlich wie jq für JSON. Damit können Sie YAML-Dateien lesen, filtern und bearbeiten, ohne ein Skript in Python oder Ruby zu schreiben.

Es gibt zwei verbreitete Tools mit dem Namen yq:

• mikefarah/yq (Go) – wird aktiv gepflegt und unterstützt YAML, JSON, XML und TOML. Diese Lektion verwendet diese Version.
• kislyuk/yq (Python) – ein jq-Wrapper für YAML; die Syntax unterscheidet sich.

Installieren Sie die Go-Version:

• brew install yq unter macOS
• snap install yq unter Linux
• Oder laden Sie die Binärdatei herunter: wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq

Überprüfen Sie die Installation: yq --version sollte v4.x.x ausgeben. Version 4 verwendet eine andere Ausdruckssyntax als Version 3, daher ist die Version wichtig.

Bevor Sie etwas bearbeiten, lernen Sie, YAML-Felder zu lesen. Bei einem Kubernetes-Deployment können Sie jeden verschachtelten Wert mit Pfaden in Punktnotation extrahieren.

Beispiel für 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

Wichtige Lese-Befehle:

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

Die Ausgabe erfolgt standardmäßig als einfacher Text (ohne Anführungszeichen). Fügen Sie das Flag -r hinzu oder verwenden Sie | yq -r, wenn Sie in Skripten rohe Zeichenfolgen benötigen.

Das wichtigste Flag für den praktischen Einsatz ist -i (in-place). Ohne dieses Flag gibt yq die Ergebnisse nach stdout aus und lässt die Datei unverändert.

Syntax:

• Nur lesen (stdout): yq '.spec.replicas' file.yaml
• Bearbeitung an Ort und Stelle: yq -i '.spec.replicas = 5' file.yaml

Der Zuweisungsoperator = setzt einen Wert. Der Ausdruck ist ein vollständiger yq-Filter, sodass Sie Lesen und Schreiben in einem Durchlauf kombinieren können.

Wichtig: yq -i schreibt die Datei vollständig neu. Kommentare in derselben Zeile wie ein Feld bleiben im Allgemeinen erhalten, eigenständige Kommentarblöcke können jedoch verschoben werden. Übertragen Sie Ihre YAML-Datei immer in die Versionsverwaltung, bevor Sie umfangreiche Bearbeitungen an Ort und Stelle durchführen.

Testen Sie zunächst ohne -i und fügen Sie es erst hinzu, wenn Sie mit der Ausgabe zufrieden sind.

Eine sehr häufige CI-Aufgabe besteht darin, den Docker-Image-Tag zu erhöhen, nachdem ein neues Image erstellt wurde. Mit yq wird daraus ein Einzeiler.

Das Muster:

• Identifizieren Sie den Container anhand seines Namens mit select(), um eine fest codierte Array-Position 0 zu vermeiden.
• Verwenden Sie |= (Update-Operator) oder =, um den neuen Wert zu setzen.

Mit Array-Index (anfällig, wenn sich die Containerliste ändert):

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

Mit select() (robust):

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

In einer CI-Pipeline würden Sie den Tag als Shell-Variable übergeben:

Über das Aktualisieren vorhandener Felder hinaus kann yq neue Schlüssel hinzufügen oder vorhandene löschen.

Ein Feld hinzufügen:

• Weisen Sie einfach einem nicht vorhandenen Pfad einen Wert zu: yq -i '.metadata.labels.version = "v2"' file.yaml
• Wenn der übergeordnete Schlüssel (labels) fehlt, erstellt yq ihn automatisch.

Ein Feld löschen:

• Verwenden Sie die Funktion del(): yq -i 'del(.metadata.annotations)' file.yaml
• Löschen Sie ein Array-Element anhand seines Index: yq -i 'del(.spec.template.spec.containers[1])' file.yaml

Ein Element zu einem Array hinzufügen:

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

Kubernetes-Manifeste enthalten häufig mehrere durch --- getrennte Ressourcen in einer einzigen Datei. Standardmäßig verarbeitet yq alle Dokumente in einer solchen Datei.

Wichtige Techniken:

• Alle Dokumenttypen auflisten: yq '.[].kind' multi.yaml – beachten Sie das vorangestellte .[], um die Dokumente zu durchlaufen.
• Ein bestimmtes Dokument nach Typ auswählen: yq 'select(.kind == "Service")' multi.yaml
• Nur passende Dokumente an Ort und Stelle bearbeiten:

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

Dokumente, die das select()-Prädikat nicht erfüllen, werden unverändert durchgereicht. Dadurch bleiben Ihr Service, Ihre ConfigMap und andere Ressourcen intakt.

Um eine Datei mit mehreren Dokumenten in einzelne Dateien aufzuteilen, können Sie die yq-Ausgabe in einer Schleife verarbeiten oder Folgendes verwenden:

• yq -s '.kind' multi.yaml – schreibt für jedes Dokument eine Datei, benannt nach ihrem .kind-Wert.

CI-Konfigurationsdateien (.github/workflows/*.yml, .gitlab-ci.yml) sind ebenfalls YAML-Dateien. Dieselben yq-Befehle funktionieren auch hier, obwohl die Pfade tief verschachtelt sein können.

Häufige CI-Patching-Aufgaben:

• Eine Runner-Version festlegen: Aktualisieren Sie runs-on für alle Jobs.
• Eine Action-Version aktualisieren: Suchen Sie nach Schritten, die eine bestimmte Action verwenden, und erhöhen Sie deren Feld uses.
• Ein Flag umschalten: Aktivieren oder deaktivieren Sie eine Einstellung auf Workflow-Ebene.

Beispiel: Alle Schritte, die actions/checkout verwenden, auf v4 aktualisieren:

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

Dieses Idiom – mit [] iterieren, mit select() eingrenzen, mit = zuweisen – ist das zentrale Muster für jede strukturierte YAML-Bearbeitung.

Fest codierte Werte in yq-Ausdrücken machen Skripte fehleranfällig. yq unterstützt das Einfügen von Shell-Variablen mit der Funktion env() oder der Kurzform strenv().

• env(VAR_NAME) – liest die Umgebungsvariable und wandelt sie in den passenden YAML-Typ um (eine Zahl bleibt eine Zahl, eine Zeichenfolge bleibt eine Zeichenfolge).
• strenv(VAR_NAME) – gibt immer eine Zeichenfolge zurück und eignet sich daher für Image-Tags.

Damit vermeiden Sie das Anführungszeichen-Chaos, das beim Einfügen von Variablen in doppelt quotierte Shell-Zeichenfolgen mit eingebetteten YAML-Pfaden entsteht.

Muster:

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

Verwenden Sie env() beim Setzen numerischer Felder wie replicas, damit der YAML-Typ erhalten bleibt (Ganzzahl statt quotierter Zeichenfolge).

Manchmal müssen Sie eine Patch-Datei (eine kleine überschreibende YAML-Datei) auf eine Basiskonfiguration anwenden – beispielsweise um umgebungsspezifische Überschreibungen in Kustomize-ähnlichen Workflows umzusetzen.

Mit yq können Sie zwei Dateien mithilfe des *-Merge-Operators zusammenführen:

• yq '. *= load("patch.yaml")' base.yaml – führt den Patch rekursiv mit der Basis zusammen und schreibt das Ergebnis nach stdout.
• Fügen Sie -i hinzu, um die Basisdatei direkt zu aktualisieren: yq -i '. *= load("patch.yaml")' base.yaml

Verhalten beim Zusammenführen:

• Skalare Werte im Patch überschreiben die Basiswerte.
• Mappings werden rekursiv zusammengeführt (Schlüssel, die im Patch nicht vorkommen, bleiben erhalten).
• Sequenzen (Arrays) werden standardmäßig ersetzt, nicht angehängt. Verwenden Sie stattdessen *+, um sie anzuhängen.

Dieses Muster ersetzt fehleranfällige sed-Skripte, die bei Änderungen an Leerzeichen nicht mehr funktionieren.

Bevor Sie gepatchtes YAML auf einen Cluster anwenden, sollten Sie es validieren und es optional für andere Tools in JSON konvertieren.

Syntax validieren:

• yq '.' file.yaml && echo "Valid" – yq wird bei Parse-Fehlern mit Code 1 beendet, sodass sich dies für CI-Prüfungen eignet.

YAML in JSON konvertieren:

• yq -o=json '.' file.yaml – gibt formatiertes JSON aus.
• Leiten Sie die Ausgabe für die weitere JSON-Verarbeitung an jq weiter: yq -o=json '.' file.yaml | jq '.metadata.name'

JSON in YAML konvertieren:

• yq -P '.' file.json – das Flag -P erzwingt eine Ausgabe im YAML-Format (prettyprint), wenn die Eingabe JSON ist.

Diese Konvertierungen machen yq zu einer Brücke zwischen YAML-nativen Tools (Helm, kubectl) und JSON-nativen Tools (Terraform, AWS CLI, jq).

Hier werden alle Techniken zu einem praxisnahen CI-Skript kombiniert, das im Rahmen einer GitOps-Pipeline ein Kubernetes-Deployment-Manifest patcht.

Das Skript:

1. Validiert das Eingabe-YAML, bevor Änderungen vorgenommen werden.
2. Verwendet env() / strenv() für alle Variablenersetzungen.
3. Aktualisiert das Container-Image-Tag mithilfe eines namensbasierten select().
4. Erhöht die Replikazahl.
5. Verseht eine deploy-time-Annotation mit dem aktuellen Zeitstempel.
6. Validiert die Ausgabe erneut, bevor sie committed wird.

Dieses Muster stellt sicher, dass jeder Schritt auch bei gleichzeitig ausgeführten Pipelines atomar und nachvollziehbar bleibt.

Sie haben die Lektion zum Bearbeiten von YAML-Konfigurationsdateien mit yq abgeschlossen. Hier ist eine kurze Zusammenfassung aller behandelten Themen:

• Installation: Verwenden Sie das mikefarah/yq-Go-Binary (v4). Überprüfen Sie die Installation mit yq --version.
• Lesen: Pfade in Punktnotation wie .spec.replicas; Array-Zugriff mit [0] oder Iteration mit [].
• Bearbeiten an Ort und Stelle: Das Flag -i schreibt die Datei neu. Zeigen Sie das Ergebnis immer zuerst ohne -i an.
• Robuste Zielauswahl: Bevorzugen Sie select(.name == "app") gegenüber fest codierten Array-Indizes.
• Hinzufügen / Löschen: Weisen Sie einem neuen Pfad einen Wert zu, um ihn zu erstellen; verwenden Sie del(), um Felder zu entfernen.
• Dateien mit mehreren Dokumenten: Verwenden Sie select(.kind == "..."), um eine Ressource anzusprechen und die übrigen unverändert zu lassen.
• CI-Variablen: Verwenden Sie strenv(VAR) für Zeichenketten und env(VAR) für typisierte Werte – so vermeiden Sie Quoting-Fehler in der Shell.
• Zusammenführen: . *= load("patch.yaml") führt eine Überschreibungsdatei rekursiv zusammen, ohne nicht gepatchte Schlüssel zu verlieren.
• Validierung & Konvertierung: yq '.' als Lint-Prüfung; -o=json und -P zur Formatkonvertierung.

Das grundlegende Muster für jeden YAML-Patch in CI lautet: validieren → auswählen → zuweisen → validieren. Kombinieren Sie dies mit strenv() und select(), und Sie müssen nie wieder auf fehleranfällige sed-Einzeiler zurückgreifen.