Skip to content

Headlamp RBAC

Headlamp presents Kubernetes resources using the permissions associated with the credential used for an API request. Treat access to the UI and any ClusterRole or ClusterRoleBinding created by this package as a security boundary.

Package-managed bindings

The bigbang.rbac values section can create cluster-scoped roles and bindings:

  • bigbang.rbac.enabled enables package-managed RBAC resources.
  • bigbang.rbac.clusterRoles defines roles that the chart creates when the entry’s create value is true or omitted.
  • bigbang.rbac.clusterRoleBindings binds a role name to ServiceAccount, User, or Group subjects.

Use Kubernetes RBAC rules appropriate for the resources and verbs required by the intended users. The chart does not validate that a role is least-privilege, that a referenced role exists, or that an identity-provider claim matches a binding subject.

upstream:
  clusterRoleBinding:
    create: false
bigbang:
  rbac:
    enabled: true
    clusterRoles:
      - name: headlamp-readonly
        create: true
        rules:
          - apiGroups: [""]
            resources: ["pods", "services", "namespaces"]
            verbs: ["get", "list", "watch"]
    clusterRoleBindings:
      - name: headlamp-readonly-users
        roleRef: headlamp-readonly
        subjects:
          - kind: Group
            name: headlamp-readers
            apiGroup: rbac.authorization.k8s.io

This is a shape example, not a recommended permission set. Do not bind cluster-admin or permissions to read Secrets unless that access has been explicitly reviewed. These are package values; umbrella v1 deployments put them under packages.headlamp.values, and legacy deployments use addons.headlamp.values.

The upstream chart otherwise creates a cluster-admin binding for its service account by default. bigbang.rbac.enabled does not disable that binding; upstream.clusterRoleBinding.create: false above does. Review existing bindings and the service account’s actual application requirements as well. Do not enable upstream.config.unsafeUseServiceAccountToken to bypass per-user authorization.

Identity subjects

For a ServiceAccount subject, specify the name and, when required, the namespace. The chart renders service-account subjects with the release name or release namespace as defaults and creates a ServiceAccount for every configured service-account subject. Review the rendered name and namespace before relying on defaults.

For Group and User subjects, use the exact name recognized by the Kubernetes API server. If OIDC is enabled, that depends on the API server’s issuer, username and group-claim configuration, and any configured prefixes. Configure the identity provider and API server outside this chart, then bind the resulting Kubernetes subject here. See OIDC and Keycloak integration.

Verify access

Render the chart and review its ClusterRole and ClusterRoleBinding objects before deployment. In a suitable non-production environment, use Kubernetes authorization checks for the real subject and the operations it needs. The package’s render and UI tests do not prove effective API-server authorization or identity-provider claim contents.

Confirm the selected kubeconfig and inspect the intended binding and role (substitute their actual names):

kubectl config current-context
kubectl get clusterrolebinding headlamp-readonly-users -o yaml
kubectl get clusterrole headlamp-readonly -o yaml

For the SSO example, suppose the API server maps the test user to oidc:alice and their group to oidc:headlamp-readers. An administrator authorized to impersonate that user and those groups can submit these authorization reviews without reading pod data or changing bindings:

TEST_USER="oidc:alice"
TEST_GROUP="oidc:headlamp-readers"
TEST_NAMESPACE="replace-with-intended-namespace"
kubectl auth can-i list pods -n "$TEST_NAMESPACE" \
  --as="$TEST_USER" --as-group="$TEST_GROUP" --as-group=system:authenticated
kubectl auth can-i get secrets -n "$TEST_NAMESPACE" \
  --as="$TEST_USER" --as-group="$TEST_GROUP" --as-group=system:authenticated

With only the example role/binding, expect yes for listing pods and no for reading Secrets. Kubernetes permissions are additive: another binding can make the second check return yes. Impersonation uses the groups supplied in the command, not an IdP lookup; repeat --as-group for the actual relevant groups. A denied impersonation request means the administrator cannot perform the test, not that the user’s resource permission is necessarily denied. Do not grant broad impersonation rights merely to run this example.

These checks test RBAC for supplied subjects, not acceptance of the OIDC token. Where available, also run kubectl auth can-i list pods -n "$TEST_NAMESPACE" using the test user’s own approved OIDC kubeconfig without impersonation. Never put bearer tokens on a command line or share them in troubleshooting output. Verify both a permitted UI operation and an operation that should remain forbidden. See the SSO troubleshooting checklist when login succeeds but the UI cannot retrieve resources.

See the Kubernetes RBAC authorization documentation for rules, subjects, and authorization behavior.