# openeuler-mirror/isulad architecture

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

- Interactive diagram: https://gitdiagram.com/openeuler-mirror/isulad
- Repository: https://github.com/openeuler-mirror/isulad

## Overview

##### Main System Type and Purpose
- Type: A C/C++‐based container engine with a daemon‐client architecture.
- Purpose: Manage container lifecycles and images either via a CLI (“isula”) or via the Kubernetes CRI (gRPC) interface; support multiple runtimes (lxc, runc, kata) and image formats (OCI, external rootfs).

##### Out Top-Level Components
- Clients (left)
– CLI client (“isula”) via Unix‐socket REST API
– Kubernetes kubelet via Unix‐socket gRPC CRI API
- Daemon (center)
– Entry Layer (transport)
– Service/API Layer
– Core Modules & Executor
– Low-level components
- External Services (right)
– Container runtimes (lxc, runc, kata)
– CNI plugins
– Image registries (OCI)
– Filesystem drivers (overlay2, devmapper)

##### Layers and Their Relationships
1. Clients → Entry Layer
– CLI → REST server
– kubelet → gRPC CRI server + gRPC runtime/image services
- Entry Layer subsystems (src/daemon/entry):
– REST services (rest_containers_service, rest_images_service, rest_metrics_service)
– gRPC services (grpc_containers_service, grpc_images_service, grpc_network_service, grpc_volumes_service)
– CRI adapters (CRI runtime/image/pod services, stream server, CNI plugin loader)

2. Entry Layer → Service/API Layer
- Service Container API (modules/service)
- Service Image API (modules/service)
- Service Network, Volume, Metrics, Events APIs
- These use common “api” definitions (src/api/services)

3. Service/API Layer → Core Modules
- Core Modules (src/daemon/modules):
– Container (state, GC, health‐check, restart, restore)
– Image (embedded sqlite, OCI store, external)
– Network (CNI operator, native, CRI)
– Volume (local driver)
– Device/CDI (registry, parser, behavior)
– Spec (namespace, mount, security, verify)
– Runtime (runtime engines lcr/isula, shim monitor)
– Sandbox (controller manager, sandboxer grpc client)
– Events (collector, sender)
– Plugin, Log, NRI adapters

4. Core Modules → Executor → Mailbox → Low-Level Subsystems
- Executor (src/daemon/executor) invokes callbacks in modules.
- Mailbox (src/daemon/mailbox) handles asynchronous messages.
- Low-Level Subsystems:
– cgroup v1/v2 management (src/daemon/common/cgroup)
– Filesystem graphdrivers overlay2, devmapper (modules/image/oci/storage)
– Network namespaces, Veth/CNI plugin execution (modules/network/cni_operator/libcni)
– OCI registry HTTP calls (utils/http)
– Crypto, tar, sha256, archive (utils)
– Process shim (isulad-shim in src/cmd)

5. Modules → External Runtimes & Services
- Container runtime engines:
– LXC via liblxc (default)
– runc via exec of `runc` binary
– kata via kata-runtime
- CNI plugins invoked by libcni
- Image registries (remote HTTP)

