راهنمای گام‌به‌گام

معرفی کوتاه و دوستانه: اگر قصد دارید از داشبورد Kubernetes به Headlamp مهاجرت کنید، اول باید تفاوت‌های اساسیِ دو ابزار را بفهمید تا مجوزها و نحوه دسترسی را درست تنظیم کنید. 😊

تفاوت مدل‌ها: هر دو ابزار نشان می‌دهند که در یک خوشه چه چیزی اجرا می‌شود، اما مدل اتصال متفاوت است. وقتی Headlamp روی دسکتاپ اجرا می‌شود، از kubeconfig محلی شما برای اتصال به یک یا چند cluster استفاده می‌کند و با plugin قابل توسعه است. وقتی داخل یک cluster نصب می‌شود، از یک ServiceAccount برای تماس با API و تبعیت از قوانین RBAC استفاده می‌کند. در مقابل، Kubernetes Dashboard معمولاً به صورت درون‌خوشه‌ای اجرا شده و همیشه روی توکن‌های ServiceAccount تکیه دارد.

چرا این تفاوت مهم است: انتخاب بین دسکتاپ یا in-cluster تعیین می‌کند که چطور ورود/هویت و دسترسی‌ها را مدیریت کنید؛ بنابراین قبل از مهاجرت باید این مدل‌ها را درک کنید تا با شفافیت تنظیمات را اعمال کنید.

تغییرات رفتاری که باید بدانید: ورود از توکن‌های موجود در kubeconfig (و گاهی SSO) تفاوت دارد، عملیات ایجاد با فرم‌ها به “apply YAML” تغییر می‌کند و بعضی بخش‌های UI مثل فرم‌های ساخت منابع ممکن است رفتار متفاوتی داشته باشند. این موارد در تجربه کاربری تیم شما تاثیر می‌گذارد، پس برنامه‌ریزی کنید.

چک‌لیست قبل از مهاجرت: هدف این چک‌لیست جلوگیری از غافلگیری و اطمینان از این است که Headlamp می‌تواند از هویت‌ها و مجوزهایی که قبلاً داشبورد استفاده می‌کرد، بهره ببرد. همچنین کمک می‌کند تا قبل از خاموش کردن داشبورد، انتقال را ثابت کنید.

ثبت وضعیت فعلی (پایه): لیست کنید که چه clusterهایی دارید (dev, staging, prod)، کدام namespaceها را بیشتر لمس می‌کنید، چه عملیات‌هایی معمولاً انجام می‌دهید (view, edit, scale, delete, debug) و نحوه دسترسی فعلی (kubeconfig، توکن، اتصالات RBAC). این خط پایه به تصمیم‌گیری برای deployment و مجوزها کمک می‌کند.

بررسی سریع کارکرد فعلی: قبل از نصب مطمئن شوید که kubeconfig و دسترسی‌ها درست کار می‌کنند. برای این کار دستورات زیر را اجرا کنید تا مطمئن شوید می‌توانید context و منابع را ببینید:

kubectl config current-context
kubectl get nodes
kubectl get pods -n 

اگر گره‌ها را نمی‌بینید، سعی کنید namespace ای را که دسترسی دارید فهرست کنید. اگر این تست‌ها کار کنند، Headlamp می‌تواند از همان هویت و RBAC استفاده کند. ✅

انتخاب استراتژی انتشار: عجله نکنید. معمولاً تیم‌ها یکی از الگوها را انتخاب می‌کنند:

• انتشار موازی (توصیه): Headlamp را نصب کنید و اجازه دهید افراد آن را امتحان کنند، سپس پس از آمادگی تیم، داشبورد قبلی را بردارید.
• برش نصب (cutover): مستقیماً روی فضای موردنظر نصب کنید و داشبورد قبلی را سریع حذف کنید.
بسیاری از تیم‌ها هم ترکیبی از هر دو را انتخاب می‌کنند — دسکتاپ برای افراد و in-cluster برای تیم پلتفرم.

کدام سرویس‌های جانبی را در نظر بگیرید: برای تجربه کامل ممکن است به metrics-server (برای نمودارهای CPU/Memory)، ingress (برای URL درون‌خوشه‌ای) و OIDC/SSO برای ورود از طریق مرورگر نیاز داشته باشید. همچنین حساب‌های قدیمی ServiceAccount و RBAC داشبورد را بررسی و پاکسازی کنید.

محل اجرا: Headlamp می‌تواند به دو شکل اجرا شود — Desktop یا In-cluster — و هرکدام مزایا و محدودیت‌های خود را دارند:

Option A — Desktop: برای هر کاربر روی دستگاه خودش اجرا می‌شود و همان kubeconfig را می‌خواند. مناسب وقتی می‌خواهید سریع شروع کنید، نیازی به مصرف منابع خوشه‌ای ندارد و با چند cluster کار می‌کند. نیاز به port-forward هم معمولاً نیست.

