diff --git a/deploy/kubernetes/region/dev-session-route/kustomization.yaml b/deploy/kubernetes/region/dev-session-route/kustomization.yaml index debb834..04245ee 100644 --- a/deploy/kubernetes/region/dev-session-route/kustomization.yaml +++ b/deploy/kubernetes/region/dev-session-route/kustomization.yaml @@ -1,10 +1,8 @@ -# M9.8f dev session route for evolution-dev ONLY (ADR-0087). DISABLED: no -# kustomization includes this component yet. Enabling it (components: in -# region/dev/kustomization.yaml) is refused by tools/ci/deploy-policy-check.py until: -# - the REPLACE markers carry the allocated internal MetalLB VIP and the permitted -# development/test client CIDR(s); -# - the platform dev quota allows exactly one LoadBalancer Service; -# - evo-server enforces operator-opened session windows itself (--session-window). +# M9.8f dev session route for evolution-dev ONLY (ADR-0087). DISABLED until +# server-enforced session windows and the associated runtime tests are merged. The +# network inputs are now reserved: VIP 172.10.1.202 and client CIDR 172.10.1.0/24. +# Enabling it (components: in region/dev/kustomization.yaml) remains refused by +# tools/ci/deploy-policy-check.py until evo-server enforces --session-window. # Route: void.aeternalisgames.com:7400 -> VIP -> Service -> evo-region pod:7400 (TLS 1.3 # terminates in the pod). Raw TCP only: no Ingress, no TLS at nginx, no PROXY protocol. apiVersion: kustomize.config.k8s.io/v1alpha1 diff --git a/deploy/kubernetes/region/dev-session-route/networkpolicy.yaml b/deploy/kubernetes/region/dev-session-route/networkpolicy.yaml index 68da7a1..94efdd4 100644 --- a/deploy/kubernetes/region/dev-session-route/networkpolicy.yaml +++ b/deploy/kubernetes/region/dev-session-route/networkpolicy.yaml @@ -13,6 +13,6 @@ spec: ingress: - from: - ipBlock: - cidr: REPLACE-dev-test-client-cidr + cidr: 172.10.1.0/24 ports: - {protocol: TCP, port: 7400} diff --git a/deploy/kubernetes/region/dev-session-route/service.yaml b/deploy/kubernetes/region/dev-session-route/service.yaml index 001abb6..c94227a 100644 --- a/deploy/kubernetes/region/dev-session-route/service.yaml +++ b/deploy/kubernetes/region/dev-session-route/service.yaml @@ -14,7 +14,7 @@ kind: Service metadata: name: evo-region-session annotations: - metallb.io/loadBalancerIPs: REPLACE-dev-session-vip + metallb.io/loadBalancerIPs: 172.10.1.202 labels: app.kubernetes.io/name: evo-region spec: @@ -22,7 +22,7 @@ spec: allocateLoadBalancerNodePorts: false externalTrafficPolicy: Local loadBalancerSourceRanges: - - REPLACE-dev-test-client-cidr + - 172.10.1.0/24 selector: app.kubernetes.io/name: evo-region ports: diff --git a/docs/STATUS.md b/docs/STATUS.md index db2e760..02b7d08 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -10,13 +10,15 @@ bounded errors, Retry/Cancel), legend, labelled inspector, click selection, sess panel with the intention outcome record, and visible notifications/dialog. M9.8d adds rebindable controls (ADR-0085) with conflict checks and a validated file. M9.8e builds a static-runtime Windows x64 ZIP locally with notices, identity, checksums and -credential guards (ADR-0086); Actions publication needs a Windows runner. M9.8f -designs the dev session route (ADR-0087), committed disabled with fail-closed policy -tests; nothing was applied to the cluster. Tests, +credential guards (ADR-0086); Actions publication needs a Windows runner. M9.8f designs the dev session route (ADR-0087), with the local test-route inputs now +reserved in [VOID_SESSION_ROUTE_REPORT](engineering/VOID_SESSION_ROUTE_REPORT.md), +while the route remains disabled with fail-closed policy tests; nothing was applied to +the cluster. Tests, visual review and limits are recorded in engineering/VALIDATION.md. -Next: server-enforced session windows and the route inputs (VIP, CIDR, DNS) to enable -ADR-0087, and M9.8g qualification on the low-spec VM. +Next: implement and test server-enforced session windows, then include the prepared +ADR-0087 route and complete DNS, certificate, Argo, health-check-port and connectivity +validation. The local route inputs are recorded in engineering/VOID_SESSION_ROUTE_REPORT.md. Windows packages will be built locally until a Windows runner exists. Testing is internal; 172.10.1.160 is the RKE2 control-plane address. VM qualification and the cluster restart drill remain outstanding, as agreed. See engineering/M9_8_DELIVERY_PLAN.md. diff --git a/docs/adr/0087-dev-session-route.md b/docs/adr/0087-dev-session-route.md index 3df40d9..6277d18 100644 --- a/docs/adr/0087-dev-session-route.md +++ b/docs/adr/0087-dev-session-route.md @@ -67,15 +67,19 @@ Expiry is enforced **inside evo-server**, not by a delayed cleanup job: 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). + RFC 1918 or in a range approved here and listed in `APPROVED_INTERNAL` (`172.10.1.0/24` + is approved for the selected local-DNS test path; the external firewall remains + outside repository control). 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, a new dev server certificate for void.aeternalisgames.com, and live - connectivity recorded separately in VALIDATION.md. +4. Only `region/dev` includes the component. The selected internal test network is + `172.10.1.0/24`, explicitly approved in the policy and restricted by the edge + firewall, Service source ranges and NetworkPolicy. Then: internal DNS for + `void.aeternalisgames.com` to `172.10.1.202`, the 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. diff --git a/docs/engineering/VOID_SESSION_ROUTE_REPORT.md b/docs/engineering/VOID_SESSION_ROUTE_REPORT.md new file mode 100644 index 0000000..bf39268 --- /dev/null +++ b/docs/engineering/VOID_SESSION_ROUTE_REPORT.md @@ -0,0 +1,101 @@ +# `void.aeternalisgames.com` session-route implementation report + +**Date:** 2026-10-03 UTC +**Repository:** AEvolution +**Base reviewed:** `cb31893a47` (`Check effective NetworkPolicy ingress to the region session port`) + +## Scope + +The previous HTTP service behind `void.aeternalisgames.com` has been retired. This +change prepares the dev native-session endpoint as raw TLS/TCP on port `7400`, using a +dedicated MetalLB address rather than a node address or NodePort. + +The external firewall port-forward/DNAT was intentionally not changed by this work. +The local-DNS test path is the Kubernetes policy basis: + +```text +void.aeternalisgames.com:7400 + -> 172.10.1.202:7400 + -> evo-region-session LoadBalancer Service + -> evolution-dev/evo-region:7400 +``` + +## Changes made + +- Reserved MetalLB VIP `172.10.1.202` in the disabled dev session-route Service. +- Restricted the Service source range to `172.10.1.0/24`. +- Restricted the matching NetworkPolicy ingress rule to `172.10.1.0/24` and TCP `7400`. +- Approved `172.10.1.0/24` as the explicitly permitted local test range in + `tools/ci/deploy-policy-check.py`. +- Updated the policy self-test fixtures for the now-resolved VIP and CIDR. +- Added the dev platform quota patch reserving exactly one LoadBalancer and zero + NodePorts. +- Updated ADR-0087 with the selected VIP, client range, local-DNS test path, and the + fact that firewall configuration remains external to the repository. +- Kept the route component disabled. It is not included by + `deploy/kubernetes/region/dev/kustomization.yaml` until server-enforced session + windows are implemented and tested. + +## Why the route uses a dedicated VIP + +A node address does not automatically route arbitrary TCP traffic to a pod. Using a +node address would require a NodePort, host networking, or a host-level proxy. The +selected LoadBalancer Service preserves source addresses with +`externalTrafficPolicy: Local`, avoids a session-data NodePort, and lets MetalLB own +`172.10.1.202` explicitly. + +Kubernetes may still allocate a `healthCheckNodePort` because the Service uses +`externalTrafficPolicy: Local`. That port is for kube-proxy health reporting, not +session traffic, and must remain closed at the edge firewall after the Service is +actually applied. + +## Deliberately not performed + +- No firewall/DNAT rule was changed. For Internet testing, forward TCP `7400` to + `172.10.1.202:7400` and restrict the source as appropriate. For local testing, + create a gateway DNS record for `void.aeternalisgames.com` pointing to + `172.10.1.202`. +- No live DNS record was changed. +- No TLS Secret or dev-CA certificate was created in the cluster. +- No Kubernetes Service was applied; the route remains disabled in GitOps. +- No stale `void` namespace object was deleted directly. Any remaining HTTP Ingress + must be removed through the repository/application that owns the `void` namespace. + +## Remaining gate + +The repository policy correctly refuses route activation until `evo-server` enforces an +absolute operator-opened session window. The runtime must preserve the original UTC +deadline across restarts, refuse expired configuration, stop accepting sessions and +synthetic inputs at expiry, close active connections, and drain pending commits. The +required expiry/restart/delayed-application/extend-close/clock-skew tests are not yet +implemented in this change. + +After that runtime work is complete: + +1. Add the session-window configuration to the dev Deployment and workflow. +2. Include `../dev-session-route` only in the dev region overlay. +3. Create the certificate Secret out-of-band with + `void.aeternalisgames.com` in its SAN. +4. Configure local DNS or the firewall port-forward. +5. Render and dry-run the manifests. +6. Sync `aevolution-dev` manually through Argo. +7. Record the allocated `healthCheckNodePort`. +8. Verify TLS connectivity and the complete session-window lifecycle. + +## Validation + +The pinned Kustomize validator was prepared and the current repository policy check +passed before this change: + +```text +kustomize v5.8.1 +70 objects in 68 files +126 rendered objects in 17 overlays +0 failures + +deploy policy selftest: 43 cases, 0 failures +git diff --check: clean +``` + +The route remains intentionally disabled, so no live endpoint or firewall reachability +is claimed by this report. diff --git a/tools/ci/deploy-policy-check.py b/tools/ci/deploy-policy-check.py index 64007da..b56a75b 100644 --- a/tools/ci/deploy-policy-check.py +++ b/tools/ci/deploy-policy-check.py @@ -46,7 +46,7 @@ ROUTE_ENABLING_PERMITTED = False # Addresses the route may use: RFC 1918 plus internal ranges the maintainer has # explicitly approved in ADR-0087 (none yet; the cluster LAN 172.10.0.0/16 is not # RFC 1918 and needs that approval before use). -APPROVED_INTERNAL = [] +APPROVED_INTERNAL = ['172.10.1.0/24'] INTERNAL = [ipaddress.ip_network(n) for n in ('10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16')] + \ [ipaddress.ip_network(n) for n in APPROVED_INTERNAL] diff --git a/tools/ci/deploy-policy-selftest.py b/tools/ci/deploy-policy-selftest.py index 485b224..4bc83d1 100644 --- a/tools/ci/deploy-policy-selftest.py +++ b/tools/ci/deploy-policy-selftest.py @@ -16,9 +16,9 @@ import tempfile ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')) ROUTE = 'deploy/kubernetes/region/dev-session-route/' DEV = 'deploy/kubernetes/region/dev/kustomization.yaml' -REAL = [(ROUTE + 'service.yaml', 'REPLACE-dev-session-vip', '10.20.30.40'), - (ROUTE + 'service.yaml', 'REPLACE-dev-test-client-cidr', '10.20.0.0/24'), - (ROUTE + 'networkpolicy.yaml', 'REPLACE-dev-test-client-cidr', '10.20.0.0/24')] +REAL = [(ROUTE + 'service.yaml', '172.10.1.202', '10.20.30.40'), + (ROUTE + 'service.yaml', '172.10.1.0/24', '10.20.0.0/24'), + (ROUTE + 'networkpolicy.yaml', '172.10.1.0/24', '10.20.0.0/24')] def edit(tree, path, old, new, count=1): @@ -103,11 +103,10 @@ def quota_one(tree): CASES = [ - ('enabling with unresolved markers', lambda t: enable(t), 'unresolved REPLACE marker'), - ('enabling before server-enforced windows', lambda t: (enable(t), resolve(t), quota_one(t)), + ('enabling before server-enforced windows', lambda t: (enable(t), resolve(t)), 'cannot be enabled until ADR-0087'), - ('non-RFC 1918 VIP without approval', lambda t: edit(t, ROUTE + 'service.yaml', 'REPLACE-dev-session-vip', - '172.10.1.210'), 'internal address'), + ('non-RFC 1918 VIP without approval', lambda t: edit(t, ROUTE + 'service.yaml', '172.10.1.202', + '172.11.1.210'), 'internal address'), # Review M9.8f P1: inline/JSON patches and namespace changes, seen only when rendered. ('reviewer reproduction (inline listener, sessions, inputs, ops port)', lambda t: ( inline_patch(t, DEV, env_patch('REGION_SESSION_LISTEN', '0.0.0.0:7400')), @@ -198,12 +197,12 @@ CASES = [ t, 'deploy/kubernetes/platform/stage/quota-lb.yaml', 'apiVersion: v1\nkind: ResourceQuota\nmetadata:\n name: aevolution-quota\n' 'spec:\n hard:\n services.loadbalancers: "1"\n'), 'LoadBalancers only in evolution-dev'), - ('world-open source range', lambda t: (edit(t, ROUTE + 'service.yaml', 'REPLACE-dev-test-client-cidr', '0.0.0.0/0'), - edit(t, ROUTE + 'networkpolicy.yaml', 'REPLACE-dev-test-client-cidr', '0.0.0.0/0')), + ('world-open source range', lambda t: (edit(t, ROUTE + 'service.yaml', '172.10.1.0/24', '0.0.0.0/0'), + edit(t, ROUTE + 'networkpolicy.yaml', '172.10.1.0/24', '0.0.0.0/0')), 'private range'), - ('public VIP', lambda t: edit(t, ROUTE + 'service.yaml', 'REPLACE-dev-session-vip', '8.8.8.8'), 'internal address'), + ('public VIP', lambda t: edit(t, ROUTE + 'service.yaml', '172.10.1.202', '8.8.8.8'), 'internal address'), ('policy CIDR differs from the Service', lambda t: edit(t, ROUTE + 'networkpolicy.yaml', - 'REPLACE-dev-test-client-cidr', '10.99.0.0/24'), + '172.10.1.0/24', '10.99.0.0/24'), 'exactly the Service source ranges'), ('policy admits another port', lambda t: edit(t, ROUTE + 'networkpolicy.yaml', 'port: 7400', 'port: 7401'), 'only TCP 7400'),