XML Prozessor¶

Installation¶

Plattform	Befehl
Ubuntu/Debian	`wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq`
Ubuntu (PPA)	`sudo add-apt-repository ppa:rmescandon/yq && sudo apt update && sudo apt install yq`
macOS (Homebrew)	`brew install yq`
macOS (MacPorts)	`sudo port install yq`
Windows (Chocolatey)	`choco install yq`
Windows (Scoop)	`scoop install yq`
Snap	`snap install yq`
Go	`go install github.com/mikefarah/yq/v4@latest`
Docker	`docker run --rm -v "${PWD}":/workdir mikefarah/yq`
Alpine Linux	`apk add yq`
Arch Linux	`yay -S yq`
Verify Installation	`yq --version`

Grundlegende Befehle - Lesen & Anzeigen¶

Befehl	Beschreibung
`yq '.' file.yaml`	Gesamte YAML-Datei anzeigen (Pretty Print)
`yq '.name' file.yaml`	Lesen Sie einen bestimmten Feldwert
`yq '.metadata.name' file.yaml`	Verschachteltes Feld mit Punktnotation lesen
`yq '.items[0]' file.yaml`	Ersten Elementes eines Arrays zugreifen
`yq '.items[*]' file.yaml`	Greife auf alle Elemente eines Arrays zu
`yq '.items[]' file.yaml`	Iteriere durch Array-Elemente
`yq '.items[].name' file.yaml`	Extrahiere spezifisches Feld aus allen Array-Elementen
`yq '.items[-1]' file.yaml`	Letztes Element eines Arrays aufrufen
`yq '.items[1:3]' file.yaml`	Array Slice (Elemente 1 und 2)
`cat file.yaml \ \| yq '.spec'`	Von stdin lesen
`yq -r '.name' file.yaml`	Gib Rohstring aus (ohne Anführungszeichen)
`yq '.items \ \| length' file.yaml`	Länge des Arrays oder Objekts abrufen
`yq 'keys' file.yaml`	Alle Top-Level-Schlüssel auflisten
`yq '.[] \ \| keys' file.yaml`	Listenkeys von verschachtelten Objekten

Grundlegende Befehle - Schreiben & Aktualisieren¶

Befehl	Beschreibung
`yq '.name = "new-value"' file.yaml`	Ein Feld aktualisieren (gibt an stdout aus)
`yq -i '.name = "new-value"' file.yaml`	Feld direkt aktualisieren (modifiziert Datei)
`yq '.spec.replicas = 3' file.yaml`	Geschachtelte Werte aktualisieren
`yq '.items[0].name = "updated"' file.yaml`	Array-Element aktualisieren
`yq '.newField = "value"' file.yaml`	Neues Feld erstellen
`yq '.metadata.labels.env = "prod"' file.yaml`	Verschachtelte Felder erstellen
`yq 'del(.fieldName)' file.yaml`	Ein Feld löschen
`yq 'del(.metadata.annotations)' file.yaml`	Geschachtelte Felder löschen
`yq 'del(.items[0])' file.yaml`	Array-Element löschen
`yq '.items += {"name": "new"}' file.yaml`	An Array anhängen
`yq '.items = []' file.yaml`	Array leeren
`yq '.count += 1' file.yaml`	Numerischen Wert erhöhen
`yq '.total = .price * .quantity' file.yaml`	Arithmetische Operationen

Erweiterte Nutzung - Filtern & Auswählen¶

Befehl	Beschreibung
`yq '.items[] \ \| select(.kind == "Pod")' file.yaml`	Elemente nach Bedingung filtern
`yq '.items[] \ \| select(.kind == "Pod" and .status == "Running")' file.yaml`	Mehrere Bedingungen (AND)
`yq '.items[] \ \| select(.kind == "Pod" or .kind == "Service")' file.yaml`	Mehrere Bedingungen (ODER)
`yq '.items[] \ \| select(.name \ \| test("^prod-"))' file.yaml`	Musterabgleich mit regex
`yq '.items[] \ \| select(has("metadata"))' file.yaml`	Überprüfe, ob Feld existiert
`yq '.items[] \ \| select(.replicas > 3)' file.yaml`	Numerischer Vergleich
`yq '.items[] \ \| select(.tags \ \| contains(["prod"]))' file.yaml`	Array enthält Prüfung
`yq '.items[] \ \| select(.name != null)' file.yaml`	Null-Werte herausfiltern
`yq '.[] \ \| select(tag == "!!str")' file.yaml`	Nach YAML-Tag-Typ filtern

