PKR-Lab

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:

---
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: "*"
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:

---
# 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
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

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:

---
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 }}
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.

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:

---
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.

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.

helm lint argocd/apps/tech/headlamp

Expected: 1 chart(s) linted, 0 chart(s) failed

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)

git push
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
kubectl get all -n headlamp

Expected: pod/headlamp-... Running, service/headlamp, ingress/headlamp

kubectl get clusterrolebinding headlamp-cluster-admin

Expected: headlamp-cluster-admin ClusterRole/cluster-admin


Task 6: Retrieve admin token and log in

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

Copy the printed token.

# Linux/macOS — add to /etc/hosts:
192.168.178.94  headlamp.homeserver

Navigate to https://headlamp.homeserver, paste the token from the step above.

Expected: Headlamp dashboard showing the k3s cluster nodes and namespaces.