platform: deploy Headlamp dashboard with Keycloak OIDC + per-user RBAC

Add Headlamp (kubernetes-sigs/headlamp Helm chart) at headlamp.home.keithjackson.dev with native Keycloak OIDC login and PER-USER RBAC: Headlamp forwards each user's id_token to the k3s apiserver, so the existing oidc:* group bindings (platform-admins->cluster-admin, viewers->view) apply per user. The ServiceAccount is deliberately NOT bound to cluster-admin (clusterRoleBinding.create=false), since user requests ride the forwarded token. Key integration nuance: the apiserver is configured oidc-client-id=kubernetes, so it only accepts tokens whose aud contains `kubernetes`. The new `headlamp` Keycloak client carries an oidc-audience-mapper (included.client.audience= kubernetes) so tokens carry aud=[headlamp, kubernetes] -- accepted by both Headlamp's own verifier and the apiserver, leaving the apiserver config untouched. A groups mapper emits the `groups` claim the apiserver maps to RBAC. - platform/headlamp: namespace, HelmRepository/HelmRelease, SOPS OIDC secret (externalSecret envFrom), default-deny NetworkPolicy + Cilium ingress (gateway)/egress (apiserver+Keycloak) policies, README. Wired into platform/kustomization.yaml (platform tier). - platform/headlamp/httproute.yaml wired into platform-config (Gateway API CR, dependsOn platform), modeled on grafana-httproute. - keycloak-realm-import: add `headlamp` confidential client + groups/audience mappers + HEADLAMP_CLIENT_SECRET placeholder. Client also created LIVE via kcadm (realm import no-ops on the existing realm). - keycloak-realm-clients.sops: add headlamp-client-secret (mirrored into headlamp-oidc-credentials clientSecret). Both encrypted to the repo age key. Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-08-28 11:44:33 -05:00
1 parent b243c753b1
commit 5fb097d019
@@ -0,0 +1,87 @@
+---
+# Headlamp — the Kubernetes web dashboard, served at headlamp.home.keithjackson.dev with Keycloak
+# native-OIDC login and PER-USER RBAC (ADR-0014, docs/15). Official kubernetes-sigs/headlamp Helm
+# chart via a Flux HelmRelease (same pattern as platform/monitoring's kube-prometheus-stack).
+#
+# ── PER-USER RBAC (the whole point) ────────────────────────────────────────────────────────────
+# Headlamp is configured for OIDC, so its backend forwards the LOGGED-IN USER's OIDC id_token as the
+# bearer to the k3s API server. The apiserver validates that token (oidc-issuer-url = this realm,
+# oidc-client-id=kubernetes, oidc-username-claim=email, oidc-groups-claim=groups; see
+# infra/ansible roles/k3s_server) and RBAC is applied per user via the EXISTING group bindings
+# (platform/keycloak/k8s-oidc-rbac.yaml: oidc:platform-admins -> cluster-admin, oidc:viewers -> view).
+# So every user gets exactly their own rights — NOT a shared identity.
+#
+#   clusterRoleBinding.create=false  ← DELIBERATE. The default chart binds Headlamp's ServiceAccount
+#   to cluster-admin; that would let the backend act as cluster-admin. We do NOT want that: user
+#   requests ride the user's forwarded id_token, so the SA needs no cluster rights. Removing the
+#   binding means an unauthenticated backend can do nothing — the secure posture for per-user RBAC.
+#
+# ── AUDIENCE NUANCE ─────────────────────────────────────────────────────────────────────────────
+# The apiserver only accepts ID tokens whose `aud` CONTAINS `kubernetes` (oidc-client-id=kubernetes).
+# A `headlamp` client would issue aud=[headlamp]. The Keycloak `headlamp` client therefore carries an
+# AUDIENCE protocol mapper that ADDS `kubernetes` to the token audience (keycloak-realm-import.yaml),
+# giving aud=[headlamp, kubernetes]: Headlamp's own verifier accepts it (aud contains headlamp) AND
+# the apiserver accepts it (aud contains kubernetes). This keeps the apiserver config untouched.
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: headlamp
+  namespace: headlamp
+spec:
+  interval: 30m
+  chart:
+    spec:
+      chart: headlamp
+      version: ">=0.40.0 <0.41.0"   # Renovate maintains; chart appVersion pins the Headlamp image
+      sourceRef:
+        kind: HelmRepository
+        name: headlamp
+        namespace: headlamp
+  install:
+    remediation:
+      retries: 3
+  upgrade:
+    remediation:
+      retries: 3
+  values:
+    replicaCount: 1
+    # In-cluster mode: Headlamp discovers the apiserver from the pod's in-cluster config, then
+    # OVERRIDES the bearer with the user's OIDC id_token for authenticated requests.
+    config:
+      inCluster: true
+      oidc:
+        # OIDC config (clientID / clientSecret / issuerURL / scopes / callbackURL) is supplied via an
+        # EXISTING SOPS-encrypted Secret consumed by name only (R-IDP-04) — the chart envFrom's it.
+        # (The chart's `externalSecret` path reads OIDC_* env from this Secret; nothing sensitive is
+        # rendered into the HelmRelease.)
+        externalSecret:
+          enabled: true
+          name: headlamp-oidc
+          hasScopes: true
+    # PER-USER RBAC: do NOT grant Headlamp's ServiceAccount cluster-admin. User requests are
+    # authorized by their forwarded OIDC token against the existing oidc:* group bindings.
+    serviceAccount:
+      create: true
+    clusterRoleBinding:
+      create: false
+    # Hardened pod defaults from the chart (runAsNonRoot, uid 100). Kept explicit for clarity.
+    securityContext:
+      runAsNonRoot: true
+      runAsUser: 100
+      runAsGroup: 101
+      privileged: false
+      allowPrivilegeEscalation: false
+      capabilities:
+        drop:
+          - ALL
+      # NOTE: readOnlyRootFilesystem intentionally left unset (chart default). Enabling it needs a
+      # writable /tmp (+ plugins dir) emptyDir; deferred as a runtime-verified follow-up hardening.
+    resources:
+      requests:
+        cpu: 50m
+        memory: 128Mi
+      limits:
+        memory: 256Mi
+    service:
+      type: ClusterIP
+      port: 80