How to Migrate from Kubernetes Dashboard to Headlamp

What this stack gives you: A step-by-step process for replacing Kubernetes Dashboard with Headlamp — gaining multi-cluster support, SSO integration, and a plugin architecture without disrupting access for teams already using the old Dashboard.

Purpose: Kubernetes Dashboard served well as a per-cluster read-only UI, but it has fundamental limitations for modern platform teams: single-cluster scope, service-account-based authentication, no extensibility, and no desktop deployment option. Headlamp is the CNCF project that replaces it with kubeconfig-based auth (same as kubectl), SSO support, multi-cluster management, and a plugin ecosystem that includes dedicated views for Kubeflow, Karpenter, and Argo.

Pre-requisites:

• Working kubeconfig with access to the target cluster(s)
• kubectl configured and tested (kubectl get nodes returns results)
• Cluster admin access or namespace-scoped permissions as required
• For in-cluster installation: an ingress controller and optionally an OIDC provider for SSO

Step 1: Verify cluster access

kubectl config current-context
kubectl get nodes
# If namespace-scoped:
kubectl get pods -n <your-namespace>

All three must succeed before proceeding. Headlamp reads your existing kubeconfig — if kubectl works, Headlamp works.

Step 2: Install Headlamp (desktop — recommended for parallel rollout)

Download the desktop app from headlamp.dev for your OS. On first launch, Headlamp reads your kubeconfig automatically and lists all available clusters. No cluster-side resources are consumed in desktop mode.

This is the recommended starting point because it lets you run Headlamp alongside the existing Dashboard with zero risk. Team members can familiarize themselves with the interface while production access stays on Dashboard.

Step 3: Install in-cluster (for shared team access)

For browser-accessible shared deployment, use Helm:

helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
helm install headlamp headlamp/headlamp -n kube-system

For SSO, add your OIDC provider configuration. For ingress, configure your existing ingress controller to route to the Headlamp service. The Kubernetes Blog migration guide covers OIDC and ingress configuration patterns in detail.

Step 4: Configure multi-cluster access

In the desktop app, all kubeconfig contexts are available by default. For the in-cluster deployment, add additional clusters via the Headlamp settings UI or by configuring multi-cluster Helm values. This is where Headlamp pays off immediately if you manage more than one cluster — a single Headlamp instance replaces multiple per-cluster Dashboard deployments.

Step 5: Install domain-specific plugins

# AI/ML workloads
helm install kubeflow-headlamp headlamp-plugins/kubeflow -n kube-system

# Autoscaling visibility
helm install karpenter-headlamp headlamp-plugins/karpenter -n kube-system

The Kubeflow plugin provides notebook server management and pipeline visualization. The Karpenter plugin surfaces node pool status and provisioner decisions. Install only what your teams actively use — the base Headlamp install is clean without them. Stack Archive has covered Kubernetes backup tooling in the CNCF ecosystem for additional context on complementary tools.

Step 6: Decommission Kubernetes Dashboard

After a one-to-two week parallel period where both tools are available:

kubectl delete -n kubernetes-dashboard \
  deployment kubernetes-dashboard \
  service kubernetes-dashboard \
  serviceaccount kubernetes-dashboard

Update runbooks, access documentation, and any bookmarks pointing to the old Dashboard URL.

The Trap

Don’t cut over on day one in a shared cluster. The temptation is to install Headlamp and immediately remove Dashboard to force adoption. The actual result is that three developers are paged because their bookmarked cluster URL returns 404, one team discovers their monitoring workflow depended on a Dashboard-specific RBAC binding, and you spend the afternoon rebuilding access patterns. Run both in parallel for at least a week. Shared clusters have dependencies you haven’t mapped yet.

Cited References

• Kubernetes Blog: Kubernetes Dashboard to Headlamp: A Step-by-Step Guide
• Headlamp official documentation
• Kubernetes Blog: Operating AI/ML Workloads on Kubernetes: A Headlamp Plugin for Kubeflow

Source: Kubernetes Blog

Content created with AI assistance and reviewed for accuracy.