Where Does Headlamp Find Clusters and Settings?
Headlamp reads clusters from your kubeconfig file, with desktop preferences in the OS app data folder.
Last updated
Headlamp does not store your clusters itself. It reads the standard kubeconfig file that kubectl uses, defaulting to .kube/config in your home directory. Add a cluster there and Headlamp lists it.
The desktop app adds a small preferences layer for theme and recent context on top. In-cluster deployments instead use a service account and ignore local files. When clusters disagree between tools, the kubeconfig file is the source both sides share.
Where Headlamp stores this, by platform
~/.kube/config
Default cluster source for kubectl and Headlamp alike. KUBECONFIG env can point elsewhere or merge several files. Desktop theme choices live separately in OS app data.
~/.kube/config
Same default path through your home folder. Docker Desktop and Rancher Desktop write here too, so Headlamp picks those clusters up automatically.
C:\Users\[username]\.kube\config
Same file under your profile. Use %KUBECONFIG% to override per shell. Line endings inside stay Unix style even on Windows.
Frequently asked questions
How do I add a cluster to Headlamp?
Edit ~/.kube/config with kubectl config commands or by hand, then refresh Headlamp. The dashboard reflects the file on load. Keep contexts minimal, since every entry appears in the cluster picker.
Can Headlamp use several kubeconfigs?
Set KUBECONFIG to a colon separated list before launching Headlamp. All listed files merge into one view. Desktop and in-cluster modes honor the same variable.
Notice an outdated path? Let us know.