yq Cheatsheet - Processeur YAML/JSON/XML

Installation

Plateforme	Commande
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`

Commandes de base - Lecture et Affichage

Commande	Description
`yq '.' file.yaml`	Afficher le fichier YAML complet (pretty print)
`yq '.name' file.yaml`	Lire une valeur de champ spécifique
`yq '.metadata.name' file.yaml`	Lire un champ imbriqué en utilisant la notation par points
`yq '.items[0]' file.yaml`	Accéder au premier élément d’un tableau
`yq '.items[*]' file.yaml`	Accéder à tous les éléments d’un tableau
`yq '.items[]' file.yaml`	Parcourir les éléments du tableau
`yq '.items[].name' file.yaml`	Extraire un champ spécifique de tous les éléments du tableau
`yq '.items[-1]' file.yaml`	Accéder au dernier élément d’un tableau
`yq '.items[1:3]' file.yaml`	Tranche de tableau (éléments 1 et 2)
`cat file.yaml \	yq ‘.spec’`
`yq -r '.name' file.yaml`	Sortie de chaîne brute (sans guillemets)
`yq ‘.items \	length’ file.yaml`
`yq 'keys' file.yaml`	Lister toutes les clés de premier niveau
`yq ’.[] \	keys’ file.yaml`

Commandes de base - Écriture et Mise à jour

Commande	Description
`yq '.name = "new-value"' file.yaml`	Mettre à jour un champ (imprime sur stdout)
`yq -i '.name = "new-value"' file.yaml`	Mettre à jour le champ sur place (modifie le fichier)
`yq '.spec.replicas = 3' file.yaml`	Mettre à jour la valeur imbriquée
`yq '.items[0].name = "updated"' file.yaml`	Mettre à jour un élément de tableau
`yq '.newField = "value"' file.yaml`	Créer un nouveau champ
`yq '.metadata.labels.env = "prod"' file.yaml`	Créer un champ imbriqué
`yq 'del(.fieldName)' file.yaml`	Supprimer un champ
`yq 'del(.metadata.annotations)' file.yaml`	Supprimer le champ imbriqué
`yq 'del(.items[0])' file.yaml`	Supprimer l’élément du tableau
`yq '.items += {"name": "new"}' file.yaml`	Ajouter à un tableau
`yq '.items = []' file.yaml`	Vider le tableau
`yq '.count += 1' file.yaml`	Incrémenter la valeur numérique
`yq '.total = .price * .quantity' file.yaml`	Opérations arithmétiques

Utilisation avancée - Filtrage et Sélection

Commande	Description
`yq ‘.items[] \	select(.kind == “Pod”)’ file.yaml`
`yq ‘.items[] \	select(.kind == “Pod” and .status == “Running”)’ file.yaml`
`yq ‘.items[] \	select(.kind == “Pod” or .kind == “Service”)’ file.yaml`
`yq ‘.items[] \	select(.name \
`yq ‘.items[] \	select(has(“metadata”))’ file.yaml`
`yq ‘.items[] \	select(.replicas > 3)’ file.yaml`
`yq ‘.items[] \	select(.tags \
`yq ‘.items[] \	select(.name != null)’ file.yaml`
`yq ’.[] \	select(tag == “!!str”)’ file.yaml`

Utilisation avancée - Opérations sur les Tableaux

Commande	Description
`yq ‘.items \	= sort_by(.name)’ file.yaml`
`yq ‘.items \	= sort_by(.metadata.creationTimestamp)’ file.yaml`
`yq ‘.items \	= reverse’ file.yaml`
`yq ‘.tags \	unique’ file.yaml`
`yq ‘.items \	flatten’ file.yaml`
`yq ‘.items \	group_by(.kind)’ file.yaml`
`yq ‘.items \	map(.name)’ file.yaml`
`yq ‘.items \	map(select(.active))’ file.yaml`
`yq '.items = .items + .newItems' file.yaml`	Concaténer des tableaux
`yq ‘.items \	= unique_by(.name)’ file.yaml`
`yq '[.items[].name]' file.yaml`	Collecter les valeurs dans un nouveau tableau

Utilisation avancée - Fusion et Combinaison

Commande	Description
`yq ea 'select(fi == 0) * select(fi == 1)' f1.yaml f2.yaml`	Fusion profonde de deux fichiers (f2 remplace f1)
`yq ea '. as $item ireduce ({}; . * $item)' *.yaml`	Fusionner plusieurs fichiers
`yq ea 'select(fi == 0) *+ select(fi == 1)' f1.yaml f2.yaml`	Fusionner avec la concaténation de tableaux
`yq ea '[.]' file1.yaml file2.yaml`	Combiner des fichiers en tableau
`yq '.config = load("config.yaml")' file.yaml`	Charger et fusionner le fichier externe
`yq '.spec.template = load("template.yaml").spec' file.yaml`	Charger un chemin spécifique depuis un fichier
`yq ea 'select(fi == 0) *d select(fi == 1)' f1.yaml f2.yaml`	Fusion profonde avec suppression

Utilisation avancée - Opérations sur les Chaînes

Commande	Description
`yq '.fullName = .firstName + " " + .lastName' file.yaml`	Concaténation de chaînes
`yq ‘.name \	= upcase’ file.yaml`
`yq ‘.name \	= downcase’ file.yaml`
`yq ‘.name \	= trim’ file.yaml`
`yq ‘.text \	= sub(“old”, “new”)’ file.yaml`
`yq ‘.text \	= gsub(“old”, “new”)’ file.yaml`
`yq ‘.path \	split(”/”)’ file.yaml`
`yq ‘.tags \	join(”, ”)’ file.yaml`
`yq ‘.name \	length’ file.yaml`
`yq ‘.text \	contains(“substring”)’ file.yaml`

Utilisation avancée - Conversion de Format

Commande	Description
`yq -o=json '.' file.yaml`	Convertir YAML en JSON
`yq -P '.' file.json`	Convertir JSON en YAML
`yq -o=xml '.' file.yaml`	Convertir YAML en XML
`yq -p=xml '.' file.xml`	Convertir XML en YAML
`yq -o=csv '.items[]' file.yaml`	Convertir YAML en CSV
`yq -o=props '.' file.yaml`	Convertir YAML au format properties
`yq -o=json -I=4 '.' file.yaml`	JSON avec indentation personnalisée
`yq -o=yaml --yaml-output-version=1.1 '.' file.yaml`	Spécifier la version YAML
`yq -p=csv -o=json '.' file.csv`	Convertir CSV en JSON via YAML

Configuration

Options de Ligne de Commande

# 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

Syntaxe d’Expression

# 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

Variables d’Environnement

# 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

Cas d’Utilisation Courants

Cas d’Utilisation 1 : Mettre à jour les Réplicas de Déploiement Kubernetes

# 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

Cas d’Utilisation 2 : Fusionner des Fichiers de Configuration

# 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

Cas d’Utilisation 3 : Extraire et Transformer des Données

# 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

Cas d’Utilisation 4 : Mises à Jour en Masse sur Plusieurs Fichiers

# 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

Cas d’Utilisation 5 : Configuration de Pipeline CI/CD

# 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

Meilleures Pratiques

Toujours tester sans -id’abord : Exécuter les commandes sans l’indicateur sur place pour prévisualiser les modifications avant de modifier les fichiers
```
yq '.spec.replicas = 5' deployment.yaml  # Preview first
yq -i '.spec.replicas = 5' deployment.yaml  # Then apply
```
Utiliser le contrôle de version : Commiter les fichiers avant des modifications en masse pour pouvoir facilement revenir en arrière
Mettre des expressions entre guillemets : Utiliser des guillemets simples pour les expressions afin d’éviter l’interprétation par le shell

Note: Since some sections (3-20) were left blank in the original text, I’ve kept them blank in the translation as well. If you want me to fill those with placeholder text or have specific content for those sections, please provide those details.```bash yq ‘.items[] | select(.name == “test”)’ file.yaml # Correct

```bash
yq '.' modified.yaml > /dev/null && echo "Valid YAML" || echo "Invalid YAML"
```(Incomplete text)
`select()`(Incomplete text)
```bash
yq '(select(.kind == "Deployment") | .spec.replicas) = 3' file.yaml
```- **Préserver les commentaires** : yq préserve les commentaires par défaut, mais soyez prudent avec les transformations complexes
`eval-all`(Incomplete text)
```bash
yq ea '. as $item ireduce ({}; . * $item)' *.yaml
```- **Exploiter les variables d'environnement** : Gardez les données sensibles hors des scripts
```bash
export SECRET_KEY="..."
yq '.apiKey = env(SECRET_KEY)' config.yaml
```(Incomplete text)
`-r`(Incomplete text)
```bash
IMAGE=$(yq -r '.spec.template.spec.containers[0].image' deployment.yaml)
```(Incomplete text)
`-e`(Incomplete text)
```bash
yq -e '.spec.replicas > 0' deployment.yaml && echo "Valid" || echo "Invalid"
```(Incomplete text)

## Dépannage

| Problème | Solution |
|-------|----------|
| **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"** | Vérifier la syntaxe de l'expression, s'assurer que les guillemets sont corrects, vérifier que les opérateurs sont exacts |
| **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 |(Incomplete text)
## Référence rapide - Modèles courants

Could you provide the full, complete texts for a comprehensive translation?```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