MiniDock Build 23: Segment Public and Private Networks

The Container Network Model

Design claim: Container networking separates network membership, endpoint attachment, and the sandbox that holds a container's network stack.

An address is an attachment, not an identity

A container may join multiple isolated networks while keeping one coherent network namespace and independently managed attachments. Connectivity is a set of scoped attachments, routes, and names, not an intrinsic property of a container record.

The tempting shortcut is straightforward: assign an IP address directly to a container record. The shortcut works only while addresses are static and every participant shares one host or trust zone. An address belongs to a network attachment, containers can have several attachments, and the network stack has a lifecycle distinct from any one network. Endpoint churn, isolation, or a second host exposes the missing scope and ownership information.

Separate network, endpoint, and sandbox

The model's power is in its arities. A sandbox belongs to one container. A network contains many endpoints and promises: members can reach each other; non-members cannot. An endpoint joins exactly one sandbox to exactly one network — so a container on two networks has two endpoints, two interfaces, two IPs. This is real segmentation: put web and db on an internal network, web alone also on a frontend network, and the db is unreachable from the edge by construction — no firewall rules to forget.

The model represents networks, endpoints, and sandboxes separately, then joins endpoints into the sandbox associated with the container. 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 LR
    subgraph FE["network: frontend"]
      EP1["endpoint
eth0 172.18.0.2"]
      EP0["endpoint
eth0 172.18.0.3"]
    end
    subgraph BE["network: internal"]
      EP2["endpoint
eth1 172.19.0.2"]
      EP3["endpoint
eth0 172.19.0.3"]
    end
    SW["sandbox: web"] --- EP1
    SW --- EP2
    SD["sandbox: db"] --- EP3
    PROXY["sandbox: edge-proxy"] --- EP0
    note1["db has NO endpoint on frontend
→ unreachable from the edge, by construction"]
    style note1 fill:#fff8ec,stroke:#f2ddb0
      

It shows multiple network endpoints joining one container sandbox. Its central claim is that each endpoint belongs to one network and joins one sandbox through an explicit lifecycle; the labels therefore describe authority rather than decorative grouping.

Join connectivity into a stable stack

The model's power is in its arities. A sandbox belongs to one container. A network contains many endpoints and promises: members can reach each other; non-members cannot. An endpoint joins exactly one sandbox to exactly one network — so a container on two networks has two endpoints, two interfaces, two IPs. This is real segmentation: put web and db on an internal network, web alone also on a frontend network, and the db is unreachable from the edge by construction — no firewall rules to forget.

A driver creates a network, allocation creates an endpoint, the engine creates or locates a sandbox, and join installs the attachment and connectivity. 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 orders create, allocate, sandbox, join, and rollback.

  sequenceDiagram
    participant U as User
    participant E as Engine
    participant N as Network "internal"
    participant S as Sandbox (web)
    U->>E: network connect internal web
    E->>N: allocate endpoint (IP from this network's subnet)
    N-->>E: endpoint ready: 172.19.0.2
    E->>S: create interface eth1 in the sandbox, assign IP
    E->>S: add routes for the internal subnet
    note over S: web now holds two endpoints —
traffic segregates by destination subnet
      

It orders create, allocate, sandbox, join, and rollback. The ordering is valid only when it continues to preserve the stated invariant under retries and interruption.

Partial attachment must stay local

Joining a second private network fails after the first is active, so cleanup must remove only the incomplete endpoint without destroying the sandbox. A stale or conflicting attachment must be refused or withdrawn locally rather than corrupting unrelated network state.

Each endpoint belongs to one network and joins one sandbox through an explicit lifecycle. The rule binds reachability to explicit, current membership within the correct scope.

Give MiniDock a composable network model

MiniDock can add connectivity without collapsing network policy into the container object. MiniDock now needs that connectivity property without being told which component to edit.