Neos - What I Learned

Appearance

Lesson 4.5: Container Network Models (CNM) ​

Welcome to the final lesson of Phase 4! You've learned about bridge, host, none networks, and how to publish ports. Now it's time to look under the hood. Docker's networking is built on the Container Network Model (CNM) – a design that provides pluggable networking for containers. In this lesson, you'll explore the CNM architecture, understand its components, and see how Docker implements network isolation and connectivity. By the end, you'll have a deeper appreciation for how container networking works and how you can extend it with plugins.

Learning Objectives ​

TIP

By the end of this lesson, you will be able to:

  • Describe the three main components of the Container Network Model: Sandbox, Endpoint, and Network.
  • Explain the role of libnetwork in Docker networking.
  • Understand how network drivers (bridge, overlay, etc.) fit into the CNM.
  • Differentiate between CNM and the older docker daemon networking implementation.
  • Inspect CNM objects using docker network inspect and docker inspect.
  • Recognize the potential for third‑party network plugins.

1. What is the Container Network Model (CNM)? ​

The Container Network Model is a specification proposed by Docker that defines the building blocks for container networking. It was developed as part of the libnetwork project, which is the native network management library for Docker.

CNM aims to:

  • Provide a pluggable architecture: you can swap out the network driver (e.g., use a third‑party overlay driver) without changing the container runtime.
  • Separate the concerns of network management from the container runtime.
  • Enable multi‑host networking (overlay networks) for orchestration tools like Docker Swarm and Kubernetes.

INFO

In practice, when you run a container, Docker (via libnetwork) creates a CNM‑compliant network stack that isolates the container's network namespace, connects it to a network, and provides service discovery.

2. The Three CNM Components ​

The model defines three primary objects:

2.1. Sandbox ​

A sandbox is an isolated network stack. It contains the container's network configuration: interfaces, routing tables, DNS settings, etc. In Linux, a sandbox corresponds to a network namespace. Each container has its own sandbox, ensuring network isolation.

  • A sandbox can hold multiple endpoints.
  • The sandbox can be moved between networks (by disconnecting and reconnecting endpoints).

2.2. Endpoint ​

An endpoint connects a sandbox to a network. It's the virtual network interface (veth pair) that plugs into the network. The endpoint has an IP address, MAC address, and other properties.

  • An endpoint belongs to exactly one sandbox and exactly one network.
  • In a bridge network, the endpoint is the container's side of the veth pair; the other side is plugged into the bridge.

2.3. Network ​

A network is a collection of endpoints that can communicate with each other. It provides the rules for connectivity (e.g., bridge, overlay). Networks are created and managed by network drivers.

  • A network can contain multiple endpoints.
  • Each network is isolated from others (unless explicitly connected via routing).

