Edición de archivos de configuración YAML con yq

yq es un procesador de YAML portátil para la línea de comandos, similar a cómo jq gestiona JSON. Permite leer, filtrar y editar archivos YAML sin escribir un script en Python o Ruby.

Hay dos herramientas populares llamadas yq:

• mikefarah/yq (Go) — se mantiene activamente y admite YAML, JSON, XML y TOML. Esta lección utiliza esta versión.
• kislyuk/yq (Python) — un envoltorio de jq para YAML; su sintaxis es diferente.

Instale la versión para Go:

• brew install yq en macOS
• snap install yq en Linux
• O descargue el binario: wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq

Verificación: yq --version debería mostrar v4.x.x. La versión 4 utiliza una sintaxis de expresiones diferente de la versión 3, por lo que la versión es importante.

Antes de editar nada, aprenda a leer campos YAML. Dado un Deployment de Kubernetes, puede extraer cualquier valor anidado mediante rutas con notación de puntos.

Ejemplo 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

Comandos de lectura principales:

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

De forma predeterminada, la salida es texto sin formato (sin comillas). Añada la opción -r o use | yq -r si necesita cadenas sin formato en scripts.

La opción más importante para el uso en situaciones reales es -i (en el propio archivo). Sin ella, yq muestra los resultados en stdout y deja el archivo sin cambios.

Sintaxis:

• Solo lectura (stdout): yq '.spec.replicas' file.yaml
• Edición en el propio archivo: yq -i '.spec.replicas = 5' file.yaml

El operador de asignación = establece un valor. La expresión es un filtro completo de yq, por lo que puede combinar la lectura y la escritura en un solo paso.

Importante: yq -i vuelve a escribir el archivo por completo. Generalmente, los comentarios colocados en la misma línea que un campo se conservan, pero los bloques de comentarios independientes pueden cambiar de posición. Confirme siempre sus archivos YAML en el control de versiones antes de ejecutar ediciones masivas en el propio archivo.

Pruebe primero sin -i y añádala cuando esté conforme con la salida.

Una tarea muy habitual de CI consiste en actualizar la etiqueta de la imagen de Docker en un manifiesto de Kubernetes después de crear una imagen nueva. Con yq, esto se reduce a una sola línea.

El patrón es:

• Seleccione el contenedor por nombre mediante select() para evitar codificar el índice 0 del array.
• Use |= (operador de actualización) o = para establecer el nuevo valor.

Usando el índice del array (frágil si cambia la lista de contenedores):

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

Usando select() (robusto):

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

En un pipeline de CI, pasaría la etiqueta como variable de shell:

Además de actualizar campos existentes, yq puede añadir claves nuevas o eliminar las existentes.

Añadir un campo:

• Asigne un valor a una ruta que no exista: yq -i '.metadata.labels.version = "v2"' file.yaml
• Si falta la clave principal (labels), yq la crea automáticamente.

Eliminar un campo:

• Use la función del(): yq -i 'del(.metadata.annotations)' file.yaml
• Elimine un elemento de un array mediante su índice: yq -i 'del(.spec.template.spec.containers[1])' file.yaml

Añadir un elemento a un array:

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

Los manifiestos de Kubernetes suelen agrupar varios recursos en un solo archivo, separados por ---. De forma predeterminada, yq procesa todos los documentos de ese archivo.

Técnicas principales:

• Enumere todos los tipos de documento: yq '.[].kind' multi.yaml — observe el .[] inicial para iterar por los documentos.
• Seleccione un documento concreto por su tipo: yq 'select(.kind == "Service")' multi.yaml
• Edite en el propio archivo solo los documentos que coincidan:

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

Los documentos que no coinciden con el predicado de select() se transfieren sin cambios, por lo que Service, ConfigMap y los demás recursos permanecen intactos.

Para dividir un archivo de varios documentos en archivos individuales, puede recorrer la salida de yq o usar:

• yq -s '.kind' multi.yaml — escribe un archivo por documento, con un nombre basado en su valor .kind.

