fifofonix/driver

NVIDIA GPU驱动容器（适用于Fedora及FedoraCoreOS）

FedoraCoreOS (FCOS) 是基于Fedora的自更新最小容器优化Linux发行版。

NVIDIA尚未直接支持FCOS，因此通过分叉的GitLab项目此处生成Fedora内核特定的容器镜像。

由于这些镜像基于跟踪next/development/stable流的FedoraCoreOS gitlab-runner构建，我们使用nvidia-driver update功能包含预编译内核模块，以加速驱动启动。

镜像首先以预发布形式推送到内置的GitLab Docker仓库，经安全扫描和验证后推送到Dockerhubhttps://hub.docker.com/repository/docker/fifofonix/driver。

作为特权“驱动容器”运行时，它们会安装/运行NVIDIA内核模块。

整体架构概述参见https://github.com/NVIDIA/nvidia-docker/wiki/%E3%80%82

支持的GPU/驱动

支持基于Pascal+架构的NVIDIA数据中心GPU（如P100、V100、T4、A100）在x86 FCOS上运行。

NVIDIA数据中心驱动支持特定CUDA版本，并具有最低支持的Linux内核约束。

当前构建的驱动版本在ci/fedora/.common-ci-fcos.yml中指定。

快速开始

运行驱动容器

驱动容器需要特权模式，以下示例使用podman（docker同样适用）启动。

bash
# https://discussion.fedoraproject.org/t/feedback-for-anyone-using-nvidia-with-kernel-6-15-x/156342
$ sudo rpm-ostree kargs --append=rd.driver.blacklist=nouveau,nova_core --append=modprobe.blacklist=nouveau,nova_core
$ DRIVER_VERSION=580.65.06 # 查看ci/fedora/.common-ci-fcos.yml获取最新驱动版本
$ FEDORA_VERSION_ID=$(cat /etc/os-release | grep VERSION_ID | cut -d = -f2)
$ podman run -d --privileged --pid=host \
     -v /run/nvidia:/run/nvidia:shared \
     -v /var/log:/var/log \
     --name nvidia-driver \
     registry.gitlab.com/container-toolkit-fcos/driver:${DRIVER_VERSION}-fedora${FEDORA_VERSION_ID}

或在FCOS上通过ignition配置片段注册为systemd单元。此单元尝试拉取与运行内核版本匹配的驱动镜像（含预编译内核头文件），若不存在则回退到通用Fedora版本，并挂载主机目录中的补丁文件（如有）。

yaml
variant: fcos
version: 1.5.0
kernel_arguments:
  should_exist:
    # https://discussion.fedoraproject.org/t/feedback-for-anyone-using-nvidia-with-kernel-6-15-x/156342
    - rd.driver.blacklist=nouveau,nova_core
    - modprobe.blacklist=nouveau,nova_core
systemd:
  units:
    - name: acme-nvidia-driver.service
      enabled: true
      contents: |
        [Unit]
        Requires=network-online.target
        After=network-online.target
        StartLimitInterval=1600
        StartLimitBurst=5
        [Service]
        TimeoutStartSec=250
        ExecStartPre=-/bin/podman stop nvidia-driver
        ExecStartPre=-/bin/podman rm nvidia-driver
        ExecStartPre=-setenforce 0
        ExecStartPre=-/bin/mkdir -p /run/nvidia
        # 5/17/24 - 若无以下行，nvidia驱动容器将崩溃且无有效错误信息
        ExecStartPre=-/usr/sbin/modprobe video

        # 若存在内核特定镜像（含预编译内核头文件）则使用，否则回退到通用Fedora镜像并挂载补丁
        # 将registry.gitlab.com/container-toolkit-fcos/driver替换为您构建/发布的驱动镜像仓库，如docker.io/fifofonix/driver
        ExecStart=/bin/sh -c ' \
          FEDORA_VERSION_ID=$(cat /etc/os-release | grep VERSION_ID | cut -d = -f2); \
          KERNEL_VERSION=$(/bin/uname -r); \
          if /bin/podman manifest inspect registry.gitlab.com/container-toolkit-fcos/driver:580.65.06-${KERNEL_VERSION}-fedora${FEDORA_VERSION_ID} > /dev/null; then \
            IMAGE_NAME=registry.gitlab.com/container-toolkit-fcos/driver:580.65.06-${KERNEL_VERSION}-fedora${FEDORA_VERSION_ID; \
          else \
            IMAGE_NAME=registry.gitlab.com/container-toolkit-fcos/driver:580.65.06-fedora${FEDORA_VERSION_ID}; \
            PATCH_MOUNT="-v /var/acme/nvidia-driver-patch:/patch"
          fi; \
          /bin/podman pull ${IMAGE_NAME}; \
          /bin/podman run --name nvidia-driver \
            -v /run/nvidia:/run/nvidia:shared \
            -v /var/log:/var/log \
            ${PATCH_MOUNT} \
            --privileged \
            --pid host \
            ${IMAGE_NAME} \
                --accept-license'

        ExecStop=/bin/podman stop nvidia-driver
        Restart=on-failure
        RestartSec=300

        [Install]
        WantedBy=multi-user.target

