ADR-0006: Edge v1 WAN exception — direct Traefik, no L4 layer¶

Status¶

accepted (2026-08-30 — approver r4 verification t_02a006fc; operator authorization recorded in the WAN Edge v1 plan review trail)

Context¶

The master plan (§17 EdgeOps) preserves VRRP + IPVS + DSR as the production edge architecture and requires a DSR PoC (§17.4) before production. The rebuild has now reached the point where the first internet-facing service (docs.wetopi.net — serving the platform's own documentation statics, with HTTPS + basic auth) is desired BEFORE the full L4 edge stack is built.

The operator decided (2026-08-30, recorded in the WAN Edge v1 plan doc): to ease testing and debugging, v1 enters WITHOUT the L4 load-balancing layer — two edge nodes with Traefik exposed directly, DNS round-robin between two public A records.

The approver's plan-review (t_a79fed0e, t_2d5385cc) correctly held that this conflicts with the prevailing master plan and that an "ADR-lite" cannot reconcile the conflict: a published internet endpoint is not an "internal" service. Hence this ADR — the accepted mechanism (same as ADR-0004 superseding the §16 endpoint design).

Decision¶

For a bounded v1 window, the edge consists of exactly: - 2 RKE2 edge nodes (rke-wan01 79.137.114.193, rke-wan02 79.137.114.194, range 79.137.114.192/27, WAN NIC on vmbr3, mgmt NIC on vmbr4/LAN). History: these VMs were built and initially named wetopi3-wan1/wetopi3-wan2 and renamed to rke-wan01/rke-wan02 on 2026-08-30 (operator decree; vmids 8041/8042 unchanged) — the rke-wan names are the active/canonical ones everywhere (infrastructure repo PR #16); - bundled Traefik exposed DIRECTLY on the nodes' WAN interfaces (ports 80/443 ONLY; in-VM nftables deny-by-default); - HA via DNS round-robin over 2 A records (TTL 300) — explicitly reduced availability: no L4 health-check, no automatic failover. Failure semantics (precise): when a node dies, its A record CONTINUES to be returned by DNS until the node recovers or the record is explicitly removed/repointed — TTL does NOT end the failures; TTL only bounds how quickly a manual removal/repoint propagates to clients. Observed failure rate is approximately half of new connections but varies with client ordering, retries, connection reuse and resolver behavior. Remediation is OPERATOR-driven: per-address health monitoring (both A records probed independently), a documented manual removal path (tofu PR dropping the dead address, or emergency Cloudflare edit), and a safe re-addition procedure after node recovery (tofu revert).

The v1 exception applies ONLY to the services explicitly listed in this ADR:

docs.wetopi.net (documentation statics, HTTPS + basic auth) — first service, the low-risk pilot.
argo.wetopi.net (Argo CD WebUI, HTTPS + two auth layers) — second service, added by UPDATE 2026-08-30 (below).

No other service name is covered; each addition to this list is its own recorded operator decision (the security rule "nada más sin necesidad demostrada y decisión explícita" holds).

The exception is bounded by these hard conditions: 1. ANY service with external paying customers (hosting workloads) REQUIRES the v2 edge: VRRP public VIP + IPVS directors + DSR, with the §17.4 PoC checklist completed — no exceptions. 2. The v2 track is a scheduled deliverable, not an aspiration: it enters the plan BEFORE the hosting pilot phase (master plan §33 Fase 16). 3. Reduced-availability semantics are documented in the service's runbook and monitored (uptime checks on both A records independently). 4. Cluster-plane identity and traffic of edge nodes are LAN-only: RKE2 node identity (node-ip), management, kubelet, and Cilium/VXLAN flows use the LAN interface exclusively (node-ip bound to 10.72.0.5x; see WAN Edge v1 plan §F1). WAN is limited to INBOUND exposure on ports 80/443; ordinary node EGRESS (image pulls, updates, outbound internet) MAY use the WAN default route — that is not cluster-plane traffic.

UPDATE 2026-08-30 — scope + security posture for argo.wetopi.net¶

Operator directive (verbatim, 2026-08-30 ~17:00, goal session docs.wetopi.net thread):

"en cuanto podamos, tambien quiero argo.wetopi.net securizado a internet, y sacado con https, para poder ver el estado de argo desde webui"

This is the explicit decision the platform security rule requires ("nada más sin necesidad demostrada y decisión explícita") — recorded here verbatim per that rule. It adds the SECOND (and so far last) v1-window service:

Scope: - v1 window service list = docs.wetopi.net + argo.wetopi.net. argo.wetopi.net is the Argo CD WebUI: an operator-only CONTROL-PLANE UI for viewing Argo state from the web — NOT a customer-facing service. - NO external customers on either name; the v2-before-customers hard condition (1 above) is UNCHANGED and still binding. - Same edge machinery as docs.wetopi.net: the two A records (TTL 300, grey-cloud), the same reduced-availability DNS round-robin failure semantics, the same nftables WAN 80/443-only posture, TLS terminated at the edge Gateway.

Security posture for argo (TWO auth layers + edge TLS): 1. Layer 1 — Traefik basic-auth at the edge (Middleware argo-basic-auth, htpasswd Secret operator-managed on the cluster, never in Git). 2. Layer 2 — Argo CD's own login (local admin auth; SSO/Dex integration remains OPEN per the bootstrap decision). Both layers must succeed to reach the WebUI. 3. TLS: Let's Encrypt PRODUCTION certificate at the edge Gateway (argo-tls, DNS-01 via the cert-manager chain validated staging-first by the F3 edge-test gate) — a control-plane UI in daily operator use does not take a staging-cert detour. 4. argocd CLI unaffected: CLI usage continues over the LAN (API VIP), exactly as before the exposure — the WAN edge is an additional, authenticated view path, not a replacement. 5. Initial admin password rotated by the operator on first login (the bootstrap-time initial admin secret is a bootstrap artifact, not a durable credential).

Consequences¶

Positive: first internet-facing service ships weeks earlier; edge path debuggable end-to-end (client→Traefik, no L4 indirection); the 2 edge VMs and their RKE2 join carry over unchanged into v2 (the L4 layer is added IN FRONT, additive).
Negative: reduced availability during the whole v1 window (a dead address serves failures until operator remediation — removal/repoint propagates within the TTL bound; rollback to the legacy address is likewise TTL-bounded for clients with cached answers); no protection against a node serving while unhealthy (no L4 health-check) — mitigated by independent per-address uptime monitoring and the documented manual removal/re-addition runbook.
Neutral: the DSR bandwidth-aggregation benefit of §17 is not realized in v1 (irrelevant for a static docs site's traffic).

Alternatives considered¶

Build the full §17 edge first: rejected for sequencing — it adds weeks of IPVS/DSR PoC work before ANY internet-facing validation of the new platform; the docs service is deliberately the low-risk pilot.
Cilium LB-IPAM / BGP instead of IPVS: viable v2 alternative; deferred with the v2 track (would change the L4 choice at v2 design time).
Keep docs on the legacy platform: rejected — the goal is validating the NEW platform's edge chain (DNS→TLS→Gateway→pods) with the most innocuous workload possible.

Migration / implementation notes¶

This ADR supersedes master plan §17 ONLY for the v1 window and ONLY for the listed service; §17 remains the production target (v2).
Implementation plan: WAN Edge v1 (doc_wetopi-wan-edge-v1-plan.md r3) — F1..F5; the v2 track lives in the plan's F6 and becomes its own plan when scheduled.
Rollback of this decision = execute the v2 track ahead of schedule and repoint DNS (bounded by TTL).

WAN Edge v1 plan (base_project: doc_wetopi-wan-edge-v1-plan.md, r3)
ADR-0004 (endpoint HA precedent for superseding §16 via ADR)
master-architecture-plan §17 (superseded partially, v1 window), §33 Fase 14
Implementation: infrastructure PR #20 (kubernetes/edge-argo + DNS tfvars) — argo.wetopi.net service manifests; docs-site service (docs.wetopi.net) in infrastructure PR #15