Kubernetes 1.35: Покращене відлагодження за допомогою версійованих API z-pages

Автор: Richa Banker, Han Kang | Перекладач(і): Андрій Головін | 31.12.2025

Відлагодження компонентів панелі управління Kubernetes може бути складним завданням, особливо коли потрібно швидко зрозуміти стан компонента під час виконання або перевірити його конфігурацію. У Kubernetes 1.35 ми вдосконалюємо точки доступу z-pages для відлагодження за допомогою структурованих відповідей, які можна обробляти засобами машинного аналізу, що спрощує створення інструментів та автоматизацію робочих процесів з усунення несправностей.

Що таке z-сторінки?

z-сторінки — це спеціальні точки доступу для відлагодження, які надаються компонентами панелі управління Kubernetes. Введені як альфа-функція в Kubernetes 1.32, ці точки доступу забезпечують діагностику під час виконання для таких компонентів, як kube-apiserver, kube-controller-manager, kube-scheduler, kubelet та kube-proxy. Назва «z-сторінки» походить від домовленості про використання шляхів /*z (додвання останньої літери латинської абетки до шляху) для точок доступу для налагодження.

Наразі Kubernetes підтримує дві основні точки доступу z-page:

/statusz: показує загальну інформацію про компоненти, включаючи інформацію про версію, час запуску, час роботи та доступні шляхи відлагодження
/flagz: показує всі аргументи командного рядка та їхні значення, що використовуються для запуску компонента (з прихованими, з міркувань безпеки, конфіденційними значеннями)

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

Що нового в Kubernetes 1.35?

Kubernetes 1.35 впроваджує структуровані відповіді з версіями для точок доступу /statusz та /flagz. Це вдосконалення зберігає зворотну сумісність з наявним форматом plain text, додаючи підтримку машиночитаних відповідей JSON.

Зворотньо сумісний дизайн

Нові структуровані відповіді є опціональними. Без вказання заголовка Accept точки доступу продовжують повертати звичний текстовий формат:

$ curl --cert /etc/kubernetes/pki/apiserver-kubelet-client.crt \
  --key /etc/kubernetes/pki/apiserver-kubelet-client.key \
  --cacert /etc/kubernetes/pki/ca.crt \
  https://localhost:6443/statusz

kube-apiserver statusz
Warning: This endpoint is not meant to be machine parseable, has no formatting compatibility guarantees and is for debugging purposes only.

Started: Wed Oct 16 21:03:43 UTC 2024
Up: 0 hr 00 min 16 sec
Go version: go1.23.2
Binary version: 1.35.0-alpha.0.1595
Emulation version: 1.35
Paths: /healthz /livez /metrics /readyz /statusz /version

Структуровані відповіді JSON

Щоб отримати структуровану відповідь, додайте відповідний заголовок Accept:

Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Statusz

Це поверне відповідь JSON з версією:

{
  "kind": "Statusz",
  "apiVersion": "config.k8s.io/v1alpha1",
  "metadata": {
    "name": "kube-apiserver"
  },
  "startTime": "2025-10-29T00:30:01Z",
  "uptimeSeconds": 856,
  "goVersion": "go1.23.2",
  "binaryVersion": "1.35.0",
  "emulationVersion": "1.35",
  "paths": [
    "/healthz",
    "/livez",
    "/metrics",
    "/readyz",
    "/statusz",
    "/version"
  ]
}

Аналогічно, /flagz підтримує структуровані відповіді з заголовком:

Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Flagz

Приклад відповіді:

{
  "kind": "Flagz",
  "apiVersion": "config.k8s.io/v1alpha1",
  "metadata": {
    "name": "kube-apiserver"
  },
  "flags": {
    "advertise-address": "192.168.8.4",
    "allow-privileged": "true",
    "authorization-mode": "[Node,RBAC]",
    "enable-priority-and-fairness": "true",
    "profiling": "true"
  }
}

Чому структуровані відповіді мають значення

Додавання структурованих відповідей відкриває кілька нових можливостей:

1. Автоматизовані перевірки стану та моніторинг

Замість аналізу простого тексту, інструменти моніторингу тепер можуть легко отримувати конкретні поля. Наприклад, ви можете програмно перевірити, чи компонент працює з несподіваною емульованою версією, або переконатися, що критичні прапорці встановлені правильно.

2. Кращі інструменти налагодження

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

3. Версії API та стабільність

Запровадивши версії API (починаючи з v1alpha1), ми забезпечуємо чіткий шлях до стабільності. У міру дозрівання функції ми запровадимо v1beta1 і, зрештою, v1, що дасть вам впевненість, що ваші інструменти не перестануть працювати з майбутніми версіями Kubernetes.

Як використовувати структуровані z-сторінки

Необхідні умови

Для обох точок доступу необхідно ввімкнути функціональні можливості:

/statusz: увімкніть функціональну можливість ComponentStatusz
/flagz: увімкніть функціональну можливість ComponentFlagz

Приклад: Отримання структурованих відповідей

Ось приклад використання curl для отримання структурованих відповідей JSON від kube-apiserver:

# Отримання структурованої відповіді statusz
curl \
  --cert /etc/kubernetes/pki/apiserver-kubelet-client.crt \
  --key /etc/kubernetes/pki/apiserver-kubelet-client.key \
  --cacert /etc/kubernetes/pki/ca.crt \
  -H «Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Statusz» \
  https://localhost:6443/statusz | jq .

# Отримання структурованої відповіді flagz
curl \
  --cert /etc/kubernetes/pki/apiserver-kubelet-client.crt \
  --key /etc/kubernetes/pki/apiserver-kubelet-client.key \
  --cacert /etc/kubernetes/pki/ca.crt \
  -H «Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Flagz» \
  https://localhost:6443/flagz | jq .

Примітка:

У наведених вище прикладах використовується автентифікація клієнтського сертифіката та перевіряється сертифікат сервера за допомогою --cacert. Якщо вам потрібно обійти перевірку сертифіката в тестовому середовищі, ви можете використовувати --insecure (або -k), але це ніколи не слід робити в промислових умовах, оскільки це робить вас вразливими до атак типу «зловмисник посередині» (man-in-the-middle).

Важливі зауваження

Статус альфа-функції

Структуровані відповіді z-page є альфа-функцією в Kubernetes 1.35. Це означає:

Формат API може змінитися в майбутніх версіях
Ці точки доступу призначені для відлагодження, а не для промислової автоматизації
Не слід покладатися на них для критично важливих робочих процесів моніторингу, доки вони не досягнуть бета-версії або стабільного статусу

Безпека та контроль доступу

z-сторінки розкривають інформацію про внутрішні компоненти і вимагають належного контролю доступу. Ось основні міркування щодо безпеки:

Авторизація: Доступ до точок доступу z-page обмежений членами групи system:monitoring, яка дотримується тієї ж моделі авторизації, що й для інших точок доступу для налагодження, таких як /healthz, /livez та /readyz. Це гарантує, що доступ до інформації для налагодження мають лише авторизовані користувачі та службові облікові записи. Якщо ваш кластер використовує RBAC, ви можете керувати доступом, надаючи відповідні дозволи цій групі.

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

Розкриття інформації: ці точки доступу розкривають деталі конфігурації компонентів вашого кластера, зокрема:

версії компонентів та інформацію про збірку
усі аргументи командного рядка та їхні значення (з видаленням конфіденційних значень)
доступні точки доступу для налагодження

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

Майбутня еволюція

У міру дозрівання функції ми (Kubernetes SIG Instrumentation) сподіваємося:

Впровадити версії API v1beta1 і, зрештою, v1.
Зібрати відгуки спільноти щодо схеми відповідей.
Можливо, додати додаткові точки доступу z-page на основі потреб користувачів.

Спробуйте

Ми заохочуємо вас експериментувати зі структурованими z-сторінками в тестовому середовищі:

Увімкніть функції ComponentStatusz та ComponentFlagz на компонентах вашої панелі управління.
Спробуйте надсилати запити до точок доступу як у вигляді простого тексту, так і у структурованому форматі.
Створіть простий інструмент або скрипт, який використовує структуровані дані.
Поділіться своїми відгуками зі спільнотою.

Дізнайтеся більше

Документація z-pages
KEP-4827: Статус компонента
KEP-4828: Компонент Flagz
Приєднуйтесь до обговорення в каналі #sig-instrumentation в Kubernetes Slack

Приєднуйтесь

Ми будемо раді отримати ваші відгуки! Функція структурованих z-сторінок призначена для спрощення відлагодження та моніторингу Kubernetes. Незалежно від того, чи ви створюєте внутрішні інструменти, берете участь в проєктах з відкритим кодом або просто вивчаєте цю функцію, ваші відгуки допоможуть сформувати майбутнє спостережуваності Kubernetes.

Якщо у вас є питання, пропозиції або ви зіткнулися з проблемами, звертайтеся до SIG Instrumentation. Ви можете знайти нас у Slack або на наших регулярних зустрічах спільноти.

Успішного відлагодження!