How containerd/rust-extensions works
Project type and purpose
• This is a collection of Rust crates providing:
• TTRPC protocol bindings for containerd shims (“shim-protos”)
• A generic shim framework (“containerd-shim”)
• A runc-based shim implementation (“containerd-runc-shim”)
• gRPC client bindings for containerd’s API (“containerd-client”)
• Logging plugin extension (“containerd-shim-logging”)
• A remote snapshotter plugin (“containerd-snapshots”)
• A Rust wrapper around the runc CLI (“runc”)
• Purpose: enable developers to build containerd runtime shims, plugins, and clients in Rust.
File structure
• Top-level crates directory holds each sub-crate.
• “shim-protos” defines the TTRPC message definitions common to all shims.
• “shim” crate is a framework/library for building runtime v2 shims.
• “runc-shim” is a concrete shim that uses the “shim” framework + “runc” wrapper to launch containers.
• “client” provides gRPC clients to talk to containerd’s API.
• “snapshots” and “logging” are containerd plugin crates—loaded by containerd as external plugins.
• Build scripts (build.rs) generate code, scripts/ handle protobuf installation and vendoring.
Extract insights from README
• The README describes each crate and its role as a containerd extension.
• No single “monolithic” service – instead 6+ components that register with containerd as plugins or are consumed by other services.
Main components & interactions
a. External Services
• containerd daemon (main host agent)
• runc CLI (OCI runtime)
b. Plugins & Libraries (Rust crates)
• containerd-shim-protos: shared TTRPC interface definitions
• containerd-shim: generic shim framework (implements the containerd runtime-v2 shim protocol over TTRPC)
• containerd-runc-shim: a concrete shim binary that uses containerd-shim + runc wrapper
• containerd-client: gRPC client library for external tooling or admin code
• containerd-shim-logging: plugin for containerd’s logging subsystem
• containerd-snapshots: plugin for containerd’s snapshotter subsystem
• runc (Rust wrapper): library used by containerd-runc-shim to invoke runc CLI operations
c. Data flows & relationships
1. At runtime, containerd loads the shim plugin (binary) for managing containers.
2. containerd and shim communicate via TTRPC over stdin/stdout (protocol defined by shim-protos).
3. Shim uses runc wrapper to fork/exec the runc CLI and manage container processes.
4. containerd-shim-logging and containerd-snapshots register themselves as plugin services with containerd; containerd invokes them via gRPC (plugin activation) for logging and snapshot operations.
5. External tools or other services can use containerd-client to call containerd’s gRPC APIs.
Architectural patterns & principles
• Plugin-based architecture: each extension is a separate binary crate exposing a gRPC or TTRPC interface and dynamically loaded by containerd.
• Separation of concerns:
• shim-protos for interface definitions
• shim framework for protocol handling
• concrete shim implementations for specific runtimes (runc)
• logging & snapshot plugins for cross-cutting concerns
• client crate for consumer-side access
• Code generation via build.rs for protobuf/TTRPC bindings and vendoring for reproducible builds.
Essential elements
• Notes on code-generation steps (optional annotation)