How Headlamp Uses RBAC-Based Controls

Headlamp adapts its interface to the permissions a user already has in a Kubernetes cluster. It does not grant new access or maintain its own permission model — instead, it reads the cluster's Role-Based Access Control (RBAC) rules and shows or hides actions accordingly. This means two users opening the same Headlamp instance can see different available operations, based on what their Kubernetes identity is allowed to do.

What "RBAC-based controls" means in Headlamp

Kubernetes RBAC decides who can perform which verbs (get, list, create, update, delete, etc.) on which resources, scoped by Roles, ClusterRoles, and their bindings. Headlamp sits on top of that system:

• It authenticates as the user (or service account) accessing the cluster.
• It queries the cluster's authorization rules to determine what that identity can do.
• It reflects those results in the UI, so the interface matches the user's actual permissions.

The site describes this directly: "Headlamp adapts to a user's cluster permissions." The practical effect is that Headlamp is not a separate security layer — it is a view onto the permissions Kubernetes already enforces.

How the interface changes by permission level

Because Headlamp mirrors RBAC, the visible feature set varies by role. The table below shows typical patterns; exact behavior depends on the cluster's role definitions.

This is why the same deployment can serve developers, operators, and auditors without separate builds — each person sees the slice of the cluster their RBAC role allows.

Why this matters for teams managing access by role

If your team already governs access through Kubernetes Roles and bindings, Headlamp inherits that governance rather than duplicating it. Benefits include:

• One source of truth. Access changes are made in Kubernetes RBAC, not in a separate UI permission system.
• Consistent enforcement. A user who cannot kubectl delete a pod generally cannot delete it through Headlamp either, because the cluster rejects the action regardless of the UI.
• Lower onboarding friction. New team members get the access their role defines, and Headlamp reflects it automatically.

A caveat worth stating: the UI reflecting permissions is a usability feature, not the security boundary. The cluster's API server remains the enforcer. A hidden button is convenience; a denied API call is the actual control.

Deployment choices and how they interact with RBAC

Headlamp can run as a desktop app or in-cluster, and the permission model differs by mode:

• Desktop app: runs locally and connects to clusters using your local kubeconfig credentials, so it inherits the permissions tied to those credentials. This suits users who want to manage clusters without deploying anything in-cluster.
• In-cluster: deployed into the cluster (for example via Helm, kubectl apply, Minikube addon, Docker Desktop extension, or Glasskube) and typically exposed through an ingress. Here, RBAC applies to how users authenticate to that deployment, and Headlamp adapts to each user's cluster permissions.

For teams that need role-based access control to be visible and consistent across users, the in-cluster deployment is the more natural fit, since access is governed centrally by the cluster's RBAC. The desktop app is better for individuals managing clusters locally with their own credentials.

How to verify the behavior yourself

1. Confirm your current identity and permissions, for example with kubectl auth can-i --list.
2. Open Headlamp using those same credentials (desktop) or sign in to the in-cluster instance.
3. Compare the actions offered in the UI against what kubectl auth can-i <verb> <resource> reports.
4. Switch to an identity with a narrower role and reload; the available actions should shrink to match.

If the UI and kubectl disagree, check which kubeconfig context or service account Headlamp is using — a mismatch there is the most common cause.

Headlamp is an official Kubernetes sub-project and part of SIG UI, so its permission behavior follows standard Kubernetes authorization rather than a proprietary scheme.