Headlamp Kubernetes UI Implementation Plan
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/archiv/superpowers/plans/2026-05-16-headlamp.md
Headlamp Kubernetes UI Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Add Headlamp as a Kubernetes web UI accessible at headlamp.homeserver via Traefik Ingress, deployed through the existing ArgoCD GitOps pipeline.
Architecture: Wrapper Helm chart in argocd/apps/tech/headlamp/ with the official headlamp-k8s/headlamp chart as a dependency. Two custom templates handle cluster-admin RBAC and a long-lived ServiceAccount token. The existing ApplicationSet picks up the new directory automatically — no ArgoCD config changes needed.
Tech Stack: Helm 3, ArgoCD ApplicationSet, Traefik Ingress, Kubernetes RBAC
Task 1: Chart.yaml
Files:
-
Create:
argocd/apps/tech/headlamp/Chart.yaml -
Create the wrapper chart descriptor
---
apiVersion: v2
name: headlamp
description: Headlamp Kubernetes web UI deployed via ArgoCD.
type: application
version: 0.1.0
appVersion: "latest"
keywords:
- headlamp
- kubernetes
- dashboard
home: https://headlamp.dev
sources:
- https://github.com/headlamp-k8s/headlamp
maintainers:
- name: home-server-admin
dependencies:
- name: headlamp
repository: https://headlamp-k8s.github.io/headlamp/
version: "*"
- Commit
git add argocd/apps/tech/headlamp/Chart.yaml
git commit -m "feat(headlamp): add wrapper Chart.yaml with upstream dependency"
Task 2: values.yaml
Files:
-
Create:
argocd/apps/tech/headlamp/values.yaml -
Create values with Traefik ingress and resource limits
---
# Values passed through to the headlamp sub-chart.
# All keys live under `headlamp:` because that is the dependency name.
headlamp:
replicaCount: 1
ingress:
enabled: true
ingressClassName: traefik
annotations: {}
hosts:
- host: headlamp.homeserver
paths:
- path: /
pathType: Prefix
tls: []
resources:
requests:
cpu: 50m
memory: 64Mi
limits:
cpu: 200m
memory: 128Mi
# The upstream chart creates a ServiceAccount named after the release.
# We bind it to cluster-admin in templates/clusterrolebinding.yaml.
serviceAccount:
create: true
- Verify rendering locally (requires
helmCLI)
helm repo add headlamp https://headlamp-k8s.github.io/headlamp/
helm dep build argocd/apps/tech/headlamp
helm template headlamp argocd/apps/tech/headlamp --namespace headlamp | grep -E 'kind:|name:'
Expected output contains: kind: Deployment, kind: Service, kind: Ingress, kind: ServiceAccount
- Commit
git add argocd/apps/tech/headlamp/values.yaml
git commit -m "feat(headlamp): add values with Traefik ingress and resource limits"
Task 3: ClusterRoleBinding template
Files:
-
Create:
argocd/apps/tech/headlamp/templates/clusterrolebinding.yaml -
Create the ClusterRoleBinding
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: {{ .Release.Name }}-cluster-admin
labels:
app.kubernetes.io/managed-by: {{ .Release.Service }}
helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- kind: ServiceAccount
name: {{ .Release.Name }}
namespace: {{ .Release.Namespace }}
- Verify it renders correctly
helm template headlamp argocd/apps/tech/headlamp --namespace headlamp | grep -A 12 'ClusterRoleBinding'
Expected: name: headlamp-cluster-admin, subjects referencing headlamp SA in headlamp namespace.
- Commit
git add argocd/apps/tech/headlamp/templates/clusterrolebinding.yaml
git commit -m "feat(headlamp): bind headlamp ServiceAccount to cluster-admin"
Task 4: Long-lived token Secret
Files:
-
Create:
argocd/apps/tech/headlamp/templates/token-secret.yaml -
Create the ServiceAccount token Secret
---
apiVersion: v1
kind: Secret
metadata:
name: headlamp-admin-token
namespace: {{ .Release.Namespace }}
annotations:
kubernetes.io/service-account.name: {{ .Release.Name }}
type: kubernetes.io/service-account-token
Kubernetes automatically populates data.token once the Secret is created and the SA exists.
- Verify it renders correctly
helm template headlamp argocd/apps/tech/headlamp --namespace headlamp | grep -A 8 'token-secret\|service-account-token'
Expected: Secret with annotation kubernetes.io/service-account.name: headlamp and type: kubernetes.io/service-account-token.
- Run helm lint to catch any issues
helm lint argocd/apps/tech/headlamp
Expected: 1 chart(s) linted, 0 chart(s) failed
- Commit
git add argocd/apps/tech/headlamp/templates/token-secret.yaml
git commit -m "feat(headlamp): add long-lived ServiceAccount token Secret"
Task 5: Push and verify ArgoCD sync
Files: none (verification only)
- Push to remote
git push
- Wait for ArgoCD to detect the new app (~30–60 s). Check status:
kubectl get application headlamp -n argocd
Expected: STATUS: Synced, HEALTH: Healthy
If not yet synced, trigger manually:
kubectl -n argocd patch application headlamp \
-p '{"operation":{"initiatedBy":{"username":"admin"},"sync":{"revision":"HEAD"}}}' \
--type merge
- Verify all resources are running
kubectl get all -n headlamp
Expected: pod/headlamp-... Running, service/headlamp, ingress/headlamp
- Verify the ClusterRoleBinding exists
kubectl get clusterrolebinding headlamp-cluster-admin
Expected: headlamp-cluster-admin ClusterRole/cluster-admin
Task 6: Retrieve admin token and log in
- Get the admin token
kubectl get secret headlamp-admin-token -n headlamp \
-o jsonpath='{.data.token}' | base64 -d
Copy the printed token.
- Add a local hosts entry (on your dev machine, not the server) so
headlamp.homeserverresolves:
# Linux/macOS — add to /etc/hosts:
192.168.178.94 headlamp.homeserver
- Open Headlamp in the browser
Navigate to https://headlamp.homeserver, paste the token from the step above.
Expected: Headlamp dashboard showing the k3s cluster nodes and namespaces.