Erweiterte Nutzung - Array-Operationen¶

Befehl	Beschreibung
`yq '.items \ \| = sort_by(.name)' file.yaml`	Array nach Feld sortieren
`yq '.items \ \| = sort_by(.metadata.creationTimestamp)' file.yaml`	Nach verschachteltem Feld sortieren
`yq '.items \ \| = reverse' file.yaml`	Array-Reihenfolge umkehren
`yq '.tags \ \| unique' file.yaml`	Eindeutige Array-Werte abrufen
`yq '.items \ \| flatten' file.yaml`	Verschachtelte Arrays abflachen
`yq '.items \ \| group_by(.kind)' file.yaml`	Gruppiere Array-Elemente
`yq '.items \ \| map(.name)' file.yaml`	Array auf Werte abbilden
`yq '.items \ \| map(select(.active))' file.yaml`	Filter und Map kombiniert
`yq '.items = .items + .newItems' file.yaml`	Arrays verketten
`yq '.items \ \| = unique_by(.name)' file.yaml`	Duplikate nach Feld entfernen
`yq '[.items[].name]' file.yaml`	Werte in neues Array sammeln

Erweiterte Nutzung - Zusammenführen & Kombinieren¶

Befehl	Beschreibung
`yq ea 'select(fi == 0) * select(fi == 1)' f1.yaml f2.yaml`	Tiefes Zusammenführen von zwei Dateien (f2 überschreibt f1)
`yq ea '. as $item ireduce ({}; . * $item)' *.yaml`	Mehrere Dateien zusammenführen
`yq ea 'select(fi == 0) *+ select(fi == 1)' f1.yaml f2.yaml`	Mit Array-Verkettung zusammenführen
`yq ea '[.]' file1.yaml file2.yaml`	Dateien in Array kombinieren
`yq '.config = load("config.yaml")' file.yaml`	Externe Datei laden und zusammenführen
`yq '.spec.template = load("template.yaml").spec' file.yaml`	Spezifischen Pfad aus Datei laden
`yq ea 'select(fi == 0) *d select(fi == 1)' f1.yaml f2.yaml`	Tiefes Zusammenführen mit Löschung

Erweiterte Nutzung - Zeichenkettenoperationen¶

Befehl	Beschreibung
`yq '.fullName = .firstName + " " + .lastName' file.yaml`	String-Verkettung
`yq '.name \ \| = upcase' file.yaml`	In Großbuchstaben umwandeln
`yq '.name \ \| = downcase' file.yaml`	In Kleinbuchstaben umwandeln
`yq '.name \ \| = trim' file.yaml`	Leerzeichen entfernen
`yq '.text \ \| = sub("old", "new")' file.yaml`	Ersetze erste Vorkommen
`yq '.text \ \| = gsub("old", "new")' file.yaml`	Ersetze alle Vorkommen
`yq '.path \ \| split("/")' file.yaml`	String in Array aufteilen
`yq '.tags \ \| join(", ")' file.yaml`	Array in String umwandeln
`yq '.name \ \| length' file.yaml`	Stringlänge
`yq '.text \ \| contains("substring")' file.yaml`	Prüfe, ob String Teilstring enthält

Erweiterte Nutzung - Formatkonvertierung¶

Befehl	Beschreibung
`yq -o=json '.' file.yaml`	YAML in JSON umwandeln
`yq -P '.' file.json`	JSON in YAML umwandeln
`yq -o=xml '.' file.yaml`	YAML zu XML konvertieren
`yq -p=xml '.' file.xml`	XML in YAML umwandeln
`yq -o=csv '.items[]' file.yaml`	YAML zu CSV konvertieren
`yq -o=props '.' file.yaml`	YAML in Properties-Format konvertieren
`yq -o=json -I=4 '.' file.yaml`	JSON mit benutzerdefinierter Einrückung
`yq -o=yaml --yaml-output-version=1.1 '.' file.yaml`	YAML-Version angeben
`yq -p=csv -o=json '.' file.csv`	CSV zu JSON über YAML konvertieren

Konfiguration¶

Befehlszeilenoptionen¶