验证驱动容器

可进入驱动容器运行nvidia-smi工具验证GPU是否被识别及CUDA版本。

bash
$ # 假设通过podman运行驱动容器并命名为nvidia-driver...
$ podman exec -it nvidia-driver sh
sh-5.2# nvidia-smi
Mon Sep  1 11:18:42 2025
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 580.65.06              Driver Version: 580.65.06      CUDA Version: 13.0     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  Tesla T4                       Off |   00000000:00:1E.0 Off |                    0 |
| N/A   35C    P0             26W /   70W |       0MiB /  15360MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+

安装容器运行时/工具包

要运行利用已启动的NVIDIA驱动容器的CUDA容器，需安装独立的NVIDIA容器运行时并注册到容器运行时系统（如docker），遵循NVIDIA的安装指南。

在FedoraCoreOS上，可通过rpm-ostree分层安装容器工具包并配置运行时，以下是ignition配置片段示例（以containerd为例，docker同样适用）：

yaml
variant: fcos
version: 1.5.0
storage:
  files:
    - path: /etc/nvidia-container-runtime/config.toml
      mode: 0644  
      contents:
        inline: |
          [nvidia-container-cli]
          #debug = "/var/log/nvidia-container-toolkit.log"
          root = "/run/nvidia/driver"
          path = "/usr/bin/nvidia-container-cli"
    # NVIDIA容器工具包1.15.0的改进似乎尚未完全支持FCOS，因此仍需显式添加驱动路径到ld.so.conf
    - path: /etc/ld.so.conf.d/container-toolkit.conf
      mode: 0644
      contents:
        inline: |
          /run/nvidia/driver/usr/lib64
systemd:
  units:
    - name: acme-layer-nvidia-container-toolkit.service
      enabled: true
      # 在zincati.service前运行，避免rpm-ostree事务冲突
      contents: |
        [Unit]
        Wants=network-online.target
        After=network-online.target
        Before=zincati.service
        ConditionPathExists=!/var/lib/%N.stamp
        StartLimitInterval=350
        StartLimitBurst=5
        [Service]
        Type=oneshot
        RemainAfterExit=yes
        ExecStartPre=-/bin/rm -rf /var/cache/rpm-ostree/repomd/{libnvidia,nvidia}*
        ExecStartPre=-/bin/sh -c 'curl -s -L https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo \
            > /etc/yum.repos.d/nvidia-container-toolkit.repo'
        # 可根据需求固定rpm版本...
        ExecStart=/usr/bin/rpm-ostree install -y --idempotent --allow-inactive nvidia-container-toolkit
        ExecStart=/bin/sh -c 'if [[ -f /usr/bin/nvidia-ctk ]]; then \
              /usr/bin/nvidia-ctk runtime configure --runtime=containerd --nvidia-set-as-default; \
              systemctl restart containerd; \
              /bin/touch /var/lib/%N.stamp; fi'
        ExecStart=/bin/systemctl --no-block reboot
        Restart=on-failure
        RestartSec=60

        [Install]
        WantedBy=multi-user.target

运行CUDA容器

最终可运行GPU工作负载，即使驱动容器通过podman运行，也可通过docker执行：

bash
$ docker run --runtime=nvidia nvidia/samples:vectoradd-cuda11.2.1
[Vector addition of 50000 elements]
Copy input data from the host memory to the CUDA device
CUDA kernel launch with 196 blocks of 256 threads
Copy output data from the CUDA device to the host memory
Test PASSED
Done

许可信息

镜像中包含的软件许可信息参见git仓库。

与所有Docker镜像一样，其中可能包含其他软件，可能受其他许可协议约束（如基础发行版中的Bash等，以及主要软件的直接或间接依赖）。

对于任何预构建镜像的使用，镜像用户有责任确保对镜像中所有软件的使用符合相关许可协议。