YAML — конфигурационный формат: полный гид

Введение

YAML (YAML Ain't Markup Language) — человекочитаемый формат сериализации данных, ставший де-факто стандартом для конфигурационных файлов в современной инфраструктуре. Его используют Docker, Kubernetes, Ansible, GitHub Actions, GitLab CI, CloudFormation и тысячи других инструментов. Если JSON оптимизирован для машин, то YAML создан для людей: минимум синтаксического шума, отступы вместо скобок, поддержка комментариев. В этом полном гиде разберём синтаксис YAML, типы данных, частые ошибки и сравнение с JSON.

Что такое YAML

YAML появился в 2001 году как расширение более раннего формата SML. Изначально аббревиатура расшифровывалась как «Yet Another Markup Language», но потом создатели переопределили её как рекурсивную — «YAML Ain't Markup Language», подчеркнув, что формат ориентирован на данные, а не на разметку документов.

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

# Конфигурация приложения
app:
  name: ConvertHub
  version: 2.4.1
  debug: false

database:
  host: localhost
  port: 5432
  name: converthub_prod
  pool: 20

features:
  - auth
  - billing
  - analytics

servers:
  - name: web-1
    ip: 10.0.0.1
  - name: web-2
    ip: 10.0.0.2

Синтаксис YAML

Отступы

В YAML иерархия задаётся исключительно отступами — обычно пробелами (табуляция запрещена). Каждый уровень вложенности — это дополнительные два пробела. Несоответствие отступов — самая частая ошибка в YAML-файлах. Чтобы её избежать, используйте редактор с подсветкой отступов и не смешивайте ширину (2 и 4 пробела в одном файле).

Ключи и значения

Пара «ключ-значение» записывается как ключ: значение. После двоеточия обязательно нужен пробел. Строковые значения в большинстве случаев можно не заключать в кавычки, но если строка содержит специальные символы (: ,#, начинает с цифры или выглядит как булево значение), кавычки обязательны.

title: Введение в YAML      # строка без кавычек
subtitle: "YAML: полный гид"  # кавычки нужны из-за двоеточия
year: '2025'                  # строка, а не число
note: 'true'                  # строка "true", а не булево
empty: ""                     # пустая строка

Списки

Списки создаются через дефис с пробелом:

languages:
  - Python
  - JavaScript
  - Go

# Альтернативная inline-запись
languages: [Python, JavaScript, Go]

Словари

Вложенные объекты (mapping) задаются отступами или в flow-стиле:

metadata:
  author: ConvertHub
  license: MIT

# Inline
metadata: {author: ConvertHub, license: MIT}

Типы данных

YAML поддерживает богатый набор типов, и это одновременно сильная и слабая сторона формата. Без явного указания типа парсер пытается «угадать» тип по значению.

Особенность YAML: yes, no, on, offавтоматически становятся булевыми значениями. Это приводит к известным багам — например, двухбуквенный код страны NO (Норвегия) превращается в false. Чтобы избежать сюрпризов, строки с подобными значениями всегда берите в кавычки.

Многострочные строки

YAML умеет работать с многострочным текстом двумя способами. | (literal) сохраняет переносы строк, > (folded) заменяет переносы на пробелы — удобно для длинных абзацев.

description: |
  Это первая строка.
  Это вторая строка.
  Переносы сохраняются.

summary: >
  Это длинный абзац,
  который при парсинге
  станет одной строкой.

Якоря и ссылки

В YAML есть механизм «якорей» (&) и «алиасов» (*), позволяющий переиспользовать фрагменты данных. Это аналог переменных в конфигурационных файлах.

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  timeout: 60   # переопределение

staging:
  <<: *defaults

Оператор << (merge keys) «встраивает» содержимое якоря в текущий объект. Это удобно, но усложняет чтение и не все парсеры поддерживают его одинаково.

YAML в Docker и Kubernetes

Docker Compose был одним из первых инструментов, популяризовавших YAML в инфраструктуре. Файл docker-compose.yml описывает сервисы, сети и тома. Kubernetes расширил эту практику: все манифесты K8s — Deployment, Service, ConfigMap, Secret — пишутся на YAML.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: converthub/api:2.4.1
          ports:
            - containerPort: 8080

В CI/CD системах GitHub Actions и GitLab CI YAML описывает пайплайны: шаги, условия, окружения. Это объясняет, почему YAML столь популярен у DevOps-инженеров.

YAML vs JSON

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

Безопасность YAML

В старых версиях спецификации YAML поддерживал теги, позволяющие инстанцировать произвольные объекты при парсинге. Это приводило к уязвимостям удалённого выполнения кода. Современные парсеры (PyYAML 5+, js-yaml 4+) по умолчанию запрещают такое поведение и требуют явного yaml.unsafe_load или yaml.load_allс указанием загрузчика. Никогда не используйте небезопасные загрузчики для данных из недоверенных источников.

Конвертация YAML и JSON

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

Лучшие практики

• Используйте 2 пробела для отступов — это стандарт в большинстве инструментов.
• Никогда не смешивайте табы и пробелы в одном файле.
• Берите в кавычки строки, похожие на числа, даты или булевы значения.
• Комментируйте нетривиальные значения — комментарии в YAML допустимы и полезны.
• Не злоупотребляйте якорями: они затрудняют чтение новых разработчиками.
• Валидируйте YAML в CI перед деплоем — опечатка в отступе сломает манифест.

YAML в CI/CD системах

Современные CI/CD-системы — GitHub Actions, GitLab CI, CircleCI, Travis CI — описывают пайплайны на YAML. Это объясняется человекочитаемостью формата: разработчик должен понимать и редактировать конфигурацию пайплайна без дополнительных инструментов. Однако YAML-файлы для сложных пайплайнов могут разрастаться до сотен строк, и без правильной структуры превратятся в нечитаемое месиво.

Лучшие практики для CI/CD YAML: группируйте задания по логическим блокам с комментариями-заголовками; используйте якоря для повторяющихся шагов (например, стандартный setup-шаг с установкой зависимостей); выносите секреты в переменные окружения, а не храните в файле; тестируйте YAML локально черезactionlint (для GitHub Actions) или gitlab-ci-lint.

# Повторно используемый шаблон
.setup: &setup
  image: node:20
  before_script:
    - npm ci

test:
  <<: *setup
  script:
    - npm test

build:
  <<: *setup
  script:
    - npm run build

YAML и ансибл

Ansible использует YAML для описания плейбуков — декларативных сценариев конфигурации серверов. Файлы плейбуков содержат списки задач (tasks), каждая из которых вызывает модуль Ansible с параметрами. Например, задача установки Nginx:

- name: Установить Nginx
  apt:
    name: nginx
    state: present
    update_cache: yes

- name: Запустить Nginx
  service:
    name: nginx
    state: started
    enabled: yes

Ansible добавляет поверх YAML свой слой: шаблоны Jinja2 для подстановки переменных, обработчики (handlers), роли (roles). Это делает YAML мощным DSL для DevOps, но требует понимания обеих составляющих — синтаксиса YAML и расширений Ansible.

Частые ошибки в YAML

• Табуляция вместо пробелов — YAML запрещает табы для отступов. Редактор должен быть настроен на пробелы.
• Пробел после двоеточия — key:value не валидно, нужно key: value.
• Магические строки — yes, no,on, off превращаются в булевы значения. Берите в кавычки, если нужна строка.
• Двусмысленные числа — 3.10 парсится как число 3.1, а не как версия. Используйте кавычки для версий.
• Коды стран — NO (Норвегия) становитсяfalse, RU остаётся строкой. Берите в кавычки.
• Смешивание отступов — если в одной части файла 2 пробела, а в другой 4, парсер выдаст непредсказуемый результат.

YAML в облаках

Все основные облачные провайдеры используют YAML для описания инфраструктуры как кода. AWS CloudFormation, Azure Resource Manager (в YAML-варианте), Google Cloud Deployment Manager, Terraform (HCL — отдельный язык, но похожий по философии) — везде YAML или его аналог. Это позволяет версионировать инфраструктуру в Git и применять практики CI/CD к развёртыванию.

Helm — пакетный менеджер Kubernetes — использует YAML для шаблонов с встроенным шаблонизатором Go. Шаблоны генерируют манифесты K8s из параметров, что позволяет создавать переиспользуемые чарты для типовых приложений. Хелм добавляет свой слой абстракции над YAML, что усложняет обучение, но резко повышает переиспользование.

Заключение

YAML — мощный и удобный формат для конфигураций, который стал стандартом в DevOps и инфраструктурном коде. Его сильные стороны — человекочитаемость, поддержка комментариев и богатая типизация. Слабые — чувствительность к отступам и риск неоднозначной интерпретации значений. Если вы только знакомитесь с YAML, начните с простых конфигов и постепенно осваивайте продвинутые возможности. Для быстрой конвертации между YAML и JSON используйте онлайн-инструменты ConvertHub, а для глубокого сравнения с другими форматами прочитайте статью«Сравнение форматов данных».