Before touring the internals, it helps to place containerd correctly in the stack of software that makes a container run at all — because it sits in a spot most beginners never realize exists.

When someone runs a container using Docker, they are typing a command into a tool called the Docker CLI, which talks to a background service called dockerd, the Docker Engine daemon. For a long time, Docker Engine handled everything itself, end to end — pulling images, managing storage, and actually starting processes. Over time, the Docker project deliberately pulled the lower, more fundamental parts of that job out into their own separate, independent piece of software, donated it to open, vendor-neutral governance, and gave it a name: containerd, pronounced “container-dee.” Docker Engine itself, today, is largely a friendly, feature-rich front end that talks to containerd underneath to actually get the real work done.

containerd’s own official description of itself is refreshingly narrow and precise: it is “an industry-standard container runtime with an emphasis on simplicity, robustness, and portability.” It deliberately does not try to be a complete, end-user-friendly platform with a polished command-line experience, image-building tools, or a rich plugin marketplace the way Docker Engine does. Its job is narrower, deeper, and more foundational: managing the complete lifecycle of a container on a single machine — pulling and storing images, preparing a filesystem for a container to run in, and starting, stopping, and supervising the actual container process — and exposing all of that functionality through a clean, well-defined programming interface that other, higher-level tools can build on top of.

This deliberate narrowness of scope is itself a design philosophy worth naming directly, because it explains so much of what follows in later chapters. A tool that tries to do everything for everyone tends to accumulate assumptions specific to whichever use case its original authors had most in mind, which quietly makes it harder for a genuinely different use case to build on top of cleanly later. By staying narrowly focused on the fundamental lifecycle of pulling images and running containers, and leaving user experience, orchestration policy, and higher-level workflow entirely to whatever client sits above it, containerd avoids baking in assumptions that would favor one particular platform over another, which is exactly what makes it equally natural, rather than merely tolerable, as a foundation for both Docker’s own opinionated tooling and Kubernetes’s very different orchestration model.

containerd is governed today by the Cloud Native Computing Foundation, the same vendor-neutral, non-profit organization that also oversees Kubernetes itself, and it has reached that foundation’s highest maturity level, called “graduated” status, reserved for projects considered stable, widely adopted, and production-proven at a very large scale. This governance detail matters practically, not just symbolically: it means containerd’s development and direction are not controlled by any single company, which is a large part of why competing platforms, including some that compete directly with Docker’s own tooling, are comfortable building on top of the exact same shared foundation.

It is worth being explicit about the historical motivation behind this extraction, because it explains a great deal about containerd’s present-day design priorities. Before containerd existed as a separate project, every tool that wanted to run a container on a machine effectively had to either depend on the full, monolithic Docker Engine, or reimplement a large amount of the same low-level plumbing itself, independently, with no guarantee that two separately reimplemented runtimes would behave identically in every edge case. This duplicated effort was genuinely wasteful across the industry, and it also meant subtle behavioral differences between runtimes could quietly cause a container that worked correctly under one platform to behave unexpectedly under another. Extracting the shared, foundational logic into containerd, and standardizing the interfaces around it, was a direct, deliberate response to exactly this problem.

containerd is built as a small core surrounded by a family of cooperating pieces, each with one clear, narrow job — understanding each piece is the fastest path to understanding the whole system.

containerd is deliberately organized as a small, stable core surrounded by a family of internal services and plugins, each handling one distinct concern: an image service for pulling and tracking images, a content store for the raw, downloaded layer data, a snapshot service for turning those layers into a real, usable filesystem, a container service for tracking container configuration and state, and a task service for actually starting, stopping, and monitoring the running process itself. Every single one of these services is reachable through the same gRPC API, which is exactly what makes containerd genuinely usable as a foundation by different higher-level tools, rather than a system with Docker-specific assumptions baked invisibly into its core.

flowchart TB
    A["Docker Engine (dockerd)"] -->|"gRPC"| C["containerd"]
    B["Kubernetes Kubelet"] -->|"CRI, gRPC"| C
    C --> D["Content Store"]
    C --> E["Snapshotters"]
    C --> F["containerd-shim-runc-v2"]
    F --> G["runc"]
    G --> H["Actual Container Process (Linux kernel)"]
        

