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

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

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

Нужно быстро начать работать с yq? Вот короткий маршрут: установка, минимальная настройка и проверка результата. Длинную теорию оставим для отдельных материалов.

Установка

В 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

Шпаргалка по командам

  • Проверьте версию и синтаксис: yq —version
  • Прочитайте значение из YAML: yq ‘.services.web.image’ compose.yaml
  • Измените значение на месте: yq -i ‘.services.web.ports = [«8080:80»]’ compose.yaml
  • Преобразуйте YAML в JSON и обратно: yq -o=json ‘.’ config.yaml > config.json
  • Обработайте несколько документов: 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, а не конкатенацию в выражении.

Что дальше

Быстрый старт не означает «настроить навсегда». Когда базовый сценарий заработает, вернитесь к конфигурации и проверьте, что она переживёт перезагрузку: файлы на месте, служба включена в автозагрузку, путь к данным не зависит от текущего каталога.

Дальше имеет смысл разобраться с резервной копией и журналами yq. Это не самая заметная часть работы, но именно она превращает эксперимент в инструмент, которым можно пользоваться каждый день.

Чек-лист

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

Короткие ответы на частые вопросы

Нужно ли запускать всё от root?

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

Что делать, если после перезагрузки ничего не работает?

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

Как обновлять без сюрпризов?

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

Рабочие сценарии

Начните со справки: у yq обычно есть страница man и примеры в описании. Затем повторите типичные операции на тестовых данных, а не на рабочих файлах.

man yq 2>/dev/null | head -40
yq --help 2>&1 | tail -30
# подготовить тестовые данные
mkdir -p /tmp/yq-test && cd /tmp/yq-test
printf 'alpha\nbeta\ngamma\n' > sample.txt

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

Итог

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

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

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

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

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

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