Kubernetes Dashboard to Headlamp: A Practical Migration Guide

by

Why Move from Kubernetes Dashboard to Headlamp?

Kubernetes Dashboard and Headlamp both visualize cluster state, but they operate on fundamentally different models. Kubernetes Dashboard is a web application strictly confined to the cluster, relying on ServiceAccount tokens for access. Headlamp, in contrast, is designed as a client with a UI. It can run on your desktop using your existing kubeconfig, supporting multi-cluster workloads natively, or be deployed inside the cluster for shared access.

This guide walks through the architectural differences, installation paths, authentication strategies, and the migration process from Dashboard to Headlamp.

Architecture and Access Models

Understanding the deployment model is critical before migrating:

  • Headlamp (Desktop): Runs on your machine, reads your kubeconfig, and uses your existing identity and RBAC rules. It requires no cluster resources and supports multiple clusters in one interface.
  • Headlamp (In-Cluster): Runs as a Kubernetes workload (often via Helm). It uses a ServiceAccount to access the API and follows RBAC rules. This is best for shared, browser-based access managed by platform teams.
  • Kubernetes Dashboard: Always runs in-cluster. It relies on ServiceAccount tokens and is typically tied to a single cluster at a time.

Installation Options

You can choose the installation path that fits your use case.

Option A: Desktop Installation

The fastest way to start is on your desktop. Headlamp reads your kubeconfig, so no separate token management is required.

  • Windows: winget install headlamp or choco install headlamp.
  • macOS: brew install --cask headlamp.
  • Linux: flatpak install flathub io.kinvolk.Headlamp.

Option B: In-Cluster Installation

Use this path for shared access managed by cluster administrators.

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

After installation, verify the pod and service are running:

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

Authentication and RBAC

Headlamp respects your cluster's existing security model.

Desktop Authentication

On the desktop, Headlamp uses the same credentials as kubectl. Ensure your kubeconfig is valid before starting:

kubectl config current-context
kubectl get nodes

In-Cluster Authentication

For shared access, you need a sign-in plan. Headlamp supports OpenID Connect (OIDC). The callback URL must be your Headlamp URL plus /oidc-callback (e.g., https://headlamp.example.com/oidc-callback).

If Headlamp is behind an ingress, ensure it forwards the X-Forwarded-Proto header to maintain HTTPS in callbacks.

Deployment Workflow: Forms vs. YAML

The most significant workflow change is the shift from forms to manifests. Headlamp does not include a multi-step deployment wizard. Instead, it focuses on YAML.

  • Create Resources: Select a cluster and namespace, click Create, and paste or upload a YAML manifest. Click Apply to deploy.
  • Generate YAML: Use kubectl create deployment ... --dry-run=client -o yaml to generate a manifest, edit it, and apply it in Headlamp.

Key Features: Map View and Multi-Cluster

Headlamp introduces features that simplify complex clusters:

  • Map View: Visualizes relationships between Deployments, ReplicaSets, Pods, and Services, aiding in troubleshooting.
  • Multi-Cluster: Switch clusters directly in the UI without changing tools, provided they are in your kubeconfig.

Migration and Cleanup

When migrating, a parallel rollout is recommended. Once Headlamp is stable:

  1. Uninstall Kubernetes Dashboard using the method you used to install it (e.g., helm uninstall kubernetes-dashboard -n kubernetes-dashboard).
  2. Security Cleanup: Review and remove Dashboard-specific service accounts and ClusterRoleBindings to reduce long-lived credentials.

Headlamp becomes your default Kubernetes UI, offering a flexible, multi-cluster client experience.