docs: bring the specification in line with the accepted implementation

The operator ruled the implementation repo's main (50c8719) the latest
and accepted state. Sync the spec to it.

Accepted changes are reflected: one bare-metal environment, TrueNAS bulk
storage, R2 off-cluster backup, CloudNativePG, single-node VPN gateway
with Cilium fail-closed, inbound WireGuard, per-app auth sidecars,
Renovate, the CI gate as approver, and the pm-agent. New ADR-0017..0025;
ADR-0016 corrected and accepted; R-* IDs unchanged, eight amended.

Where the implementation has simply not met a requirement, the
requirement stands and the shortfall is recorded in docs/16-known-gaps.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
jakman85andClaude Opus 5.5 committed 2026-11-08 22:46:00 -06:00
1 parent 1ddc14b918
commit 250fb54154
43 files changed
+1672 -575

No files matched your search

+35 -16
View File
@@ -17,22 +17,32 @@ Defense in depth with declarative, auditable controls:
- **Supply chain**: pin images by digest where automation allows; prefer known-good upstreams;
updates flow through policy, not ad-hoc pulls ([11](11-automated-updates.md)).
- **Identity / SSO**: a central IdP (**Keycloak**) provides single sign-on, one user directory,
group-based authorization, and MFA; services authenticate via native OIDC or an oauth2-proxy
forward-auth layer so no management UI is unauthenticated ([15](15-identity-and-access.md),
[ADR-0014](../decisions/adr-0014-idp-keycloak.md), R-IDP-*). This is the primary *authentication*
control, complementing network default-deny (the primary *isolation* control).
- **Policy enforcement (admission)**: **Kyverno** runs in-cluster as an admission controller and
rejects non-conforming resources at reconcile time — e.g. a namespace missing its default-deny
baseline, or a workload without a required egress-class/auth-mode label. The *same* policies
gate CI ([14](14-testing-and-conformance.md), [ADR-0011](../decisions/adr-0011-test-tooling-kyverno-chainsaw.md)),
so invariants are enforced both before merge and at admission (defense in depth). Enforcement
complements — never replaces — the runtime behavior tests.
group-based authorization, and MFA; services authenticate via native OIDC or a per-app
oauth2-proxy forward-auth gate so no management UI is unauthenticated
([15](15-identity-and-access.md), [ADR-0014](../decisions/adr-0014-idp-keycloak.md),
[ADR-0022](../decisions/adr-0022-forward-auth-per-app-oauth2-proxy-sidecars.md), R-IDP-*). This is
the primary *authentication* control, complementing network default-deny (the primary *isolation*
control).
- **Policy enforcement (admission)**: **Kyverno** runs in-cluster as an admission controller over
**application namespaces**. It generates and backfills each namespace's default-deny baseline,
rejects a malformed baseline, and rejects a workload that lacks a required egress-class/auth-mode
label or uses host namespaces or privileged mode. Separate enforcing policies constrain the exact
Job shapes that CI and agent credentials may create; these are security boundaries, so they fail
closed and no environment overlay can downgrade them. No policy-exception mechanism is in use:
controller-generated pods are mutated to carry truthful labels instead. Platform namespaces sit
outside these policies and carry hand-authored equivalents. Policies are authored once and gate
CI ([14](14-testing-and-conformance.md), [ADR-0011](../decisions/adr-0011-test-tooling-kyverno-chainsaw.md)),
so invariants are enforced both before merge and at admission (defense in depth); the job-shape
policies act only at admission and are unit-tested in CI. Enforcement complements — never
replaces — the runtime behavior tests.
- **Plaintext-secret enforcement is split by layer (do not conflate):** the "no plaintext Secret"
invariant is a **CI-time** check (the committed Secret must carry SOPS ciphertext). It **cannot**
be an admission rule, because Flux **decrypts SOPS before** the object reaches the API server —
an admitted Secret never carries ciphertext, so an admission "reject plaintext" rule would reject
*every* real Secret. Admission instead enforces **SOPS provenance** (the Secret was reconciled
through the Flux/SOPS path), not ciphertext presence.
*every* real Secret. Admission instead enforces **SOPS provenance** on application-namespace
Secrets (the Secret was reconciled through the Flux/SOPS path), not ciphertext presence.
- Host-namespace and privileged-pod control is Kyverno-based for the application tier; Pod
Security Admission labels are applied selectively, on namespaces with their own need for them.
- **Auditability**: isolation, egress path, cert validity, and backup integrity are all
demonstrable (R-SEC-03) via Hubble, cert status, and DR drills.
@@ -53,8 +63,13 @@ Defense in depth with declarative, auditable controls:
- DNS provider API token (Cloudflare) for ACME DNS-01 + ExternalDNS.
- Cloudflare Tunnel credential/token for in-cluster cloudflared (SOPS-encrypted; ADR-0016).
- SMTP credentials for Alertmanager email.
- Service credentials (Nextcloud, Gitea admin, UniFi, Semaphore, Kasm, DB passwords).
- Off-cluster backup target credentials (S3/NFS) for Velero/Longhorn.
- Service credentials (Nextcloud, Gitea admin, UniFi, Semaphore, DB passwords; Kasm is not onboarded).
- Per-app forward-auth gate credentials (IdP client secret + cookie secret; [ADR-0022](../decisions/adr-0022-forward-auth-per-app-oauth2-proxy-sidecars.md)).
- WireGuard ingress server key, held in SOPS because a rebuild must restore it without re-enrolling
every client (ADR-0021).
- Off-cluster backup target credentials (Cloudflare R2) for Velero and the database archives (ADR-0018).
- In-cluster AI agent credentials (ADR-0025) and infrastructure-as-code runtime secrets (state
encryption, remote-state keys).
- Grafana admin, and any API tokens the C2 UI needs.
### Rotation
@@ -73,10 +88,14 @@ Defense in depth with declarative, auditable controls:
- Platform controllers (Flux, cert-manager, ExternalDNS, Velero, KubeVirt) get scoped permissions;
application workloads get near-zero cluster permissions.
- The C2 UI's operational actions run through a constrained, audited path — not a shared admin
kubeconfig handed to a browser.
kubeconfig handed to a browser. The Kubernetes console forwards each user's own IdP-issued token,
so an action runs under that user's group-bound RBAC; the console's ServiceAccount holds no
cluster rights (see [known gaps](16-known-gaps.md)).
- Human access to the Kubernetes API is Keycloak OIDC, with roles bound to IdP groups
([15](15-identity-and-access.md)).
## Node & host security
- Nodes baselined via cloud-init/Ansible ([02](02-environments-and-provisioning.md)); SSH key-only,
- Nodes baselined as code with Ansible ([02](02-environments-and-provisioning.md)); SSH key-only,
minimal packages, required sysctls only.
- Host-level changes are IaC, not hand edits (drift + auditability).