Відлагодження компонентів панелі управління Kubernetes може бути складним завданням, особливо коли потрібно швидко зрозуміти стан компонента під час виконання або перевірити його конфігурацію. У Kubernetes 1.35 ми вдосконалюємо точки доступу z-pages для відлагодження за допомогою структурованих відповідей, які можна обробляти засобами машинного аналізу, що спрощує створення інструментів та автоматизацію робочих процесів з усунення несправностей.
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 впроваджує структуровані відповіді з версіями для точок доступу /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
Щоб отримати структуровану відповідь, додайте відповідний заголовок 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"
}
}
Додавання структурованих відповідей відкриває кілька нових можливостей:
Замість аналізу простого тексту, інструменти моніторингу тепер можуть легко отримувати конкретні поля. Наприклад, ви можете програмно перевірити, чи компонент працює з несподіваною емульованою версією, або переконатися, що критичні прапорці встановлені правильно.
Розробники можуть створювати складні інструменти налагодження, які порівнюють конфігурації декількох компонентів або відстежують зміни конфігурації з часом. Структурований формат спрощує порівняння конфігурацій або перевірку того, чи компоненти працюють з очікуваними налаштуваннями.
Запровадивши версії API (починаючи з v1alpha1), ми забезпечуємо чіткий шлях до стабільності. У міру дозрівання функції ми запровадимо v1beta1 і, зрештою, v1, що дасть вам впевненість, що ваші інструменти не перестануть працювати з майбутніми версіями Kubernetes.
Для обох точок доступу необхідно ввімкнути функціональні можливості:
/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. Це означає:
z-сторінки розкривають інформацію про внутрішні компоненти і вимагають належного контролю доступу. Ось основні міркування щодо безпеки:
Авторизація: Доступ до точок доступу z-page обмежений членами групи system:monitoring, яка дотримується тієї ж моделі авторизації, що й для інших точок доступу для налагодження, таких як /healthz, /livez та /readyz. Це гарантує, що доступ до інформації для налагодження мають лише авторизовані користувачі та службові облікові записи. Якщо ваш кластер використовує RBAC, ви можете керувати доступом, надаючи відповідні дозволи цій групі.
Автентифікація: Вимоги до автентифікації для цих точок доступу залежать від конфігурації вашого кластера. Якщо для вашого кластера не ввімкнено анонімну автентифікацію, зазвичай для доступу до цих точок доступу потрібно використовувати механізми автентифікації (наприклад, сертифікати клієнта).
Розкриття інформації: ці точки доступу розкривають деталі конфігурації компонентів вашого кластера, зокрема:
Надавайте доступ лише надійним операторам та інструментам налагодження. Уникайте розкриття цих точок доступу неавторизованим користувачам або автоматизованим системам, які не потребують такого рівня доступу.
У міру дозрівання функції ми (Kubernetes SIG Instrumentation) сподіваємося:
v1beta1 і, зрештою, v1.Ми заохочуємо вас експериментувати зі структурованими z-сторінками в тестовому середовищі:
ComponentStatusz та ComponentFlagz на компонентах вашої панелі управління.Ми будемо раді отримати ваші відгуки! Функція структурованих z-сторінок призначена для спрощення відлагодження та моніторингу Kubernetes. Незалежно від того, чи ви створюєте внутрішні інструменти, берете участь в проєктах з відкритим кодом або просто вивчаєте цю функцію, ваші відгуки допоможуть сформувати майбутнє спостережуваності Kubernetes.
Якщо у вас є питання, пропозиції або ви зіткнулися з проблемами, звертайтеся до SIG Instrumentation. Ви можете знайти нас у Slack або на наших регулярних зустрічах спільноти.
Успішного відлагодження!