docs(dev-session): reserve 172.10.1.202 route

This commit is contained in:
aevolution-gitops-bot
2026-10-03 00:02:08 -04:00
parent cb31893a47
commit 6152d58fa6
8 changed files with 136 additions and 32 deletions
@@ -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
@@ -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}
@@ -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:
+7 -5
View File
@@ -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.
+9 -5
View File
@@ -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.
@@ -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.
+1 -1
View File
@@ -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]
+10 -11
View File
@@ -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'),