Skip to main content
Version: 7.13.x

Headlamp

Modern, actively maintained Kubernetes web UI with OAuth2 Proxy integration examples.

Key features:

  • Active development and maintenance
  • Modern, intuitive interface
  • Multi-cluster support
  • Plugin system
  • Works with all OAuth2 providers

Configuring for use with Headlamp​

Headlamp is a modern, user-friendly Kubernetes web UI that can be integrated with OAuth2 Proxy for authentication. This is a recommended alternative to the deprecated Kubernetes Dashboard.

Architecture​

User → Ingress → OAuth2 Proxy → Authentication Provider (e.g., Azure Entra ID)
                      ↓
                  Headlamp

Prerequisites​

  • Kubernetes cluster (e.g., AKS, EKS, GKE, or self-hosted)
  • Headlamp installed in the cluster
  • OAuth2 provider configured (Azure Entra ID, Google, GitHub, etc.)
  • Ingress controller (Nginx, Traefik, etc.)

Configuration Overview​

When integrating Headlamp with OAuth2 Proxy, the OAuth2 Proxy acts as a reverse proxy in front of Headlamp:

  1. User requests access to Headlamp
  2. Ingress forwards to OAuth2 Proxy
  3. OAuth2 Proxy authenticates the user via the OAuth2 provider
  4. After successful authentication, OAuth2 Proxy proxies requests to Headlamp
  5. Headlamp receives the authenticated user information via headers

OAuth2 Proxy Configuration​

Configure OAuth2 Proxy to proxy to the Headlamp service:

upstreamConfig:
  upstreams:
    - id: headlamp
      path: /
      uri: http://headlamp-service.headlamp-namespace.svc.cluster.local:4466

Enable the necessary headers:

extraArgs:
  reverse-proxy: true
  pass-authorization-header: true
  set-xauthrequest: true
  email-domain: "*"  # Or restrict to your organization

Example with Azure Entra ID on AKS​

For detailed instructions on deploying Headlamp with OAuth2 Proxy on Azure Kubernetes Service using Azure Entra ID, see the official Headlamp documentation:

https://headlamp.dev/docs/latest/installation/in-cluster/aks-cluster-oauth/

Key steps include:

  1. Set up AKS with OIDC: Enable Microsoft Entra ID authentication with Kubernetes RBAC
  2. Create Azure App Registration: Configure redirect URI and create client secret
  3. Deploy Headlamp: Install Headlamp via Helm in your cluster
  4. Deploy OAuth2 Proxy: Configure OAuth2 Proxy with Entra ID provider settings and upstream pointing to Headlamp
  5. Configure Ingress: Set up Ingress to route traffic through OAuth2 Proxy to Headlamp
  6. Set RBAC Policies: Apply Kubernetes RBAC bindings based on users or groups

Integration with Other Providers​

The same integration pattern works with other OAuth2 providers supported by OAuth2 Proxy:

  • Google: Use the Google provider configuration
  • GitHub: Use the GitHub provider configuration
  • GitLab: Use the GitLab provider configuration
  • Keycloak: Use the Keycloak OIDC provider configuration
  • Any OIDC Provider: Use the generic OIDC provider configuration

For provider-specific configuration examples, see the OAuth Provider Configuration documentation.

Benefits Over Kubernetes Dashboard​

Headlamp offers several advantages:

  • Active Development: Headlamp is actively maintained and developed
  • Modern UI: Clean, intuitive interface with better UX
  • Plugin System: Extensible with custom plugins
  • Multi-cluster Support: Built-in support for managing multiple clusters
  • Desktop App: Available as both web UI and desktop application
note

If you set up your OAuth2 provider to rotate your client secret, you can use the client-secret-file option to reload the secret when it is updated.