# nvidia/nvidia-container-toolkit architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia/nvidia-container-toolkit
- Repository: https://github.com/nvidia/nvidia-container-toolkit

## Overview

##### Components
- Driver and Host Environment:
– A node representing the underlying host system, which must have the NVIDIA driver installed. This component is essential since many of the runtime and hook operations depend on NVIDIA driver capabilities.
- External Library – libnvidia-container:
- NVIDIA Container Toolkit Core:
▪ Command-Line Utilities (located under “cmd”):
– nvidia-cdi-hook, nvidia-container-runtime-hook, nvidia-ctk-installer, nvidia-ctk, etc.
– Each utility handles different tasks (e.g., creating symlinks, updating ldconfig, injection of hooks).
▪ Internal Libraries:
– “internal” directory contains modules that manage configuration (internal/config), device discovery (internal/discover), CUDA utilities (internal/cuda), logging, system-level operations (internal/system), and modification logic.
– “pkg” directory modules (like pkg/config and pkg/nvcdi) further encapsulate runtime configurations and NVIDIA CDI (Container Device Interface) logic.
▪ OCI Hooks:
– Representation for integration with container runtimes (Docker, containerd, CRI-O). The toolkit uses OCI hook configurations (located in pkg/config/ocihook and internal/oci) to modify container specifications to allow GPU access.
- Packaging and Deployment:
– Include a section for packaging (in the “packaging” directory and “deployments”) to show how the toolkit is built into container images or native packages.
- CI/CD and Testing:
– Represent the continuous integration workflows (.github/workflows, .gitlab-ci.yml) and tests (in tests and internal/test). Indicate that automated tests, release scripts, and build pipelines verify the toolkit.

##### Technologies / Frameworks
- The project is written in Golang (as evidenced by .go files and go.mod/go.sum).
- It relies on container and OCI standards.
- CI/CD pipelines are configured using GitHub Actions, GitLab CI, and other scripts (see .github/workflows and hack/ scripts).

## Diagram (Mermaid)

```mermaid
graph TD
    H["Host Environment (NVIDIA Drivers)"]:::host
    L["libnvidia-container"]:::external

    subgraph "NVIDIA Container Toolkit"
        subgraph "Command-Line Utilities"
            A["nvidia-cdi-hook"]:::cli
            B["nvidia-container-runtime-hook"]:::cli
            C["nvidia-ctk-installer"]:::cli
            D["nvidia-ctk"]:::cli
            E["nvidia-container-runtime"]:::cli
        end
        subgraph "Internal Libraries"
            F["Internal Modules (config, discover, cuda, logger, system, modifier)"]:::internal
            G["Pkg Modules (config, nvcdi)"]:::internal
        end
        subgraph "OCI Hooks Integration"
            H1["OCI Hooks"]:::oci
        end
    end

    subgraph "Container Runtime Integration"
        I["Docker"]:::runtimes
        J["containerd"]:::runtimes
        K["CRI-O"]:::runtimes
    end

    subgraph "Support Services"
        L1["Packaging & Deployment"]:::packaging
        M["CI/CD & Testing"]:::cicd
    end

    H -->|"requires"| A
    L -->|"dependency"| A

    E -->|"configures"| H1
    B -->|"enables"| H1
    F -->|"discovers/modifies"| H1
    G -->|"CDI_logic"| H1

    H1 -->|"injects"| I
    H1 -->|"injects"| J
    H1 -->|"injects"| K

    L1 -->|"builds"| F
    M -->|"tests"| F

    click A "https://github.com/nvidia/nvidia-container-toolkit/tree/main/cmd/nvidia-cdi-hook"
    click B "https://github.com/nvidia/nvidia-container-toolkit/tree/main/cmd/nvidia-container-runtime-hook"
    click C "https://github.com/nvidia/nvidia-container-toolkit/tree/main/cmd/nvidia-ctk-installer"
    click D "https://github.com/nvidia/nvidia-container-toolkit/tree/main/cmd/nvidia-ctk"
    click E "https://github.com/nvidia/nvidia-container-toolkit/tree/main/cmd/nvidia-container-runtime"
    click F "https://github.com/nvidia/nvidia-container-toolkit/tree/main/internal"
    click G "https://github.com/nvidia/nvidia-container-toolkit/tree/main/pkg"
    click H1 "https://github.com/nvidia/nvidia-container-toolkit/tree/main/pkg/config/ocihook"
    click L1 "https://github.com/nvidia/nvidia-container-toolkit/tree/main/packaging"
    click M "https://github.com/nvidia/nvidia-container-toolkit/tree/main/.github/workflows"
    click L "https://github.com/nvidia/nvidia-container-toolkit/tree/main/third_party/libnvidia-container"

    classDef host fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef external fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef cli fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef internal fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef oci fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef runtimes fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef packaging fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef cicd fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
