API

containerd's wire API is defined as protobuf in the api/ directory, which is itself a separate Go module (api/go.mod). Clients import the generated stubs from github.com/containerd/containerd/api/....

Purpose

• Stable, language-neutral contracts for clients and proxy plugins.
• Three transports:
  • gRPC for client → daemon communication
  • ttrpc for daemon ↔ shim communication
  • HTTP (Prometheus, pprof) for observability

Why a separate module

api/ has its own go.mod so consumers (clients, proxy plugins, third-party tools) can import the contracts without pulling in the daemon's full dependency graph (bbolt, OCI, runtime libs). The main module pins the api module via replace during development; release tags are coordinated.

Top-level layout

api/
├── buf.gen.yaml         # buf code generation config
├── buf.lock
├── buf.yaml
├── doc.go
├── events/              # Event message types (TaskCreate, ImageDelete, ...)
├── go.mod / go.sum
├── next.txtpb           # buf descriptor of the API surface (committed)
├── releases/
├── runtime/
│   └── task/v3/         # Shim ttrpc API (TaskService)
├── services/            # gRPC service definitions, one directory per service
└── types/               # Shared message types (Mount, Descriptor, Platform, ...)

gRPC services

Under api/services/<name>/v1/<name>.proto:

Service	Proto	Purpose
Containers	api/services/containers/v1/containers.proto	CRUD on container records
Content	api/services/content/v1/content.proto	Read/write/list/walk content blobs
Diff	api/services/diff/v1/diff.proto	Apply and compute layer diffs
Events	api/services/events/v1/events.proto	Subscribe, publish, and forward events
Images	api/services/images/v1/images.proto	Image record CRUD
Introspection	api/services/introspection/v1/introspection.proto	Plugin and deprecation listing
Leases	api/services/leases/v1/leases.proto	Lease lifecycle
Mounts	api/services/mounts/v1/mounts.proto	Mount operations from the mount manager
Namespaces	api/services/namespaces/v1/namespace.proto	Namespace CRUD
Sandbox	api/services/sandbox/v1/*.proto	Sandbox lifecycle
Snapshots	api/services/snapshots/v1/snapshots.proto	Snapshotter interface as gRPC
Streaming	api/services/streaming/v1/streaming.proto	Bidirectional stream broker
Tasks	api/services/tasks/v1/tasks.proto	Task lifecycle (Create, Start, Kill, Exec, ...)
Transfer	api/services/transfer/v1/transfer.proto	High-level pull/push/import/export
TTRPC events	api/services/ttrpc/events/v1/events.proto	Event types over ttrpc (shim → daemon)
Version	api/services/version/v1/version.proto	containerd.version

Each service has both a v1 generated .pb.go/_grpc.pb.go and (where it makes sense) a _ttrpc.pb.go for the ttrpc transport.

Shim API

api/runtime/task/v3/task.proto defines the ttrpc TaskService. The shim implements it (in cmd/containerd-shim-runc-v2/task/) and the daemon-side runtime v2 manager calls it (in core/runtime/v2/).

Code generation

make protos regenerates everything via buf generate. The generation runs protoc-gen-go-grpc, protoc-gen-ttrpc, and the project's own protoc-gen-go-fieldpath. Constraints:

• make check-protos fails CI if the generated files are out of sync.
• buf-breaking.yml (.github/workflows/buf-breaking.yml) enforces no-breaking-change rules across PRs.
• buf format enforces protobuf style.

Stability

The api/ module follows the rules in RELEASES.md:

• New fields and methods may be added in any release.
• Existing fields, message types, and methods are not removed for the lifetime of the major version.
• Reserved field numbers are kept around when fields are deprecated.

Entry points for modification

• Add a service: create api/services/<new>/v1/<new>.proto, add a builtin in plugins/services/<new>/, and run make protos.
• Add a method: extend the existing .proto, regenerate, and implement in plugins/services/<svc>/service.go.
• Add an event type: see api/events/. Each event needs a typeurl registration so the events service can deserialize it.

For the actual server-side handlers, see Plugins → services.