Skip to main content

Data Flow: Headlamp UI

Purpose: For platform engineers, explains how operators access the cluster through Headlamp UI, authenticated via Keycloak OIDC and scoped by RBAC.

Flow Summary​

Components​

ComponentNamespaceRole
MetalLBmetallb-systemExposes Headlamp via external IP
Gateway APIgateway-systemRoutes HTTPS traffic to Headlamp service
HeadlampheadlampKubernetes web dashboard with plugin support
KeycloakkeycloakIssues OIDC tokens for Headlamp authentication
RBAC Managerrbac-managerMaps group claims to RoleBindings
Kubernetes APIkube-systemServes resource requests scoped by user's RBAC

Sequence​

  1. Operator opens Headlamp URL in browser.
  2. Request hits MetalLB external IP, forwarded to Gateway API.
  3. Gateway API terminates TLS and routes to the Headlamp service in the headlamp namespace.
  4. Headlamp redirects to Keycloak for OIDC authentication.
  5. Operator authenticates against the upstream IdP (via Keycloak federation).
  6. Keycloak issues a JWT with group claims; browser stores the token.
  7. Headlamp uses the token to proxy requests to the Kubernetes API server.
  8. API server validates the JWT, extracts groups, and enforces RBAC.
  9. Operator sees only the resources their RoleBindings permit.

Deployment​

Headlamp is deployed via FluxCD from openCenter-gitops-base. The branding plugin (@opencenter/headlamp-plugin-branding) is injected as an init container or ConfigMap mount. Plugins run entirely client-side — no server component beyond the Headlamp container itself.