# containerd/rust-extensions architecture

> Architecture diagram of the GitHub repository containerd/rust-extensions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/containerd/rust-extensions
- Repository: https://github.com/containerd/rust-extensions

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        direction TB
        Client["containerd-client (gRPC client)"]:::client
        RuncCLI["runc CLI (OCI runtime)"]:::external
    end

    %% Core Daemon
    Containerd["containerd daemon"]:::external

    %% Rust Plugins (loaded by containerd)
    subgraph "Containerd Plugins" 
        direction TB
        RuncShim["containerd-runc-shim"]:::plugin
        Logging["containerd-shim-logging"]:::plugin
        Snapshots["containerd-snapshots"]:::plugin
    end

    %% Rust Libraries/Crates
    subgraph "Rust Crates"
        direction TB
        ShimProtos["containerd-shim-protos"]:::lib
        ShimFW["containerd-shim (framework)"]:::lib
        RuncWrap["runc (wrapper)"]:::lib
    end

    %% External to Containerd
    Client -->|"gRPC"| Containerd
    Containerd -->|"gRPC"| Logging
    Containerd -->|"gRPC"| Snapshots
    Containerd -->|"TTRPC"| RuncShim
    RuncShim -->|"uses TTRPC protocol definitions"| ShimProtos
    RuncShim -->|"built on framework"| ShimFW
    ShimFW -->|"defines protocol via TTRPC"| ShimProtos
    RuncShim -->|"invokes via wrapper"| RuncWrap
    RuncWrap -->|"CLI exec"| RuncCLI

    %% Code Generation Dependencies
    ShimProtos -.->|"build.rs generates bindings"| ShimFW
    ShimProtos -.-> ShimProtos
    ShimProtos -.-> Logging
    ShimProtos -.-> Snapshots

    %% Click Events
    click ShimProtos "https://github.com/containerd/rust-extensions/tree/main/crates/shim-protos/"
    click ShimProtos "https://github.com/containerd/rust-extensions/blob/main/crates/shim-protos/Cargo.toml"
    click ShimProtos "https://github.com/containerd/rust-extensions/blob/main/crates/shim-protos/build.rs"
    click ShimProtos "https://github.com/containerd/rust-extensions/blob/main/crates/shim-protos/src/lib.rs"
    click ShimFW "https://github.com/containerd/rust-extensions/tree/main/crates/shim/"
    click ShimFW "https://github.com/containerd/rust-extensions/blob/main/crates/shim/Cargo.toml"
    click ShimFW "https://github.com/containerd/rust-extensions/blob/main/crates/shim/src/lib.rs"
    click ShimFW "https://github.com/containerd/rust-extensions/blob/main/crates/shim/src/monitor.rs"
    click ShimFW "https://github.com/containerd/rust-extensions/blob/main/crates/shim/src/publisher.rs"
    click ShimFW "https://github.com/containerd/rust-extensions/blob/main/crates/shim/src/util.rs"
    click RuncShim "https://github.com/containerd/rust-extensions/tree/main/crates/runc-shim/"
    click RuncShim "https://github.com/containerd/rust-extensions/blob/main/crates/runc-shim/Cargo.toml"
    click RuncShim "https://github.com/containerd/rust-extensions/blob/main/crates/runc-shim/build.rs"
    click RuncShim "https://github.com/containerd/rust-extensions/blob/main/crates/runc-shim/src/main.rs"
    click RuncShim "https://github.com/containerd/rust-extensions/blob/main/crates/runc-shim/src/runc.rs"
    click Client "https://github.com/containerd/rust-extensions/tree/main/crates/client/"
    click Client "https://github.com/containerd/rust-extensions/blob/main/crates/client/Cargo.toml"
    click Client "https://github.com/containerd/rust-extensions/blob/main/crates/client/build.rs"
    click Client "https://github.com/containerd/rust-extensions/blob/main/crates/client/src/lib.rs"
    click Client "https://github.com/containerd/rust-extensions/tree/main/crates/client/examples/"
    click Logging "https://github.com/containerd/rust-extensions/tree/main/crates/logging/"
    click Logging "https://github.com/containerd/rust-extensions/blob/main/crates/logging/Cargo.toml"
    click Logging "https://github.com/containerd/rust-extensions/blob/main/crates/logging/src/lib.rs"
    click Logging "https://github.com/containerd/rust-extensions/blob/main/crates/logging/examples/journal.rs"
    click Snapshots "https://github.com/containerd/rust-extensions/tree/main/crates/snapshots/"
    click Snapshots "https://github.com/containerd/rust-extensions/blob/main/crates/snapshots/Cargo.toml"
    click Snapshots "https://github.com/containerd/rust-extensions/blob/main/crates/snapshots/build.rs"
    click Snapshots "https://github.com/containerd/rust-extensions/blob/main/crates/snapshots/src/lib.rs"
    click Snapshots "https://github.com/containerd/rust-extensions/blob/main/crates/snapshots/src/convert.rs"
    click Snapshots "https://github.com/containerd/rust-extensions/blob/main/crates/snapshots/src/wrap.rs"
    click RuncWrap "https://github.com/containerd/rust-extensions/tree/main/crates/runc/"
    click RuncWrap "https://github.com/containerd/rust-extensions/blob/main/crates/runc/Cargo.toml"
    click RuncWrap "https://github.com/containerd/rust-extensions/blob/main/crates/runc/src/lib.rs"
    click RuncWrap "https://github.com/containerd/rust-extensions/blob/main/crates/runc/src/asynchronous/runc.rs"
    click RuncWrap "https://github.com/containerd/rust-extensions/blob/main/crates/runc/src/synchronous/runc.rs"
    click InstallProto "https://github.com/containerd/rust-extensions/blob/main/scripts/install-protobuf.sh"
    click UpdateVendor "https://github.com/containerd/rust-extensions/blob/main/scripts/update-vendor.sh"

    %% Legend
    subgraph Legend
        direction TB
        ext["External Services"]:::external
        plug["Containerd Plugins"]:::plugin
        libc["Rust Crates"]:::lib
        cli["Client Libraries"]:::client
    end

    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef plugin fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef client fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef lib fill:#F0E68C,stroke:#000,stroke-width:1px;
```
