Kubernetes Distribution — Enterprise Commercial Phase Plan¶
Status: Deferred from v0.1. Planned for the enterprise commercial phase. Scope owner: Platform + SRE. Source of truth: PRD §4.4 deployment, scope-90-day.md:39.
v0.1 ships a single-node Docker Compose reference deployment because every design-partner activation criterion (15-minute time-to-first-scan, signed status artifact from CI, local-first evidence) can be met without Kubernetes. The Kubernetes distribution is an enterprise packaging track for regulated providers who already run their stack on Kubernetes and require their compliance tooling to live there too. It is explicitly a paid distribution, not an OSS deliverable.
Why it is deferred¶
Kubernetes adds operational surface — Helm charts, operators, network policies, storage classes, secrets backends, RBAC mapping — that does not change any compliance control. Shipping it before the controls themselves are stable would force every later control change to ship twice: once in Compose, once in Kubernetes. The right sequencing is: stabilize controls and the Compose distribution through P0–P3, then promote to Kubernetes when an enterprise customer pays for it.
Architectural preconditions v0.1 must preserve¶
| Precondition | Owner phase | Why it matters |
|---|---|---|
| Every service has a documented health endpoint and a deterministic readiness signal | Phase 4–6 | Kubernetes readiness/liveness probes are a 1:1 map; no service rewrites |
Persistent state lives on declared volume mounts (evidence_data, key_data, config_data), never in container layers | Phase 7–8 | PVCs in Kubernetes use the same mount contract |
| Egress-proxy is the only outbound network path; this is a runtime invariant, not a deployment convention | Phase 13 | NetworkPolicies in Kubernetes encode the same invariant; the application doesn't change |
| Containers run as non-root with a read-only root filesystem | Phase 6, Phase 14 | PodSecurity restricted profile applies without exception lists |
| Configuration is environment-variable + mounted-file driven, not docker-compose-specific syntax | Phase 4–6 | ConfigMaps and Secrets drop in unchanged |
| Inter-service discovery is by DNS name, not by hard-coded container names | Phase 4–6 | Kubernetes Service DNS works without code edits |
| Official images are signed with a verifiable provenance chain | Phase 14 | Enterprise admission controllers (Sigstore policy-controller, Kyverno) gate on signatures |
If a v0.1 change adds Docker-Compose-only behavior (host networking, named-container links, host-path mounts as defaults), raise it — it will need a rewrite for Kubernetes.
Scope when it ships¶
In scope:
- Helm chart for the full service topology (
gateway-api,risk-engine,evidence-vault,doc-generator,egress-proxy). - NetworkPolicies enforcing the egress invariant: only
egress-proxymay make outbound connections; all other pods deny egress. - PodSecurity restricted profile; no exceptions.
- StorageClass-aware PVC templates for
evidence_data,key_data,config_datawith documented retention and backup expectations. - Secrets integration: ExternalSecrets for AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault.
- RBAC mapping from enterprise IdP groups (via the Enterprise RBAC and SSO work) to in-cluster ServiceAccounts and to the application's authorization model.
- Air-gapped install path: tarballed images + Helm chart + offline policy bundle, verified against a customer-loaded signing root.
- Upgrade runbook with explicit ledger migration semantics — append-only invariants must survive every upgrade.
Out of scope (intentional):
- A Kubernetes Operator. Helm is sufficient at GA; an Operator is a future track if customer pull justifies the operational burden of maintaining one.
- Service mesh integration (Istio, Linkerd) as a default. Optional, customer-driven, documented as an integration recipe.
- Horizontal pod autoscaling for the Evidence Vault. The ledger is append-only and single-writer by design; scaling reads is fine, scaling writes requires a separate ADR.
- Multi-cluster federation.
- An OSS Helm chart published to a public repo before the enterprise distribution ships. The chart is part of the paid distribution.
Milestones (indicative)¶
- K0 — Internal Helm chart that installs cleanly on a stock kind cluster; passes the full v0.1 control suite end to end.
- K1 — Hardened chart: NetworkPolicies enforced, PodSecurity restricted, ExternalSecrets integration tested against at least one secrets backend.
- K2 — Air-gapped install path validated against a partner's regulated environment.
- K3 — First enterprise customer running in production on Kubernetes with signed images verified at admission.
Exit gate for "GA": one enterprise customer in production for 60 consecutive days with no Kubernetes-specific control regressions vs. the Compose distribution.
Open questions¶
- Chart distribution channel: OCI registry only, or also traditional Helm repo? OCI-only aligns with signed-image story but raises the bar for some enterprise tooling.
- Whether to support the customer's chosen ingress controller or ship an opinionated one. Likely BYO — the gateway-api is the only externally exposed service.
- How to handle ledger backups in Kubernetes without weakening append-only semantics — likely a documented snapshot procedure, not a built-in backup operator.