Lore

A short narrative history of the containerd codebase, derived from git history (initial commit Nov 2015 → v2.3.0 preparation Apr 2026).

Eras

The metrics-server origin (Nov 2015 – Mar 2016)

The repository started life on 2015-11-05 with 15a96783c "Initial commit" and 2af0f297f "Add basic counters". Early commits focused on a containers metrics service. The containerd name was already in place but the daemon's role was much narrower than what shipped later.

v0.x containerd as a Docker daemon split (Mar 2016 – Dec 2017)

After the Docker Engine refactor, containerd became the lower-half daemon that Docker's dockerd would call into. Image distribution, snapshots, and the runc shim landed in this period. Most files in the repository root from that era still trace their lineage to commits by Michael Crosby, Stephen Day, Derek McGowan, and Kenfe-Mickaël Laventure.

CRI integration and CNCF graduation (2018 – 2020)

The CRI plugin moved into the main repository and over time became the way containerd is consumed in the Kubernetes ecosystem. The project graduated within CNCF in 2019. Most of internal/cri/ predates the v2 reorg but has been moved several times.

v1.x stability (2020 – 2023)

The 1.x line settled on a stable plugin model, runtime v2 with the runc-v2 shim, and the bbolt-backed metadata store. Snapshotter implementations multiplied: overlay, btrfs, native, devmapper, blockfile, windows, lcow.

The v2 reorg (Jan 2024 – early 2024)

A high-density burst of file moves on 2024-01 carried out the v2 directory restructuring documented in CONTRIBUTING.md:

• 21b4f3f0a "Move content to core/content"
• 9456048f4 "Move containers to core/containers"
• 913edcd48 "Move diff to core/diff"
• 57ea8aef3 "Move images to core/images"
• f80760f9f "Move leases to core/leases"
• 1a1e0e8c8 "Move metadata to core/metadata"
• 6e5408dce "Move mount to core/mount"
• 0dabf6f15 "Move remotes to core/remotes"
• 228ad5a5c "Move sandbox to core/sandbox"
• fcd39ccc5 "Move snapshots to core/snapshots"
• df9b0a067 "Move metrics to core/metrics"
• dbc74db6a "Move runtime to core/runtime"
• f46aea618 (Feb 2024) "Move transfer and unpack packages"
• 72f21833b (Feb 2024) "Move events to plugins and core"

The containerd package that used to live at the repo root was renamed to client/ and the module path changed to github.com/containerd/containerd/v2. Source files were forbidden from the repo root from this point forward.

Sandbox controller maturity and proxy plugins (2024 – 2025)

a12acedfa (Feb 2024) "sandbox: make a independent shim plugin", 9104e6a24 (Mar 2024) "Add events proxy interface", ec04e4f63 (May 2024) "Add streaming proxy", and the streaming-by-default work b8dfb4d8f (Mar 2024) "cri: support io by streaming api" reflect the shift toward proxy-able subsystems.

Toward v2.3 (early – mid 2026)

The most recent commits in the repository prepare v2.3.0:

• 2976f38cc (2026-04-30) "Merge pull request #13325 from dmcgowan/prepare-v2.3.0" — current HEAD
• 77eeb2d8e (2026-04-29) "Prepare release notes for v2.3.0"
• c55ada3f3 (2026-04-29) "Update api to v1.11.0"
• b7f8c3510 (2026-04-29) "erofs: remove fsmerge threshold from snapshotter"
• 8f2fce4ce (2026-04-29) "Prepare release notes for v1.11.0" (the API submodule)

Long-standing pieces

• The runc shim at cmd/containerd-shim-runc-v2/ traces back to early v1 work on a shim-per-container model. The shim's contract — ttrpc on a unix socket, lifecycle events streamed back to the daemon — has been stable for years.
• The bbolt metadata store in plugins/metadata/ has been the canonical source of truth for images/containers/leases since v1.0.
• The overlay snapshotter at plugins/snapshots/overlay/ is the default on Linux and has survived every reorg.

Deprecated / removed

• The legacy "v1 runtime" (io.containerd.runtime.v1) — superseded by runtime v2 with the runc-v2 shim.
• cri-containerd-... release tarballs — kept as Makefile targets for backward compatibility but flagged "Deprecated (only kept for external CI)" in Makefile.
• The cmd/containerd-shim-runc-v1 shim, removed during the v2 reorg.
• gogo/protobuf is still pulled in transitively but new code uses google.golang.org/protobuf.

Major rewrites

• v2 directory reorg (Jan 2024): the largest single restructure, hundreds of files moved.
• Streaming-based CRI I/O (Mar 2024 onward): replaced fifo-based stdio plumbing with streaming requests.
• Sandbox controller refactor (Feb 2024): turned the sandbox controller into an independent shim plugin so non-pause-container sandboxes (microVMs, etc.) can plug in.

Speculation

Where the "why" behind a change isn't immediately clear from the commit message, this page sticks to what's verifiable. Read the linked PRs and the RELEASES.md for the official narrative around any specific change.