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

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

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

yq — инструмент, который стоит освоить, если вы регулярно работаете в Linux. Ниже — путь от установки до уверенной повседневной работы: без предположений, что всё уже настроено само.

Зачем нужен yq

yq решает вполне конкретные задачи: yq — редактор и язык запросов для YAML, JSON и других структурированных форматов. Он позволяет читать и менять манифесты без ручного редактирования отступов. Важно не превращать инструмент в самоцель — если задача проще решается штатными средствами системы, начните с них.

Установка

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

sudo apt install yq

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

sudo dnf install yq

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

sudo pacman -S yq

Пошаговая настройка

После установки переходите к базовому сценарию. Команды ниже выполняйте от пользователя с достаточными правами, но не запускайте всё под root без необходимости.

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

5. Обработайте несколько документов

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

yq '.kind + "/" + .metadata.name' manifests.yaml

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

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

Совет 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, а не конкатенацию в выражении.

Совет 5. Флаг -o=json удобен для последующей обработки через jq, а -o=yaml возв

Флаг -o=json удобен для последующей обработки через jq, а -o=yaml возвращает читаемый YAML.

Практический сценарий

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

Дальше действуйте короткими шагами: установка, минимальная конфигурация, проверка, затем расширение. После каждого шага фиксируйте, что именно изменилось и как это проверить. Такой журнал экономит время, когда через месяц понадобится повторить настройку на другом сервере или объяснить её коллеге.

Порядок работ для этого сценария выглядит так:

  1. Проверьте версию и синтаксис
  2. Прочитайте значение из YAML
  3. Измените значение на месте
  4. Преобразуйте YAML в JSON и обратно
  5. Обработайте несколько документов

Отдельно продумайте, что произойдёт при сбое. Для 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 перед коммитом и храните важные пояснения в документации.

Что проверить перед вводом в работу

Перед тем как считать настройку завершённой, пройдитесь по короткому списку. Он не заменяет полноценный аудит, но отсекает большинство очевидных проблем.

Чек-лист

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

Если какой-то пункт вызывает затруднение, это сигнал вернуться к соответствующему разделу, а не откладывать проверку. Настройка, которую нельзя повторить, плохо работает не только у коллег, но и у вас самих через полгода.

Итог

yq — это не «поставил и забыл». Рабочая конфигурация складывается из понимания задачи, аккуратной установки и проверки результата. Начните с базового сценария, затем добавляйте только те возможности, которые действительно используете.

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

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

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

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

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