Option B — In-cluster: به‌عنوان یک workload داخل خوشه (معمولاً با Helm) نصب می‌شود. مناسب وقتی نیاز دارید تیم پلتفرم مدیریت متمرکز، URL مشترک و دسترسی هماهنگ داشته باشد. مدیران می‌توانند نصب، ارتقاء و پیکربندی را با ابزارهای استاندارد Kubernetes مدیریت کنند.

نصب Desktop: برای شروع سریع می‌توانید Headlamp را روی ماشین محلی نصب کنید. مثال‌های نصب:

# Windows
winget install headlamp
# یا
choco install headlamp

# macOS
brew install --cask headlamp

# Linux (Flatpak)
flatpak install flathub io.kinvolk.Headlamp

نصب In-cluster (با Helm): وقتی می‌خواهید دسترسی مشترک داشته باشید، Headlamp را با Helm نصب کنید. یک روند ساده:

helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
helm repo update
kubectl create namespace headlamp
helm install headlamp headlamp/headlamp -n headlamp

یا می‌توانید از مانیفست YAML ارائه شده استفاده کنید و مطابق نیاز تنظیمش کنید.

تأیید نصب: برای بررسی اجرا بودن:

kubectl get pods -n headlamp
kubectl get svc -n headlamp

برای تست سریع با port-forward:

kubectl port-forward -n headlamp svc/headlamp 8080:80
[/yaml</p>

<p>و سپس باز کنید: http://localhost:8080</p>

<p>برای دسترسی پایدارتر، سرویس را از طریق Ingress یا LoadBalancer در معرض قرار دهید. توجه داشته باشید که Headlamp URL عمومی به اضافه /oidc-callback برای OIDC مهم است؛ بنابراین تنظیمات TLS و ingress باید درست باشند.</p>

<p>به‌روزرسانی‌ها: روش به‌روزرسانی بستگی به نحوه نصب دارد. اگر با Winget یا Homebrew نصب کرده‌اید، از ابزار همان پکیج منیجر برای upgrade استفاده کنید. برای نصب‌های Flatpak، AppImage یا tarball، روش‌های مخصوص آن‌ها را دنبال کنید.</p>

<p>امنیت و دسترسی (نکات مهم): هر سرویس درون‌خوشه که به خوشه سرویس می‌دهد را مثل هر endpoint حساس دیگر محافظت کنید: TLS فعال باشد، دسترسی شبکه محدود باشد و کنترل عملیات از طریق Kubernetes auth و RBAC انجام شود. Headlamp از همان قوانین RBAC ای که kubectl از آن پیروی می‌کند تبعیت می‌کند؛ یعنی Headlamp فقط اقداماتی را نشان می‌دهد که هویت شما اجازه دارد.</p>

<p>ورود و OIDC: برای in-cluster معمولاً باید یک طرح ورود مشخص کنید. Headlamp از OIDC پشتیبانی می‌کند یا می‌توانید یک لایه auth جلوتر از Headlamp قرار دهید (مثلاً یک پروکسی یا سیستم SSO شرکتی). اگر از OIDC داخلی استفاده می‌کنید، نیاز به Client ID، Client Secret و Issuer URL دارید و باید callback URL مانند:</p>

<p>https://headlamp.example.com/oidc-callback</p>

<p>در صورتی که Headlamp پشت یک load balancer یا ingress قرار دارد، مطمئن شوید X-Forwarded-Proto به درستی ارسال می‌شود تا callback URL با https ساخته شود.</p>

<p>RBAC: اصل حداقل امتیاز را رعایت کنید. با کمترین مجوزهای لازم شروع کنید و در صورت نیاز مجوزها را افزایش دهید. اگر داشبورد قدیمی از یک ServiceAccount پرامتیاز استفاده می‌کرد، در برنامه‌ریزی مهاجرت آن دسترسی را سخت یا حذف کنید.</p>

<p>عیب‌یابی سریع Desktop: اگر خوشه خود را نمی‌بینید، معمولاً دلیلش مکان یا محتوی kubeconfig است. با این دستورات وضعیت را بررسی کنید:</p>

<p>[yaml]
kubectl config current-context
kubectl get nodes
kubectl get pods -n 

همچنین می‌توانید KUBECONFIG را برای انتخاب فایل خاص تنظیم کنید:

KUBECONFIG=/path/to/config headlamp

نکته پایانی دوستانه: مهاجرت به Headlamp می‌تواند تجربه تیمی را روان‌تر کند ولی نیاز به برنامه‌ریزی برای دسترسی‌ها، احراز هویت و deployment strategy دارد. اگر سوال فنی یا نیاز به سناریوی خاص دارید، بگید تا با هم دقیق‌تر پیش بریم. 🚀