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/cilium
+
+**Cilium** — CNI, kube-proxy replacement, Gateway API ingress, Egress Gateway, and Hubble.
+
+- **Governing ADR:** [ADR-0002 — CNI, network policy & ingress: Cilium + Gateway API](../../../home-network-k3s/decisions/adr-0002-cni-cilium.md)
+- **Spec:** [docs/03 — Networking](../../../home-network-k3s/docs/03-networking-isolation-and-egress.md),
+  [docs/09 — DNS & Ingress](../../../home-network-k3s/docs/09-dns-and-ingress.md)
+- **Serves:** R-NET-01..07, R-DNS-01, R-SEC-02
+- **Owner:** WS-NET (bootstrap shared with WS-INFRA)
+
+## What this stub is
+
+A Flux `HelmRelease` + `HelmRepository` stub with placeholder values. **No cluster exists** (Phase 0);
+this does not reconcile. Cilium replaces k3s' bundled **flannel + kube-proxy + Traefik**
+(ADR-0001/0002).
+
+## Bootstrap vs. GitOps (important)
+
+Per [docs/02](../../../home-network-k3s/docs/02-environments-and-provisioning.md), Cilium's **initial**
+install is done by the **Ansible k3s bootstrap** (Phase 1, WS-INFRA), because a cluster needs a CNI
+before Flux can run. This HelmRelease **manages Cilium configuration thereafter**. The Helm values
+here MUST stay consistent with the Ansible bootstrap values (`kubeProxyReplacement`, `k8sServiceHost`,
+`k8sServicePort`) — otherwise Flux and the bootstrap fight. **Coordinate this contract with WS-INFRA.**
+
+## TODO (later phases — not Phase 0)
+
+- **Phase 1 (WS-INFRA/WS-NET):** align Helm values with the Ansible bootstrap; pin chart version.
+- **Phase 2 (WS-NET):** default-deny network baseline; Egress Gateway policies; L2 announcement IP
+  pool + `CiliumL2AnnouncementPolicy` for the ingress VIP; Hubble metrics → kube-prometheus-stack.
+- **Phase 3 (WS-NET):** egress-class routing integration with the VPN gateway (ADR-0013).
@@ -0,0 +1,55 @@
+---
+# Cilium — CNI, kube-proxy replacement, Gateway API, Egress Gateway, Hubble (ADR-0002).
+# Phase 0 STUB. Values are PLACEHOLDERS; fill in during Phase 1/2 (WS-NET).
+#
+# IMPORTANT (cross-workstream contract): Cilium's INITIAL install is performed by the Ansible
+# bootstrap (spec docs/02, Phase 1), replacing k3s flannel/kube-proxy. This HelmRelease manages
+# Cilium CONFIG going forward. Its values MUST match the Ansible bootstrap values (kubeProxyReplacement,
+# k8sServiceHost/Port) or Flux and the bootstrap will fight. Owner: WS-NET + WS-INFRA.
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: cilium
+  namespace: kube-system
+spec:
+  interval: 30m
+  chart:
+    spec:
+      chart: cilium
+      version: ">=1.16.0 <1.17.0"   # TODO(WS-NET): pin exact version at bring-up; Renovate maintains
+      sourceRef:
+        kind: HelmRepository
+        name: cilium
+        namespace: kube-system
+  install:
+    remediation:
+      retries: 3
+  upgrade:
+    remediation:
+      retries: 3
+  # Placeholder values — see values.yaml for the annotated skeleton. Inlined here so the intent
+  # (Cilium REPLACES flannel + kube-proxy + Traefik) is visible at the release.
+  values:
+    # --- kube-proxy replacement (ADR-0001/0002: k3s kube-proxy disabled) ---
+    kubeProxyReplacement: true
+    # TODO(WS-INFRA): k8sServiceHost/k8sServicePort must equal the Ansible bootstrap's API endpoint.
+    k8sServiceHost: "REPLACE-ME"     # e.g. the k3s API VIP/host
+    k8sServicePort: 6443
+    # --- Gateway API (ingress; replaces Traefik) — docs/09, ADR-0002 ---
+    gatewayAPI:
+      enabled: true
+    # --- Egress Gateway (egress-class steering; part of VPN model with ADR-0013) ---
+    egressGateway:
+      enabled: true
+    # --- Hubble (flow observability / isolation audit) ---
+    hubble:
+      enabled: true
+      relay:
+        enabled: true
+      ui:
+        enabled: true   # exposure gated behind oauth2-proxy forward-auth later (ADR-0014)
+    # --- L2 announcement for the ingress VIP on the flat LAN (docs/09, OQ-1 resolved) ---
+    l2announcements:
+      enabled: true
+    # TODO(WS-NET, Phase 2): default-deny baseline, CiliumL2AnnouncementPolicy + IP pool,
+    #   Egress Gateway policies, Hubble metrics export to kube-prometheus-stack.
@@ -0,0 +1,9 @@
+---
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: HelmRepository
+metadata:
+  name: cilium
+  namespace: kube-system
+spec:
+  interval: 1h
+  url: https://helm.cilium.io/
@@ -0,0 +1,8 @@
+---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: kube-system
+resources:
+  - namespace.yaml
+  - helmrepository.yaml
+  - helmrelease.yaml
@@ -0,0 +1,6 @@
+---
+# Cilium runs in kube-system (it is the CNI). Declared for completeness; k3s provides it.
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: kube-system
@@ -0,0 +1,13 @@
+# Cilium Helm values — PLACEHOLDER skeleton (Phase 0). Authoritative values live inline in
+# helmrelease.yaml for now; this file documents the knobs WS-NET must set in Phase 1/2.
+#
+# MUST match the Ansible bootstrap (docs/02) for the fields the bootstrap also sets.
+#
+# kubeProxyReplacement: true            # k3s kube-proxy disabled (ADR-0001/0002)
+# k8sServiceHost / k8sServicePort       # = Ansible bootstrap API endpoint (WS-INFRA contract)
+# gatewayAPI.enabled: true              # ingress via Gateway API, no Traefik (docs/09)
+# egressGateway.enabled: true           # egress-class steering (ADR-0002, VPN model ADR-0013)
+# hubble.{enabled,relay,ui}             # flow observability + isolation audit
+# l2announcements.enabled: true         # ingress VIP on flat LAN (docs/09, OQ-1)
+# ipam / ipv4NativeRoutingCIDR          # TODO: pin to the cluster pod/LAN CIDRs at bring-up
+# encryption (wireguard/ipsec)          # TODO(WS-SEC/WS-NET): decide east-west encryption later