# containerd/nerdctl architecture

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

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

## Overview

##### Project Type and Purpose
- nerdctl is a CLI tool that wraps container runtime functionality provided by containerd. It includes support for Docker-compatible commands, container image management, building images via BuildKit, networking configuration using CNI plugins, rootless mode, and even experimental features (like lazy pulling, encrypted images, P2P image distribution, etc.).

##### File Structure
- The top-level structure consists of configuration and CI/CD files, multiple Dockerfiles for building, and an extensive set of source directories.
- The “cmd/nerdctl” directory organizes the different commands/subcommands (e.g., container, image, compose, network, system, apparmor, etc.). This makes it clear that each command is implemented in its own package/module, potentially following similar patterns.
- The “pkg” directory holds reusable libraries that implement core functionalities such as container operations, image handling, network and namespace utilities, logging, snapshotter support, and integration with other utilities (e.g., ocicrypt, ipfs).
- There are also testing, documentation (“docs”), examples, and even a “mod/tigron” directory indicating internal testing or additional features, reinforcing a modular, layered architecture.

##### README for Additional Insights
- The README provides usage examples that highlight interactions with containerd, BuildKit for builds, and support for Docker Compose.
- It lists external dependencies (CNI plugins, BuildKit, RootlessKit, etc.) that should be shown as external components interacting with nerdctl.
- It also indicates that nerdctl is “non-core” to containerd, hinting at a separation between this tool’s functionality and the container runtime itself.

a. Main Components:
- CLI Interface: Represent the user-facing layer that receives commands (e.g., ‘nerdctl run’, ‘nerdctl build’, ‘nerdctl compose’).
- Command Modules: Break down into subcomponents such as:
- Container Subsystem (handling run, start, stop, logs, etc.)
- Image Subsystem (pull, push, tag, convert, etc.)
- Compose Subsystem (Docker Compose compatibility)
- Builder/BuildKit Integration (for image builds)
- Network, Namespace, and Volume management modules
- Security and AppArmor module (for security-related operations)
- Core Library/Business Logic: The “pkg” layer that encapsulates shared library code for networking, logging, containerd interfacing, API types, and more.
- External Dependencies: Include containerd (the actual runtime), BuildKit daemon, CNI plugins, RootlessKit, slirp4netns, and optional components like IPFS, ocicrypt, and cosign for signing.

b. Relationships and Interactions:
- The core libraries communicate with external systems. For example, the image and build modules interact with BuildKit for image building, while container management modules interface with containerd.
- Logging and configuration system as a shared utility that feeds into all subsystems.

c. Architectural Patterns and Design Principles:
- The project follows a modular, layered structure where the CLI (presentation) delegates to command-specific modules (controllers) that leverage core libraries (“pkg”) for business logic.
- Reusability is key—the “pkg” directory contains many libraries that are reused across commands (e.g., networking, logging, container manipulation).

d. Relevant Technologies:
- Languages/Frameworks: Written in Go; so illustrate Go packages as modules.
- External Libraries/Tools: containerd (runtime), BuildKit (image building), CNI plugins (networking), RootlessKit and slirp4netns (rootless containers), IPFS, ocicrypt, and cosign.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLIInterface["CLI Interface"]:::cli
        ContainerModule["Container Module"]:::cli
        ImageModule["Image Module"]:::cli
        ComposeModule["Compose Module"]:::cli
        BuilderCLI["Builder CLI"]:::cli
        NetworkModule["Network Module"]:::cli
        SystemModule["System Module"]:::cli
        SecurityModule["Security Module"]:::cli
        IPFSModule["IPFS Module"]:::cli
    end

    %% Core Libraries Layer
    subgraph "Core Libraries"
        CoreBL["Core Business Logic (pkg)"]:::core
        BuildKitUtil["BuildKit Util (pkg/buildkitutil)"]:::core
        RootlessUtil["Rootless Utilities (pkg/rootlessutil)"]:::core
        CNIPlugin["CNI Plugin (pkg/netutil)"]:::core
    end

    %% External Systems Layer
    subgraph "External Systems"
        Containerd["Containerd Runtime"]:::external
        BuildKitDaemon["BuildKit Daemon"]:::external
        CNIPlugins["CNI Plugins"]:::external
        IPFSExternal["IPFS Network"]:::external
    end

    %% Connections from CLI Layer to Command Modules
    CLIInterface -->|"invokes"| ContainerModule
    CLIInterface -->|"invokes"| ImageModule
    CLIInterface -->|"invokes"| ComposeModule
    CLIInterface -->|"invokes"| BuilderCLI
    CLIInterface -->|"invokes"| NetworkModule
    CLIInterface -->|"invokes"| SystemModule
    CLIInterface -->|"invokes"| SecurityModule
    CLIInterface -->|"invokes"| IPFSModule

    %% Connections from Command Modules to Core Libraries
    ContainerModule -->|"calls"| CoreBL
    ImageModule -->|"calls"| CoreBL
    ComposeModule -->|"calls"| CoreBL
    BuilderCLI -->|"calls"| BuildKitUtil
    NetworkModule -->|"calls"| CNIPlugin
    SecurityModule -->|"calls"| CoreBL
    IPFSModule -->|"calls"| CoreBL
    SystemModule -->|"optional"| RootlessUtil

    %% Connections from Core Libraries to External Systems
    CoreBL -->|"executes on"| Containerd
    BuildKitUtil -->|"triggers"| BuildKitDaemon
    CNIPlugin -->|"interfaces with"| CNIPlugins
    IPFSModule -->|"utilizes"| IPFSExternal

    %% Styles
    classDef cli fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef core fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef external fill:#AED6F1,stroke:#2471A3,stroke-width:2px;

    %% Click Events
    click CLIInterface "https://github.com/containerd/nerdctl/blob/main/cmd/nerdctl/main.go"
    click ContainerModule "https://github.com/containerd/nerdctl/tree/main/cmd/nerdctl/container"
    click ImageModule "https://github.com/containerd/nerdctl/tree/main/cmd/nerdctl/image"
    click ComposeModule "https://github.com/containerd/nerdctl/tree/main/cmd/nerdctl/compose"
    click BuilderCLI "https://github.com/containerd/nerdctl/tree/main/cmd/nerdctl/builder"
    click BuildKitUtil "https://github.com/containerd/nerdctl/tree/main/pkg/buildkitutil"
    click NetworkModule "https://github.com/containerd/nerdctl/tree/main/cmd/nerdctl/network"
    click SystemModule "https://github.com/containerd/nerdctl/tree/main/cmd/nerdctl/system"
    click SecurityModule "https://github.com/containerd/nerdctl/tree/main/cmd/nerdctl/apparmor"
    click IPFSModule "https://github.com/containerd/nerdctl/tree/main/cmd/nerdctl/ipfs"
    click CoreBL "https://github.com/containerd/nerdctl/tree/main/pkg"
    click RootlessUtil "https://github.com/containerd/nerdctl/tree/main/pkg/rootlessutil"
    click CNIPlugin "https://github.com/containerd/nerdctl/blob/main/pkg/netutil/cni_plugin.go"
```
