Редактирование файлов конфигурации YAML с yq

yq — переносимый обработчик YAML в командной строке, аналогично тому, как jq работает с JSON. С его помощью можно читать, фильтровать и редактировать файлы YAML, не создавая скрипт на Python или Ruby.

Существуют два популярных инструмента с именем yq:

• mikefarah/yq (Go) — активно поддерживается, работает с YAML, JSON, XML и TOML. В этом уроке используется именно эта версия.
• kislyuk/yq (Python) — оболочка для jq, работающая с YAML; синтаксис отличается.

Установите версию на Go:

• brew install yq в macOS
• snap install yq в Linux
• Или скачайте двоичный файл: wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq

Проверьте установку: команда yq --version должна вывести v4.x.x. В версии 4 используется другой синтаксис выражений, чем в v3, поэтому версия имеет значение.

Прежде чем что-либо редактировать, научитесь читать поля YAML. В описании развёртывания Kubernetes можно извлечь любое вложенное значение с помощью путей в точечной нотации.

Пример 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

Основные команды чтения:

• yq '.metadata.name' deployment.yaml — выводит my-app
• yq '.spec.replicas' deployment.yaml — выводит 3
• yq '.spec.template.spec.containers[0].image' deployment.yaml — выводит my-app:1.0.0

По умолчанию выводится обычный текст (без кавычек). Добавьте флаг -r или используйте | yq -r, если в скриптах нужны необработанные строки.

Самый важный флаг для практического использования — -i (редактирование на месте). Без него yq выводит результаты в stdout, не изменяя файл.

Синтаксис:

• Только чтение (stdout): yq '.spec.replicas' file.yaml
• Редактирование на месте: yq -i '.spec.replicas = 5' file.yaml

Оператор присваивания = задаёт значение. Выражение представляет собой полноценный фильтр yq, поэтому чтение и запись можно объединить за один проход.

Важно: yq -i полностью перезаписывает файл. Комментарии в той же строке, что и поле, обычно сохраняются, но отдельные блоки комментариев могут переместиться. Всегда фиксируйте YAML в системе контроля версий перед массовым редактированием на месте.

Сначала проверьте результат без -i, а затем добавьте его, когда результат Вас устроит.

Очень распространённая задача CI — изменить тег образа Docker в манифесте Kubernetes после сборки нового образа. С yq это выполняется одной строкой.

Шаблон выглядит так:

• Находите контейнер по имени с помощью select(), чтобы не привязываться к индексу 0 в массиве.
• Используйте |= (оператор обновления) или =, чтобы задать новое значение.

С использованием индекса массива (ненадёжно, если список контейнеров изменится):

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

С использованием select() (надёжно):

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

В конвейере CI тег передаётся как переменная оболочки:

Помимо обновления существующих полей, yq может добавлять новые ключи и удалять существующие.

Добавление поля:

• Просто присвойте значение пути, которого ещё нет: yq -i '.metadata.labels.version = "v2"' file.yaml
• Если родительский ключ (labels) отсутствует, yq создаст его автоматически.

Удаление поля:

• Используйте функцию del(): yq -i 'del(.metadata.annotations)' file.yaml
• Удалите элемент массива по индексу: yq -i 'del(.spec.template.spec.containers[1])' file.yaml

Добавление элемента в массив:

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

Манифесты Kubernetes часто объединяют несколько ресурсов в одном файле, разделённых с помощью ---. По умолчанию yq обрабатывает все документы в таком файле.

Основные приёмы:

• Вывести виды всех документов: yq '.[].kind' multi.yaml — обратите внимание на начальный .[], который перебирает документы.
• Выбрать конкретный документ по виду: yq 'select(.kind == "Service")' multi.yaml
• Редактировать на месте только подходящие документы:

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

Документы, не соответствующие условию select(), передаются без изменений, поэтому Ваши Service, ConfigMap и другие ресурсы сохраняются.

Чтобы разделить многофайловый документ на отдельные файлы, можно перебрать вывод yq в цикле или использовать:

• yq -s '.kind' multi.yaml — записывает по одному файлу на документ, используя значение его .kind в имени.

