# cri-o/cri-o architecture

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

- Interactive diagram: https://gitdiagram.com/cri-o/cri-o
- Repository: https://github.com/cri-o/cri-o

## Overview

##### Project type and purpose
- CRI-O is a Kubernetes Container Runtime Interface (CRI) implementation that uses OCI-conformant runtimes (e.g., runc, crun).
- It is a backend daemon written in Go that exposes a gRPC CRI API (for kubelet) plus an HTTP status API, pulls/manages container images, invokes OCI runtimes, configures networking via CNI, and collects metrics/tracing.

##### File structure
- cmd/crio: the CLI entrypoint and daemon bootstrap (main.go).
- server/: the gRPC service handlers implementing CRI calls (container_create, sandbox_run, image_pull, metrics, health, etc.).
- internal/: core libraries broken out by concern—config loading, client code, factory for sandbox & container construction, OCI runtime integration, CNI/networking, cgroup/hostport managers, seccomp/Selinux, resource stores, logging, metrics, tracing, NRI plugin hooks.
- pkg/: shared types and configuration abstractions.
- contrib/, scripts/, hack/, nix/: build, packaging, CI/CD and deployment support.
- test/: end-to-end, BATS, unit and integration tests, mocks, testdata.
- docs/, tutorials/: user-facing documentation.

##### Key insights from the README
- CRI-O sits between the Kubelet (gRPC CRI caller) and an OCI Runtime (runc/crun).
- It delegates image management to containers/image, storage to containers/storage, and networking to CNI.
- Exposes metrics and tracing for observability.

##### Detail is key
- Major modules and external integrations.
- Configuration flow (config loader → modules).
- Observability paths (metrics/tracing).
- Don’t hesitate to break out sub-modules if it aids comprehension (e.g., separate Image Manager vs Storage Manager).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        direction TB
        Kubelet["Kubernetes Kubelet"]:::external
        Registry["Container Image Registry(s)"]:::external
        CNIPlugins["CNI Plugins & Network Fabric"]:::external
        StorageBackends["Storage Backends"]:::external
        MetricsBackend["Metrics/Tracing Backend"]:::external
    end

    %% CRI-O Daemon
    subgraph "CRI-O Daemon"
        direction TB
        CLI["CLI & Daemon Bootstrap"]:::core
        ConfigLoader["Configuration Loader"]:::core
        subgraph "Server APIs"
            direction TB
            GRPC["gRPC CRI Server"]:::core
            HTTPAPI["HTTP Status API"]:::core
        end
        subgraph "Core Modules"
            direction TB
            Factory["Factory & Sandbox Manager"]:::core
            ContainerMgr["Container Manager"]:::core
            OCIIntegr["OCI Integration"]:::core
            OCIArtifacts["OCI Artifacts"]:::core
            ImageMgr["Image Manager"]:::core
            StorageMgr["Storage Manager"]:::core
            NetworkMgr["Network Manager"]:::core
            SecurityMgr["Security Manager"]:::core
            PluginHooks["Plugin Hooks"]:::core
            MetricsTracing["Metrics & Tracing"]:::core
            LoggingEvents["Logging & Events"]:::core
            HostportMgr["Hostport Manager"]:::core
            VersionUA["Versioning & User Agent"]:::core
        end
    end

    %% Third-party & Runtimes
    subgraph "OCI Runtime & Third-Party"
        direction TB
        ContainersImage["containers/image"]:::thirdparty
        ContainersStorage["containers/storage"]:::thirdparty
        OCIRuntime["OCI Runtime (runc/crun)"]:::thirdparty
    end

    %% Dependencies & flows
    Kubelet -->|"gRPC over unix socket"| GRPC
    CLI --> GRPC
    CLI --> HTTPAPI
    ConfigLoader --> Factory
    ConfigLoader --> ContainerMgr
    ConfigLoader --> NetworkMgr
    ConfigLoader --> SecurityMgr
    GRPC --> Factory
    Factory -->|"create sandbox/container"| OCIRuntime
    ContainerMgr --> Factory
    OCIIntegr --> OCIRuntime
    OCIArtifacts --> OCIIntegr
    ImageMgr --> ContainersImage
    ImageMgr --> Registry
    StorageMgr --> ContainersStorage
    StorageMgr --> StorageBackends
    NetworkMgr --> CNIPlugins
    SecurityMgr -->|"configure seccomp/SELinux"| OCIRuntime
    PluginHooks --> Factory
    PluginHooks --> ContainerMgr
    MetricsTracing --> MetricsBackend
    LoggingEvents -->|"emit logs/events"| OCIRuntime
    HostportMgr --> ContainerMgr
    VersionUA --> GRPC

    %% Click Events
    click CLI "https://github.com/cri-o/cri-o/blob/main/cmd/crio/main.go"
    click ConfigLoader "https://github.com/cri-o/cri-o/tree/main/internal/config"
    click GRPC "https://github.com/cri-o/cri-o/blob/main/server/server.go"
    click HTTPAPI "https://github.com/cri-o/cri-o/blob/main/server/runtime_status.go"
    click Factory "https://github.com/cri-o/cri-o/blob/main/internal/factory/container/container.go"
    click ContainerMgr "https://github.com/cri-o/cri-o/blob/main/internal/lib/container_server.go"
    click OCIIntegr "https://github.com/cri-o/cri-o/blob/main/internal/oci/oci.go"
    click OCIArtifacts "https://github.com/cri-o/cri-o/blob/main/internal/ociartifact/artifact.go"
    click ImageMgr "https://github.com/cri-o/cri-o/blob/main/internal/storage/image.go"
    click StorageMgr "https://github.com/cri-o/cri-o/blob/main/internal/storage/runtime.go"
    click NetworkMgr "https://github.com/cri-o/cri-o/blob/main/internal/config/cnimgr/cnimgr.go"
    click SecurityMgr "https://github.com/cri-o/cri-o/blob/main/internal/config/seccomp/seccomp.go"
    click PluginHooks "https://github.com/cri-o/cri-o/blob/main/internal/nri/nri.go"
    click MetricsTracing "https://github.com/cri-o/cri-o/blob/main/server/metrics/metrics.go"
    click LoggingEvents "https://github.com/cri-o/cri-o/blob/main/internal/log/log.go"
    click HostportMgr "https://github.com/cri-o/cri-o/blob/main/internal/hostport/hostport_manager.go"
    click VersionUA "https://github.com/cri-o/cri-o/blob/main/internal/version/version.go"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef thirdparty fill:#FFA500,stroke:#333,stroke-width:1px
```
