Headlamp

Headlamp is the browser-based Kubernetes UI for the Lumie cluster. In this repo it is intentionally minimal: the upstream Helm chart creates the workload, the local values disable direct ingress, and Teleport provides the only operator access path.

Responsibility

• Provide a cluster UI for browsing workloads and resources.
• Run as a dedicated workload in the headlamp namespace.
• Delegate external access to Teleport instead of publishing its own ingress.

Source paths

Path	Role
lumie-infra/applications/headlamp/argocd.yaml	ArgoCD Application targeting namespace headlamp
lumie-infra/applications/headlamp/helm-values.yaml	Upstream chart values, image, resources, service account, and service
lumie-infra/applications/headlamp/common-values.yaml	Disables duplicate service, deployment, and ingress generation from charts/common
lumie-infra/security/teleport/agent/helm-values.yaml	Teleport app entry for headlamp

Ownership boundaries

• The upstream headlamp chart owns the deployment, service account, ClusterRoleBinding, and service objects.
• The local common-values.yaml file exists only to prevent the shared common chart from creating duplicate objects.
• Teleport owns operator access to the UI.

Public surface and contracts

Surface	Contract
Teleport app	headlamp
In-cluster service	headlamp.headlamp.svc.cluster.local:80
Service account	headlamp, created by the upstream chart
Access mode	ClusterIP only; no direct ingress in applications/headlamp/**

The checked-in values explicitly request a ClusterRoleBinding, but the exact bound ClusterRole comes from upstream chart defaults. Treat that as an upgrade-sensitive contract and re-check the rendered manifest on chart version changes.

Runtime flow

Dependencies

• Kubernetes API access through the Headlamp service account.
• Teleport for external access.
• The internal image mirror at zot.lumie-infra.com/headlamp-k8s/headlamp:v0.40.1.

Failure behavior and operational risks

• Teleport failures make the UI unreachable even when the Headlamp deployment is healthy.
• Because the RBAC shape comes from the upstream chart, a chart upgrade can widen or narrow access without a corresponding local manifest change.
• A broken service account or ClusterRoleBinding surfaces as API authorization failures inside the UI rather than as pod crashes.

Observability

• ArgoCD app health confirms that the chart rendered and synced.
• Pod readiness and deployment logs are the primary signals; there is no checked-in ServiceMonitor or app-specific metrics contract in this slice.

Verification

kubectl get applications.argoproj.io -n argocd headlamp
kubectl get deploy,pods -n headlamp -l app.kubernetes.io/name=headlamp
kubectl get svc headlamp -n headlamp
kubectl get sa headlamp -n headlamp
kubectl get clusterrolebinding | rg headlamp
kubectl logs -n headlamp -l app.kubernetes.io/name=headlamp --all-containers --tail=200

Success signals:

• The headlamp Argo CD application is Healthy and Synced.
• One headlamp deployment and one headlamp service exist in the headlamp namespace.
• The headlamp service account and a matching ClusterRoleBinding are present.
• The Headlamp pod logs show normal startup and Kubernetes API access, not repeated authorization failures.

Related pages

• Applications overview
• Teleport