# Headlamp: a Kubernetes web UI that outgrew its original org name

> A Kubernetes dashboard built around plugins, desktop use and RBAC-aware controls, now maintained under the Kubernetes SIG UI after moving into the kubernetes-sigs organisation.

**kubernetes-sigs/headlamp** — A Kubernetes web UI that is fully-featured, user-friendly and extensible

- Repository: https://github.com/kubernetes-sigs/headlamp
- Website: https://headlamp.dev
- Stars: 7,425 · Forks: 1,151
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/kubernetes-sigs-headlamp

## A UI that recently changed address mid sentence

The first thing the README does is apologise. A notice at the top says the project has moved under the Kubernetes SIG UI, that the repository now lives in the kubernetes-sigs organisation, and that container images are still published under the old headlamp-k8s name. It asks readers to bear with possible broken links while that settles.

That single notice explains a lot of what the rest of the repository looks like. The project has 7,314 stars and 1,113 forks, the language is TypeScript, and the licence is Apache 2.0. The tree shows a frontend, a Go backend, a separate desktop application directory, Helm charts, a Docker extension, an end to end test suite and a load test suite. There is also a directory named `backstage-test`, which is an unusual thing to find in a Kubernetes dashboard and hints at a plugin that has been tested against Backstage somewhere along the way.

The topics list is long and includes `kubernetes-dashboard`, `kubernetes-ui` and `kinvolk`, the company the project originally came out of. The last push was on 2026-09-17, so the code is moving even while the identity is in transition.

## Feature claims that describe a policy-aware UI, not just a lister

The feature list is short, and one line in it does most of the work: UI controls reflecting user roles, with no deletion or update offered if the user is not allowed. Another line claims read-write and interactive behaviour based on permissions. That is a design decision rather than a feature checkbox, because most dashboards render a delete button and let the API server return a 403 later.

Headlamp checks Kubernetes RBAC itself and shapes the interface around the answer. The README is blunt about the consequence: if you try it with a token that has very limited permissions, you may not be able to view your cluster resources correctly. That is a real operational difference from kubectl, which will always show you a verb it will not let you perform. If you plan to give people a read-only token, expect a read-only UI, including an empty-looking cluster view rather than an error.

Other lines worth taking seriously are cancellable creation, update and deletion operations, logs plus exec plus a resource editor with inline documentation, multi-cluster support, and a choice of running in-cluster or as a desktop app. Vendor independence is claimed outright, which is the interesting one for anyone currently using a cloud console.

## Two consecutive releases spent on scale and startup cost

Version 0.44.0, published 2026-07-29, is mostly a performance release with an unusually specific list. Cluster support is extended past 30,000 pods, pod lists fetch 1,000 items at a time, the cluster overview avoids unbounded watch traffic, and Brotli pre-compression cuts typical JavaScript and CSS transfers by 75 to 80 percent while taking server-side compression load to zero. It also stops connecting to every configured cluster at startup, which the notes describe in terms of not wanting to open several browser login windows. That one line tells you the multi-cluster implementation uses ordinary credential flows rather than a single shared session.

Version 0.45.0 followed on 2026-08-20 and reduced desktop startup memory and background requests, added scheduling and Gateway API views, and shipped guided resource creation forms. It also lists 31 bug fixes across authentication, port forwarding, the resource map, tables and the desktop app.

Between them, the two releases tell you where the real complaints were. Bugs cluster in authentication, port forwarding and large-manifest editing, and a separate 0.44.0 note mentions protections against white-screen startup failures on Windows when developing Headlamp. A dashboard whose open issues number 1,484 against 7,314 stars is collecting a lot of platform-specific friction, which fits a project that ships three installation paths.

## Plugins are the point, and they arrive from outside the repo

Extensibility is listed as a feature and immediately linked out, because the plugins do not live in this repository. Official plugins sit in a separate headlamp-k8s plugins repository, and published ones are indexed on Artifact Hub, which the README uses as the discovery path.

That arrangement has consequences the README does not spell out. Version 0.45.0 lists verifying external plugin archives as a security fix, which tells you plugins are fetched as archives from somewhere and that the trust boundary is a download. The same release notes describe a plugin internationalisation change where translation files are fetched only for the active locale, described as a fix for a flood of 404 requests when a plugin declares several languages. Both are symptoms of the same thing: a plugin is a bundle of frontend assets loaded into the same page, so its behaviour and its bandwidth cost are part of your dashboard's behaviour.

For a team writing internal tooling, this is the draw. Anything you need that the core UI does not show is a plugin you write once and distribute, and the plugin development guide is linked for that purpose.

## Three organisations, one product

Follow the identifiers through the build files and you find the migration is not finished. The module path in `package.json` is `github.com/kubernetes-sigs/headlamp`, and the Makefile stamps the version into that same path. But the same Makefile sets the image repository default to the old organisation, and the Dockerfile builds from pinned base images while the FOSSA badge in the README still points at the old repository path.

```make
DOCKER_REPO ?= ghcr.io/headlamp-k8s
DOCKER_IMAGE_VERSION ?= $(shell git describe --tags --match 'v*' --always --dirty)
```

