اشکالزدایی اجزای کنترلپلین با تمرکز بر Kubelet در Kubernetes 1.35 دشوار است؛ اما با APIهای z و خروجیهای JSON ساختاریافته، مشاهده وضعیت زمان اجرا، نسخه و پیکربندی بهطور خودکار ساده میشود.
Kubelet و APIهای z در Kubernetes
در این مقاله، با تمرکز بر Kubelet، نحوه دریافت پاسخهای JSON ساختاریافته از z-pages را توضیح میدهیم تا ابزارهای DevOps و اسکریپتهای خودکاری به دادههای دقیق دسترسی پیدا کنند.
Kubernetes 1.35: بهبود رفع اشکال با APIهای نسخهشده z-pages 🙂
اشکالزدایی اجزای control plane همیشه چالشبرانگیز است، مخصوصاً وقتی سریع میخواهید وضعیت زمان اجرا، نسخه یا پیکربندی یک مؤلفه را بررسی کنید. در Kubernetes 1.35، z-pages تقویت شدهاند تا علاوه بر خروجی متنمحور سنتی، پاسخهای ساختاریافته و قابل پارس شدن توسط ماشین (JSON) ارائه دهند؛ این کار ساخت ابزارها و گردشکارهای خودکار عیبیابی را بسیار سادهتر میکند.
z-pages چیست؟ z-pages نقاط پایانی اشکالزداییای هستند که توسط اجزای control plane مثل kube-apiserver، kube-controller-manager، kube-scheduler، kubelet و kube-proxy منتشر میشوند. این قابلیت بهعنوان یک ویژگی alpha از Kubernetes 1.32 معرفی شد و convention مسیرهای /*z را برای این منظور به کار میبرد. دو نقطه پایانی کلیدی بهطور معمول مورد استفاده قرار میگیرند: /statusz (برای وضعیت کلی مؤلفه، نسخه، زمان شروع، uptime و مسیرهای اشکالزدایی) و /flagz (برای نمایش پرچمها و آرگومانهای خط فرمان). تا پیش از این، خروجیها صرفاً متنپایه بودند که پارس برنامهنویسی آنها سخت بود.
چه چیزی در Kubernetes 1.35 تغییر کرده؟ سازگاری با خروجی متن ساده حفظ شده، اما حالا میتوانید پاسخهای JSON نسخهدار دریافت کنید. اگر هدر Accept را تعیین نکنید، همان متن ساده برگشت داده میشود. برای نمونه، یک پرس و جوی ساده متنمحور ممکن است به صورت زیر باشد:
[pyaml]
$ 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
# خروجی نمونه (متن ساده)
Starting: Wednesday 16 Oct 21:03:43 UTC 2024
Uptime: 0:00:16
Go Version: go1.23.2
Binary Version: 1.35.0-alpha.0.1595
Paths: /healthz /livez /readyz /statusz /version
[/pyaml]
برای گرفتن پاسخ ساختاریافته، هدر Accept مناسب را اضافه کنید؛ مثلاً برای /statusz:
[pyaml]
-H “Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Statusz”
[/pyaml]
و یک پاسخ JSON نمونه (نسخهای از API) ممکن است شبیه این باشد:
[pyaml]
{
“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”, “/readyz”, “/statusz”, “/version”]
}
[/pyaml]
بهطور مشابه، /flagz هم پاسخ JSON ساختاریافته را وقتی هدر مناسب ارسال شود، پشتیبانی میکند. نمونه هدر و پاسخ:
[pyaml]
-H “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-admission-plugins”: “true”
}
}
[/pyaml]
چرا پاسخهای ساختاریافته مهماند؟ 🚀
این فرمت چند قابلیت مهم میآورد که برای تیمهای SRE/DevOps خیلی کاربردیاند:
1) نظارت و بررسی خودکار: ابزارها میتوانند فیلدهای مشخصی را بدون نیاز به regex یا پارس متن استخراج کنند (مثلاً بررسی نسخه شبیهسازیشده یا مقدار یک flag).
2) ابزارهای اشکالزدایی بهتر: با JSON میتوانید مقایسه پیکربندی بین مؤلفهها، دنبال کردن تغییرات در طول زمان و نوشتن اسکریپتهایی که تصمیمگیری خودکار انجام میدهند را ساده کنید.
3) پایداری با نسخه API: پاسخها نسخهبندی شدهاند (شروع با v1alpha1). این مسیر نسخهای به شما امکان میدهد در آینده به v1beta1 و سپس v1 بروید و ابزارهای شما کمتر در برابر تغییرات شکسته شوند.
نحوه استفاده و پیشنیازها
هر دو endpoint نیاز به فعال بودن feature gate دارند: برای /statusz باید ComponentStatusz فعال باشد و برای /flagz باید ComponentFlagz فعال باشد. نمونهای از استفاده curl برای دریافت JSON ساختاریافته از kube-apiserver:
[pyaml]
# درخواست 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 .
[/pyaml]
توجه: مثالهای بالا از احراز هویت با گواهی مشتری استفاده میکنند و سرور را با –cacert تأیید میکنند. اگر صرفاً در محیط آزمایشی هستید و میخواهید تأیید گواهی را نادیده بگیرید، میتوانید از –insecure (یا -k) استفاده کنید؛ اما هرگز این کار را در تولید انجام ندهید 🔒.
ملاحظات مهم و امنیتی ⚠️
• وضعیت alpha: این قابلیت در Kubernetes 1.35 بهصورت alpha است؛ بنابراین قالب API ممکن است تغییر کند. تا رسیدن به beta یا stable از تکیه کامل بر این endpoints برای گردشکارهای حیاتی خودداری کنید.
• مجوزها: دسترسی به z-pages محدود به گروههای سیستمی مشخص میشود (مشابه /healthz، /livez، /readyz). اگر از RBAC استفاده میکنید، با اعطای مجوز مناسب دسترسی را مدیریت کنید.
• احراز هویت: بسته به پیکربندی خوشه، معمولاً برای دسترسی به این endpoints باید احراز هویت انجام شود (مثلاً client certificates). اگر auth ناشناس فعال باشد، ممکن است نیاز به بررسی تنظیمات داشته باشید.
• افشای اطلاعات: این نقاط پایانی جزئیات پیکربندی و آرگومانهای خط فرمان را نشان میدهند؛ بنابراین فقط به اپراتورهای مورد اعتماد و ابزارهای اشکالزدایی مجاز دسترسی بدهید و از قرار دادن آنها در معرض کاربران یا سرویسهای غیرمجاز خودداری کنید.
چشمانداز و مشارکت
با بالغ شدن ویژگی، SIG Instrumentation انتظار دارد نسخههای v1beta1 و سپس v1 را منتشر کند و بر اساس بازخورد جامعه API را تثبیت کند. اگر فرصت داشتید در محیط آزمایشی آن را امتحان کنید: feature gates را فعال کنید، endpoints را هم با متن و هم با JSON پرسوجو کنید، یک اسکریپت یا ابزار ساده بسازید که از دادههای ساختاریافته استفاده کند و بازخوردتان را در کانالهای SIG Instrumentation (مثلاً #sig-instrumentation در Slack) به اشتراک بگذارید — جامعه منتظر نظرات شماست 🙌.
اگر سؤال یا پیشنهادی دارید، با SIG Instrumentation در ارتباط باشید یا در جلسات منظم جامعه شرکت کنید. اشکالزدایی مبارک! 🐞🔍
