От YAML до JSON: конвертируем конфиги, не теряя рассудка

Что на самом деле делает преобразование YAML в JSON

YAML и JSON описывают одни и те же фигуры — карты, списки, строки, числа, логические значения и ноль — поэтому преобразование в основном сводится к повторной сериализации одного синтаксиса в другой. Что меняется, так это поверхность: отступы становятся фигурными скобками, комментарии исчезают, привязки становятся копиями, а многострочные строки сворачиваются в escape-символы `\n`. Каждое из этих преобразований в некотором смысле имеет потери, поэтому шаг преобразования стоит делать сознательно, а не рассматривать его как второстепенную мысль о форматировании.

Практическая причина преобразования заключается в том, что JSON — это то, что нужно следующему инструменту. Kubernetes принимает YAML, но `kubectl`, конвейеры jq, вызовы API и JavaScript более комфортно говорят на JSON. Однократное правильное преобразование лучше, чем параллельное редактирование двух форматов вручную.

Несколько документов YAML: проблема молчаливого первого документа

Файл YAML может содержать несколько документов, разделенных `---`. Большинство преобразователей спокойно возвращают первый и выбрасывают остальные — поэтому пакет манифеста с развертыванием, службой и ConfigMap становится одним объектом без предупреждения. Правильное преобразование либо выдает массив документов, либо явно спрашивает, какой из них вам нужен. Если преобразователь не обеспечивает такого контроля, он теряет данные.

Ошибки должны указывать на строку и столбец.

Толерантность YAML к пробелам – именно поэтому небольшие ошибки трудно найти. Табуляция недопустима для отступов, отсутствие двоеточия превращает сопоставление в строку, а повторяющиеся ключи принимаются одними анализаторами и отклоняются другими. Если преобразование завершается неудачей, единственное полезное сообщение называет строку и столбец и показывает оскорбительный отрывок:

                spec:
  containers:
	- name: web      # tab used for indentation
error: line 3, column 0 — tabs cannot be used for indentation
              

Дубликаты ключей представляют собой опасный случай: анализаторы YAML обычно сохраняют последнее значение и ничего не сообщают. Если `replicas: 3` появляется дважды, полученное вами JSON выглядит совершенно правильным — и это неправильное число.

Цитирование правил, которые выдержат поездку

JSON более строго относится к строкам, чем YAML, поэтому при преобразовании добавляются кавычки вокруг пустых значений. Это нормально, но две особенности YAML вызывают реальные ошибки: `yes`, `no`, `on` и `off` являются логическими значениями в YAML 1.1, но строки в семантике JSON и значения с начальным нулем, такие как почтовые индексы и номера телефонов, теряют свой нуль, если рассматривать их как числа. Если поле должно оставаться строкой во время преобразования, заключите его в кавычки в источнике.

Запускайте его локально, особенно для конфигураций кластера.

Манифесты Kubernetes обычно содержат учетные данные в объектах `Secret`, строки подключения в ConfigMaps и токены в файлах CI. Вставка их в веб-сервис передает их на сервер, который вы не контролируете. Конвертер на основе браузера выполняет анализ и сериализацию на той же вкладке, которую вы читаете, поэтому ничего не передается, а страница, которая продолжает работать с отключенной сетью, является доказательством этого, а не обещанием.

Разумный рабочий процесс

1. Сначала проверьте YAML и исправьте все строки, столбцы и отрывки, о которых сообщается.
2. Выберите, как следует обрабатывать файлы, состоящие из нескольких документов: массив или конкретный документ.
3. Преобразуйте с отступом, соответствующим стилю вашей кодовой базы (2 или 4 пробела), и отсортируйте ключи, если вы различаете выходные данные.
4. Сохраняйте YAML как источник истины в git и рассматривайте JSON как сгенерированный артефакт; комментарии живут только в YAML.