Коротко о главном
YAML широко используется в Kubernetes, CI, Ansible и конфигурациях приложений. yq даёт предсказуемый способ выбрать поле, изменить значение и проверить результат. В статье разберём синтаксис mikefarah yq версии 4, преобразование форматов и работу с несколькими документами. Примеры подходят для разработчиков и администраторов, которые автоматизируют работу с конфигурациями.
Ручная правка YAML легко приводит к ошибкам отступов и типов. yq сохраняет структуру и позволяет менять только нужный ключ. Его удобно использовать в скриптах и проверках перед применением манифеста. В результате конфигурации становятся воспроизводимыми и удобными для ревью.
yq выглядит простым снаружи, но именно детали определяют поведение под нагрузкой. Посмотрим на внутреннее устройство и тонкие настройки.
Как это устроено
yq состоит из нескольких взаимодействующих частей: конфигурации, рабочего процесса и данных, с которыми он работает. Понимание этой схемы помогает предсказывать поведение системы и быстрее находить причину сбоя.
Ручная правка YAML легко приводит к ошибкам отступов и типов. 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
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.
Типичные ошибки
Ниже — сбои, которые встречаются чаще всего. Перед исправлением сохраните текущие конфиги и запишите, какие изменения вносите: так проще откатиться.
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. Табуляция недопустима, а вложенные ключи должны иметь согласованный сдвиг.
Что улучшить после базовой настройки
Когда yq работает предсказуемо, следующий шаг — наблюдаемость. Добавьте проверку состояния, которая отвечает на вопрос «жив ли сервис», и метрику, показывающую нагрузку. Без этого вы узнаёте о проблеме от пользователей, а не от системы.
Второе направление — воспроизводимость. Опишите установку и конфигурацию так, чтобы их можно было повторить на чистой машине: список пакетов, файлы настроек, порядок команд. Это одновременно документация, план восстановления и основа для автоматизации.
Не оптимизируйте то, что не измеряли. Сначала соберите базовые показатели, затем меняйте один параметр и сравнивайте результат. Иначе легко получить конфигурацию, которая выглядит сложнее, но работает не быстрее.
Итог
Понимание внутреннего устройства yq экономит часы диагностики. Когда знаете, где хранится состояние и как компоненты общаются, ошибка перестаёт быть «магией».