Check rendered kustomize output in the deploy policy (M9.8f review)

The policy check now renders every overlay with pinned, checksum-verified
kustomize v5.8.1 (ADR-0088) and validates effective namespaces, session/input/
listener environment and arguments, ports, Services, quotas, policies, Ingresses
and Secrets, so inline/JSON patches and namespace changes cannot bypass it.
Route enabling is gated on an ADR-0087 amendment with tested server windows, route
addresses must be RFC 1918 or explicitly approved, and the Local health-check node
port is documented with its enabling evidence. Self-test grows to 33 cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-02 18:02:57 -04:00
co-authored by Claude Opus 5.5
parent 9f622cf6b3
commit 8a1e5ef53d
12 changed files with 386 additions and 32 deletions
+37 -8
View File
@@ -2,7 +2,8 @@
## Status
Accepted for M9.8f as design (2026-10-02), evolution-dev only. The route is committed
**disabled**; nothing was applied to the cluster. Enabling it is blocked by policy until
**disabled**; nothing was applied to the cluster. The M9.8f gate stays open until the
route is enabled and connectivity is recorded. Enabling it is blocked by policy until
the inputs and server-side window enforcement below exist. Narrowly supersedes
ADR-0083 (loopback-only listener, never a Service) and ADR-0069 (no LoadBalancer
Services) for evolution-dev, and only once enabled.
@@ -23,8 +24,13 @@ fronts one LoadBalancer Service `evo-region-session` in evolution-dev, which for
the region pod's port 7400. TLS 1.3 terminates in the region pod; its dev-CA server
certificate carries `void.aeternalisgames.com`, which the client verifies. No HTTP
Ingress, no TLS termination at nginx, no PROXY-protocol prefix. The Service uses
`externalTrafficPolicy: Local` (client addresses preserved), no node ports, a pinned
`metallb.io/loadBalancerIPs` annotation and `loadBalancerSourceRanges`. New connections
`externalTrafficPolicy: Local` (client addresses preserved), no node port for the
session data (`allocateLoadBalancerNodePorts: false`), a pinned
`metallb.io/loadBalancerIPs` annotation and `loadBalancerSourceRanges`.
**Health-check exception:** with `Local`, Kubernetes still allocates
`spec.healthCheckNodePort`, an HTTP endpoint kube-proxy serves on every node reporting
local endpoint health. It carries no session traffic, must stay closed at the edge
firewall, and `services.nodeports: "0"` is not assumed to prevent or account for it. New connections
reach only a ready pod; after a replacement, clients reconnect with a fresh grant and
baseline (ADR-0083).
@@ -54,18 +60,37 @@ Expiry is enforced **inside evo-server**, not by a delayed cleanup job:
closed Git configuration. Grant expiry alone does not stop the generator.
## Enabling (all required; `tools/ci/deploy-policy-check.py` refuses otherwise)
1. The VIP (private, from the MetalLB pool) and permitted client CIDR(s) (private, no
wider than /16) replace the REPLACE markers; Service ranges equal the policy's.
0. `ROUTE_ENABLING_PERMITTED` in the policy check is `False` and is changed only together
with an amendment here that records the implemented window argument/configuration
contract and its runtime expiry tests (expiry during an active session, restart after
expiry, delayed application, extend/close races, clock movement, synthetic inputs
stopping while pending commits drain). A flag string in a manifest is not evidence.
1. The VIP (from the MetalLB pool) and permitted client CIDR(s) (no wider than /16)
replace the REPLACE markers; Service ranges equal the policy's. Addresses must be
RFC 1918 or in a range approved here and listed in `APPROVED_INTERNAL` (none yet;
the recorded cluster LAN addresses, 172.10.1.x, are not RFC 1918).
2. `deploy/kubernetes/platform/dev` raises `services.loadbalancers` to exactly 1;
node ports stay 0; stage and World0 stay 0.
3. evo-server implements the session window (`--session-window`) as above, with tests
and an amendment to this ADR, and the base deployment passes it.
4. Only `region/dev` includes the component. Then: internal DNS for void to the VIP, the
edge firewall rule, and a server-side dry-run (quota accounting of the Local health
check port is to be confirmed there), a new dev server certificate for
void.aeternalisgames.com, and live connectivity recorded separately in VALIDATION.md.
edge firewall rule, a new dev server certificate for void.aeternalisgames.com, and live
connectivity recorded separately in VALIDATION.md.
5. Health-check port: a server-side dry-run and the applied object show the allocated
`healthCheckNodePort` and how the quota accounts for it; the firewall handling is
recorded. `services.nodeports` is not raised without that evidence.
6. The rendered-output checks (ADR-0088) pass for every overlay with the route included.
## Open points for the maintainer
Review recommendations (M9.8f review, 2026-10-02), pending the maintainer's decision:
keep manual Argo sync for the first delivery and report a workflow-created window as
pending until applied, with an absolute expiry that delayed sync never shifts (Close
also needs propagation; the server deadline is the upper bound); keep the existing void
HTTP endpoint unless explicitly retired, possibly choosing a dedicated session hostname
instead (DNS cannot select by TCP port), before issuing the certificate; confirm the
actual MetalLB pool and client addresses; set the maximum window length and clock
handling before implementing windows.
- **Argo delivery.** The aevolution-dev Application has no automated sync, and the
policy forbids auto-sync outside the platform app (ADR-0069). A workflow commit alone
will not deploy; either a manual sync per window or a scoped dev exception must be
@@ -83,6 +108,10 @@ Expiry is enforced **inside evo-server**, not by a delayed cleanup job:
- NodePort: opens a port on every node; forbidden by ADR-0069.
- Always-on sessions in dev: continuous synthetic history; rejected for now.
Policy evaluation (ADR-0088): the check renders every overlay with the pinned kustomize
and validates the effective objects, so inline or JSON patches and namespace changes
cannot enable listeners, sessions, inputs or session ports outside the route.
## Consequences
One reviewed exception to "no LoadBalancer" for evolution-dev. The policy check and its
fail-closed self-test (`tools/ci/deploy-policy-selftest.py`) encode the route's shape and
@@ -0,0 +1,41 @@
# ADR-0088: Rendered deployment-policy checks with pinned kustomize
## Status
Accepted 2026-10-02 (M9.8f review correction). Extends ADR-0069's offline policy check.
## Context
`tools/ci/deploy-policy-check.py` validated manifest files one by one. Kustomize
inline strategic-merge or JSON patches, components and namespace transformations
change the effective objects without appearing as checkable files; the M9.8f review
reproduced inline patches enabling the session listener, sessions, synthetic inputs
and a session port while the check passed.
## Decision
- The check renders every non-component kustomization under `deploy/` with a pinned
kustomize and validates the effective output: overlay namespaces; evo-region's
session/input/listener environment, the single listener argument and container ports;
Service types and the session port; route Service shape; NetworkPolicies admitting the
session port; quotas; Ingresses; and the absence of Secrets. Source-file checks stay.
- Kustomizations may use only the keys in use today (resources, components, patches,
images, labels, common labels/annotations, namespace, ConfigMap generators);
generators/transformers plugins, Helm inflation and Secret generators are refused.
- Dependency: kustomize **v5.8.1** (kubernetes-sigs, Apache-2.0), official Linux amd64
release archive, SHA-256
029a7f0f4e1932c52a0476cf02a0fd855c0bb85694b82c338fc648dcb53a819d, matching the
release's checksums.txt. Maintenance evidence (GitHub releases, 2026-10-02): v5.8.0
2025-11-09, v5.8.1 2026-02-09, v5.8.2 2026-09-30. v5.8.1 is pinned rather than the
two-day-old v5.8.2; updates change the version and checksum together.
- Acquisition is explicit: `tools/ci/prepare-kustomize.sh [dir]` downloads, verifies and
installs it (default `.cache/tools/kustomize-v5.8.1`); the CI deploy image runs it.
The check uses `$KUSTOMIZE`, that cache path or `kustomize` on PATH, and fails unless
the binary reports exactly the pinned version. No build step downloads it implicitly.
## Alternatives considered
- `kubectl kustomize`: its embedded kustomize version follows kubectl releases.
- Parsing patches in Python: re-implements kustomize semantics incompletely.
- kubeconform/schema validation: complements but does not evaluate policy.
## Consequences
Running the policy check locally needs the pinned binary (Linux x86_64 is pinned).
Rendering adds seconds to the deploy suite. The self-test covers inline and JSON patches,
namespace changes and unsupported features.
+1
View File
@@ -97,6 +97,7 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0083: Dev region sessions](0083-dev-region-sessions.md) - session server in evo-server, durable no-effect intentions on synthetic carriers, empty organism presentation, reconnect with fresh baselines, loopback-only drill-time dev deployment.
- [ADR-0084: Engineering UI toolkit](0084-engineering-ui-toolkit.md) - Dear ImGui 1.92.9b pinned (M9.8a) and integrated as the engineering client overlay with toolkit-first input routing (M9.8c).
- [ADR-0088: Rendered deployment policy](0088-rendered-deployment-policy.md) - the deploy policy check renders every overlay with pinned kustomize v5.8.1 (checksum-verified, explicit preparation) and validates effective objects; unsupported kustomize features refused.
- [ADR-0087: Dev session route](0087-dev-session-route.md) - evolution-dev only: void.aeternalisgames.com:7400 via a dedicated internal MetalLB VIP to the region pod, TLS end to end, CIDR-limited, operator-opened windows enforced by evo-server; committed disabled with fail-closed policy tests.
- [ADR-0086: Windows client package](0086-windows-client-package.md) - static-runtime Windows x64 ZIP with explicit allowlist, licence texts, build identity, SHA256 manifest, credential guards and deterministic layout; local packaging until a Windows runner exists.
- [ADR-0085: Rebindable engineering controls](0085-rebindable-engineering-controls.md) - SDL-free action/HID-key bindings, conflict validation, versioned all-or-nothing controls file, binding capture before toolkit/world.