# Input/Output format options
-p, --input-format string    Input format (yaml/json/xml/csv/props)
-o, --output-format string   Output format (yaml/json/xml/csv/props)
-P, --prettyPrint           Pretty print (shorthand for -o=yaml)

# Modification options
-i, --inplace               Edit file in place
-I, --indent int            Indentation (default 2)

# Processing options
-e, --exit-status           Exit with status code based on result
-n, --null-input            Don't read input, start with null
-N, --no-colors             Disable colored output
-C, --colors                Force colored output

# Multiple file options
ea, eval-all                Evaluate all files together

Ausdruckssyntax¶

# Basic path expressions
.field                      # Access field
.nested.field              # Nested access
.[0]                       # Array index
.[]                        # Array iteration
.*                         # All fields

# Operators
=                          # Assignment
|=                         # Update assignment
+=                         # Append/increment
*                          # Multiply/merge
+                          # Add/concatenate
-                          # Subtract
//                         # Alternative operator (default value)

# Functions
select()                   # Filter
map()                      # Transform array
has()                      # Check existence
keys                       # Get keys
length                     # Get length
sort_by()                  # Sort array
group_by()                 # Group array
unique                     # Remove duplicates

Umgebungsvariablen¶

# Use environment variables in expressions
export APP_NAME="my-app"
yq '.name = env(APP_NAME)' file.yaml

# With default value
yq '.name = (env(NAME) // "default")' file.yaml

# String interpolation
yq '.message = "Hello " + env(USER)' file.yaml

Häufige Anwendungsfälle¶

Anwendungsfall 1: Kubernetes Deployment-Replikate aktualisieren¶

# Single deployment
yq -i '.spec.replicas = 5' deployment.yaml

# Multiple deployments in one file
yq -i '(.spec.replicas | select(. != null)) = 5' deployments.yaml

# Conditionally update specific deployment
yq -i '(select(.metadata.name == "api-server") | .spec.replicas) = 10' deployment.yaml

# Update all deployments in multiple files
yq -i '.spec.replicas = 3' k8s/*.yaml

Anwendungsfall 2: Konfigurationsdateien zusammenführen¶

# Merge base config with environment-specific overrides
yq ea 'select(fi == 0) * select(fi == 1)' base-config.yaml prod-config.yaml > final-config.yaml

# Merge multiple environment files
yq ea '. as $item ireduce ({}; . * $item)' base.yaml dev.yaml local.yaml > merged.yaml

# Merge with array concatenation
yq ea 'select(fi == 0) *+ select(fi == 1)' config1.yaml config2.yaml > combined.yaml

Anwendungsfall 3: Daten extrahieren und transformieren¶

# Extract all container images from Kubernetes manifests
yq '.spec.template.spec.containers[].image' deployment.yaml

# Get all service names and ports
yq '.items[] | select(.kind == "Service") | .metadata.name + ":" + (.spec.ports[0].port | tostring)' services.yaml

# Create summary report
yq '.items[] | {"name": .metadata.name, "kind": .kind, "namespace": .metadata.namespace}' resources.yaml -o=json

Anwendungsfall 4: Massenaktualisierungen über mehrere Dateien¶

# Add label to all resources
find . -name "*.yaml" -exec yq -i '.metadata.labels.environment = "production"' {} \;

# Update image tag in all deployments
yq -i '(.spec.template.spec.containers[].image | select(. == "*:latest")) |= sub(":latest", ":v1.2.3")' k8s/**/*.yaml

# Add annotation to specific resources
yq -i 'select(.kind == "Service") | .metadata.annotations."prometheus.io/scrape" = "true"' *.yaml

Anwendungsfall 5: CI/CD Pipeline-Konfiguration¶

# Update version in multiple config files
export VERSION="2.1.0"
yq -i '.version = env(VERSION)' chart/Chart.yaml
yq -i '.image.tag = env(VERSION)' values.yaml

# Inject secrets from environment
yq -i '.database.password = env(DB_PASSWORD)' config.yaml

# Generate environment-specific configs
for env in dev staging prod; do
  yq ea 'select(fi == 0) * select(fi == 1)' base.yaml "env-${env}.yaml" > "config-${env}.yaml"
done

Bewährte Praktiken¶