##### Architectural Patterns and Technologies
- Layered/Clean Architecture – clear separation: transport → API → core modules → low‐level
- Plugin/Adapter Pattern – dynamic CNI plugins, runtime engines, device modules (CDI), NRI
- Event‐Driven – mailbox and events collector/sender
- Build & Config – CMake build, JSON/YAML configuration, C headers for APIs
- Communication – Unix sockets, gRPC, HTTP REST

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        CLI["CLI Client\n(isula)"]:::external
        Kubelet["Kubernetes kubelet\n(CRI gRPC)"]:::external
    end

    %% Entry Layer
    subgraph "Entry Layer"
        RESTCS["REST Services\n(containers, images, metrics)"]:::entry
        GRPCS["gRPC Services\n(containers, images, network, volumes)"]:::entry
        CRIA["CRI Adapters\n(runtime, image, pod, stream, CNI loader)"]:::entry
    end

    %% Service/API Layer
    subgraph "Service/API Layer"
        SAMod["Service/API Module\n(Container, Image, Network, Volume, Metrics, Events)"]:::service
        CommonAPI["Common API Definitions"]:::service
    end

    %% Core Modules
    subgraph "Core Modules"
        ContainerMod["Container Module\n(state, GC, health-check)"]:::core
        ImageMod["Image Module\n(OCI store, external)"]:::core
        NetworkMod["Network Module\n(CNI operator, native)"]:::core
        VolumeMod["Volume Module\n(local driver)"]:::core
        DeviceMod["Device/CDI Module\n(registry, parser)"]:::core
        SpecMod["Spec Module\n(namespace, mount, security)"]:::core
        RuntimeMod["Runtime Module\n(engines, shim monitor)"]:::core
        SandboxMod["Sandbox Module\n(controller mgr, grpc client)"]:::core
        EventsMod["Events Module\n(collector, sender)"]:::core
        PluginMod["Plugin & NRI Adapters"]:::core
    end

    %% Executor & Mailbox
    subgraph "Executor & Mailbox"
        Executor["Executor"]:::exec
        Mailbox["Mailbox"]:::exec
    end

    %% Low-Level Subsystems
    subgraph "Low-Level Subsystems"
        Cgroup["cgroup v1/v2"]:::low
        GraphDrv["GraphDrivers\n(overlay2, devmapper)"]:::low
        LibCNI["CNI Invocation\n(libcni)"]:::low
        HTTP["OCI Registry HTTP Client"]:::low
        SHA["Crypto/Tar/SHA256"]:::low
        Cutils["Archive Utilities"]:::low
        Shim["Process Shim\n(isulad-shim)"]:::low
    end

    %% External Dependencies
    subgraph "External Runtimes & Services" style dashed
        LXC["LXC (liblxc)"]:::external
        Runc["runc binary"]:::external
        Kata["kata-runtime"]:::external
        CNIPlugins["CNI Plugins"]:::external
        Registries["Image Registries\n(OCI remote)"]:::external
    end

    %% Connections
    CLI -->|Unix socket REST| RESTCS
    Kubelet -->|Unix socket gRPC| GRPCS
    RESTCS -->|calls| SAMod
    GRPCS -->|calls| SAMod
    CRIA -->|adapts CRI| SAMod
    SAMod -->|uses| CommonAPI
    SAMod -->|invokes| ContainerMod
    SAMod -->|invokes| ImageMod
    SAMod -->|invokes| NetworkMod
    SAMod -->|invokes| VolumeMod
    SAMod -->|invokes| DeviceMod
    SAMod -->|invokes| SpecMod
    SAMod -->|invokes| RuntimeMod
    SAMod -->|invokes| SandboxMod
    SAMod -->|invokes| EventsMod
    SAMod -->|invokes| PluginMod
    ContainerMod -->|callback| Executor
    ImageMod -->|callback| Executor
    NetworkMod -->|callback| Executor
    VolumeMod -->|callback| Executor
    DeviceMod -->|callback| Executor
    SpecMod -->|callback| Executor
    RuntimeMod -->|callback| Executor
    SandboxMod -->|callback| Executor
    EventsMod -->|callback| Executor
    PluginMod -->|callback| Executor
    Executor -->|posts messages| Mailbox
    Mailbox -->|manages| Cgroup
    Mailbox -->|manages| GraphDrv
    Mailbox -->|manages| LibCNI
    Mailbox -->|manages| HTTP
    Mailbox -->|manages| SHA
    Mailbox -->|manages| Cutils
    Mailbox -->|manages| Shim
    RuntimeMod -->|executes| LXC
    RuntimeMod -->|executes| Runc
    RuntimeMod -->|executes| Kata
    NetworkMod -->|loads| CNIPlugins
    ImageMod -->|pulls from| Registries

    %% Click Events
    click CLI "https://github.com/openeuler-mirror/isulad/tree/master/src/cmd/isula"
    click Kubelet "https://github.com/openeuler-mirror/isulad/tree/master/src/client/connect/grpc"
    click RESTCS "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/entry/connect/rest"
    click GRPCS "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/entry/connect/grpc"
    click CRIA "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/entry/cri"
    click SAMod "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/service"
    click CommonAPI "https://github.com/openeuler-mirror/isulad/tree/master/src/api/services"
    click ContainerMod "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/container"
    click ImageMod "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/image"
    click NetworkMod "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/network"
    click VolumeMod "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/volume"
    click DeviceMod "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/device"
    click SpecMod "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/spec"
    click RuntimeMod "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/runtime"
    click EventsMod "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/events"
    click PluginMod "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/plugin"
    click Executor "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/executor"
    click Mailbox "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/mailbox"
    click Cgroup "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/common/cgroup"
    click GraphDrv "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/image/oci/storage/layer_store/graphdriver"
    click LibCNI "https://github.com/openeuler-mirror/isulad/tree/master/src/daemon/modules/network/cni_operator/libcni"
    click HTTP "https://github.com/openeuler-mirror/isulad/tree/master/src/utils/http"
    click SHA "https://github.com/openeuler-mirror/isulad/tree/master/src/utils/sha256"
    click Cutils "https://github.com/openeuler-mirror/isulad/tree/master/src/utils/tar"
    click Shim "https://github.com/openeuler-mirror/isulad/tree/master/src/cmd/isulad-shim"

    %% Styles
    classDef entry fill:#cce5ff,stroke:#3399ff,color:#003366
    classDef service fill:#d4edda,stroke:#28a745,color:#155724
    classDef core fill:#fff3cd,stroke:#ffc107,color:#856404
    classDef exec fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef low fill:#f8f9fa,stroke:#adb5bd,color:#495057
    classDef external fill:none,stroke:#6c757d,stroke-dasharray: 5 5,color:#6c757d
```
