AI
Headlamp: A Kubernetes GUI Built for Extension
Headlamp is a graphical Kubernetes UI under SIG UI, the same umbrella that hosted Kubernetes Dashboard before it was archived in 2025. It runs as a desktop app, in-cluster, or as a deployed service, and ships extensions for Docker, Podman Desktop, and Backstage. It requires nothing installed inside Kubernetes, and the UI adapts to RBAC permissions: if a user cannot delete a resource, no delete button appears. The plugin catalog itself is a plugin, so deployments that do not need it can simply omit it.
What Headlamp Plugins Can and Cannot Do
Plugins are JavaScript bundles loaded dynamically at runtime. They can register new routes, add toolbar buttons, change branding, query the Kubernetes API, and detect whether Headlamp is running on the desktop or in-cluster. Not every internal surface is exposed. Each new API the team opens becomes a maintenance commitment they must carry forward. Rocha noted the team has not intentionally broken plugin API compatibility yet. New plugin hooks are added on a need basis, so opening a GitHub discussion is the fastest path to getting one added.
When a Fork Makes Sense
Three situations justify a fork. First, plugins cannot reach the specific change needed. Second, a PR could sit in review for weeks while a release deadline is tomorrow. Third, a security fix is ready but the next Headlamp release is still a week out. Rocha also flags what he calls organization practicality: extracting a tarball and applying patches manually is not a fork strategy, git exists for good reason. A “friendly fork” with a small delta is manageable. A fork that diverges across many files becomes hard to rebase and harder to maintain.
Three Ways to Structure a Headlamp Fork
A plain clone puts plugin files and changed Headlamp files in one tree. It is simple but the repo structure mirrors Headlamp’s, including its GitHub Actions CI. A git subtree imports Headlamp into a subdirectory as a single squashed commit, giving a clean file layout, but there is no subtree rebase command. A git submodule keeps plugin history and Headlamp history fully separate and makes rebasing easier because only the downstream commits sit on top of the Headlamp tree. The cost is that submodules are not intuitive, and most people who have used them have opinions.
Submodule in One Repo: The AKS Desktop Pattern
AKS Desktop solved the two-repo problem by pointing the submodule at a different branch inside the same repository. Plugin code lives on one branch; the Headlamp fork lives on an orphan branch with its own history. Committing a change to the Headlamp folder pushes to the fork branch, then a pointer update in the plugin branch records the new commit. The git history looks identical to the two-repo submodule approach. The submodule pain does not go away, but scripts that wrap the common update commands reduce the friction to something workable.
Fork Maintenance: Atomic Commits and Frequent Rebases
Mixing plugin changes and Headlamp core changes in one commit means the next rebase surfaces a conflict that implicates both. Atomic commits, one concern per commit, avoid that. The fewer commits in the fork, the less maintenance burden. Label commits intended for upstream so they are easy to find six months later. Rebase early and often: Rocha’s threshold is that forgetting what you did three months ago is better than forgetting what you did six months ago. Send changes upstream as frequently and as close to the project’s conventions as possible.
Notable Quotes
By for by fork I mean I mean essentially what sometimes is called a friendly fork or a lean fork is basically it is a fork, right? You clone the project and you you’re responsible for that clone. Joaquim Rocha · ▶ 08:57
the the g subm module pane Um, how do you work around the pain? You don’t. You endure. Joaquim Rocha · ▶ 21:47
The answer is whatever rocks your boat. Joaquim Rocha · ▶ 23:05
the the less commits you have in your fork like I said the least burden on you for for maintaining it just offload that to us as maintainers. Joaquim Rocha · ▶ 25:28
Key Takeaways
- Headlamp plugins cover most use cases; forks are for when they cannot reach the needed change.
- Git submodule pointing to a branch in the same repo keeps history clean without a second remote.
- Atomic commits and frequent rebases are the two habits that make a friendly fork survivable.
About the Speaker(s)
Joaquim Rocha is a Founding Engineer at Amutable and a Headlamp maintainer. He has contributed to Free and Open Source Software for 15 years, spanning the Linux desktop and phones through to cloud-native projects. He is Kubernetes SIG UI Lead and an Emeritus Member of the GNOME Foundation, and has spoken at KubeCon and GUADEC.