KYAML для Kubernetes: як зменшити неоднозначність маніфестів без поспішної міграції

Навіщо читати цю новину

Kubernetes підтримує бажаний стан контейнерних застосунків на групі машин. Якщо контейнер, Pod, вузол або кластер поки незнайомі, спочатку прочитайте «Що таке Kubernetes: де він потрібен і коли краще обрати простіше». Тут розглянуто вужчу тему — спосіб запису маніфестів Kubernetes.

У маніфесті команда описує, який об’єкт має існувати та як його налаштувати. Такі файли часто пишуть у YAML. У ньому відступи визначають вкладеність, а парсер може сприйняти значення без лапок як число або логічне значення. Через це файл іноді виглядає правильним для людини, хоча програма читає іншу структуру.

KYAML звужує набір дозволених способів запису й залишається валідним YAML. Він робить структуру та рядкові значення явнішими, але не змінює роботу кластера й не виправляє помилкову конфігурацію.

Виведення kubectl -o kyaml з’явилося як alpha у Kubernetes 1.34 і стало beta у 1.35. Офіційний допис підтверджує beta-етап від версії 1.35. KYAML однаково треба явно вибирати через -o kyaml: він не стає типовим форматом і не зобов’язує команди перетворювати наявні маніфести.

Як програма читає маніфест

Ресурс Kubernetes — це об’єкт, яким керує система. У наскрізному прикладі використано ConfigMap: ресурс для неконфіденційних конфігураційних значень. Його поле data містить пари, значення яких мають бути текстовими рядками.

apiVersion: v1
kind: ConfigMap
metadata:
  name: demo-settings
data:
  FEATURE_ENABLED: "true"
  RETRY_LIMIT: "3"

Поля означають таке:

• apiVersion: v1 указує версію Kubernetes API, у якій визначено цей тип ресурсу;
• kind: ConfigMap називає тип ресурсу;
• metadata.name задає ім’я demo-settings;
• data містить два конфігураційні значення.

Спочатку YAML-парсер перетворює текст на загальну структуру даних. Потім Kubernetes перевіряє її за схемою ресурсу: чи відомі поля та чи мають значення дозволені типи.

Тип даних визначає, чи є значення рядком, числом, логічним значенням, списком або об’єктом. Лапки показують, що true і 3 тут є рядками. Без лапок парсер може прочитати їх як логічне значення та число. Точна поведінка залежить від версії YAML і конкретного парсера.

Відступи теж несуть зміст. Якщо посунути RETRY_LIMIT ліворуч, ключ може вийти з data й опинитися на іншому рівні. Інший зсув може зробити файл синтаксично неправильним. Лінтер знаходить частину синтаксичних і стильових проблем, але не може сам визначити задум автора.

Той самий об’єкт у KYAML і JSON

KYAML використовує flow style. Межі структур із парами «ключ — значення» позначено {}, а межі списків — []. Рядкові значення беруть у подвійні лапки. Офіційний запис також має початковий маркер документа --- і кінцеві коми.

---
{
  apiVersion: "v1",
  kind: "ConfigMap",
  metadata: {
    name: "demo-settings",
  },
  data: {
    # Ці значення мають залишитися рядками.
    FEATURE_ENABLED: "true",
    RETRY_LIMIT: "3",
  },
}

Це валідний YAML, а не окрема мова. Його може прочитати звичайний YAML-парсер; окремий KYAML-парсер не потрібен.

JSON також використовує явні дужки й лапки, але в ньому треба брати в лапки й ключі. Стандартний JSON не дозволяє коментарі або кінцеві коми.

{
  "apiVersion": "v1",
  "kind": "ConfigMap",
  "metadata": {
    "name": "demo-settings"
  },
  "data": {
    "FEATURE_ENABLED": "true",
    "RETRY_LIMIT": "3"
  }
}

Практична різниця така:

• YAML зазвичай коротший і підтримує коментарі, але структура залежить від відступів, а типи значень без лапок можуть бути неочевидними.
• KYAML зберігає коментарі та сумісність із YAML, проте явно позначає структури й рядки. Ціна — довший і менш звичний запис.
• JSON теж явно позначає структуру та широко підтримується інструментами, але не дозволяє коментарі й кінцеві коми.

Коментар у написаному вручну KYAML не входить до структури даних. Якщо отримати об’єкт із кластера через kubectl get, коментарі з початкового маніфесту не відновляться: Kubernetes API їх не зберігає.

