Skip to main content

Headlamp UI Overview

Purpose: For platform engineers, explains what Headlamp provides including branding, themes, and plugin architecture.

Repository

Headlamp plugin development and branding customization are not CLI features. The Headlamp deployment manifests and base configuration are maintained in the openCenter-gitops-base repository. The branding plugin source lives in the headlamp-branding-plugin monorepo. The openCenter-cli does not manage Headlamp directly.

What Headlamp Is​

Headlamp is an open-source Kubernetes web UI that openCenter deploys as the default cluster dashboard. It ships as a single container (ghcr.io/headlamp-k8s/headlamp) and exposes a plugin system that lets teams extend the interface without forking the upstream project.

openCenter uses Headlamp for two things:

  1. Giving operators a visual interface to cluster resources (pods, deployments, services, config maps, etc.)
  2. Applying openCenter branding and themes through the @opencenter/headlamp-plugin-branding plugin.

Headlamp is deployed via FluxCD from openCenter-gitops-base and lands in the headlamp namespace.

Plugin Architecture​

Headlamp exposes a JavaScript plugin API through the @kinvolk/headlamp-plugin package. Plugins are CommonJS bundles loaded at startup from a /headlamp/plugins/ directory inside the container. Each plugin gets its own subdirectory containing a main.js entry point and any static assets.

The plugin API provides registration functions that hook into the UI lifecycle:

  • registerAppLogo — replaces the default Headlamp logo in the sidebar
  • registerAppTheme — adds a selectable theme to Settings → Appearance
  • registerRoute — adds custom pages and navigation entries
  • registerSidebarEntry — adds items to the sidebar navigation
  • registerDetailsViewHeaderAction — adds action buttons to resource detail views

Plugins run entirely client-side. They have no server component and make no network calls beyond what the Headlamp frontend already does against the Kubernetes API.

openCenter Branding Plugin​

The @opencenter/headlamp-plugin-branding plugin lives in the headlamp-branding-plugin/ monorepo and provides:

Custom logos — Two PNG variants (logo.png for light themes, logo_dark.png for dark themes). The AppLogo component receives logoType and themeName props from Headlamp and selects the correct variant. Logo sizing adapts to sidebar state: 48px max-height when expanded, 32px when collapsed.

Two themes:

ThemeTypePrimary ColorBackgroundUse Case
OpenCenter Cloud DayLight#C8102E (Red)#F3F3F3 (Light Gray)Production dashboards, customer-facing
OpenCenter Abyssal NightDark#E63D4F (Bright Red)#121824 (Dark Blue)NOC displays, developer environments

Themes are registered via registerAppTheme() and appear in the Headlamp settings dropdown. The selected theme persists across page reloads via browser local storage.

How Headlamp Fits the Platform​

Headlamp integrates with several openCenter platform services:

  • Keycloak — OIDC authentication. Users log in through Keycloak, and Headlamp respects the RBAC bindings managed by RBAC Manager.
  • cert-manager — TLS termination for the Headlamp ingress.
  • Gateway API / Ingress NGINX — External access routing.
  • Harbor — The Headlamp container image is mirrored through Harbor for air-gap deployments.

Headlamp itself is stateless. It reads cluster state through the Kubernetes API using the authenticated user's token, so it shows exactly what the user's RBAC permissions allow.

Deployment Model​

FluxCD reconciles the Headlamp HelmRelease from openCenter-gitops-base. The branding plugin is injected via a ConfigMap or init container that places the built plugin artifacts into the /headlamp/plugins/branding/ path inside the Headlamp pod.

In air-gap environments, both the Headlamp image and the plugin artifacts are packaged into the Zarf bundle by openCenter-AirGap. No internet access is required at runtime.

Further Reading​