PKR-Lab

Headlamp Kubernetes UI — Design Spec

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/archiv/superpowers/specs/2026-05-16-headlamp-design.md

Headlamp Kubernetes UI — Design Spec

Date: 2026-05-16
Status: Approved

Overview

Add Headlamp as a Kubernetes web UI to the home-server stack, deployed via ArgoCD GitOps following the existing argocd/apps/* Helm-chart pattern.

Goals

Architecture

Approach

Wrapper Helm chart in argocd/apps/tech/headlamp/ with the official headlamp-k8s/headlamp chart as a dependency. ArgoCD runs helm dependency build natively; no extra pipeline steps needed.

Directory Structure

argocd/apps/tech/headlamp/
├── Chart.yaml                      # wrapper chart + headlamp dependency
├── values.yaml                     # ingress, SA, resource overrides
└── templates/
    ├── clusterrolebinding.yaml     # headlamp SA → cluster-admin
    └── token-secret.yaml           # long-lived kubernetes.io/service-account-token

Components

Component Details
Deployment Official headlamp-k8s/headlamp chart, latest stable
Namespace headlamp (created automatically by ArgoCD syncOptions)
ServiceAccount headlamp (created by upstream chart)
ClusterRoleBinding headlamp SA → cluster-admin
Token Secret headlamp-admin-token, type kubernetes.io/service-account-token
Ingress Traefik, host headlamp.homeserver

Configuration

Ingress

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: headlamp.homeserver
      paths:
        - path: /
          pathType: Prefix

Resources

resources:
  requests:
    cpu: 50m
    memory: 64Mi
  limits:
    cpu: 200m
    memory: 128Mi

Token Retrieval

After ArgoCD syncs the app, retrieve the admin token once:

kubectl get secret headlamp-admin-token -n headlamp \
  -o jsonpath='{.data.token}' | base64 -d

Paste this token into the Headlamp login screen. The browser caches it for future visits.

Non-Goals