Modifier des fichiers de configuration YAML avec yq

yq est un processeur YAML portable en ligne de commande, comparable à la manière dont jq traite JSON. Il vous permet de lire, filtrer et modifier des fichiers YAML sans écrire de script en Python ou en Ruby.

Deux outils populaires portent le nom yq :

• mikefarah/yq (Go) — activement maintenu, il prend en charge YAML, JSON, XML et TOML. Cette leçon utilise cette version.
• kislyuk/yq (Python) — un adaptateur de jq pour YAML ; sa syntaxe est différente.

Installez la version Go :

• brew install yq sur macOS
• snap install yq sur Linux
• Ou téléchargez le binaire : wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq

Vérifiez l’installation : yq --version doit afficher v4.x.x. La version 4 utilise une syntaxe d’expression différente de celle de v3 ; la version est donc importante.

Avant de modifier quoi que ce soit, apprenez à lire les champs YAML. À partir d’un déploiement Kubernetes, vous pouvez extraire toute valeur imbriquée à l’aide de chemins en notation pointée.

Exemple de 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

Principales commandes de lecture :

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

Par défaut, la sortie est du texte brut (sans guillemets). Ajoutez l’option -r ou utilisez | yq -r si vous avez besoin de chaînes brutes dans vos scripts.

L’option la plus importante pour une utilisation réelle est -i (sur place). Sans elle, yq affiche les résultats dans la sortie standard et laisse le fichier inchangé.

Syntaxe :

• Lecture seule (sortie standard) : yq '.spec.replicas' file.yaml
• Modification sur place : yq -i '.spec.replicas = 5' file.yaml

L’opérateur d’affectation = définit une valeur. L’expression est un filtre yq complet ; vous pouvez donc combiner lecture et écriture en un seul passage.

Important : yq -i réécrit entièrement le fichier. Les commentaires placés sur la même ligne qu’un champ sont généralement conservés, mais les blocs de commentaires autonomes peuvent être déplacés. Validez toujours votre YAML dans le système de contrôle de version avant d’effectuer des modifications sur place en grand nombre.

Faites d’abord un essai sans -i, puis ajoutez cette option lorsque la sortie vous convient.

Une tâche très courante d’intégration continue consiste à incrémenter l’étiquette de l’image Docker dans un manifeste Kubernetes après la création d’une nouvelle image. Avec yq, cela se fait en une seule ligne.

Le modèle est le suivant :

• Ciblez le conteneur par son nom avec select() afin d’éviter de coder en dur l’index 0 du tableau.
• Utilisez |= (opérateur de mise à jour) ou = pour définir la nouvelle valeur.

Avec un index de tableau (fragile si la liste des conteneurs change) :

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

Avec select() (robuste) :

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

Dans une chaîne d’intégration continue, vous transmettriez l’étiquette sous forme de variable d’interpréteur de commandes :

En plus de mettre à jour les champs existants, yq peut ajouter de nouvelles clés ou en supprimer certaines.

Ajouter un champ :

• Attribuez simplement une valeur à un chemin qui n’existe pas : yq -i '.metadata.labels.version = "v2"' file.yaml
• Si la clé parente (labels) est absente, yq la crée automatiquement.

Supprimer un champ :

• Utilisez la fonction del() : yq -i 'del(.metadata.annotations)' file.yaml
• Supprimez un élément de tableau par son index : yq -i 'del(.spec.template.spec.containers[1])' file.yaml

Ajouter un élément à un tableau :

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

Les manifestes Kubernetes regroupent souvent plusieurs ressources dans un même fichier, séparées par ---. Par défaut, yq traite tous les documents présents dans un tel fichier.

Techniques principales :

• Répertorier tous les types de documents : yq '.[].kind' multi.yaml — notez le .[] initial qui permet d’itérer sur les documents.
• Cibler un document précis par son type : yq 'select(.kind == "Service")' multi.yaml
• Modifier sur place uniquement les documents correspondants :

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

Les documents qui ne correspondent pas au prédicat de select() sont transmis sans modification ; votre Service, votre ConfigMap et vos autres ressources restent donc intacts.

Pour séparer un fichier à plusieurs documents en fichiers individuels, vous pouvez parcourir la sortie de yq ou utiliser :

• yq -s '.kind' multi.yaml — écrit un fichier par document, nommé d’après sa valeur .kind.

