The website uses cookies to optimize your user experience. Using this website grants us the permission to collect certain information essential to the provision of our services to you, but you may change the cookie settings within your browser any time you wish. Learn more
I agree
Text direction?


To ensure clean separation of concerns, we have organized the units of containerd's behavior into components. Components are roughly organized into subsystems. Components that bridge subsystems may be referred to as modules. Modules typically provide cross-cutting functionality, such as persistent storage or event distribution. Understanding these components and their relationships is key to modifying and extending the system.

This document will cover very high-level interaction. For details on each module, please see the relevant design document.

The main goal of this architecture is to coordinate the creation and execution of bundles. Bundles contain configuration, metadata and root filesystem data and are consumed by the runtime. A bundle is the on-disk representation of a runtime container. Bundles are mutable and can be passed to other systems for modification or packed up and distributed. In practice, it is simply a directory on the filesystem.

Note that while these architectural ideas are important to understand the system, code layout may not reflect the exact architecture. These ideas should be used as a guide for placing functionality and behavior and understanding the thought behind the design.


External users interact with services, made available via a GRPC API.

  • Bundle: The bundle service allows the user to extract and pack bundles from disk images.
  • Runtime: The runtime service supports the execution of bundles, including the creation of runtime containers.

Typically, each subsystem will have one or more related controller components that implement the behavior of the subsystem. The behavior of the subsystem may be exported for access via corresponding services.


In addition to the subsystems, we have several components that may cross subsystem boundaries, referenced to as components. We have the following components:

  • Executor: The executor implements the actual container runtime.
  • Supervisor: The supervisor monitors and reports container state.
  • Metadata: Stores metadata in a graph database. Use to store any persistent references to images and bundles. Data entered into the database will have schemas coordinated between components to provide access to arbitrary data. Other functionality includes hooks for garbage collection of on-disk resources.
  • Content: Provides access to content addressable storage. All immutable content will be stored here, keyed by content hash.
  • Snapshot: Manages filesystem snapshots for container images. This is analogous to the graphdriver in Docker today. Layers are unpacked into snapshots.
  • Events: Supports the collection and consumption of events for providing consistent, event driven behavior and auditing. Events may be replayed to various modules
  • Metrics: Each components will export several metrics, accessible via the metrics API. (We may want to promote this to a subsystem.

Client-side components

Some components are implemented on the client side for flexibility:

  • Distribution: Functions for pulling and pushing images

Data Flow

As discussed above, the concept of a bundle is central to containerd. Below is a diagram illustrating the data flow for bundle creation.

Let's take pulling an image as a demonstrated example:

  1. Instruct the Distribution layer to pull a particular image. The distribution layer places the image content into the content store. The image name and root manifest pointers are registered with the metadata store.
  2. Once the image is pulled, the user can instruct the bundle controller to unpack the image into a bundle. Consuming from the content store, layers from the image are unpacked into the snapshot component.
  3. When the snapshot for the rootfs of a container is ready, the bundle controller can use the image manifest and config to prepare the execution configuration. Part of this is entering mounts into the execution config from the snapshot module.
  4. The prepared bundle is then passed off to the runtime subsystem for execution. It reads the bundle configuration to create a running container.
Related Notes
Get a free MyMarkup account to save this article and view it later on any device.
Create account

End User License Agreement

Summary | 19 Annotations
2020/08/20 08:41
2020/08/20 08:39
prepare the execution configuration
2020/08/20 08:39
2020/08/20 08:32
unpack the image into a bundle
2020/08/20 08:25
image name and root manifest pointers are registered with the metadata store
2020/08/20 08:24
image content into the content store
2020/08/20 08:24
pull a particular image.
2020/08/20 08:24
2020/08/20 08:21
a bundle is central to containerd
2020/08/20 08:16
metrics API
2020/08/19 16:45
Layers are unpacked into snapshots
2020/08/19 16:45
content addressable storage
2020/08/19 16:44
any persistent references to images and bundles
2020/08/19 16:44
code layout may not reflect the exact architecture
2020/08/19 16:43
2020/08/19 16:39
2020/08/19 16:37
2020/08/19 16:33
2020/08/19 16:33