Los archivos de configuración de CI (.github/workflows/*.yml, .gitlab-ci.yml) también están en YAML. Los mismos comandos de yq funcionan, aunque las rutas pueden estar profundamente anidadas.

Tareas habituales al modificar CI:

• Fijar la versión del runner: actualice runs-on en todos los trabajos.
• Actualizar la versión de una acción: busque los pasos que utilizan una acción determinada y actualice su campo uses.
• Cambiar un indicador: active o desactive una configuración del nivel del workflow.

Ejemplo: actualizar a v4 todos los pasos que usan actions/checkout:

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

Esta expresión — iterar con [], restringir con select() y asignar con = — es el patrón fundamental para cualquier edición de YAML estructurado.

Codificar valores directamente en las expresiones de yq hace que los scripts sean frágiles. yq permite inyectar variables de shell mediante la función env() o la abreviatura strenv().

• env(VAR_NAME) — lee la variable de entorno y la convierte al tipo YAML adecuado (un número sigue siendo un número y una cadena sigue siendo una cadena).
• strenv(VAR_NAME) — siempre devuelve una cadena, lo que resulta útil para las etiquetas de imágenes.

Esto evita la pesadilla de las comillas que supone interpolar variables dentro de cadenas de shell entre comillas dobles con rutas YAML incrustadas.

Patrón:

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

Use env() al establecer campos numéricos como replicas para conservar el tipo YAML (entero, no una cadena entre comillas).

A veces necesita aplicar un archivo de parche (un YAML pequeño con sobrescrituras) sobre una configuración base; por ejemplo, para aplicar sobrescrituras específicas del entorno en flujos de trabajo de estilo Kustomize.

yq puede fusionar dos archivos mediante el operador de fusión *:

• yq '. *= load("patch.yaml")' base.yaml — fusiona el parche en profundidad con la base y escribe el resultado en la salida estándar.
• Añada -i para actualizar la base directamente: yq -i '. *= load("patch.yaml")' base.yaml

Comportamiento de la fusión:

• Los valores escalares del parche sobrescriben los de la base.
• Los mapeos se fusionan en profundidad (se conservan las claves que no están en el parche).
• Las secuencias (matrices) se reemplazan de forma predeterminada, no se concatenan. Utilice *+ para añadirlas.

Este patrón sustituye los frágiles scripts de sed que se rompen cuando cambia el espaciado.

Antes de aplicar un YAML parcheado a un clúster, es recomendable validarlo y, opcionalmente, convertirlo a JSON para utilizarlo con otras herramientas.

Validar la sintaxis:

• yq '.' file.yaml && echo "Valid" — yq termina con el código 1 si hay errores de análisis, por lo que esto funciona en las comprobaciones de CI.

Convertir YAML a JSON:

• yq -o=json '.' file.yaml — muestra JSON con formato legible.
• Envíe el resultado a jq para procesar más el JSON: yq -o=json '.' file.yaml | jq '.metadata.name'

Convertir JSON a YAML:

• yq -P '.' file.json — la opción -P fuerza la salida en formato YAML (con formato legible) cuando la entrada es JSON.

Estas conversiones convierten yq en un puente entre herramientas nativas de YAML (Helm, kubectl) y herramientas nativas de JSON (Terraform, AWS CLI, jq).

Reunamos todas las técnicas en un script de CI real que parchea un manifiesto de Deployment de Kubernetes como parte de un flujo de GitOps.

El script:

1. Valida el YAML de entrada antes de modificarlo.
2. Utiliza env() / strenv() para todas las sustituciones de variables.
3. Actualiza la etiqueta de la imagen del contenedor mediante un select() basado en el nombre.
4. Aumenta el número de réplicas.
5. Establece una anotación deploy-time con la marca de tiempo actual.
6. Vuelve a validar la salida antes de confirmar los cambios.

Este patrón garantiza que, incluso si el flujo se ejecuta de forma simultánea, cada paso sea atómico y auditable.

Compruebe sus conocimientos sobre la edición de archivos YAML de Kubernetes con varios documentos mediante yq.

Ha completado la lección sobre la edición de archivos de configuración YAML con yq. Este es un resumen conciso de todo lo tratado:

• Instalación: Utilice el binario de Go de mikefarah/yq (v4). Verifique la instalación con yq --version.
• Lectura: Rutas con notación de punto como .spec.replicas; acceda a matrices con [0] o recórralas con [].
• Edición directa: La opción -i reescribe el archivo. Previsualice siempre el resultado sin -i primero.
• Selección robusta: Prefiera select(.name == "app") a los índices de matriz codificados.
• Adición y eliminación: Asigne un valor a una ruta nueva para crearla; utilice del() para eliminar campos.
• Archivos con varios documentos: Utilice select(.kind == "...") para seleccionar un recurso y dejar los demás intactos.
• Variables de CI: Utilice strenv(VAR) para cadenas y env(VAR) para valores tipados; así evitará errores de comillas del shell.
• Fusión: . *= load("patch.yaml") fusiona en profundidad un archivo de sobrescrituras sin perder las claves que no se hayan parcheado.
• Validación y conversión: Utilice yq '.' como comprobación de lint, y -o=json y -P para convertir formatos.

El patrón fundamental para cualquier parche YAML en CI es: validar → seleccionar → asignar → validar. Combínelo con strenv() y select() y no tendrá que recurrir de nuevo a frágiles comandos de una línea con sed.