Deploy Headlamp Kubernetes Dashboard today using NodePort access—your cluster’s future depends on it. Don’t get left behind while others modernize. Step-by-step Helm guide inside. Read now before your outdated Dashboard costs you. #CentLinux #Linux #Kubernetes
Table of Contents
Introduction
As a DevOps engineer with years in IT Industry, I’ve evaluated nearly every major Kubernetes management panel on the market. From the early official Dashboard to Lens, and then Rancher’s built-in UI, the pace of tool iteration is striking. But Headlamp’s arrival caught my attention—it wasn’t just accepted as an official Kubernetes SIG sub-project, but also redefined the K8s visualization experience with a plugin-based architecture and lightweight design. (Headlamp official website)
If you’re looking for a Kubernetes Dashboard tool that can replace the traditional Dashboard (which is now archived and no longer maintained), this article will walk you through deploying Headlamp via Helm step by step. I’ll share how to expose the service through NodePort, generate secure tokens, and offer a few pitfall-avoidance tips based on my production experience.
Why I Chose Headlamp as the Kubernetes Dashboard
Before diving into the commands, it’s worth understanding Headlamp’s positioning. Its biggest difference from the traditional Kubernetes Dashboard is the philosophy of “extensibility.” Headlamp’s core remains lightweight, but through the plugin system, you can load capabilities like cert-manager management and OPA Gatekeeper policy viewing on demand.
For DevOps teams in the United States, another appeal of Headlamp is its CNCF ecosystem background and active community iteration. The official Dashboard project has been stagnant for years, while Headlamp is continuously maintained by the Kubernetes SIG UI group with a stable release cadence.
My evaluation criteria are simple: if a tool can save me a few kubectl describe commands when troubleshooting a crashing Pod at 3 AM, it has value. Headlamp’s multi-cluster management capabilities and real-time resource status refresh have indeed met that standard.
Prerequisites
Before starting, ensure your environment meets the following requirements:
- A running Kubernetes cluster (version 1.24+, because the token generation method changed)
kubectlinstalled and configured- Helm 3.x installed
cluster-adminor equivalent permissions on the target cluster
Step 1: Add the Headlamp Helm Repository
Helm is the most convenient way to deploy Headlamp. The officially maintained Helm Chart is located in the Kubernetes SIG GitHub Pages repository.
helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
helm repo updateExperience tip: The helm repo update step is often overlooked. If an old repository entry named headlamp already exists in your Helm cache, directly running helm install might pull a stale Chart version. Make it a habit to update the cache immediately after adding a repository—this is especially important in production pipelines.
Step 2: Create the Configuration Directory and values.yaml
The default configuration of the Helm Chart sets the Service type to ClusterIP, which means Headlamp can only be accessed from within the cluster. For Kubernetes Dashboard deployment scenarios, we need to expose it to an external browser via NodePort.
mkdir ~/headlamp
cd ~/headlamp
vi values.yamlWrite the following content into values.yaml:
service:
# Change the default ClusterIP to NodePort
type: NodePort
# The internal port the service targets (Headlamp defaults to 80)
port: 80
# Optional: Assign a specific static NodePort
# Must be within your cluster's allowed range (default is 30000-32767)
# If you leave this null or omit it, Kubernetes will automatically assign an available port
nodePort: 30080Engineering Advice on NodePort:
Choosing 30080 as a fixed port is my personal preference—it’s easy to remember and far from port ranges that some cloud vendor load balancers might occupy. But I’ll be candid: in production environments, I strongly recommend using Ingress rather than NodePort to expose Headlamp.
There are three reasons: First, NodePort bypasses standard TLS termination and HTTP routing layers, and your Token may lack encryption protection during transmission. Second, the NodePort port range is limited, and conflicts are prone to occur in large-scale clusters. Third, Ingress can work with cert-manager to automatically manage certificates and enable HTTPS access.
However, for lab environments, temporary troubleshooting, or quick intranet access, NodePort’s simplicity is irreplaceable. That’s why I’m demonstrating this method in this article.
Step 3: Execute the Helm Installation
Once the configuration is ready, run the installation command:
helm install headlamp headlamp/headlamp \
--namespace headlamp \
--create-namespace \
-f values.yamlParameter breakdown:
headlamp(the first one): Release name, which you can customizeheadlamp/headlamp: repository name/Chart name--namespace headlamp: Deploy Headlamp to a dedicated namespace--create-namespace: Automatically create the namespace if it doesn’t exist-f values.yaml: Apply our custom configuration
After installation, run the command output by Helm to verify the deployment:
kubectl get pods -n headlampYou should see output similar to headlamp-xxxx-xxxxx 1/1 Running. If the Pod is in Pending or CrashLoopBackOff state, check resource quotas and image pull permissions immediately.
Step 4: Get the Headlamp UI Access Address
At the end of the Helm install command, several hints will be output, one of which is the command to get the access URL. You can confirm the NodePort with:
kubectl get svc -n headlampThe PORT(S) column in the output will show a mapping like 80:30080/TCP. Next, get the IP of any node:
kubectl get nodes -o wideAccess http://<node-ip>:30080 in your browser, and you’ll see the Headlamp login interface.
A pitfall I’ve encountered: If your node has multiple network interfaces, make sure you’re using an IP that can be routed to from your client machine. In some cloud environments, only the Internal IP is available, while the External IP may be empty. Also, check whether security groups or firewall rules allow port 30080.
Step 5: Generate a Service Account Token
Headlamp uses Kubernetes RBAC for authentication, and the recommended way to log in is through a Service Account Token. The Headlamp Helm Chart does not create a headlamp-admin Service Account by default, so we need to create one manually with administrator permissions (for initial access only; you should tighten this later following the principle of least privilege).
Create the Service Account and ClusterRoleBinding
# Create the Service Account
kubectl -n headlamp create serviceaccount headlamp-admin
# Bind the cluster-admin role
kubectl create clusterrolebinding headlamp-admin \
--serviceaccount=headlamp:headlamp-admin \
--clusterrole=cluster-adminGenerate the Token
Kubernetes 1.24+ uses the kubectl create token command to generate a temporary Token:
kubectl create token headlamp-admin -n headlampBy default, this Token is valid for 1 hour. For scenarios requiring long-term access, you can specify the --duration parameter:
kubectl create token headlamp-admin -n headlamp --duration=8760hSecurity reminder: --duration=8760h generates a Token valid for 365 days. As a security professional holding the ISC2 CC certification, I must emphasize: long-lived Tokens are security debt. In production environments, my approach is to create short-term Tokens (e.g., 8-24 hours) and rotate them regularly with a password manager, or directly integrate OIDC authentication.
Copy the generated Token into the Token input field on the Headlamp login screen to access the Dashboard.
Key Production Environment Recommendations
Based on my CKA and RHCE experience, here are a few optimization directions worth your time:
RBAC Tightening: The cluster-admin binding is only suitable for initial validation. In production, you should create a custom ClusterRole limiting Headlamp users to specific namespaces and resource types. Headlamp’s RBAC fully follows the native Kubernetes model—whatever permissions you grant, users can see.
Ingress + TLS: As mentioned earlier, change service.type back to ClusterIP and then expose it through Ingress. Headlamp’s Helm Chart natively supports Ingress configuration:
ingress:
enabled: true
ingressClassName: nginx
hosts:
- host: headlamp.example.com
paths:
- path: /
type: Prefix
tls:
- secretName: headlamp-tls
hosts:
- headlamp.example.comToken Management Strategy: If you manage Headlamp with Helm, note that the Service Account lifecycle is independent of the Helm Release. Upgrading or uninstalling Headlamp will not automatically clean up the RBAC resources you created. I recommend managing these resources in a separate IaC repository.
Monitoring and Observability: Headlamp’s values.yaml supports configuring OpenTelemetry endpoints (if using a custom Chart). In scaled deployments, integrating Headlamp’s own metrics and logs into your existing observability stack can help you quickly pinpoint UI-level performance issues.
Video Tutorial
Summary
Headlamp is becoming the de facto standard for Kubernetes management panels. Its Helm Chart maturity, SIG official backing, and plugin architecture give it a clear long-term advantage among Kubernetes Dashboard-class tools.
The NodePort deployment method demonstrated in this article is an ideal path for quick onboarding, but remember: quick access and production security require different trade-offs. Spending 30 minutes configuring Ingress and tightening RBAC might save you days of explanation costs in a future security audit.
If you’re migrating from the old Kubernetes Dashboard, or want to experience a lightweight alternative to Lens, Headlamp is worth an afternoon of exploration.
Frequently Asked Questions (FAQ)
1. Why does my Headlamp Pod show CrashLoopBackOff immediately after Helm install, even though the values.yaml looks correct?
This is almost always a resource constraint or an image pull issue—not a configuration syntax problem. Run kubectl describe pod <headlamp-pod> -n headlamp and inspect the Events section at the bottom. If you see OOMKilled, your nodes are memory-constrained and you need to increase the container’s memory limit in values.yaml. If you see ImagePullBackOff, your cluster may be behind a proxy or using a private registry that can’t reach ghcr.io. A less obvious cause: if your cluster has a PodSecurityPolicy or Pod Security Admission label set to restricted on the headlamp namespace, the container may be rejected for running as root. Label the namespace with pod-security.kubernetes.io/enforce=baseline to resolve it.
2. Can I use a NodePort outside the default 30000–32767 range, and what happens if I do?
Technically you can, but only if you explicitly reconfigure the --service-node-port-range flag on your kube-apiserver and restart the control plane. This is a cluster-wide change and carries real risk. If you set a NodePort below 30000—say 80 or 443—the API server will reject the Service creation with a validation error unless that flag is widened. My strong advice: don’t widen the range just to get a prettier port number. A 30080-style port is fine. If you genuinely need port 80/443 exposure, that’s a signal you should be using Ingress with a LoadBalancer, not NodePort.
3. How do I rotate the Headlamp Service Account Token without disrupting active users?
Token rotation in Headlamp isn’t automatic because the Helm Chart doesn’t manage the Service Account. The cleanest approach is to create a second Service Account (headlamp-admin-v2) with the same RBAC binding, distribute the new token to users, wait for the old token to expire or be revoked, then delete the old Service Account and its ClusterRoleBinding. If you need immediate revocation, delete the Service Account itself—Kubernetes will invalidate all tokens issued to it within seconds. Never rely on --duration alone as a rotation mechanism; treat token expiry as a backstop, not a strategy.
4. Is it safe to bind cluster-admin to the Headlamp Service Account in a multi-tenant cluster?
No—and this is the single most common misconfiguration I see. In a multi-tenant cluster, cluster-admin gives Headlamp’s users visibility into every namespace, including Secrets in other teams’ workloads. The correct pattern is to create a namespace-scoped Role for each tenant and bind it to a dedicated Service Account, then have each team log in with their own token. Headlamp will only render the resources that token can list and get. If you need a shared admin view, restrict NodePort access at the network layer (VPN, IP allowlist, or bastion host) so the admin token never reaches an untrusted network.
5. What’s the actual performance impact of running Headlamp in a large cluster with thousands of Pods?
Headlamp’s UI itself is lightweight, but its watch-based resource streaming can generate noticeable API server load in clusters exceeding roughly 5,000 Pods. The default Helm Chart sets no resource requests, which means the scheduler treats it as BestEffort—fine for labs, dangerous for production. Set explicit requests and limits (I typically start at 100m CPU / 128Mi memory for requests and 500m / 512Mi for limits) and monitor apiserver_request_total by verb after rollout. If you observe sustained LIST or WATCH spikes, enable Headlamp’s namespace filtering or restrict the Service Account to specific namespaces. In very large clusters, consider running Headlamp per-team rather than as a single shared instance.
Summary
Headlamp is becoming the de facto standard for Kubernetes management panels. Its Helm Chart maturity, SIG official backing, and plugin architecture give it a clear long-term advantage among Kubernetes Dashboard-class tools.
The NodePort deployment method demonstrated in this article is an ideal path for quick onboarding, but remember: quick access and production security require different trade-offs. Spending 30 minutes configuring Ingress and tightening RBAC might save you days of explanation costs in a future security audit.
If you’re migrating from the old Kubernetes Dashboard, or want to experience a lightweight alternative to Lens, Headlamp is worth an afternoon of exploration.
Recommended Courses
If you’re eager to kickstart your journey into cloud-native technologies, “Kubernetes for the Absolute Beginners – Hands-on” by Mumshad Mannambeth is the perfect course for you. Designed for complete beginners, this course breaks down complex concepts into easy-to-follow, hands-on lessons that will get you comfortable deploying, managing, and scaling applications on Kubernetes.
Whether you’re a developer, sysadmin, or IT enthusiast, this course provides the practical skills needed to confidently work with Kubernetes in real-world scenarios. By enrolling through the links in this post, you also support this website at no extra cost to you.
Disclaimer: Some of the links in this post are affiliate links. This means I may earn a small commission if you make a purchase through these links, at no additional cost to you.
Leave a Reply
You must be logged in to post a comment.