MiniDock Build 24: Connect Same-Host Workloads

Bridge Networking

Design claim: Same-host container connectivity is built by connecting private network namespaces through virtual links and a host bridge.

Same host does not mean same network stack

Containers on one host need isolated interfaces, local peer connectivity, and external egress without sharing the host network stack. Connectivity is a set of scoped attachments, routes, and names, not an intrinsic property of a container record.

The tempting shortcut is straightforward: place every container directly in the host network namespace. The shortcut works only while addresses are static and every participant shares one host or trust zone. Host sharing removes per-container address and route isolation, creates port conflicts, and weakens network segmentation. Endpoint churn, isolation, or a second host exposes the missing scope and ownership information.

Cross the namespace with a virtual cable

A veth pair crosses the namespace boundary, one end enters the sandbox, the other joins a host bridge, and host routing or NAT provides egress. The mechanism separates membership from packet movement so drivers can implement the same connection contract at different boundaries.

Read the topology by following an endpoint from its sandbox through the selected network boundary, keeping control information separate from packet flow.

  flowchart TB
    subgraph HOST["host network namespace"]
      BR["bridge mdock0
172.18.0.1/16 (software switch)"]
      VA["veth-a (cable end)"]
      VB["veth-b (cable end)"]
      NIC["physical NIC
(host IP 203.0.113.7)"]
      BR --- VA
      BR --- VB
      BR -- "outbound only:
source NAT" --> NIC
    end
    subgraph SA["sandbox: container A"]
      EA["eth0 172.18.0.2"]
    end
    subgraph SB["sandbox: container B"]
      EB["eth0 172.18.0.3"]
    end
    EA === VA
    EB === VB
      

It connects container-side veth interfaces to a host bridge and egress path. Its central claim is that each sandbox reaches the bridge through its own attachment while the host controls forwarding between boundaries; the labels therefore describe authority rather than decorative grouping.

Attach, address, route, then forward

The bridge driver builds physical-network topology from virtual parts. The bridge is a software Ethernet switch living on the host. A veth pair is two interfaces acting as one cable: bytes in one end exit the other, even across namespace boundaries. For each container the driver creates a pair, pushes one end into the sandbox (renamed eth0, given an IP from the network's subnet), and plugs the other end into the bridge. Container-to-container traffic is then ordinary switching: A → cable → bridge → cable → B, never touching the host's physical NIC. Outbound traffic to the internet takes one extra hop — the host routes it out with source NAT, rewriting the private container IP to the host's own.

The driver creates the pair, moves one end into the sandbox, assigns address and routes, attaches the host end to the bridge, and installs required policy. Trace both the forward and cleanup paths; connectivity is correct only when allocation and removal agree about ownership.

The second figure tests the same model in motion: it traces endpoint creation, namespace movement, addressing, and cleanup.

  sequenceDiagram
    participant A as A's eth0 (172.18.0.2)
    participant BR as bridge mdock0
    participant B as B's eth0 (172.18.0.3)
    A->>BR: packet dst 172.18.0.3 (via veth cable)
    BR->>BR: switch lookup: which port owns that address?
    BR->>B: forward out B's veth port
    note over A,B: pure layer-2 switching —
the physical NIC never sees this packet
      

It traces endpoint creation, namespace movement, addressing, and cleanup. The ordering is valid only when it continues to preserve the stated invariant under retries and interruption.

A removed endpoint leaves no host debris

A container is removed after its bridge port is created, so the veth, routes, and policy must be reclaimed without disrupting peers. A stale or conflicting attachment must be refused or withdrawn locally rather than corrupting unrelated network state.

Each sandbox reaches the bridge through its own attachment while the host controls forwarding between boundaries. The rule binds reachability to explicit, current membership within the correct scope.

Wire MiniDock's local network

MiniDock connects same-host workloads through explicit virtual links rather than shared host identity. MiniDock now needs that connectivity property without being told which component to edit.