Understanding PouchContainer’s Network Architecture and Connect Mechanism

Introduction

PouchContainer is an open‑source, lightweight enterprise‑grade container engine from Alibaba that offers strong isolation, high portability, and low resource consumption, enabling rapid containerization of existing workloads and improving data‑center resource utilization at massive scale.

The article focuses on the mechanism behind PouchContainer’s network implementation and explains how a container is dynamically connected to an existing network using the Connect method.

1. Mechanism of network implementation in PouchContainer

PouchContainer adopts Docker’s Container Network Model (CNM) and builds its networking on top of libnetwork. The core CNM components are Sandbox, Endpoint, and Network.

Sandbox represents a container’s network stack configuration, including its network namespace, interfaces, routing table, and DNS settings. It can be realized via Linux network namespaces, FreeBSD jails, or similar mechanisms, and a sandbox may contain multiple endpoints.

Endpoint links a sandbox to a network. It is typically realized with a veth pair: one end (eth0) resides inside the container, while the peer is attached to the host bridge. An endpoint belongs to a single network and a single sandbox.

Network is a collection of endpoints that can communicate with each other. Networks can be implemented with Linux bridges, VLANs, or other technologies, and a network may contain many endpoints.

2. Built‑in network modes

2.1 bridge mode

The default mode. When a container is created without specifying --net, PouchContainer creates a virtual bridge p0 on the host. The container’s eth0 receives an unused IP from the bridge’s subnet, and the bridge acts as the default gateway.

2.2 host mode

In host mode the container shares the host’s network namespace, so it has no separate IP or network interfaces and uses the host’s IP and ports, while other namespaces (fs, pid) remain isolated.

2.3 container mode

The container shares the network namespace of an existing container, reusing its veth pair.

2.4 none mode

The container gets an isolated network namespace but no network configuration; it cannot communicate until interfaces and IPs are manually added.

2.5 Interaction between CNM and network modes

A network is a uniquely identifiable group of endpoints; an endpoint can be thought of as a veth pair, and a sandbox may hold multiple endpoints, each representing a connection to a specific network.

3. Analysis of network connect flow

Key source file:

daemon/mgr/container.go

// Connect is used to connect a container to a network.
func (mgr *ContainerManager) Connect(ctx context.Context, name string, networkIDOrName string, epConfig *types.EndpointSettings) error {
    // ...
    if err := mgr.updateNetworkConfig(c, n.Name, epConfig); err != nil {
        return err
    } else {
        if err := mgr.connectToNetwork(ctx, c, networkIDOrName, epConfig); err != nil {
            return err
        }
    }
    return c.Write(mgr.Store)
}

The Connect function first resolves the target container and network, then examines epConfig, which holds CLI flags such as alias and IP range. If the container is not running, only updateNetworkConfig is called, updating the stored network settings without allocating a network interface. For a running container, connectToNetwork is invoked to allocate a veth pair, configure the host bridge, and attach the interface to the container’s sandbox, after which the metadata is persisted via c.Write(mgr.Store).

Implementation of connectToNetwork (same file):

func (mgr *ContainerManager) connectToNetwork(ctx context.Context, container *Container, networkIDOrName string, epConfig *types.EndpointSettings) (err error) {
    // ...
    endpoint := mgr.buildContainerEndpoint(container)
    // ...
    if _, err := mgr.NetworkMgr.EndpointCreate(ctx, endpoint); err != nil {
        // handle error
    }
    return mgr.updateNetworkConfig(container, networkIDOrName, endpoint.EndpointConfig)
}

The endpoint built by buildContainerEndpoint aggregates information from the container, the network, and the CLI flags. It is then handed to libnetwork’s EndpointCreate method.

Relevant source:

daemon/mgr/network.go

// EndpointCreate is used to create network endpoint.
func (nm *NetworkManager) EndpointCreate(ctx context.Context, endpoint *types.Endpoint) (string, error) {
    // ...
    epOptions, err := endpointOptions(n, endpoint)
    // ...
    endpointName := containerID[:8]
    ep, err := n.CreateEndpoint(endpointName, epOptions...)
    // ...
    sb := nm.getNetworkSandbox(containerID)
    if sb == nil {
        sandboxOptions, err := buildSandboxOptions(nm.config, endpoint)
        // ...
        sb, err = nm.controller.NewSandbox(containerID, sandboxOptions...)
    }
    // ...
    joinOptions, err := joinOptions(endpoint)
    // ...
    if err := ep.Join(sb, joinOptions...); err != nil {
        return "", fmt.Errorf("failed to join sandbox(%v)", err)
    }
    // Update endpoint settings (gateway, IP, etc.)
    epInfo := ep.Info()
    if epInfo.Gateway() != nil {
        endpointConfig.Gateway = epInfo.Gateway().String()
    }
    // ... other fields ...
    endpoint.ID = ep.ID()
    endpointConfig.EndpointID = ep.ID()
    endpointConfig.NetworkID = n.ID()
    // ...
    return endpointName, nil
}

This flow shows how libnetwork creates the endpoint, builds or retrieves the sandbox, joins the endpoint to the sandbox (allocating the veth pair), and finally updates the endpoint configuration with IP, gateway, and IDs.

4. Summary

Establishing a network connection involves three core steps: creating a sandbox (the container’s network namespace), creating an endpoint (the virtual network interface), and joining the endpoint to the sandbox. Once these steps complete, the container can communicate with other containers on the same network.