Файлы конфигурации CI (.github/workflows/*.yml, .gitlab-ci.yml) также являются файлами YAML. Те же команды yq работают и с ними, хотя пути могут быть глубоко вложенными.

Распространённые задачи исправления CI:

• Зафиксировать версию исполнителя: обновить runs-on во всех заданиях.
• Обновить версию действия: найти шаги, использующие определённое действие, и изменить его поле uses.
• Переключить флаг: включить или отключить настройку уровня рабочего процесса.

Пример: обновить до v4 все шаги, использующие actions/checkout:

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

Этот приём — перебирать с помощью [], сужать выбор с помощью select(), присваивать с помощью = — является основным шаблоном любого структурированного редактирования YAML.

Жёстко заданные значения в выражениях yq делают скрипты хрупкими. yq поддерживает передачу переменных оболочки с помощью функции env() или сокращённой записи strenv().

• env(VAR_NAME) — считывает переменную окружения и преобразует её в соответствующий тип YAML (число остаётся числом, строка — строкой).
• strenv(VAR_NAME) — всегда возвращает строку; это удобно для тегов образов.

Так Вы избежите сложного экранирования при подстановке переменных во вложенные строки оболочки в двойных кавычках с путями YAML.

Шаблон:

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

Используйте env() при задании числовых полей, например replicas, чтобы сохранить тип YAML (целое число, а не строка в кавычках).

Иногда необходимо применить файл исправлений (небольшой YAML-файл с переопределениями) к базовой конфигурации — например, чтобы задать переопределения для конкретной среды в рабочих процессах в стиле Kustomize.

yq позволяет объединять два файла с помощью оператора объединения *:

• yq '. *= load("patch.yaml")' base.yaml — выполняет глубокое объединение patch с base и записывает результат в стандартный вывод.
• Добавьте -i, чтобы обновить base на месте: yq -i '. *= load("patch.yaml")' base.yaml

Поведение при объединении:

• Скалярные значения из patch заменяют значения в base.
• Отображения объединяются рекурсивно (ключи, отсутствующие в patch, сохраняются).
• Последовательности (массивы) по умолчанию заменяются, а не добавляются в конец. Чтобы добавлять элементы, используйте *+.

Этот подход заменяет хрупкие сценарии sed, которые ломаются при изменении пробелов.

Перед применением исправленного YAML к кластеру рекомендуется проверить его и при необходимости преобразовать в JSON для других инструментов.

Проверка синтаксиса:

• yq '.' file.yaml && echo "Valid" — при ошибках разбора yq завершается с кодом 1, поэтому этот вариант подходит для проверок в CI.

Преобразование YAML в JSON:

• yq -o=json '.' file.yaml — выводит отформатированный JSON.
• Передайте результат в jq для дальнейшей обработки JSON: yq -o=json '.' file.yaml | jq '.metadata.name'

Преобразование JSON в YAML:

• yq -P '.' file.json — флаг -P принудительно задаёт вывод в формате YAML (с форматированием), если входные данные представлены в JSON.

Эти преобразования превращают yq в связующее звено между инструментами, ориентированными на YAML (Helm, kubectl), и инструментами, ориентированными на JSON (Terraform, AWS CLI, jq).

Объединим все рассмотренные приёмы в одном рабочем сценарии CI, который исправляет манифест развёртывания Kubernetes в рамках GitOps-конвейера.

Сценарий:

1. Проверяет входной YAML, прежде чем вносить изменения.
2. Использует env() / strenv() для всех подстановок переменных.
3. Обновляет тег образа контейнера с помощью select() по имени.
4. Увеличивает количество реплик.
5. Добавляет в аннотацию deploy-time текущую метку времени.
6. Снова проверяет результат перед фиксацией изменений.

Этот подход гарантирует атомарность и возможность аудита каждого шага, даже если конвейер выполняется одновременно в нескольких экземплярах.

Проверьте, насколько хорошо Вы поняли редактирование YAML-файлов Kubernetes с несколькими документами с помощью yq.

Вы завершили урок о редактировании файлов конфигурации YAML с помощью yq. Ниже приведено краткое резюме всего изученного:

• Установка: Используйте двоичный файл mikefarah/yq для Go (версии 4). Проверьте установку с помощью yq --version.
• Чтение: Пути в точечной нотации, например .spec.replicas; доступ к массиву с помощью [0] или перебора через [].
• Редактирование на месте: Флаг -i перезаписывает файл. Сначала всегда просматривайте результат без -i.
• Надёжный выбор элементов: Предпочитайте select(.name == "app") жёстко заданным индексам массива.
• Добавление и удаление: Присвойте значение новому пути, чтобы создать его; используйте del(), чтобы удалить поля.
• Файлы с несколькими документами: Используйте select(.kind == "..."), чтобы выбрать один ресурс и не затронуть остальные.
• Переменные CI: Используйте strenv(VAR) для строк и env(VAR) для типизированных значений — это позволяет избежать ошибок экранирования в оболочке.
• Объединение: . *= load("patch.yaml") выполняет глубокое объединение файла с переопределениями, не теряя ключи, для которых нет исправлений.
• Проверка и преобразование: Используйте yq '.' как проверку перед продолжением, а -o=json и -P — для преобразования формата.

Основной шаблон любого исправления YAML в CI таков: проверить → выбрать → присвоить → проверить. Сочетайте его с strenv() и select(), и Вам больше не придётся прибегать к хрупким однострочным командам sed.