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:
1 parent
1ddc14b918
commit
250fb54154
43 files changed
+1672
-575
No files matched your search
@@ -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).
|
||||
|
||||
|
||||
Reference in new issue
Block a user