Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 111 Β· Getting Started

How Docker Works

Understand Docker's architecture: client, daemon, containerd and runc, registries, and the Linux namespaces and cgroups that isolate and limit every container.

You have run a few containers by now, and the commands probably felt like magic. A single docker run produced an isolated environment in a second. There is no magic, though, only a short chain of programs and a handful of Linux kernel features. Knowing that chain turns confusing situations (why does docker say it cannot connect? why can a container not see the host's processes? what does "killed" mean?) into simple ones.

In this lesson you will meet the components of Docker's architecture, follow a request through them, and then look at the two kernel features that do the real work: namespaces (what a container can see) and cgroups (how much a container can use). You will also confirm both from inside a running container.

The big picture

Docker is a client–server system. The command you type is only a client; the real work happens in a background service.

flowchart LR
    CLI["docker CLI<br/>(client)"] -->|"REST API"| D["dockerd<br/>(daemon)"]
    D --> CD["containerd"]
    CD --> R["runc"]
    R --> K["Linux kernel:<br/>namespaces + cgroups"]
    D <-->|"pull / push"| REG[("Registry")]

Your command goes to the daemon, which hands the work down to containerd and runc; the kernel does the actual isolation.

TEXT
 β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   REST API over a socket    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
 β”‚  docker CLI  β”‚ ──────────────────────────▢ β”‚  dockerd  (the Docker daemon)  β”‚
 β”‚  (the client)β”‚ ◀────────────────────────── β”‚  images, networks, volumes,    β”‚
 β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                             β”‚  builds, API                   β”‚
                                              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                                              β”‚ gRPC
                                              β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                                              β”‚  containerd                    β”‚
                                              β”‚  image store, container        β”‚
                                              β”‚  lifecycle, snapshots          β”‚
                                              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                                              β”‚ one shim per container
                                              β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                                              β”‚  runc  (OCI runtime)           β”‚
                                              β”‚  creates namespaces + cgroups, β”‚
                                              β”‚  starts the process, then exitsβ”‚
                                              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                                              β–Ό
                                                    your container process

Alongside this chain sits the registry, a remote server that stores images. The daemon (through containerd) talks to it when you pull or push.

The client: docker

The docker command parses your arguments, turns them into an HTTP request and sends it to the daemon. It does no container work itself. This is why the client and server versions in docker version can differ, why one client can talk to several daemons through contexts, and why on Windows the CLI (a Windows program) can control containers that run in a Linux VM:

CONSOLE
$ docker context ls
NAME              DESCRIPTION                               DOCKER ENDPOINT                             ERROR
default           Current DOCKER_HOST based configuration   npipe:////./pipe/docker_engine
desktop-linux *   Docker Desktop                            npipe:////./pipe/dockerDesktopLinuxEngine

The asterisk marks the active context. The endpoint is where the CLI sends requests: a Windows named pipe here, a Unix socket (unix:///var/run/docker.sock) on Linux, or an ssh:// or tcp:// address for a remote machine. The environment variable DOCKER_HOST and the docker context use command change it.

The daemon: dockerd

dockerd is a long-running background service. It exposes the Docker Engine API and owns the higher-level features: building images, networks, volumes, logging, and the Docker-specific behavior you know, such as --restart and port publishing. When you run docker ps, the daemon answers. When the daemon is stopped, every docker command fails with a "cannot connect" error, even though your containers might keep running (with the optional live-restore setting).

You can ask the daemon about itself:

CONSOLE
$ docker info --format '{{.ServerVersion}} on {{.OSType}}, runtime {{.DefaultRuntime}}, cgroup v{{.CgroupVersion}}'
29.8.1 on linux, runtime runc, cgroup v2

containerd: the container manager

Since Docker 1.11 the daemon delegates the container lifecycle to containerd, an independent project that also powers Kubernetes. containerd pulls and stores images, manages file system snapshots (the layers of the next chapters) and supervises running containers. In recent Docker versions containerd is also the default image store, which is why docker info on a modern installation may say the storage driver is overlayfs with driver-type: io.containerd.snapshotter.v1, rather than the older overlay2. Both achieve the same layered file system; you rarely need to care which one you have.

runc: the OCI runtime

When containerd needs a container to actually exist, it calls a low-level runtime that follows the Open Container Initiative (OCI) specification. The default is runc. runc does the kernel work: it creates the namespaces and cgroups, sets up the root file system, drops capabilities, applies the seccomp filter, and finally starts your process. After the container has started, runc exits. A tiny supervisor called the containerd shim stays behind to watch the process, keep its streams open and report its exit code. Because the shim, not the daemon, parents your container, a daemon restart does not have to kill your containers.

The OCI specifications matter for a practical reason: an image built with Docker runs on Podman, Kubernetes, containerd directly or a cloud service, because they all read the same standard formats.

Registries

A registry stores images in repositories, each holding tagged versions. When a name has no host part, Docker assumes Docker Hub. The full form of alpine:3.22 is docker.io/library/alpine:3.22; you can see Docker use it in docker pull output:

CONSOLE
$ docker pull alpine:3.22
3.22: Pulling from library/alpine
Digest: sha256:2e0b81d60597f449baa56dc25d355367869d2dca4cd57e866f1e2b52af3eb55f
Status: Image is up to date for alpine:3.22
docker.io/library/alpine:3.22

(When the image was missing locally, the status line reads Downloaded newer image instead.) The long sha256: value is the image's content digest, a fingerprint that identifies the image exactly. See Tags and Registries.

Following a request through the system

Putting the parts together, docker run --rm alpine:3.22 echo hi goes like this:

  1. The CLI sends create container and start container requests to dockerd over the socket.
  2. dockerd checks whether the image exists; if not, it asks containerd to pull it from the registry.
  3. dockerd prepares the container's configuration: networking (a virtual network interface and an IP address), mounts, environment, resource limits.
  4. containerd creates a writable snapshot on top of the image's layers and starts a shim.
  5. The shim calls runc, which creates the namespaces and cgroups, switches into the new root file system and executes echo hi.
  6. The output travels back through the shim, containerd and the daemon to your terminal.
  7. When the process exits, the shim reports the exit code, and (because of --rm) the daemon removes the container.

You can watch the daemon's side of this with docker events, which streams everything the daemon does. In one terminal run docker events --format '{{.Type}} {{.Action}}', in another run a container named demo; the events appear as they happen:

CONSOLE
$ docker events --filter container=demo --format '{{.Type}} {{.Action}} {{.Actor.Attributes.name}}'
container create demo
container attach demo
container start demo
container die demo

Those four lines are the container's life: created, attached to your terminal, started, and finished (die is the name of the event when the main process exits, regardless of success).

Namespaces: what a container can see

The kernel feature that makes a process feel alone on the machine is the namespace. A namespace wraps a global system resource so that processes inside see their own private copy of it. Docker gives each container a new namespace of every important kind:

Namespace Isolates Effect in a container
pid Process IDs The first process is PID 1; the host's processes are invisible.
net Network interfaces, routes, ports The container has its own eth0 and its own port space.
mnt Mount points The container sees only its image's file system plus its mounts.
uts Hostname The container has its own hostname.
ipc Shared memory, message queues No shared memory with other containers by default.
cgroup The view of the cgroup tree The container sees itself at the root of its own cgroup.
user User and group IDs Maps IDs between container and host (not used by default in Docker, but by rootless mode).
time Clocks Allows per-container clock offsets.

Every process on Linux lists its namespaces under /proc/<pid>/ns. Here they are from inside a container:

CONSOLE
$ docker run --rm alpine:3.22 ls -l /proc/self/ns
total 0
lrwxrwxrwx    1 root     root             0 Oct 23 14:11 cgroup -> cgroup:[4026532912]
lrwxrwxrwx    1 root     root             0 Oct 23 14:11 ipc -> ipc:[4026532910]
lrwxrwxrwx    1 root     root             0 Oct 23 14:11 mnt -> mnt:[4026532908]
lrwxrwxrwx    1 root     root             0 Oct 23 14:11 net -> net:[4026532913]
lrwxrwxrwx    1 root     root             0 Oct 23 14:11 pid -> pid:[4026532911]
lrwxrwxrwx    1 root     root             0 Oct 23 14:11 pid_for_children -> pid:[4026532911]
lrwxrwxrwx    1 root     root             0 Oct 23 14:11 time -> time:[4026532981]
lrwxrwxrwx    1 root     root             0 Oct 23 14:11 time_for_children -> time:[4026532981]
lrwxrwxrwx    1 root     root             0 Oct 23 14:11 user -> user:[4026531837]
lrwxrwxrwx    1 root     root             0 Oct 23 14:11 uts -> uts:[4026532909]

(Numbers and dates will differ; the point is that most of them are fresh.) The number in brackets identifies a namespace; processes with the same number share it. Notice that user has a low number, 4026531837, which is the initial namespace: by default Docker does not remap users, so root in the container is UID 0 on the host's kernel too, only with fewer capabilities. The other six are the container's own.

Namespaces are not all-or-nothing. You can choose to share one on purpose, for example --pid=host runs a container in the host's process namespace and --network=host uses the host's network. These are useful for debugging and special tools, but each one removes a layer of isolation, so use them deliberately.

You can prove the PID namespace is working by listing processes inside a container. There is exactly one other process besides your own command:

CONSOLE
$ docker run --rm alpine:3.22 ps
PID   USER     TIME  COMMAND
    1 root      0:00 ps

From the host, the same process has a normal, large PID; docker top shows the host's view:

CONSOLE
$ docker top demo
UID    PID     PPID    C   STIME   TTY   TIME       CMD
root   46022   45996   7   14:20   ?     00:00:00   sleep 100

(Columns slightly condensed; the PID differs on every machine.) Inside, that process is PID 1; outside, it is just another process with a parent (the shim). A container is a view of a normal process, not a separate machine.

Control groups: how much a container can use

Namespaces hide things; control groups (cgroups) limit them. A cgroup is a kernel object to which you attach processes and then set resource ceilings on CPU, memory, process count and disk I/O. Docker puts every container in its own cgroup. Without any options there are no limits, and memory shows as max:

CONSOLE
$ docker run --rm alpine:3.22 cat /sys/fs/cgroup/memory.max
max

Now ask for 64 MB of memory and half a CPU, then read the files that the kernel exposes to the container:

CONSOLE
$ docker run --rm --memory 64m --cpus 0.5 alpine:3.22 sh -c 'cat /sys/fs/cgroup/memory.max; cat /sys/fs/cgroup/cpu.max'
67108864
50000 100000

67108864 is exactly 64 Γ— 1024 Γ— 1024 bytes. 50000 100000 means "50,000 microseconds of CPU time in every 100,000 microsecond period", which is half a core. If a process in this container tries to use more than 64 MB, the kernel's out-of-memory killer ends it, and Docker reports exit code 137. These files are from cgroup v2, the unified hierarchy used by current kernels (check with docker info); older systems use cgroup v1, which has the same ideas but different file paths. Resource Limits covers limits in depth.

Union file systems and layers (a preview)

The last piece is the file system. An image is a stack of read-only layers, and a container adds a thin writable layer on top. The kernel (via overlayfs) presents the whole stack as one directory tree to the process. When the process changes a file, the change goes into the top layer only, so the image underneath never changes and many containers can share the same layers. You saw the effect in the previous lesson: a file created in one container was missing from a fresh one. Layers and the Union Filesystem takes this apart.

Why this matters in practice

  • "Cannot connect to the Docker daemon" means the client could not reach dockerd through the socket: it is stopped, you lack permission on the socket, or DOCKER_HOST/the context points somewhere unexpected.
  • Containers share the host kernel, so a kernel-level exploit can affect all of them. This is why security hardening matters and why VMs remain the stronger boundary.
  • Linux images run only on Linux kernels. On Windows and macOS this works because of the hidden VM; a Windows container is a different thing (it uses the Windows kernel) and is not covered here.
  • A container is a process. You can see it with docker top, kill it with docker kill, and limit it with cgroups. If you remember this, the model never feels mysterious.

You may hear that "Docker is deprecated in Kubernetes". What was removed was a Kubernetes shim for dockerd, not Docker images or containers. Kubernetes talks to containerd directly, and the images you build with Docker run there unchanged.

Check your understanding

Quick check Β· 5 questions

of 5 answered You scored / 5 Β· perfect!

  1. 1. What does the docker command-line program actually do?

    docker is a client. It talks to dockerd over a socket (or pipe). That is why you can control a remote or VM-hosted daemon with the same command.
  2. 2. Which component calls the kernel to create namespaces and cgroups and start the container process?

    containerd asks runc (through a shim) to create the container. runc sets up namespaces, cgroups, the root file system and security settings, then starts the process.
  3. 3. Inside a container, ps shows your command as PID 1. Why?

    The pid namespace gives the container its own process numbering. From the host the same process has a different, ordinary PID.
  4. 4. You run docker run --memory 64m ... and read /sys/fs/cgroup/memory.max inside the container. What do you see?

    Docker writes the limit into the container's cgroup, and the kernel shows it in bytes. Without a limit the file contains max.
  5. 5. What is the difference between namespaces and cgroups?

    Namespaces give isolated views of resources (processes, network, mounts...). Cgroups account for and cap CPU, memory, process counts and I/O.

Summary

  • Docker is client–server: the docker CLI talks to the dockerd daemon, which uses containerd, which uses runc to start containers.
  • A registry stores images; names without a host (like alpine:3.22) mean Docker Hub.
  • Namespaces (pid, net, mnt, uts, ipc, cgroup, user, time) give each container a private view of the system.
  • Cgroups limit CPU, memory and other resources; without options there are no limits.
  • Containers share the host kernel and are ordinary processes, which explains both their speed and their security trade-offs.
  • Images are read-only layer stacks; a container adds a thin writable layer.

Next: The Docker CLI