YAML вже багато років є стандартним способом написання маніфестів Kubernetes. Кожен приклад, посібник чи конфігураційний файл, який вам траплявся, написаний саме в цьому форматі. Проблема не в тому, що YAML — поганий формат. Проблема в тому, що YAML дає багато варіантів вибору, і не всі вони однаково хороші для написання маніфестів Kubernetes. Деякі можливості ускладнюють читання файлів, деякі легко використати неправильно, а деякі можуть призводити до несподіваної поведінки.
Цікаво те, що Kubernetes насправді не потребує більшості цих можливостей. Він використовує лише невелику підмножину YAML. Це навело на просте запитання: якщо Kubernetes потребує лише невелику частину YAML, чому б не стандартизувати саме цю частину й не уникати решти? Замість того щоб вигадувати нову мову конфігурації, SIG CLI представила KYAML — суворіший і послідовніший спосіб запису YAML.
KYAML — це строга підмножина (або «діалект») стандартного YAML, розроблена таким чином, щоб її можна було аналізувати в наявній екосистемі без будь-яких змін, як запропоновано в KEP 5295. Він не вводить новий формат чи новий парсер. Він лише звужує кількість варіантів, які ви обираєте під час написання YAML, тож усі зрештою обирають ті самі варіанти.
Уявляйте це не як нову мову, а швидше як узгоджений стиль. Усе, що є валідним у KYAML, є валідним YAML.
У стандартного YAML є кілька добре відомих пасток, і JSON також не позбавлений своїх.
Чутливість до пробілів. Відступи визначають структуру в YAML, а це означає, що файл з неправильними відступами може залишатися синтаксично валідним, представляючи при цьому зовсім інший обʼєкт, ніж було задумано. Це особливо болісно з інструментами шаблонізації на кшталт Helm, де ви маніпулюєте відступами ззовні контексту YAML.
Неявне приведення типів. Лапки для рядків у YAML необовʼязкові, що звучить зручно, доки не стає проблемою. Деякі значення, які виглядають як рядки, неявно перетворюються на інші типи без жодного попередження. Класичний приклад — "Norway Bug".
country: NO
У стандартному YAML NO перетворюється як булеве значення false, а не як рядок "NO", і це вже не раз заскочувало людей зненацька.
JSON теж не є відповіддю. У ньому немає підтримки коментарів, він суворо забороняє кінцеві коми та вимагає лапок для кожного ключа — усе це не робить його зручним для написання конфігурацій.
KYAML вирішує всі ці проблеми, роблячи структуру та типи явними:
{} для мап і структур[] для списків---, щоб відрізнити його від JSON з першого погляду, оскільки обидва починаються з {У YAML це називається flow-стиль, на відміну від звичного блокового стилю, яким користується більшість. KYAML розташовується десь між JSON і YAML: більш явний, ніж стандартний YAML, і дружніший, ніж JSON.
Ось той самий маніфест Pod, написаний в обох форматах для порівняння.
apiVersion: v1
kind: Pod
metadata:
name: my-pod
labels:
app: demo
spec:
containers:
- name: nginx
image: nginx:1.20
---
{
apiVersion: "v1",
kind: "Pod",
metadata: {
name: "my-pod",
labels: {
app: "demo",
},
},
spec: {
containers: [{
name: "nginx",
image: "nginx:1.20",
}],
},
}
Зверніть увагу на рядкові значення в подвійних лапках, фігурні дужки навколо кожної мапи, квадратні дужки навколо списку та кінцеві коми. Додатковий синтаксис робить структуру документа явною, а не залежною від відступів.
Існує кілька способів отримати вивід у форматі KYAML.
Починаючи з Kubernetes 1.34, kubectl підтримує KYAML як нативний формат виводу.
# Kubernetes 1.35+ (beta; функція зазвичай увімкнена, але все ще потребує параметра CLI -o kyaml)
kubectl get deployment my-app -o kyaml
# Kubernetes 1.34 (alpha, опційно)
export KUBECTL_KYAML=true
kubectl get deployment my-app -o kyaml
Щоб зберегти вивід у файл:
kubectl get deployment my-app -o kyaml > my-app.yaml
Наразі немає планів робити KYAML стандартним форматом виводу. Якщо ви хочете використовувати KYAML як стандартний формат, ви можете налаштувати бажані параметри через kuberc. Детальніше дивіться в документації kuberc.
# Kubernetes 1.36+
kubectl kuberc set --section defaults --command get --option output=kyaml
# Kubernetes 1.33–1.35 (все ще потрібен префікс alpha)
kubectl alpha kuberc set --section defaults --command get --option output=kyaml
sigs.k8s.io/yaml постачає інструмент yamlfmt, який може конвертувати файли у KYAML.
Встановіть через Go:
go install sigs.k8s.io/yaml/yamlfmt@latest
Запуск інструмента проти файлу виводить KYAML-версію у stdout. Він також приймає теку, і в такому разі конвертує та виводить кожен файл у цій теці. Тож вам доведеться перенаправити вивід у файл (або файли), якщо ви хочете, щоб конвертація збереглася.
yamlfmt -o=kyaml my-deployment.yaml
Він також може показати вам diff замість повної конвертації:
yamlfmt -o=kyaml -d my-deployment.yaml
Для конвертації наявних файлів у yamlfmt від Google зʼявився спеціальний форматувальник kyaml у версії v0.21.0.
Встановіть через Go або завантажте бінарник зі сторінки релізів:
go install github.com/google/yamlfmt/cmd/yamlfmt@latest
Він також доступний як pre-commit хук та як Docker-образ для CI-конвеєрів.
Додайте конфігурацію .yamlfmt у корінь вашого проєкту:
formatter:
type: kyaml
Перегляньте результат без зміни файлу:
yamlfmt -dry my-deployment.yaml
а потім застосуйте:
yamlfmt my-deployment.yaml
Щоб конвертувати всю теку:
yamlfmt ./k8s/
Форматувальник kyaml не потребує додаткової конфігурації і не має спільних опцій зі стандартним форматувальником, тож їх змішування призведе до помилки.
Детальніше про доступні режими та прапорці дивіться в документації з використання команд.
Кожен валідний файл KYAML є водночас валідним файлом YAML. Тож що б ви не написали в KYAML, ваші наявні інструменти, ваш kubectl, ваші CI-конвеєри — жодному з них не потрібно змінюватися. Ви навіть можете передати KYAML як вхідні дані для будь-якої версії kubectl, а не лише 1.34+, тому що зрештою це просто YAML.
KYAML не є суворо обовʼязковим. Ви можете й далі писати YAML у блоковому стилі, і все працюватиме. Але це свідомий вибір зробити ваші конфігурації менш схильними до помилок і більш послідовними, особливо в команді чи великому репозиторії.
Це більше не міграція, а радше краща звичка.