Skip to content

Deprecated — Consolidated into OBS-0001 on 2026-05-02 per ADR-0047. This source file is retained as a reference; the canonical content is in OBS-0001.

ADR-0045 — Headlamp as Kubernetes Dashboard

Field Value
Status Accepted
Date 2026-05-01
Author Ben Peries
WI WI-377
Supersedes —
Related ADR-0043 (cert-manager), ADR-0044 (Traefik IngressRoutes TLS)

Context

The archon-platform k3s cluster lacked a graphical Kubernetes dashboard. Visibility into CRD state (cert-manager Certificates, IngressRoutes, ExternalSecrets) required kubectl command-line access. A lightweight web UI was needed for operational visibility without adding significant resource overhead.

Three options were evaluated:

Option Pros Cons
Kubernetes Dashboard (A) Official CNCF project Heavy, separate auth proxy required, less CRD-aware
Portainer (B) Already deployed on caneast-site1-node2 Docker-centric; k3s support limited, not cluster-native
Headlamp (C) CRD-aware, plugin store, lightweight (~80 MB), active development by Microsoft/Kinvolk Requires cluster-admin for full view

Decision

Deploy Headlamp (chart headlamp/headlamp v0.41.0) into the archon-infra namespace.

Configuration: - inCluster: true with context name archon - ClusterRoleBinding to cluster-admin (read-only use expected; cluster is single-tenant lab) - Plugin directory at /headlamp/plugins for post-install plugin store access - Exposed at https://headlamp-platform.peries.ca via Traefik IngressRoute + cert-manager TLS

Resource allocation: 50m/64Mi requests, 200m/128Mi limits.

Consequences

Positive: - Full CRD visibility: cert-manager Certificates, IngressRoutes, ExternalSecrets, Middlewares - Plugin store available in UI — cert-manager plugin installable without redeployment - ~80 MB RAM idle; minimal cluster footprint - Follows established IngressRoute + TLS pattern (ADR-0044)

Negative / Accepted: - cluster-admin RBAC is broad; acceptable for single-tenant homelab; revisit if multi-tenant - Headlamp has no built-in Prometheus integration — Grafana dashboards for Headlamp resource usage require a separate ServiceMonitor (deferred; not a current requirement)

Implementation

Helm release:  archon-headlamp
Namespace:     archon-infra
Chart:         headlamp/headlamp 0.41.0
Repo:          https://kubernetes-sigs.github.io/headlamp/
URL:           https://headlamp-platform.peries.ca
Certificate:   headlamp-platform-tls (letsencrypt-prod, DNS-01)
Manifests:     k8s/ingress/headlamp/{certificate,middleware-redirect-https,ingressroute}.yaml
Values:        kubernetes/archon-infra/headlamp/values.yaml

Post-install: install cert-manager plugin from Headlamp UI → Plugin Store → search "cert-manager".

References