Immer zuerst ohne -itesten: Befehle ohne In-Place-Flag ausführen, um Änderungen zu previwen, bevor Dateien modifiziert werden

  yq '.spec.replicas = 5' deployment.yaml  # Preview first
  yq -i '.spec.replicas = 5' deployment.yaml  # Then apply
  ```

- **Versionskontrolle verwenden**: Dateien vor Massänderungen committen, um bei Bedarf einfach zurückzukehren

- **Ausdrücke in Anführungszeichen**: Einzelne Anführungszeichen für Ausdrücke verwenden, um Shell-Interpretation zu verhindern```bash
  yq '.items[] | select(.name == "test")' file.yaml  # Correct
  ```
- **YAML nach Änderungen validieren**: Stellen Sie sicher, dass Ihre Änderungen gültiges YAML erzeugen
```bash
  yq '.' modified.yaml > /dev/null && echo "Valid YAML" || echo "Invalid YAML"
  ```
(No complete text)
`select()`
- **Kommentare beibehalten**: yq bewahrt Kommentare standardmäßig auf, aber seien Sie vorsichtig bei komplexen Transformationen
```bash
  yq '(select(.kind == "Deployment") | .spec.replicas) = 3' file.yaml
  ```
- **Umgebungsvariablen nutzen**: Halten Sie sensible Daten aus Skripten heraus
`eval-all`
(No complete text)
```bash
  yq ea '. as $item ireduce ({}; . * $item)' *.yaml
  ```
(No complete text)
```bash
  export SECRET_KEY="..."
  yq '.apiKey = env(SECRET_KEY)' config.yaml
  ```
## Fehlerbehebung

Would you like to provide the complete texts so I can translate them fully?`-r` flag when piping to other commands
  ```bash
  IMAGE=$(yq -r '.spec.template.spec.containers[0].image' deployment.yaml)
  ```

- **Check exit codes for validation**: Use `-e` flag to fail on null/false results
  ```bash
  yq -e '.spec.replicas > 0' deployment.yaml && echo "Valid" || echo "Invalid"
  ```

## Troubleshooting

| Problem | Lösung |
|-------|----------|
| **Error: "bad file descriptor"** | Use `-i` flag correctly or redirect output: `yq '.' file.yaml > temp && mv temp file.yaml` |
| **Changes not persisted** | Add `-i` flag for in-place editing: `yq -i '.field = "value"' file.yaml` |
| **"null" appears in output** | Field doesn't exist or is null. Use alternative operator: `yq '.field // "default"' file.yaml` |
| **Comments are removed** | Use `... comments=""` to explicitly remove, or check if using operations that don't preserve comments |
| **Array merge replaces instead of concatenates** | Use `*+` instead of `*` for merge: `yq ea 'select(fi==0) *+ select(fi==1)' f1.yaml f2.yaml` |
| **"Error: bad expression"** | Überprüfe Ausdruckssyntax, stelle korrekte Anführungszeichen sicher, verifiziere Operatoren |
| **Output has extra quotes** | Use `-r` flag for raw output: `yq -r '.name' file.yaml` |
| **Cannot process multiple files** | Use `ea` (eval-all) command: `yq ea '.' file1.yaml file2.yaml` |
| **Wrong version of yq** | Verify you have mikefarah/yq (not kislyuk/yq): `yq --version` should show github.com/mikefarah/yq |
| **Permission denied on `-i`** | Ensure write permissions: `chmod u+w file.yaml` or run with appropriate privileges |
| **Encoding issues with special characters** | Ensure UTF-8 encoding: `yq --encoding=utf-8 '.' file.yaml` |
| **Large files cause memory issues** | Process in chunks or use streaming: `yq -N '.items[]' large-file.yaml` |
| **Path not found errors** | Verify path exists: `yq 'has("path.to.field")' file.yaml` before accessing |
| **Merge conflicts with complex structures** | Use explicit merge strategies: `*d` for deep merge with deletion, `*+` for array concatenation |
## Quick Reference - Common Patterns

```bash
# Read value
yq '.path.to.field' file.yaml

# Update value
yq -i '.path.to.field = "new-value"' file.yaml

# Delete field
yq -i 'del(.path.to.field)' file.yaml

# Filter array
yq '.items[] | select(.name == "target")' file.yaml

# Merge files
yq ea 'select(fi==0) * select(fi==1)' base.yaml override.yaml

# Convert format
yq -o=json '.' file.yaml

# Use environment variable
yq '.field = env(VAR_NAME)' file.yaml

# Multiple operations
yq -i '.field1 = "value1" | .field2 = "value2"' file.yaml