Les fichiers de configuration d’intégration continue (.github/workflows/*.yml, .gitlab-ci.yml) sont eux aussi au format YAML. Les mêmes commandes yq fonctionnent, même si les chemins peuvent être profondément imbriqués.

Tâches courantes de correction de l’intégration continue :

• Figer la version d’un exécuteur : mettez à jour runs-on dans toutes les tâches.
• Mettre à jour la version d’une action : recherchez les étapes qui utilisent une action donnée et incrémentez son champ uses.
• Activer ou désactiver une option : activez ou désactivez un paramètre au niveau du flux de travail.

Exemple : mettre à jour vers v4 toutes les étapes qui utilisent actions/checkout :

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

Cette méthode — itérer avec [], restreindre avec select(), affecter avec = — constitue le modèle central de toute modification structurée de YAML.

Coder des valeurs en dur dans les expressions yq rend les scripts fragiles. yq permet d’injecter des variables de l’interpréteur de commandes avec la fonction env() ou l’abréviation strenv().

• env(VAR_NAME) — lit la variable d’environnement et la convertit vers le type YAML approprié (un nombre reste un nombre, une chaîne reste une chaîne).
• strenv(VAR_NAME) — renvoie toujours une chaîne, ce qui est utile pour les étiquettes d’image.

Cela évite le cauchemar des guillemets lié à l’interpolation de variables dans des chaînes de l’interpréteur de commandes entre guillemets doubles contenant des chemins YAML.

Modèle :

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

Utilisez env() lorsque vous définissez des champs numériques comme replicas, afin de préserver le type YAML (entier et non chaîne entre guillemets).

Vous devez parfois appliquer un fichier de correctif (un petit YAML de remplacement) à une configuration de base — par exemple pour gérer des remplacements propres à un environnement dans des flux de travail de type Kustomize.

yq peut fusionner deux fichiers à l’aide de l’opérateur de fusion * :

• yq '. *= load("patch.yaml")' base.yaml — effectue une fusion en profondeur du correctif dans la base et écrit le résultat sur la sortie standard.
• Ajoutez -i pour mettre à jour la base sur place : yq -i '. *= load("patch.yaml")' base.yaml

Fonctionnement de la fusion :

• Les valeurs scalaires du correctif écrasent celles de la base.
• Les mappages sont fusionnés en profondeur (les clés absentes du correctif sont conservées).
• Les séquences (tableaux) sont remplacées par défaut et non ajoutées à la suite. Utilisez *+ pour les ajouter à la suite.

Ce modèle remplace les scripts sed fragiles qui cessent de fonctionner lorsque les espaces changent.

Avant d’appliquer un YAML corrigé à un cluster, il est recommandé de le valider et, si nécessaire, de le convertir en JSON pour d’autres outils.

Valider la syntaxe :

• yq '.' file.yaml && echo "Valid" — yq se termine avec le code 1 en cas d’erreur d’analyse, ce qui convient aux contrôles d’intégration continue.

Convertir YAML en JSON :

• yq -o=json '.' file.yaml — produit un JSON mis en forme.
• Transmettez le résultat à jq pour poursuivre le traitement JSON : yq -o=json '.' file.yaml | jq '.metadata.name'

Convertir JSON en YAML :

• yq -P '.' file.json — l’option -P force la sortie au format YAML (mise en forme) lorsque l’entrée est au format JSON.

Ces conversions font de yq un pont entre les outils natifs de YAML (Helm, kubectl) et les outils natifs de JSON (Terraform, AWS CLI, jq).

Voici comment réunir toutes les techniques : un véritable script d’intégration continue qui corrige un manifeste de déploiement Kubernetes dans le cadre d’un flux GitOps.

Le script :

1. Valide le YAML d’entrée avant toute modification.
2. Utilise env() / strenv() pour toutes les substitutions de variables.
3. Met à jour la balise de l’image du conteneur à l’aide d’un select() basé sur le nom.
4. Augmente le nombre de réplicas.
5. Ajoute une annotation deploy-time contenant l’horodatage actuel.
6. Valide à nouveau la sortie avant la validation des modifications.

Ce modèle garantit que, même si le flux s’exécute simultanément, chaque étape est atomique et vérifiable.

Vérifiez votre compréhension de la modification de fichiers YAML Kubernetes contenant plusieurs documents avec yq.

Vous avez terminé la leçon sur la modification de fichiers de configuration YAML avec yq. Voici un résumé concis de tout ce qui a été abordé :

• Installation : utilisez le binaire Go de mikefarah/yq (v4). Vérifiez l’installation avec yq --version.
• Lecture : chemins en notation par points tels que .spec.replicas ; accès aux tableaux avec [0] ou itération avec [].
• Modification sur place : l’option -i réécrit le fichier. Affichez toujours un aperçu sans -i au préalable.
• Ciblage fiable : préférez select(.name == "app") aux indices de tableau codés en dur.
• Ajout et suppression : affectez une nouvelle valeur à un chemin pour le créer ; utilisez del() pour supprimer des champs.
• Fichiers contenant plusieurs documents : utilisez select(.kind == "...") pour cibler une ressource et laisser les autres intactes.
• Variables d’intégration continue : utilisez strenv(VAR) pour les chaînes et env(VAR) pour les valeurs typées — cela évite les problèmes de guillemets du shell.
• Fusion : . *= load("patch.yaml") fusionne en profondeur un fichier de remplacement sans perdre les clés qui ne sont pas corrigées.
• Validation et conversion : utilisez yq '.' comme contrôle de qualité ; -o=json et -P servent à convertir le format.

Le modèle essentiel pour tout correctif YAML en intégration continue est : valider → sélectionner → affecter → valider. Combinez-le avec strenv() et select() et vous n’aurez plus jamais besoin de recourir aux commandes sed fragiles d’une seule ligne.