Chủ Nhật, 04/10/2026, 17:00 (GMT+0)

[Part 2] Bắt đầu với Headlamp: Cài đặt và kết nối Kubernetes cluster

Thumbnail Blog
Quay lại Trang chủ Blog
Trên trang này

Ở Part 1, chúng ta đã tìm hiểu vai trò của Headlamp và các thao tác có thể thực hiện trên giao diện. Bài viết này hướng dẫn từng bước cài đặt Headlamp, kết nối tới cluster hiện có, cấu hình authentication và authorization.

Trước khi cài đặt: Headlamp có những mô hình triển khai nào?

Bản desktop

Laptop  →  Headlamp  →  Kubernetes API của cluster

Phù hợp khi cá nhân (developer, DevOps, quản trị viên) cần giao diện để làm việc với cluster ngay trên máy tính của mình.

Triển khai trong cluster (in-cluster)

Trình duyệt  →  Headlamp chạy trong cluster  →  Kubernetes API

Phù hợp khi cần cung cấp giao diện dùng chung cho nhiều người qua trình duyệt. Mô hình này cần cấu hình authentication, authorization và bảo vệ truy cập phù hợp.

Bài viết đi từ mô hình desktop đến triển khai trong cluster.

Cài Headlamp trên laptop

Windows

 PowerShell · WinGet
 winget install headlamp

Hoặc dùng Chocolatey: choco install headlamp. Cũng có thể tải bộ cài đặt từ trang GitHub Releases của Headlamp.

macOS

 Terminal · Homebrew
 brew install --cask headlamp

Hoặc tải file .dmg từ GitHub Releases.

Linux

 Terminal · Flatpak (Flathub)
 flatpak install flathub io.kinvolk.Headlamp

Gói io.kinvolk.Headlamp được phát hành trên Flathub. Ngoài ra có bản AppImage và tarball trên GitHub Releases.

Kết nối Headlamp với Kubernetes cluster

Headlamp bản desktop sử dụng thông tin kết nối và authentication trong kubeconfig để gọi Kubernetes API:

Headlamp trên laptop  →  Kubeconfig / Authentication  →  Kubernetes API Server

Headlamp không tạo cluster. Công cụ kết nối tới cluster đã có và cung cấp giao diện để giám sát, quản lý resource theo quyền được cấp.

Bước 1: Mở Headlamp

Theo mặc định, Headlamp sử dụng kubeconfig tại vị trí mặc định của người dùng (thường là ~/.kube/config) và liệt kê các cluster có trong đó. Có thể chỉ định file khác qua biến môi trường KUBECONFIG (xem bước 3).

Màn hình chọn cluster của Headlamp

Danh sách cluster được đọc từ kubeconfig, kèm trạng thái kết nối và phiên bản Kubernetes. Nguồn: Alok Shankar, dev.to (đã chỉnh sửa)

Bước 2: Chọn cluster và kiểm tra kết nối

Nếu cluster báo Active, tiếp tục mở một namespace để xác nhận có thể đọc resource. Nếu kết nối lỗi, kiểm tra cấu hình bằng:

 kubectl config current-context
 kubectl get nodes

Nếu kubectl hoạt động với cùng context và credentials, đây là bước kiểm tra ban đầu hữu ích. Tuy nhiên vẫn cần xác nhận Headlamp đang dùng đúng file kubeconfig đó; với cluster dùng exec plugin (EKS, AKS, GKE), binary của exec plugin tương ứng phải có trong PATH của ứng dụng.

Bước 3: Dùng nhiều file kubeconfig (nếu cần)

Đặt biến môi trường KUBECONFIG trước khi khởi chạy Headlamp. Dấu phân cách là : trên macOS/Linux và ; trên Windows:

 macOS / Linux
 KUBECONFIG=~/.kube/dev:~/.kube/prod headlamp
 Windows PowerShell
 $env:KUBECONFIG = "$HOME\.kube\dev;$HOME\.kube\prod"

Biến môi trường chỉ có hiệu lực khi Headlamp được khởi chạy từ chính phiên terminal đó; mở ứng dụng từ Start Menu hoặc Dock sẽ không kế thừa giá trị này.

Authentication và Authorization

Đây là hai khái niệm khác nhau:

  • Authentication: xác định bạn là ai, tức danh tính hoặc credentials đang được sử dụng.
  • Authorization: xác định danh tính đó được phép làm gì trên resource nào. Trong Kubernetes, authorization được thực hiện bằng RBAC tại API server.

Với bản desktop, Headlamp dùng credentials có sẵn trong kubeconfig. Khi triển khai trong cluster, cách authentication phụ thuộc mô hình triển khai và cấu hình; bài viết minh hoạ hai cách phổ biến:

ServiceAccount Token

  • Khi nào dùng: môi trường thử nghiệm, cluster nhỏ, hoặc khi chưa có hệ thống đăng nhập tập trung.
  • Token dùng để làm gì: authentication khi Headlamp gọi Kubernetes API thay mặt người dùng.
  • Quyền hạn: do RBAC gán cho ServiceAccount quyết định.

