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.
+4 -3
View File
@@ -4,9 +4,10 @@ Status: M9.8a probe, M9.8b owned state/capture/event bounds, M9.8c launcher,
legend, labelled inspector and click selection, and M9.8d rebindable controls
complete, 2026-10-02. M9.8e local Windows ZIP complete (ADR-0086); its Gitea
Actions publication waits for a Windows runner and its clean-VM run for M9.8g.
M9.8f route design, disabled manifests and fail-closed policy tests complete
(ADR-0087); enabling waits for the VIP, client CIDR, DNS, dev quota and server-enforced
session windows. M9.8g remains.
M9.8f design, disabled manifests and rendered fail-closed policy checks delivered
(ADR-0087, ADR-0088); the M9.8f gate stays open until the route is enabled (VIP, client
CIDR, DNS, dev quota, health-check port evidence and server-enforced session windows)
and connectivity is recorded. M9.8g remains.
No application UI or deployment completion is claimed. See ADR-0084 for the toolkit boundary.
## Confirmed scope
+32
View File
@@ -3930,3 +3930,35 @@ were run directly), any cluster/server dry-run, MetalLB allocation, DNS, firewal
connectivity. Server-enforced session windows and the Gitea window workflow are not
implemented; Argo delivery for windows and the existing void HTTP Ingress are open
maintainer decisions recorded in ADR-0087.
## 2026-10-02 — M9.8f review corrections (.cache/reviews/M9.8f-9f622cf-review.md)
P1 (rendered configuration): the policy check now renders all 17 non-component
kustomizations with pinned kustomize v5.8.1 (ADR-0088; official archive, SHA-256
029a7f0f…a819d checked against the release checksums) and validates the effective
objects: overlay namespaces, evo-region session/input/listener environment, a single
listener argument, container ports, Service types and session port, route shape, session
NetworkPolicies, quotas, Ingresses and no Secrets. Unsupported kustomize features
(plugin generators/transformers, Helm, Secret generators) are refused. Route enabling is
gated by `ROUTE_ENABLING_PERMITTED = False`, changed only with an ADR-0087 amendment
recording the implemented window contract and runtime expiry tests; the earlier
`--session-window` string test is gone. Route addresses must be RFC 1918 or listed in
`APPROVED_INTERNAL` (empty; 172.10.1.x is not RFC 1918).
P2 (health-check port): manifest comment and ADR-0087 now state that the Local policy
allocates `healthCheckNodePort`; allocation, quota accounting and firewall handling are
enabling preconditions. Review recommendations (manual Argo sync, preserving the void
endpoint, address confirmation, window limits and tests) are recorded in ADR-0087 as
pending maintainer decisions. The M9.8f gate stays open.
Executed (WSL Ubuntu, Python 3, PyYAML 6.0.1, kustomize v5.8.1 via the new prepare
script, idempotent on rerun): policy check 70 source objects / 126 rendered objects in
17 overlays, 0 failures; self-test 33/33 refused (20 earlier cases plus non-RFC 1918 VIP,
the reviewer's combined inline patches, inline listener/session/input patches, JSON
patches adding a session port, a LoadBalancer, a container port and a second listener
argument, namespace transformation, inline stage quota, Secret generator, Helm inflation);
the reviewer's m98f-policy-repro.py now exits 1 with the listener, session/input and
ops-port failures in both region/dev and dev; the check fails without kustomize and with
kustomize v5.4.3; ops-lib and ci-path fixtures pass.
Not run: the ci-deploy Docker stage (no Docker here; its commands were run directly,
including prepare-kustomize.sh), any cluster dry-run or live action.
+3 -2
View File
@@ -89,5 +89,6 @@ ADR-0087 designs `void.aeternalisgames.com:7400` through a dedicated internal Me
VIP to the region pod (TLS end to end, development/test CIDR only), opened only in
operator windows that evo-server itself expires. The manifests are in
`deploy/kubernetes/region/dev-session-route` and are not included anywhere; the policy
check refuses to enable them until the VIP, client CIDR, dev quota and the server-side
`--session-window` exist. Until then use the port-forward procedures above.
check refuses to enable them until the VIP, client CIDR, dev quota and server-enforced
session windows exist (ADR-0087 enabling list). Until then use the port-forward
procedures above.