This diagram is worth reading carefully, because the two arrows entering containerd from above are the whole story in miniature: two entirely different clients, built by different teams for different purposes, speaking to the exact same daemon through the exact same kind of structured API call. Neither Docker nor Kubernetes needs to know anything special about the other’s existence; each simply issues ordinary requests against containerd’s published interface, and containerd itself handles the rest identically regardless of which client happened to make the call.

The shim deserves special attention, because it explains one of containerd’s most practically valuable design decisions. Rather than having the containerd daemon itself directly parent every running container process, containerd spawns one small, lightweight shim process per running container, and that shim, not containerd itself, becomes the direct parent of the actual container process. The shim’s entire job is narrow: keep the container’s standard input and output streams connected, report the container’s exit status back to containerd, and keep the container running even if containerd itself is restarted or temporarily unavailable. This narrow, single-purpose design is deliberate, following the same minimal-surface philosophy that shapes containerd’s architecture at every layer.

Finally, runc is the piece that does the truly low-level work. It is a small, focused command-line tool implementing the Open Container Initiative runtime specification — a vendor-neutral, industry-agreed standard describing exactly how a container should be created on a Linux system. runc’s job, invoked by the shim, is to actually call into the Linux kernel and set up the isolation primitives — namespaces and control groups, covered in depth in Chapter 6 — and then start the container’s actual application process inside that isolated environment. Once that process is running, runc itself exits, leaving the shim as the process’s direct, lightweight supervisor.

It is worth noting explicitly that this entire architecture is built in deliberate, well-defined layers, each conforming to a published, vendor-neutral specification rather than a single company’s private implementation detail. The Open Container Initiative specification that runc implements exists specifically so that a container built and validated against one OCI-compliant runtime should behave identically under any other OCI-compliant runtime, and containerd’s own shim interface exists specifically so an entirely different runtime implementation can be swapped in without requiring any change at all to containerd itself, Docker, or Kubernetes above it. This layered, standards-based design is precisely what allows the pluggable, stronger-isolation runtimes discussed in Chapter 6 to exist as genuine drop-in alternatives rather than requiring an entirely separate, parallel ecosystem of tooling built around them.

Tracing exactly what containerd does, step by step, from receiving a request to a real process running on the machine, turns the architecture from Chapter 2 into a concrete, understandable sequence.

The task concept, introduced briefly above, is worth naming explicitly, because containerd deliberately separates it from the idea of a “container.” A container, in containerd’s own internal model, is really just a stored, persistent description — configuration, metadata, an associated snapshot — that can exist even while nothing is actually running. A task is the live, running execution of that container’s process at a given moment. This separation is what allows a container to be created, paused as a task, resumed, or even have its running task fail and be restarted, all while the container’s own underlying identity and configuration remain a single, stable, tracked object throughout.

This container-versus-task distinction is easy to underestimate on first read, but it has real, practical consequences worth spelling out. Because a container object can exist with no running task at all, containerd can represent a container that has been fully created and configured, with its filesystem snapshot already prepared, but deliberately not yet started — useful for platforms that want to prepare a container ahead of time and start it later with minimal delay. It also means that when a container’s process exits, whether cleanly or due to a crash, the task itself is what ends, while the container object, its configuration, and its filesystem snapshot can remain intact, ready to be inspected for diagnostic purposes or restarted as a fresh task without needing to rebuild the container’s configuration from scratch each time.

Zooming out from one single container to the full picture reveals how containerd organizes many containers, from many different clients, on one shared machine, without them stepping on each other.

containerd introduces its own concept of a namespace — not to be confused with the Linux kernel isolation namespaces covered in Chapter 6, though the two share a name and a similar spirit. A containerd namespace is a logical partition inside containerd’s own internal bookkeeping, letting completely separate clients — Docker Engine and Kubernetes’s kubelet, for instance — use the very same containerd daemon on the very same machine, storing and listing their own containers, images, and tasks, without ever seeing or interfering with each other’s. This is precisely what makes the shared-kitchen analogy from Chapter 1 literally true at the software level, not just a loose comparison.