OIDC

  • Khi nào dùng: khi muốn tích hợp với Identity Provider của tổ chức như Keycloak, Microsoft Entra ID, Okta.
  • Cách hoạt động: người dùng đăng nhập bằng tài khoản tổ chức; quyền hạn được xác định theo user/group trong RBAC.
  • Lưu ý: đăng nhập thành công không đồng nghĩa người dùng có quyền đọc hoặc thay đổi mọi resource.

Authentication cho biết bạn là ai; RBAC quyết định bạn được làm gì. Giao diện Headlamp có thể ẩn các nút không được phép, nhưng lớp bảo vệ thực sự là authorization tại Kubernetes API server.

Triển khai Headlamp trong cluster bằng Helm

Khi cần một giao diện dùng chung, triển khai Headlamp trong cluster theo luồng:

Kubernetes cluster  →  Triển khai Headlamp  →  Service / Ingress  →  Trình duyệt  →  Đăng nhập

Bước 1: Thêm Helm repository

 helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
 helm repo update

Bước 2: Cài Headlamp vào namespace riêng

 helm install headlamp headlamp/headlamp \
   --namespace headlamp --create-namespace

Nên ghi lại phiên bản chart đã dùng (helm list -n headlamp) để có thể tái hiện khi nâng cấp hoặc troubleshooting.

Bước 3: Kiểm tra và truy cập thử

 kubectl get pods,svc -n headlamp
 kubectl port-forward -n headlamp svc/headlamp 8080:80

Theo mặc định của chart, Service có kiểu ClusterIP và port 80. Mở http://localhost:8080 trên trình duyệt. Port-forward chỉ dùng để kiểm tra.

Bước 4: Tạo token đăng nhập (nếu dùng ServiceAccount Token)

 kubectl -n headlamp create serviceaccount headlamp-viewer
 kubectl create clusterrolebinding headlamp-viewer \
   --serviceaccount=headlamp:headlamp-viewer \
   --clusterrole=view
 kubectl create token headlamp-viewer -n headlamp

Ví dụ trên gán quyền chỉ xem (view) trên toàn cluster. Nếu chỉ cần một namespace, nên dùng RoleBinding trong namespace đó. Ưu tiên quyền tối thiểu theo nhu cầu công việc; cluster-admin cho phép thay đổi mọi resource trên toàn cluster, chỉ nên dùng trong môi trường kiểm thử có kiểm soát.

Phương án thay thế: cài bằng manifest YAML

 kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/headlamp/main/deployment/headlamp.yaml

Lệnh trên lấy manifest từ nhánh main. Với môi trường chính thức, nên dùng manifest theo phiên bản phát hành đã kiểm thử thay vì phụ thuộc vào nhánh đang phát triển.

Một số cấu hình cần lưu ý

  • RBAC và ServiceAccount: cấp quyền tối thiểu (view, edit theo namespace); không cấp quyền cao hơn chỉ để giao diện hiển thị đầy đủ nút thao tác.
  • Ingress và TLS: khi cung cấp giao diện qua URL, bật TLS và kiểm soát người được phép truy cập.
  • OIDC: khai báo Client ID, Client secret, Issuer URL, scopes trong Helm values và cấu hình tương ứng trên Identity Provider. Callback URL có dạng https://<địa-chỉ-headlamp>/oidc-callback. Ingress hoặc reverse proxy phía trước cần chuyển tiếp header X-Forwarded-Proto để callback sinh đúng https.
  • Truy cập mạng: nếu cần truy cập từ xa, kết hợp TLS, authentication, authorization và giới hạn truy cập mạng (VPN, IP allowlist) phù hợp với kiến trúc.
  • Cập nhật phiên bản: winget upgrade headlamp, brew upgrade --cask headlamp, flatpak update io.kinvolk.Headlamp, hoặc helm upgrade headlamp headlamp/headlamp -n headlamp với bản trong cluster. Đọc ghi chú phát hành trước khi nâng cấp.
 values.yaml · ví dụ Ingress và OIDC
 ingress:
   enabled: true
   ingressClassName: nginx
   hosts:
     - host: headlamp.example.com
       paths:
         - path: /
           type: ImplementationSpecific
   tls:
     - secretName: headlamp-tls
       hosts:
         - headlamp.example.com
 config:
   oidc:
     clientID: headlamp
     clientSecret: "<client-secret>"
     issuerURL: https://sso.example.com/realms/platform
     scopes: "openid,profile,email"

Tên khoá cấu hình có thể thay đổi giữa các phiên bản chart; đối chiếu với helm show values headlamp/headlamp trước khi áp dụng.

Hoàn tất: Headlamp đã sẵn sàng

  • Headlamp khởi chạy thành công.
  • Kết nối được Kubernetes API của cluster mục tiêu.
  • Authentication hoạt động đúng với mô hình đã chọn.
  • Người dùng chỉ truy cập và thao tác được trong phạm vi quyền được cấp.

Headlamp đã sẵn sàng. Ở Part 3, chúng ta sẽ thực hành kiểm tra trạng thái resource, log, Events và các thao tác quản lý phổ biến trên giao diện Headlamp.

Đọc tiếp Part 3: https://cloud.vnpt.vn/blog/part-3-quan-sat-va-quan-tri-kubernetes-ngay-tren-laptop-3471 

Tài liệu tham khảo