When you run docker run --network mynet, Docker:

  1. Creates a sandbox (if not already present).
  2. Creates an endpoint with an IP address from the network's IP pool.
  3. Attaches the endpoint to the sandbox (plugs the veth into the container's namespace).
  4. Attaches the endpoint to the network (plugs the other veth into the bridge or other driver).

3. libnetwork and Network Drivers ​

libnetwork is the reference implementation of CNM. It is integrated into Docker and provides the API for managing networks. It delegates the actual network creation to network drivers.

3.1. Built‑in Drivers ​

DriverDescription
bridgeCreates a Linux bridge and veth pairs.
overlayCreates an overlay network across multiple hosts (used by Swarm).
macvlanAssigns a MAC address to containers, making them appear as physical devices.
ipvlanSimilar to macvlan but at layer 3.
hostRemoves isolation, shares host network stack.
noneDisables all networking.

3.2. Remote Drivers ​

Third‑party vendors can implement the CNM driver API to provide their own network solutions (e.g., Cisco Contiv, VMware NSX, Calico, Weave). These are loaded as plugins.

When you run docker network create -d weave mynet, Docker loads the Weave plugin, which implements the CNM driver interface.

4. How Docker Uses CNM (Step‑By‑Step) ​

Let's trace the creation of a container with a custom bridge network.

  1. User runs: docker network create mybridge

    • Docker creates a network object with driver bridge.
    • The bridge driver creates a Linux bridge on the host (e.g., br-abc123).
    • The network gets a subnet and gateway (either default or user‑specified).

  2. User runs: docker run --network mybridge --name c1 alpine sleep 3600

    • Docker (via libnetwork) creates a sandbox for the container (a new network namespace).
    • It creates an endpoint (veth pair) with one end placed in the sandbox and the other plugged into the bridge.
    • The endpoint is assigned an IP from the network's subnet.
    • The container's network namespace is configured with that IP, default route via the bridge gateway.
    • The endpoint is added to the network's internal list.

  3. Second container on same network:

    • Similar steps, but the sandbox already exists (new container, new sandbox).
    • Endpoint added to the same bridge.
    • Now the two containers can communicate because they are on the same bridge.

  4. DNS resolution:

    • Docker runs an embedded DNS server that listens on 127.0.0.11 inside each container.
    • When container c2 tries to resolve c1, the DNS returns the IP of c1 (from the network's endpoint list).
    • This works for user‑defined bridge networks but not the default bridge.

5. Inspecting CNM Objects ​

Docker's CLI exposes CNM objects through network and container inspection.

5.1. Inspect a Network ​

bash
docker network inspect mybridge

You'll see:

  • Driver: bridge
  • Scope: local
  • IPAM (IP Address Management): subnet, gateway, IP range
  • Containers: list of endpoints attached, with their IPs and container names

5.2. Inspect a Container's Networking ​

bash
docker inspect c1

Look at the NetworkSettings section. It contains:

  • Networks: For each network the container is attached to, you'll find the endpoint IP, gateway, and aliases.
  • SandboxKey: The path to the network namespace (e.g., /var/run/docker/netns/...).

5.3. Advanced: See Namespaces ​

On Linux, you can enter the container's network namespace with nsenter (requires root and the PID). Example:

bash
# Get container PID
docker inspect -f '{{.State.Pid}}' c1
# Enter its network namespace
sudo nsenter -t <PID> -n ip addr

This shows the network interfaces inside the sandbox.

6. CNM vs. Legacy Networking ​

Before libnetwork, Docker's networking was tightly coupled to the docker daemon. The introduction of CNM brought:

  • Pluggable drivers (third‑party network plugins).
  • Better multi‑host networking (overlay).
  • Clear separation between the container runtime and network management.
  • Improved service discovery (DNS) for user‑defined networks.

The default bridge network (the old docker0) still exists for backward compatibility, but user‑defined bridges are the CNM way.

7. Hands‑On Tasks ​

Task 1: Explore CNM Components with a User‑Defined Bridge ​

  1. Create a network:
    bash
    docker network create cnm-net
  2. Inspect the network and note the Containers section (empty).
  3. Run two containers on this network:
    bash
    docker run -d --name c1 --network cnm-net alpine sleep 3600
docker run -d --name c2 --network cnm-net alpine sleep 3600
  4. Inspect the network again. Now you'll see the containers listed under Containers with their endpoint IDs and IPs.
  5. Inspect one container (docker inspect c1) and look at NetworkSettings.Networks["cnm-net"]. You'll see its IP, gateway, and endpoint ID.

Task 2: View the Underlying Linux Interfaces (Linux Only) ​

  1. Find the bridge name associated with the network:
    bash
    docker network inspect cnm-net | grep -i bridge
    The output shows something like: "com.docker.network.bridge.name": "br-abc123"
  2. Use brctl show or ip link show to list bridges. You'll see the bridge created by Docker.
  3. List veth pairs: ip link show | grep veth. One end of each veth is attached to the bridge; the other is inside the container.
  4. If you have root access, enter the container's network namespace (see advanced) and observe the interfaces.

Task 3: Create a Network with a Remote Driver (Simulate) ​

Though you don't have a third‑party plugin, you can see the remote driver concept by looking at Docker's network plugin directory:

bash
ls /var/lib/docker/plugins/  # may show plugins if installed

(Not necessary for the exercise.)

Task 4: Compare Default Bridge vs. User‑Defined Bridge ​

  1. Inspect the default bridge: docker network inspect bridge.
    • Note the Containers section – it shows containers attached to the default bridge (if any).
    • There is no DNS service; the Options field may show "com.docker.network.bridge.default_bridge": "true".
  2. Compare with the cnm-net you created. The user‑defined network has an embedded DNS server and service discovery.

Task 5: Endpoint Details ​

  1. Create a new container on a user‑defined network, but do not start it:
    bash
    docker create --name c3 --network cnm-net alpine sleep 3600
  2. Inspect the network: you'll see the container listed under Containers but with a placeholder (it doesn't have an IP yet because it's not running).
  3. Start the container:
    bash
    docker start c3
  4. Inspect again; now it has an IP.
  5. Disconnect the container from the network:
    bash
    docker network disconnect cnm-net c3
  6. Inspect the network – c3 is gone. The endpoint is removed.

Task 6: Multi‑Endpoint Sandbox ​

  1. Run a container attached to two networks:
    bash
    docker run -d --name c4 --network cnm-net alpine sleep 3600
docker network create other-net
docker network connect other-net c4
  2. Inspect the container: docker inspect c4 – under NetworkSettings.Networks you'll see two networks listed, each with its own endpoint IP.
  3. This container has a single sandbox (one network namespace) but two endpoints (two virtual interfaces) inside that namespace.

Summary ​

Key Takeaways

  • The Container Network Model (CNM) defines how container networking is structured, with sandbox, endpoint, and network as key abstractions.
  • libnetwork is the reference implementation of CNM used by Docker.
  • Network drivers (bridge, overlay, etc.) implement the underlying connectivity.
  • User‑defined networks use CNM features like embedded DNS and service discovery.
  • You can inspect CNM objects via docker network inspect and docker inspect.
  • CNM enables pluggable networking, allowing third‑party drivers to be used.

Check Your Understanding ​

  1. What are the three core components of the Container Network Model?
  2. How does a sandbox relate to a container's network namespace?
  3. What is the role of a network driver in CNM?
  4. How does Docker's embedded DNS work on user‑defined networks?
  5. Why does the default bridge network not support container name resolution?
  6. How can you list the veth pairs created for a specific bridge network on Linux?
Click to see answers
  1. Sandbox (isolated network stack), Endpoint (connection between sandbox and network), and Network (collection of endpoints).
  2. A sandbox corresponds directly to a Linux network namespace—a container's isolated view of network interfaces, routing tables, and DNS configuration.
  3. Network drivers implement the actual network creation and management. They handle creating bridges, overlay tunnels, or other network types, and provide the connectivity rules for endpoints.
  4. Docker runs an embedded DNS server at 127.0.0.11 inside each container on user-defined networks. When a container queries for another container's name, the DNS server returns the IP from the network's endpoint list.
  5. The default bridge predates CNM and doesn't include the embedded DNS server. Only user-defined bridges have the DNS service that enables name resolution.
  6. Use ip link show | grep veth to see veth pairs, or inspect the specific bridge with ip link show br-xxx to see which veths are attached.

Additional Resources ​

Next Up

This concludes Phase 4: Networking in Docker. You now have a comprehensive understanding of Docker's networking capabilities, from basic bridge networks to the underlying CNM architecture. In Phase 5, you'll learn Docker Compose – the tool for defining and running multi‑container applications. See you there!