← All writing

The Illustrated Guide to Docker Architecture: Daemon, containerd, runc, Namespaces & cgroups

· Sourabh G Kulkarni

Explore Docker internals: dockerd, containerd, runc, OCI standards, Linux namespaces, cgroups, overlay2 filesystems, and how a container truly boots.

Ask most developers what a Docker container is, and you will hear metaphors: "It's like a lightweight virtual machine with its own tiny operating system."

While helpful for newcomers, that mental model is technically incorrect.

There is no such thing as a "container" inside the Linux kernel. If you inspect the kernel source code, you will search in vain for a struct container.

Instead, a container is simply a standard Linux host process that has been wrapped in a set of isolation boundaries (Namespaces), throttled by resource constraints (cgroups), and mounted to a layered copy-on-write filesystem (OverlayFS).

Here is an architectural deep dive into Docker's internal engine, tracing what happens from the moment you run docker run down to the low-level Linux syscalls that boot a container.


1. The High-Level Component Stack

Modern Docker is not a monolithic binary. Following years of open-source standardization under the Open Container Initiative (OCI) and the Cloud Native Computing Foundation (CNCF), Docker was modularized into clean architectural layers:

┌────────────────────────────────────────────────────────┐
│                   Docker CLI (Client)                  │
│                     `docker run ...`                   │
└───────────────────────────┬────────────────────────────┘
                            │ (REST API via /var/run/docker.sock)
┌───────────────────────────▼────────────────────────────┐
│                  Docker Daemon (dockerd)               │
│      Image building, volumes, networking, auth         │
└───────────────────────────┬────────────────────────────┘
                            │ (gRPC via /run/containerd/containerd.sock)
┌───────────────────────────▼────────────────────────────┐
│                       containerd                       │
│    High-level runtime: image push/pull, lifecycle      │
└───────────────────────────┬────────────────────────────┘
                            │ (Executes containerd-shim)
┌───────────────────────────▼────────────────────────────┐
│                    containerd-shim                     │
│    Maintains stdout/stderr I/O; keeps container alive  │
└───────────────────────────┬────────────────────────────┘
                            │ (Invokes OCI CLI)
┌───────────────────────────▼────────────────────────────┐
│                         runc                           │
│    Low-level OCI runtime: configures namespaces/cgroups│
└───────────────────────────┬────────────────────────────┘
                            │ (clone / unshare syscalls)
┌───────────────────────────▼────────────────────────────┐
│                      Linux Kernel                      │
│        Namespaces, Control Groups (cgroups), VFS       │
└────────────────────────────────────────────────────────┘

Let's walk through what each component actually does during container creation.


2. Component Roles: From dockerd to runc

1. The Docker Client (docker)

A simple command-line interface. When you type docker run -d -p 80:80 nginx, it formats that request into an HTTP REST payload and sends it over the Unix domain socket /var/run/docker.sock to the daemon.

2. The Docker Daemon (dockerd)

The centralized background service responsible for user-facing management features:

  • Managing Docker build caches (BuildKit)
  • Creating virtual bridge networks (docker0)
  • Managing persistent volumes and credentials
  • Once ready to launch, it hands execution over to containerd via gRPC.

3. containerd (The Industrial-Strength Container Supervisor)

Originally carved out of Docker in 2016 and donated to the CNCF, containerd is the high-level container runtime that powers both Docker and Kubernetes (via the Container Runtime Interface, CRI):

  • Pulls OCI image layers from registries.
  • Unpacks layers into an active filesystem root.
  • Supervises running containers.

4. runc (The Low-Level OCI Execution Engine)

runc is a lightweight CLI wrapper written in Go that implements the official OCI runtime specification. It takes an unpacked root filesystem directory and a config.json specification file, talks directly to the Linux kernel, configures the isolation boundaries, executes the process, and exits.

5. containerd-shim (The Parent Proxy)

Notice that runc exits as soon as the container process starts! If runc exits, who holds the container's open file descriptors and standard I/O streams?

That is the job of containerd-shim. The shim runs as the immediate parent of the container process. This brilliant design means:

  • If dockerd or containerd crashes or gets upgraded, running containers do not terminate! The shim keeps them running without dropping a connection.
  • It captures exit codes and streams logs even when the main daemon restarts.

3. The Three Pillars of Linux Isolation

If containers are just regular Linux processes, how does Docker prevent a container from seeing processes or files on the host machine?

It uses three native Linux kernel features:

Pillar 1: Linux Namespaces (What You Can See)

Namespaces provide process virtualization. When a process runs inside a namespace, it has its own private view of the operating system:

NamespaceWhat It Isolates
PIDProcess IDs (Container process becomes PID 1 inside, while having a normal PID on the host)
NETNetwork interfaces, IP routing tables, port bindings
MNTFilesystem mount points (Container only sees its mounted root)
UTSHostname and domain name
IPCInter-Process Communication (shared memory, message queues)
USERUser and Group IDs (maps root inside container to unprivileged user on host)

Pillar 2: Control Groups / cgroups (What You Can Use)

While namespaces control visibility, cgroups control resource limits.

Implemented directly by the Linux kernel, cgroups enforce hard ceilings and quotas on:

  • Memory: resources.limits.memory (enforced by the kernel's memory subsystem; triggers OOMKilled if exceeded).
  • CPU: CFS (Completely Fair Scheduler) bandwidth quotas.
  • Disk I/O: Read/write IOPS throttles on block devices.

Pillar 3: OverlayFS (How You Store Files)

Container images are composed of immutable, read-only layers. When you run a container, Docker stacks those read-only layers using the Overlay2 storage driver:

[ Container Read-Write Layer ] (Ephemeral: stores modifications & logs)
──────────────────────────────────────────────────────────────────────────
[ Read-Only Image Layer 3   ] (e.g. npm dependencies)
[ Read-Only Image Layer 2   ] (e.g. Node.js runtime)
[ Read-Only Image Layer 1   ] (e.g. Ubuntu base OS)
  • When the container reads a file, OverlayFS looks down through the layers and returns it.
  • When the container modifies a file, OverlayFS uses Copy-on-Write (CoW): it copies the file up to the thin read-write layer and modifies it there, leaving the underlying base image pristine and shared across hundreds of other containers.

4. Tracing a Container from the Host

To prove that a container is just a normal Linux process, run an Nginx container on a Linux machine:

docker run -d --name web -m 512m nginx

Now inspect it using native Linux host utilities:

  1. Find the Container's Host PID:

    docker inspect -f '{{.State.Pid}}' web
    # Output: 4921
    
  2. Inspect the Process via ps on the Host:

    ps -ef | grep 4921
    

    On the host, process 4921 is just a standard worker process running nginx: master process. But inside the container, running ps shows it as PID 1.

  3. Inspect the cgroup Memory Limit:

    cat /sys/fs/cgroup/system.slice/docker-<id>.scope/memory.max
    # Output: 536870912 (Exactly 512 MB in bytes)
    

Summary Key Architectural Takeaways

  1. Modular Architecture: Docker CLI talks to dockerd, which delegates to containerd, which invokes runc via containerd-shim.
  2. No Kernel Container Object: Containers are regular processes isolated by Linux Namespaces and constrained by Control Groups (cgroups).
  3. Daemon Independence: Thanks to containerd-shim, the Docker daemon can crash or restart without terminating running containers.
  4. Overlay2 Storage: Image layers are shared, immutable read-only snapshots; container writes happen via copy-on-write on an ephemeral top layer.