Dora NodaFor years, the honest answer to "how do I see the state of my Cluster API fleet?" was a stack of terminal incantations: kubectl get clusters -A, then clusterctl describe cluster with the right combination of --show-conditions and --grouping flags, then a mental traversal of the Cluster → ControlPlane → MachineDeployment → Machine → InfraMachine ownership chain to figure out which layer was actually stuck. In June 2026, Headlamp — the Kubernetes SIG UI-backed dashboard — shipped an official Cluster API plugin that puts all of that behind a point-and-click interface: a live map of your CAPI resources, human-readable health conditions, and one-click kubeconfig downloads for workload clusters.
Here is the verdict up front, because it is the thing you came for: adopt the plugin for the read path, keep the write path in Git. The plugin genuinely lowers the bar for reading fleet state — enough that an engineer who has never memorized a clusterctl flag can answer "which clusters are unhealthy and why" safely. But it also ships write controls (node scaling from the UI) that will fight your GitOps reconciler if you let them, and at 0.2.0-beta it is a diagnostic surface, not a control plane. The rest of this post is the concrete version of that sentence: what the CLI workflow looks like today, what the plugin replaces (in a side-by-side table), where the GUI is a real win, where it is a trap, and whether a platform team running a self-hosted PaaS should adopt it or keep building their own fleet dashboard.
What Reading a CAPI Fleet Looks Like Without It
Cluster API's whole premise is that clusters are just Kubernetes resources: a management cluster runs controllers that reconcile Cluster, MachineDeployment, and Machine objects into real infrastructure. That declarative model is why CAPI is the right substrate for a fleet. It is also why reading a fleet is hostile to newcomers — the state you care about is smeared across an ownership hierarchy of five or six custom resources per cluster.
The standard read path today looks like this:
# What clusters exist, and are they provisioned?
kubectl get clusters -A
# Why is this one unhealthy?
clusterctl describe cluster prod-eu-1 --show-conditions all
# Which machines back that MachineDeployment?
kubectl get machines -A -l cluster.x-k8s.io/cluster-name=prod-eu-1
# And what infrastructure object is behind the stuck machine?
kubectl get hcloudmachine <name> -o yamlclusterctl describe is genuinely good at its job — it groups machines that share the same state so healthy resources collapse into one line, and it hides bootstrap and infrastructure objects unless their conditions diverge from the machine that owns them. But it presumes you know it exists, know the flags (--show-conditions, --grouping=false, --echo), and can interpret condition names like WaitingForBootstrapData back into "the bootstrap token secret didn't get created."
That knowledge tax is fine for the two platform engineers who built the fleet. It fails at the next tier: the on-call generalist at 3 a.m., the support engineer triaging a tenant complaint, the engineering manager who just wants to know whether the upgrade finished. For them, "learn seven resource kinds and a CLI" is not a reasonable prerequisite for reading a status page.
What the Plugin Actually Ships
Headlamp's Cluster API plugin (maintained in the official headlamp-k8s/plugins repository, alongside plugins for Flux, Karpenter, Metal3, and about twenty others) installs from Headlamp's built-in Plugin Catalog — search "Cluster API," click install. Point Headlamp at your management cluster and the plugin gives you:
- A map view of CAPI resource relationships. The Cluster → ControlPlane → MachineDeployment → Machine → InfraMachine chain rendered as an interactive graph, with hover tooltips for quick diagnostics — the ownership traversal you used to do in your head.
- Human-readable condition tracking. Ready, Paused, and Error states surfaced per resource, without knowing which
kubectl get ... -o yamlto run or which condition name matters. - ClusterClass template visualization. If you use ClusterClass to stamp out clusters from templates, the plugin shows what a class produces — previously an exercise in reading nested YAML.
- One-click kubeconfig download for any workload cluster, replacing the
clusterctl get kubeconfig/ secret-extraction dance. - Node scaling controls in the UI — the one write operation the plugin ships, and the one we will come back to with a warning.
Compatibility is broad: the plugin supports both the v1beta1 and v1beta2 CAPI APIs and is provider-agnostic — Docker, AWS, Azure, GCP, and vSphere are called out, and because it reads the portable CAPI contract rather than provider internals, fleets on providers like Hetzner (via CAPH) get the same view. The version history — 0.1.0-alpha to 0.2.0-beta — tells you where it is in its life: young, moving fast, not yet something to bet a production workflow's write path on.
The requirements are worth noting because they define the safety story: the plugin renders whatever the viewer's RBAC allows. Run Headlamp in-cluster with a read-only ServiceAccount and the UI is structurally incapable of mutating your fleet — which is exactly how you should deploy it for the audience it serves best.
The Table: Fleet Questions, With and Without the Plugin
This is the core of the day-2 story — the questions an operator actually asks, what answering them costs today, and what the plugin changes:
| Fleet question | CLI path today | With the plugin | Real win? |
|---|---|---|---|
| Which clusters exist and are they healthy? | kubectl get clusters -A, then per-cluster clusterctl describe | Sidebar list with condition badges | Yes — one glance, no flags |
| Why is this Machine stuck? | clusterctl describe cluster X --show-conditions all, then kubectl get the infra machine | Click the machine on the map, read conditions in the tooltip | Yes — the ownership chain is drawn for you |
| What does this ClusterClass produce? | Read nested YAML across templates | ClusterClass visualization | Yes for template-based fleets |
| Get me a workload-cluster kubeconfig | clusterctl get kubeconfig X > kc.yaml or extract the secret | Single-click download | Convenient — but see the RBAC caveat below |
| Scale this node pool | Edit replicas in Git, let the reconciler roll it | Scale control in the UI | No — this is the trap if you run GitOps |
| Roll out a Kubernetes version upgrade | Change the version in Git, watch the rolling update | Watch it: the plugin shows machine turnover live | Read yes, write no |
The pattern in the last column is the whole thesis: every read row is an unambiguous improvement, and both write-adjacent rows come with an asterisk.
Where It Genuinely Lowers the Bar
The plugin's real contribution is not saving experts keystrokes — clusterctl describe was already fine for experts. It is that fleet state stops being gated on CLI fluency.
Deployed in-cluster behind your SSO with a read-only ServiceAccount, Headlamp plus this plugin is a fleet status page that the on-call generalist, the support engineer, and the EM can all read without anyone teaching them what a MachineDeployment is. The map view does the thing documentation never manages: it teaches the CAPI object model by showing it, one hover at a time. "Safely" is carried by RBAC, not by trust — a viewer with read-only permissions cannot press a button the ServiceAccount can't execute.
Timing makes this more significant than one plugin release normally would be. Kubernetes Dashboard — the default answer to "just give me a GUI" for a decade — is now archived, and Headlamp (an official SIG UI sub-project, adopted by Microsoft, Oracle, and Swisscom among others) is its designated successor, publishing migration guides as of May 2026. That means the maintained, CNCF-adjacent GUI path for Kubernetes now has first-party Cluster API coverage. A free fleet dashboard with SIG backing is a materially different proposition than a random VC-backed observability SaaS wrapping your management cluster: no per-seat pricing, no wondering whether it exists in three years, and it runs on your machines — the same posture that gets teams self-hosting their PaaS in the first place.
The desktop-versus-in-cluster split matters here too. Platform engineers can run the desktop app against their own kubeconfig with their own (write-capable) permissions; everyone else gets the shared read-only in-cluster deployment. Same UI, two trust tiers, zero custom code.
Where It Can't Replace a GitOps Loop
Now the asterisks.
The scale button versus your reconciler. Suppose your MachineDeployments are managed by Flux or Argo CD, with replicas: 3 committed in Git. An operator uses the plugin's scaling control to bump a hot node pool to 5. It works — for up to a sync interval. Then the reconciler notices live state diverged from Git and reverts to 3, draining the two new nodes, possibly mid-incident. Worse, nothing in the UI tells the operator why their change evaporated. Every imperative write control pointed at declaratively-managed resources has this failure mode; the plugin didn't invent it, but it does put a friendly button on it. If you run GitOps — and if you operate a CAPI fleet seriously, you do — treat the scale control as something to disable via RBAC on the shared deployment, not a feature to socialize.
The kubeconfig button is a privilege statement. Workload-cluster kubeconfigs live as secrets in the management cluster, typically with cluster-admin on the workload side. A UI that offers them as a single click is only as safe as the ServiceAccount behind it — grant the shared Headlamp deployment secret-read on those namespaces and you have quietly made "can log into the dashboard" equivalent to "can admin every workload cluster." Scope it deliberately.
No audit trail, no review, no rollback. A Git-driven change is a PR: reviewed before it lands, attributed forever, revertible with one command, and replayable when you rebuild the management cluster from scratch. A UI click is none of those things. The plugin has no opinion about this — it is a viewer with a couple of write conveniences, not a deployment system — which is precisely why the write path has to stay in Git.
Beta is beta. At 0.2.0-beta, expect UI edges and expect the feature set to shift. That is a fine risk profile for a read-only status surface and a poor one for anything in the critical path of mutations.
Should a Self-Hosted PaaS Build Its Own Fleet Dashboard?
For teams running a Cluster API-based platform, this plugin sharpens a build-versus-adopt question, and the answer splits cleanly along one line: who is looking at the screen?
Operator-facing fleet view: adopt, don't build. An internal dashboard showing CAPI clusters, machines, and upgrade state is undifferentiated work — every hour spent building one is an hour not spent on the platform your users actually touch, and your homegrown React app will lose to a SIG-maintained project on every axis that matters within a year. Point Headlamp at the management cluster, install the plugin, scope the RBAC read-only, done.
Tenant-facing surface: still yours, necessarily. Your users think in apps, deploys, and URLs — not Machines and ClusterClasses. No CAPI-shaped viewer, however polished, can be the product surface of a PaaS, because the abstraction is wrong by design. The dashboard your tenants see has to speak the platform's own nouns.
At Bex.co this boundary is explicit. The fleet under the platform is Cluster API-managed, so operators can point Headlamp's plugin at the management cluster today and get the map view for free — no custom fleet dashboard on the roadmap. The tenant surface, meanwhile, is the Render-compatible API and machine-readable service state: git push, get a running HTTPS service, query its status — whether the one asking is a human or an AI agent operating the app. Machines are the operator's vocabulary; apps are the tenant's; the plugin covers the first so the platform can spend its effort on the second.
What to Watch
The interesting question is where the plugin goes next. Upgrade orchestration — plan a fleet-wide Kubernetes version rollout, watch it wave through MachineDeployments — is the obvious growth direction, and also exactly where the GitOps tension will get sharper: the more day-2 actions the UI grows, the more teams will need the discipline (and the RBAC) to keep using it as a window rather than a steering wheel. Watch the release cadence out of beta, and watch whether condition rendering keeps pace as CAPI's v1beta2 API evolves.
But the takeaway stands regardless: reading a Cluster API fleet no longer requires living in kubectl, and it doesn't require buying anything or building anything either. A SIG-backed dashboard with a first-party CAPI plugin, self-hosted on your own machines, closes the gap that made CAPI fleets expert-only territory. Install it read-only, keep your writes in Git, and let the map view teach your whole team what the fleet actually looks like.
Bex.co is the open-source, AI-native Render alternative — push a git repo, get a running HTTPS service on machines you own, on a Cluster API-managed fleet. Star the repo on GitHub or deploy your first app today.
