Headlamp

What is Headlamp?

Headlamp is a lightweight, extensible Kubernetes dashboard providing a clean web UI for browsing workloads, events, nodes, storage, RBAC, and custom resources. It is plugin-based and actively maintained by the CNCF ecosystem.

Why Headlamp?

Headlamp is faster and lighter than the standard Kubernetes Dashboard, and it is the only cluster UI here. Anything it cannot do is done through Argo CD or kubectl — the cluster is GitOps-managed, so changes belong in code rather than in a console.

How It's Used Here

Headlamp runs in the headlamp namespace, accessible at https://headlamp.madhan.app. You log in with a short-lived token for the headlamp-admin ServiceAccount, which is bound to cluster-admin. No static token Secret exists.

Source: workloads/management/headlamp.go

Configuration

Authentication

Headlamp uses token-based authentication. Mint a short-lived token (optional duration, e.g. 8h):

just headlamp-token [duration]
# equivalent to: kubectl create token headlamp-admin -n headlamp [--duration=<duration>]

Paste the token into the Headlamp login screen.

Resource Views

Headlamp shows pod CPU and memory usage if Metrics Server is installed. Without Metrics Server, the resource columns show N/A.

External Access

Headlamp is LAN-only by default (no Cloudflare A record). For temporary external access, use the NetBird reverse proxy feature.

→ Exposing Headlamp via NetBird Reverse Proxy

Screenshots

Troubleshooting

Token Expired / Invalid

Tokens from kubectl create token expire, and recreating the ServiceAccount invalidates them early. Mint a new one:

just headlamp-token

Resource Metrics Not Showing

Ensure Metrics Server is running:

kubectl get deployment metrics-server -n kube-system
kubectl top nodes  # should return data