Skip to content

ADR 0019 — OOBI Immutable VXLAN Fabric

  • Status: Accepted (formalized 2026-05-12 with v3.7.0 — scaffolds shipping in v3.7.0)
  • Date: 2026-05-10
  • Deciders: TLSStress.Art project
  • Targets: v5.0 (Phase 1 Materialization scaffolds: OOBI-1..5 + GW-1..3 + RELAY-1..3 already merged Wave 4-5)
  • Patent claim family: claims #1..#12 (DOM/OOBI/GATEWAY/RELAY)

Context

Prior to 2026-05 the bench's "mgmt overlay" was a soft convention — VLAN 99, subnet 10.254.254.0/24, no strict allocation rules. Two realizations pushed this to formalize:

  1. Lab Deployment Staging wizard (LDS-1..17) needs to bootstrap benches reliably. Soft conventions don't survive 30+ operators.
  2. Cloud-split future (CONTROL plane to SaaS) needs a deterministic transport between bench MÓDULOs + cloud orchestrator. Soft mgmt IP allocation can't carry that.

The decision: lock the OOBI fabric canonically + immutably. Every bench in every deployment uses the same fabric address space + the same VXLAN encap. Operator IP customization is rejected — this is the moral equivalent of TCP/IP port numbers.

Decision

OOBI becomes a canonically immutable VXLAN overlay with the following fixed elements:

Logical L2 + addressing — IMMUTABLE

Element Value
VLAN ID (underlay) 99
IPv4 subnet 10.254.254.0/24
IPv6 subnet (ULA) fd5a:7c5e:a72:0::/64
VXLAN VNI 254254
Encap UDP/4789, HER (Head-End Replication)
Mode tunnel (no L2 broadcast leakage outside the overlay)

Slot allocation (per ARCHITECTURE.md)

Range Function
.1-.3 Underlay infra (Nexus SVI, MGMT0, NGFW MGMT)
.4-.49 Spare for DUT mgmt expansion
.50-.79 MGMT-light MÓDULOs (allocated as needed)
.80-.84 Special slots (CA / DoYour / KALI / HAR / VALIDATOR)
.85-.99 Spare
.100 Infra Stack VIP — sole initiator of OOBI traffic
.220 MÓDULO TREX.Art
.230 MÓDULO SPAN.Art
.240-.241 MÓDULO RELAY.Art (HA pair)
.250 MÓDULO GATEWAY.Art

3-phase bootstrap

Phase 1 — CABLING
  Operator physically cables UCS hosts to OOBI mgmt switch.
  All MÓDULO pods come up with stub OOBI iface, no L3 yet.

Phase 2 — mDNS DISCOVERY
  Each MÓDULO advertises _tlsstress-oobi._tcp via mDNS on stub iface.
  Leader election (RAFT-style) picks the orchestrator instance.
  Operator's dashboard polls discovery state every 5s.

Phase 3 — OVERLAY UP
  Orchestrator hands out VXLAN VNI + per-MÓDULO IPs.
  Each pod brings up vxlan0 interface (master eth0, VNI 254254).
  VTEP table populated via HER multicast.
  Connectivity check: ping Infra VIP from each MÓDULO.

Three trust zones

Zone Examples Trust assumption
OOBI overlay All .50-.250 MÓDULOs TRUSTED — orchestrator can rely on identity
OOBI underlay VLAN 99 packets pre-VXLAN SEMI — physically yours, but soft
Customer MGMT Customer NGFW/switch mgmt ports UNTRUSTED — touch only via RELAY.Art

DUTs and customer-side switches NEVER join the OOBI overlay. RELAY.Art (slot .240/.241, HA pair) bridges OOBI ↔ customer MGMT via dedicated NICs.

Architecture

┌─ Bench K8s cluster ───────────────────────────────────────────────┐
│                                                                  │
│  ┌─ OOBI VXLAN overlay (VNI 254254, 10.254.254.0/24) ─────────┐  │
│  │   .50-.84 MGMT-light  .100 Infra VIP  .220 TREX  .230 SPAN │  │
│  │   .240/.241 RELAY     .250 GATEWAY                          │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                          │ VLAN 99 underlay                      │
│                          ▼                                       │
│              ┌─ Nexus 9000 / linux-bridge ─┐                     │
│              └──────────────────────────────┘                    │
└──────────────────────────────────────────────────────────────────┘
                          │
                          ▼ (RELAY.Art bridges only)
              ┌─ Customer mgmt network ─┐
              │   NGFW MGMT, switches    │
              └──────────────────────────┘
                  (UNTRUSTED zone)

Consequences

Pros

  • Reproducible: every bench bootstraps identically
  • Cloud-split ready: CONTROL plane can move to SaaS w/o touching DATA
  • Strict isolation: DUTs cannot inject into OOBI overlay
  • Patent moat: VXLAN fabric + 3-phase bootstrap = 4 of 17 claims

Cons / risks

  • No operator IP customization (intentional — operator pushback expected)
  • Requires Multus + VXLAN kernel module in every K8s node
  • HER multicast can be noisy at scale (>50 MÓDULOs) — future ADR may introduce BGP EVPN

Compatibility

  • Pre-2026-05 benches running soft mgmt overlay → migration script scripts/oobi-migrate-v1-to-v2.sh (scaffold shipping in v3.7.0 Tier-3 batch D — no-op until v2 schema lands)
  • Single-node dev benches (Docker Desktop) → fabric runs in-host as Linux bridge + vxlan; otherwise behavior identical

References

  • Memory: discuss_oobi_immutable_gateway_art_2026_05_10.md
  • Code: dashboard/src/lib/oobi/canon.ts, pkg/oobi/canon.go (constants, Wave 4)
  • Code: scripts/airgap-oobi-canon-verify.sh (preflight, OOBI-2)
  • Code: k8s/oobi/ (VTEP + GATEWAY + RELAY manifests)
  • Patent claims: #1..#4 (OOBI fabric subset of DOM family)