T-0.1 Flux GitOps layout + dev/prod overlays + platform component skeletons (R-GITOPS-01/03, R-ENV-02, R-PLAT-01)

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-08-16 00:08:31 -05:00
1 parent bd8de96456
commit af4f6c07ae
@@ -0,0 +1,30 @@
+# platform/keycloak
+
+**Keycloak** — the platform Identity Provider (SSO via OIDC + SAML).
+
+- **Governing ADR:** [ADR-0014 — IdP: Keycloak](../../../home-network-k3s/decisions/adr-0014-idp-keycloak.md)
+- **Spec:** [docs/15 — Identity & Access](../../../home-network-k3s/docs/15-identity-and-access.md)
+- **Serves:** R-IDP-01..06
+- **Owner:** WS-SEC
+
+## What this stub is
+
+Flux `HelmRelease` for the Keycloak instance with **PostgreSQL on Longhorn** (DR-critical). Replica
+count is an overlay knob (`${KEYCLOAK_REPLICAS}`, R-ENV-02). Admin/DB credentials referenced **by
+name**, **SOPS-encrypted** (WS-SEC). Realms/clients/groups are config-as-code (Phase 6).
+
+> The ADR allows the **Keycloak Operator OR Helm** for the instance; this stub uses Helm — swap to
+> the Operator if WS-SEC prefers CR-driven config.
+
+## Contract (SSO/auth)
+
+The "SSO/auth contract" (`roadmap/workstreams.md`, WS-SEC): a ServiceDefinition's `auth` block maps to
+a Keycloak client (native OIDC) or oauth2-proxy protection (forward-auth — see
+[`../oauth2-proxy`](../oauth2-proxy)). Consumed by WS-APPS/WS-C2.
+
+## TODO (later phases — onboarded EARLY in Phase 6)
+
+- Realms/clients/groups as code (keycloak-config-cli / realm-import); MFA for privileged groups.
+- **DR-critical:** off-cluster DB backup (velero/) + documented **break-glass** local-admin path.
+- Exceptions that keep native auth (do not force SSO): Plex/Seerr (Plex auth), Minecraft
+  (Mojang/Microsoft), UniFi (native) — ADR-0014.
@@ -0,0 +1,40 @@
+---
+# Keycloak — platform IdP (OIDC + SAML), config-as-code, PostgreSQL on Longhorn (ADR-0014).
+# Phase 0 STUB. DR-CRITICAL: DB backed up off-cluster; documented break-glass local-admin path.
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: keycloak
+  namespace: keycloak
+spec:
+  interval: 30m
+  chart:
+    spec:
+      chart: keycloak
+      version: ">=24.0.0 <25.0.0"   # TODO(WS-SEC): pin at bring-up; Renovate maintains
+      sourceRef:
+        kind: HelmRepository
+        name: bitnami
+        namespace: keycloak
+  install:
+    remediation:
+      retries: 3
+  upgrade:
+    remediation:
+      retries: 3
+  values:
+    replicaCount: ${KEYCLOAK_REPLICAS}       # overlay knob: dev 1 / prod 2 (HA) — R-ENV-02
+    production: true                          # TLS/proxy-aware; served behind the Gateway (public)
+    proxyHeaders: xforwarded
+    # PostgreSQL on Longhorn (ADR-0014) — DR-critical, backed up off-cluster (velero/).
+    postgresql:
+      enabled: true
+      primary:
+        persistence:
+          storageClass: longhorn
+    # Admin + DB credentials: SOPS-encrypted secrets referenced BY NAME only (WS-SEC, ADR-0007).
+    auth:
+      existingSecret: keycloak-admin-credentials
+    # TODO(WS-SEC, Phase 6): realms/clients/groups as code (keycloak-config-cli / realm-import);
+    #   MFA for privileged groups; break-glass local-admin path (e.g. on Gitea). Onboarded EARLY
+    #   (with PiHole/Gitea) so later services adopt SSO as they come up (roadmap Phase 6).
@@ -0,0 +1,11 @@
+---
+# TODO(WS-SEC): the ADR permits Keycloak Operator OR Helm for the instance. This stub uses a Helm
+# chart source; swap to the Keycloak Operator if WS-SEC prefers CR-driven config. (ADR-0014)
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: HelmRepository
+metadata:
+  name: bitnami
+  namespace: keycloak
+spec:
+  interval: 1h
+  url: https://charts.bitnami.com/bitnami
@@ -0,0 +1,7 @@
+---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - helmrepository.yaml
+  - helmrelease.yaml
@@ -0,0 +1,5 @@
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: keycloak
@@ -0,0 +1,8 @@
+# Keycloak Helm values — PLACEHOLDER (Phase 0). Authoritative values inline in helmrelease.yaml.
+#
+# replicaCount: ${KEYCLOAK_REPLICAS}          # overlay knob (dev 1 / prod 2 HA)
+# postgresql on longhorn                       # DR-critical (ADR-0014), backed up off-cluster
+# auth.existingSecret: keycloak-admin-credentials   (SOPS-encrypted, WS-SEC — name only)
+# realm/clients/groups as code                 # keycloak-config-cli / realm-import (Phase 6)
+# public (hardened) exposure so login flows work for internet-exposed services (ADR-0014).
+# Exceptions (do NOT force SSO): Plex/Seerr (Plex auth), Minecraft (Mojang), UniFi (native).