Коротко о главном

YAML широко используется в Kubernetes, CI, Ansible и конфигурациях приложений. yq даёт предсказуемый способ выбрать поле, изменить значение и проверить результат. В статье разберём синтаксис mikefarah yq версии 4, преобразование форматов и работу с несколькими документами. Примеры подходят для разработчиков и администраторов, которые автоматизируют работу с конфигурациями.

Ручная правка YAML легко приводит к ошибкам отступов и типов. yq сохраняет структуру и позволяет менять только нужный ключ. Его удобно использовать в скриптах и проверках перед применением манифеста. В результате конфигурации становятся воспроизводимыми и удобными для ревью.

Большинство проблем с yq сводится к нескольким повторяющимся ошибкам. Ниже — что проверить в первую очередь и как не усугубить ситуацию.

Почему это происходит

Ошибки почти всегда связаны с контекстом: другая версия пакета, не тот пользователь, устаревший конфиг или команда из руководства для другой системы. yq не исключение. Поэтому сначала фиксируем исходное состояние, затем меняем одну вещь за раз.

Типичные ошибки

Ниже — сбои, которые встречаются чаще всего. Перед исправлением сохраните текущие конфиги и запишите, какие изменения вносите: так проще откатиться.

1. yq не найден после установки.

Проверьте имя пакета и PATH для своего дистрибутива. Убедитесь, что установлена именно нужная реализация yq, а не другая утилита с тем же именем.

2. Команда с -i или eval-all завершается ошибкой unknown flag.

Скорее всего, установлена другая версия yq. Проверьте yq —version и используйте синтаксис своей версии либо установите mikefarah yq 4.

3. Ошибка mapping values are not allowed in this context.

Проверьте отступы и двоеточия в YAML. Табуляция недопустима, а вложенные ключи должны иметь согласованный сдвиг.

4. После yq -i файл выглядит переупорядоченным или потерял комментарии.

Некоторые преобразования нормализуют YAML и не сохраняют комментарии. Проверяйте diff перед коммитом и храните важные пояснения в документации.

Как настроить правильно

Правильная последовательность проста: проверить версию и зависимости, сделать резервную копию конфигурации, внести минимальное изменение, проверить логи и только потом двигаться дальше.

Установка

В Debian, Ubuntu и Linux Mint используется пакетный менеджер APT:

sudo apt install yq

В Fedora и RHEL-совместимых системах пакет ставится через DNF:

sudo dnf install yq

В Arch Linux и производных пакет доступен в официальных репозиториях:

sudo pacman -S yq

1. Проверьте версию и синтаксис

У yq существует несколько реализаций с разным синтаксисом. Примеры в статье рассчитаны на mikefarah yq версии 4. Проверьте вывод yq —version перед выполнением команд.

yq --version

2. Прочитайте значение из YAML

Путь к ключам записывается через точку, а индексы массивов — в квадратных скобках. yq печатает найденное значение без изменения файла. Если ключ отсутствует, результатом будет null.

yq '.services.web.image' compose.yaml
yq '.items[].name' config.yaml

3. Измените значение на месте

Флаг -i записывает результат обратно в файл. Перед массовой правкой сохраните копию или используйте Git, потому что резервная копия автоматически не создаётся. Проверьте результат отдельным чтением.

yq -i '.services.web.ports = ["8080:80"]' compose.yaml
yq '.services.web.ports' compose.yaml

4. Преобразуйте YAML в JSON и обратно

Параметр -o задаёт выходной формат. Это удобно для передачи данных в jq или для проверки структуры инструментами, которые не читают YAML. Обратное преобразование выполняется с -o=yaml.

yq -o=json '.' config.yaml > config.json
yq -o=yaml '.' config.json

Практические советы

Эти рекомендации проверены на повседневных задачах. Начните с тех, которые закрывают вашу текущую боль, а не со всего списка сразу.

Совет 1. Всегда проверяйте yq —version: Python-обёртка и Go-версия mikefarah и

Всегда проверяйте yq —version: Python-обёртка и Go-версия mikefarah используют разные флаги и синтаксис.

Совет 2. Ключи с точками и слэшами берите в квадратные скобки: .[«app.kubernete

Ключи с точками и слэшами берите в квадратные скобки: .[«app.kubernetes.io/name»].

Совет 3. Перед yq -i делайте коммит в Git или копию файла: флаг меняет документ

Перед yq -i делайте коммит в Git или копию файла: флаг меняет документ без автоматического backup.

Совет 4. Для безопасной подстановки строк из скрипта используйте —arg, а не ко

Для безопасной подстановки строк из скрипта используйте —arg, а не конкатенацию в выражении.

Профилактика

Большинство повторяющихся сбоев с yq связано не с ошибкой в самой программе, а с окружением: обновились зависимости, изменился путь, закончилось место или другой администратор поправил конфиг. Поэтому профилактика начинается с фиксации исходного состояния.

Сохраните рабочий конфиг в систему контроля версий, добавьте короткий комментарий о том, зачем нужен каждый нестандартный параметр, и запишите команду проверки. Через месяц вы скажете себе спасибо: восстановить логику по чужому файлу без пояснений почти невозможно.

Чек-лист

  • Версия пакета и конфигурация зафиксированы и доступны для сравнения.
  • Есть автоматическая проверка синтаксиса перед перезапуском службы.
  • Журналы ротуются, а диск не заполняется ими за неделю.
  • Изменения проходят через тестовый стенд, а не сразу на рабочий сервер.

Итог

Большинство ошибок с yq лечится не переустановкой, а проверкой конфигурации, логов и прав доступа. Действуйте по одному изменению за раз — и причина быстро найдётся.

Насколько публикация полезна?

Нажмите на звезду, чтобы оценить!

Средняя оценка 0 / 5. Количество оценок: 0

Оценок пока нет. Поставьте оценку первым.

Поделиться: Telegram ВКонтакте