Files
aevolution/docs/engineering/VOID_SESSION_ROUTE_REPORT.md

4.2 KiB

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:

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:

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.