The practical effect is narrow but real. If you script a pull by image name from the README rather than from the chart, you will pull from `ghcr.io/headlamp-k8s`, not from the kubernetes-sigs path. The 0.45.0 release also published a separate `headlamp-helm-0.45.0` tag four minutes after the main one, which tells you the Helm chart is versioned and released on its own cadence rather than derived from the application tag.

## What the build files say about the desktop app

The desktop application is not an afterthought in the tree. There is a top-level `app/` directory, the Makefile reads its version and product name out of `app/package.json`, and it defines an embed binary name for the shell that wraps the server. The Docker build has a stage comment that calls out moving the plugin folder for backwards compatibility, which means older layouts are still supported in the image.

The toolchain requirements are stated plainly in the root manifest:

```json
"engines": {
  "npm": ">=11.0.0",
  "node": ">=22.6.0"
}
```

The Go backend builds with a trimmed binary and stripped symbols, and the Dockerfile pins its toolchain images by digest, starting from an Alpine base and a Go 1.26.8 builder. Pinning by digest for a UI project is more conservative than most, and it costs you nothing but a slower first build.

The desktop path matters because it changes the trust model. Running in-cluster means the UI is inside the perimeter you already control and authenticates through the cluster. Running as a desktop app means the UI runs on a laptop and talks to clusters using whatever credentials the kubeconfig holds, which is why the README insists your kubeconfig already lists your favourite clusters in the default path.

## Where the README stops and the docs take over

The README is a directory page more than a manual. Installation is delegated entirely to headlamp.dev, split into an in-cluster page and separate desktop pages for Linux, Mac and Windows. RBAC and service account token creation are documented externally. The FAQ, the plugin development guide, the platform compatibility list and the release roadmap all live off the repository, and the roadmap is a GitHub project board rather than a document in the tree.

That is a reasonable split for a project with this many ways to install it, but it means the repository alone will not answer the questions that decide whether you adopt it. Whether to expose the UI through an ingress, how to hand plugins to users, and what happens when a plugin version and a Headlamp version disagree are all documentation questions.

One thing the repository does answer is how to report platform problems. There is a maintained list of tested Kubernetes platforms, and the README invites readers to add missing ones or comment on regressions. With 1,484 open issues, that invitation is also the honest description of how this project absorbs platform diversity.

## Conclusion

Headlamp is at its best when you want a cluster UI that respects the permissions you already have and lets your own team add the screens you keep building in separate tools. The plugin model and the desktop build are the two reasons to pick it over a plain resource browser. What the README does not settle is the operational half: how the Helm chart is meant to be exposed, how plugins get distributed to users, and what happens when the org migration catches up with the links. Install the in-cluster guide first, read the plugin development guide next, and treat every link that still points at the headlamp-k8s organisation as a document that has not moved yet.

## FAQ

### How does Headlamp compare with the official Kubernetes dashboard?

Headlamp presents itself as vendor-independent, works as a desktop app as well as in-cluster, and puts plugins at the centre of its extension model. Its distinguishing behaviour is that it reads Kubernetes RBAC and removes controls the signed-in user cannot use, so a limited token gives a reduced interface rather than a set of buttons that fail when pressed. The repository does not include a feature-by-feature comparison with the official dashboard, so that comparison belongs in your own evaluation.

### Can Headlamp run outside the cluster as a desktop app?

Yes. The README describes running Headlamp locally as a desktop application for Linux, Mac and Windows, using a kubeconfig that already lists your clusters in the default location. Separate installation pages exist for each platform. The trade is that the UI then runs on your machine and authenticates with your kubeconfig credentials rather than sitting behind the cluster's own authentication.

### What can plugins add to Headlamp?

Plugins extend the UI with new views and functionality, and they are the documented path for tailoring Headlamp to a specific use case. Official plugins live in a separate repository and published ones are listed on Artifact Hub, so discovery happens outside this project. Version 0.45.0 added verification for external plugin archives, which tells you plugin bundles are downloaded and trusted once installed.

### Why are resources or buttons missing when I open Headlamp?

Headlamp checks RBAC for the user or token it is running as, and controls you are not permitted to use are removed from the interface rather than shown and then refused. The README warns that a token with very limited permissions may not show your cluster resources correctly at all. To get a fuller view you need a token with broader permissions, created through the documented service account token process.

### How do I report a problem on a Kubernetes platform you have not tested?

The project maintains a list of Kubernetes platforms it has tested Headlamp against, and invites readers to add platforms they have tested or to comment when they hit a regression in an existing one. There is also a community meeting and a Slack channel linked from the README for anything that does not fit an issue.

## Sources

- [kubernetes-sigs/headlamp on GitHub](https://github.com/kubernetes-sigs/headlamp)
- [License: Apache-2.0](https://github.com/kubernetes-sigs/headlamp/blob/main/LICENSE)
- [Project website](https://headlamp.dev)
- [README](https://github.com/kubernetes-sigs/headlamp/blob/main/README.md)
- [Releases](https://github.com/kubernetes-sigs/headlamp/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kubernetes-sigs-headlamp