sequenceDiagram
    participant Client as Client (Docker or Kubelet)
    participant CD as containerd
    participant Snap as Snapshotter
    participant Shim as Shim + runc
    Client->>CD: Pull image (into client's own namespace)
    CD->>CD: Store layers in content store
    Client->>CD: Create container from image
    CD->>Snap: Prepare root filesystem snapshot
    Client->>CD: Start task
    CD->>Shim: Spawn shim, invoke runc
    Shim-->>CD: Report running status, exit code on completion
        

Following one image’s full lifecycle end to end makes the whole picture concrete. An image begins as a reference to a specific, tagged artifact in a remote registry. Once pulled, its layers live permanently in containerd’s content store, addressed by their own content hash, exactly the same content-addressable principle covered in the discussion of Docker image layers. When a container is created from that image, a snapshotter produces a fresh, writable filesystem view built on top of those shared, read-only layers — the same layered, copy-on-write behavior described in the article on Docker storage drivers, just implemented here directly inside containerd’s own snapshot subsystem rather than through Docker Engine. When a task is started, that snapshot becomes the actual root filesystem the running process sees. When the container is eventually removed, its snapshot is released, though the underlying, shared image layers it was built from remain in the content store, ready to be reused instantly by the next container built from that same image.

The snapshotter layer deserves one further, closer look, because it is one of the more genuinely pluggable pieces of the entire architecture, in the same spirit as the runtime pluggability covered in Chapter 6. containerd does not hard-code one single way of turning stacked image layers into a usable filesystem; instead, it defines a snapshotter interface, and different snapshotter implementations can satisfy that interface using different underlying storage technologies — the overlay-filesystem approach covered in the article on Docker storage drivers is the most common default, but alternative snapshotters exist built on other filesystem technologies entirely, chosen for specific performance characteristics or specific storage hardware a given deployment happens to rely on. This mirrors, deliberately, the exact same design philosophy that produced the pluggable runtime layer: define a clear, stable interface, and let different implementations compete and specialize underneath it, rather than locking the entire system to one fixed choice made once and never revisited.

Pulling containerd out of Docker Engine and standardizing it as shared, vendor-neutral infrastructure was a deliberate trade, not an unambiguous, cost-free improvement.

This industry-wide consolidation is worth appreciating on its own terms, separate from any single technical feature. Getting competing companies and open-source projects to agree on shared, foundational infrastructure, rather than each defending their own separately built version, is a genuinely difficult organizational achievement, not just a technical one, and containerd’s vendor-neutral governance was a deliberate, necessary condition for making that agreement possible at all.

The complexity trade-off deserves a direct, honest response, since it is the concern raised most often by newcomers. For an ordinary developer using Docker day to day, this layered architecture is almost entirely invisible — Docker Engine’s own tooling continues to present the same familiar experience it always has, with containerd doing its work silently underneath. The added complexity becomes practically relevant mainly for platform engineers and infrastructure teams operating container platforms at scale, for whom understanding this layered architecture directly is exactly the kind of depth that turns a mysterious, hard-to-diagnose production problem into a well-understood one, addressable at precisely the right layer instead of by guesswork.

There is a second, more subtle trade-off worth naming as well: standardizing on one shared, widely used runtime is a genuine strength in ordinary circumstances, but it also means a vulnerability or a serious bug discovered in containerd itself has an unusually wide blast radius, since it potentially affects every platform built on top of it at once, rather than being isolated to a single vendor’s own, separately maintained implementation. In practice, this concentrated exposure is offset by the intense, broad scrutiny a widely used, foundational open-source project like containerd naturally receives from a large, diverse community of contributors and security researchers, but it remains an honest, structural trade-off worth understanding rather than assuming away. Diversity in implementation offers some protection against a single point of failure; a shared, well-maintained standard offers protection through depth of scrutiny and consistency instead. Neither trade-off is free, and containerd’s design represents a deliberate bet on the latter.

containerd itself does not invent container isolation; it orchestrates and configures kernel features that have existed in Linux for years, through runc, and its own architecture adds a distinct security boundary of its own.

The actual isolation a container experiences comes from two Linux kernel features that runc configures on containerd’s behalf: namespaces, which give a process its own private, restricted view of specific system resources — its own process list, its own network interfaces, its own filesystem mount points — so it cannot see or affect what is happening in other containers or on the host outside its own view, and control groups, commonly called cgroups, which limit and account for how much of a shared physical resource — CPU time, memory, disk input and output — any given process is allowed to consume, preventing one container from starving every other container sharing the same machine.

This last point is exactly why containerd’s own architecture deliberately supports pluggable runtimes rather than hard-coding runc as the only possible option. Because the shim layer described in Chapter 2 defines a well-specified interface rather than assuming runc specifically, containerd can just as easily hand a container off to an alternative runtime implementation — one that runs each container inside its own lightweight, hardware-isolated micro virtual machine instead of relying purely on shared-kernel namespaces, for workloads where that stronger isolation boundary is worth the additional resource cost. This pluggability is a direct, practical consequence of the same shim architecture originally motivated by upgrade safety in Chapter 3, now also serving a distinct, valuable security purpose.

It is worth being precise about one common point of confusion here: containerd’s own internal namespace concept from Chapter 4, used to separate Docker’s bookkeeping from Kubernetes’s bookkeeping on a shared machine, is an organizational convenience, not itself a security isolation boundary. It does not, on its own, prevent a process running inside one container from reaching another container through kernel-level namespaces and control groups, which remain the actual enforcement mechanism regardless of which containerd namespace either container’s metadata happens to be recorded under.

It is also worth being clear about where containerd’s own security responsibility genuinely does begin and end. containerd itself does not decide, on its own initiative, which namespaces or control-group limits a given container should receive; that configuration is supplied to it by the client making the request — Docker Engine, Kubernetes’s kubelet, or another caller — based on that client’s own configuration and policy. This means a meaningful share of a container’s actual real-world security posture is determined above containerd, by whichever client is requesting the container in the first place, and containerd’s own responsibility is faithfully and correctly carrying out whatever isolation configuration it is asked to apply, through runc, exactly as specified, every single time, with no silent shortcuts or inconsistencies.

Because containerd sits underneath both Docker and Kubernetes, its own health directly affects everything running above it — making it a layer worth monitoring in its own right, not just observing indirectly through the platforms built on it.

containerd exposes a structured, built-in event stream, reporting every meaningful state change — an image pull starting and completing, a container being created, a task starting, exiting, or being deleted — as a discrete, timestamped event. This event stream is precisely how higher-level platforms like Docker Engine and Kubernetes’s kubelet stay informed about what is actually happening at the runtime layer in real time, rather than having to repeatedly poll and ask. A team operating containerd directly can consume this same event stream to build monitoring and alerting specifically at the runtime layer, catching a runtime-level problem before it surfaces confusingly as an application-level symptom several layers higher up.

A second, practically important signal is shim process count, compared against how many containers should actually be running according to containerd’s own tracked state. Because each running container has its own dedicated shim, a mismatch between expected and actual shim counts is a strong, direct signal of a runtime-layer problem — an orphaned shim left behind after its container was supposed to be cleaned up, or a shim that failed to start correctly, leaving a container stuck in a state that neither Docker nor Kubernetes above it can fully explain from their own vantage point alone. This kind of mismatch is exactly the sort of problem that looks, from several layers above, like a vague, unexplained “container won’t start” or “container won’t stop” report, when the actual root cause is fully visible and easily diagnosed the moment someone checks shim state directly at the runtime layer instead.

A third is containerd’s own API responsiveness, since every operation any client performs — Docker starting a container, Kubernetes’s kubelet checking on a pod — ultimately depends on containerd’s gRPC API responding promptly. A machine under heavy load, with containerd itself struggling to keep up, can manifest as slow, seemingly unrelated symptoms several layers above — slow container starts, delayed status updates — that are much faster to diagnose correctly once containerd’s own API latency is tracked directly rather than inferred indirectly from higher-level platform behavior.

A fourth signal worth tracking, closely related to shim count, is snapshot storage growth over time. Because every container created draws on the snapshotter subsystem described in Chapter 4 to prepare its writable filesystem view, a machine that creates and removes many containers over its lifetime, without those snapshots being reliably cleaned up when their containers are removed, can quietly accumulate unused, orphaned snapshot data in exactly the same way stale, dangling image layers can accumulate at the Docker level, as covered in the article on image layer optimization. Tracking snapshot storage directly, separately from general host disk usage, surfaces this specific failure mode early, before it manifests only as a confusing, unexplained disk-space crisis with no obvious single cause.

These are the proven, repeatable patterns experienced platform teams reach for when building on or operating containerd directly, roughly in order of impact.

Together, these four patterns describe a coherent operational posture: consolidate on one well-understood shared foundation, apply stronger isolation deliberately rather than universally or never, observe the runtime layer directly rather than only through higher-level proxies, and trust — while still verifying — the specific architectural guarantees containerd was built to provide.

A fifth pattern worth naming explicitly is routine snapshot and content garbage collection, building directly on the monitoring signal introduced in Chapter 7. Rather than waiting for accumulated, orphaned snapshot data to become a visible disk-space emergency, mature teams schedule regular, automated cleanup of unused snapshots and unreferenced content-store entries, mirroring the same proactive cleanup discipline recommended at the Docker image layer in earlier articles, applied here directly at containerd’s own storage layer instead. This pattern reinforces the third pattern above particularly well, since the same monitoring that surfaces snapshot growth as a signal is exactly what confirms scheduled cleanup is actually working as intended, rather than silently falling behind unnoticed.

Every one of these anti-patterns is the exact mirror image of a pattern from Chapter 8, which is why recognizing the pattern makes the anti-pattern obvious.

A condensed, practical checklist — what to consistently do, and where teams most often slip.

containerd’s journey from an internal Docker component to a shared, industry-standard foundation is one of the most well-documented examples of successful, vendor-neutral infrastructure collaboration in the entire container ecosystem.

For most ordinary development and application work, no. Docker Engine’s own tooling continues to provide the familiar, complete experience most users interact with, and it talks to containerd underneath entirely on its own. Direct, hands-on knowledge of containerd becomes genuinely valuable specifically for platform engineers and infrastructure teams operating container platforms at scale, or anyone diagnosing a problem that turns out to live at the runtime layer itself.

No — this is one of the most common misconceptions. containerd is deliberately built as vendor-neutral, shared infrastructure, and Kubernetes talks to it directly and natively through the Container Runtime Interface, without needing Docker Engine in the middle at all. Several other platforms and cloud services also build directly on containerd as their own underlying runtime.

containerd is the higher-level daemon managing the complete lifecycle of images, containers, and tasks, exposing a rich API that clients like Docker and Kubernetes talk to. runc is a much smaller, lower-level tool that containerd, through its shim, actually invokes to perform the final, literal work of creating an isolated Linux process using namespaces and control groups. containerd manages the overall lifecycle; runc executes one specific, narrow step within it.

Primarily for upgrade and restart safety, as covered in Chapter 3. Because each running container’s true, direct parent process is its own dedicated shim rather than containerd itself, the containerd daemon can be restarted or upgraded without killing any already-running container, since each shim keeps its own container alive independently and simply reconnects once containerd comes back.

Yes, through its pluggable runtime support described in Chapters 6 and 8. Because the shim layer defines a well-specified interface rather than assuming a single, fixed runtime implementation, containerd can hand a container off to an alternative runtime that provides stronger, hardware-backed isolation, such as running each container inside its own lightweight virtual machine, for workloads where that additional isolation is worth its resource cost.

Docker Engine’s own image storage is, today, actually built directly on top of containerd’s own content store and snapshot subsystems described in Chapter 2, rather than being a separate, parallel implementation. This is exactly why an image pulled through Docker and an image pulled through Kubernetes on the same machine, if built from the same underlying layers, can share the very same stored content in containerd’s content store rather than being duplicated.

Architecturally, yes, since containerd’s own namespace mechanism from Chapter 4 is specifically designed to let multiple independent clients share one daemon while keeping their bookkeeping separate. In practice, most production Kubernetes deployments today run containerd directly, without Docker Engine in the middle at all, since Kubernetes talks to containerd natively through the Container Runtime Interface and does not require Docker’s own additional layer to function.

Because each running container’s direct parent process is its own dedicated shim rather than containerd itself, as explained in Chapter 3, the container’s actual process generally keeps running completely undisturbed even if containerd crashes. Once containerd restarts, it reconnects to the still-running shims, recovering its own view of exactly which containers and tasks are currently active without needing to restart any of them. This exact behavior is what makes containerd upgrades and even unexpected crashes far less disruptive than they would be under a simpler, monolithic architecture where the runtime daemon itself directly parented every container process.

Not necessarily, though the everyday experience does change. containerd ships with its own, much lower-level command-line client, intended primarily for debugging and direct interaction by platform engineers rather than as a full replacement for Docker’s own polished, feature-rich tooling. Most teams that adopt containerd directly do so specifically in a Kubernetes context, where Kubernetes’s own tooling becomes the primary day-to-day interface, with containerd itself operating silently underneath, much the same way it already does underneath Docker.

The chapters above moved from what containerd is, through its architecture, its internal mechanics, its trade-offs, its security model, its operational signals, its design and anti-patterns, and finally its real-world adoption across the industry — the same order a platform engineer would naturally want to learn it in, building each layer of understanding on the one directly before it.