Що відомо про статус KYAML

KYAML розвивається в межах KEP 5295. KEP, або Kubernetes Enhancement Proposal, описує мотивацію, межі й технічний дизайн зміни.

У kubectl 1.34 можливість була alpha й потребувала окремого ввімкнення. У 1.35 вона перейшла в beta та стала ввімкненою за замовчуванням, хоча формат виведення однаково треба вибирати параметром -o kyaml.

Станом на 15 серпня 2026 року офіційний список релізів називає 1.36 останньою випущеною minor-версією, а 1.37 — upcoming. Водночас KEP уже має позначки STABLE, Implemented і Latest v1.37. Вони описують реалізацію та цільовий milestone майбутнього релізу, але не доводять, що 1.37 вже доступна користувачам. Тому стаття називає beta підтвердженим етапом від 1.35, а stable — запланованим станом для 1.37.

Майбутня стабілізація не зробить формат обов’язковим автоматично. Звичайний kubectl get не починає друкувати KYAML, і KEP не вимагає міграції проєктів. Формат треба вибрати явно. Наприклад, на окремому тестовому кластері з відповідною версією клієнта синтаксис має такий вигляд:

kubectl get deployment my-app -o kyaml

Ця команда не є частиною локального уроку нижче: вона звертається до кластера. Для першого знайомства достатньо порівняти синтаксис на одноразовій локальній копії. Перед використанням у репозиторії окремо перевірте фактичні редактори, форматери, лінтери та CI.

KYAML не виправляє неправильну назву поля, неприпустиме значення чи хибну логіку конфігурації. Синтаксично валідний файл може не відповідати схемі Kubernetes. Відповідність схемі також не доводить, що конфігурація реалізує задум автора.

Один локальний експеримент з агентом

Створіть нову одноразову порожню теку й збережіть у ній перший синтетичний приклад як demo-settings.yaml. Не використовуйте робочий репозиторій, справжній маніфест або приватні дані. Для цього кроку не потрібні kubectl, кластер, мережа чи облікові дані.

Запит агенту:

У вказаній мною новій порожній теці є лише синтетичний demo-settings.yaml із
цієї статті. Прочитай тільки його. Не змінюй оригінал. Створи поруч лише
demo-settings.kyaml з тією самою структурою та notes.md із поясненням змін.
Не запускай команд, не читай інші теки, не використовуй мережу, Git, kubectl,
kubeconfig чи секрети. Покажи повний diff. Зупинися, якщо шлях неоднозначний,
тека не порожня, дані не синтетичні або потрібна додаткова програма.

Очікуваний результат: новий файл починається з ---, структури записано у flow style з {}, рядкові значення взято в лапки, а елементи мають кінцеві коми. apiVersion, kind, metadata.name і дві пари в data мають залишитися незмінними.

Незалежна перевірка: не вважайте фразу агента «структури однакові» доказом. Самостійно зіставте всі ключі та значення з оригіналом. Якщо на комп’ютері вже є довірений YAML-парсер, окремо порівняйте нормалізовані структури. Не встановлюйте програму лише заради цього уроку. Якщо дані змінилися, з’явився третій файл або знадобився доступ поза текою, експеримент не пройдено.

Чи варто використовувати KYAML

У навчальному файлі KYAML допомагає побачити межі об’єктів і рядкові значення. У новому репозиторії його можна випробувати на одному маніфесті після перевірки редактора, форматера, лінтера, парсера, версії kubectl і CI.

У наявній кодовій базі спершу з’ясуйте, чи команда справді стикається з помилками відступів або неоднозначними типами. Якщо звичайний YAML уже має узгоджений стиль і надійні перевірки, масове перетворення створить великий diff без гарантованої користі.

Висновок простий: локальний експеримент на копії виправданий, термінова міграція — ні. KYAML робить структуру й рядки помітнішими, але не замінює схеми, тести та перевірку людиною. Рішення слід приймати лише після перевірки фактичних інструментів команди. Якщо сама роль платформи ще неясна, поверніться до базового пояснення Kubernetes, а вже потім оцінюйте формат маніфесту.

Джерела

• Kubernetes Blog: How to Pretty-Print Your Kubernetes YAML as KYAML and Why You’d Want To
• Kubernetes Enhancement Proposal 5295
• Kubernetes: Releases