Как открыть доступ к NVIDIA GPU в Docker

• Установите и проверьте драйверы NVIDIA на хосте (команда nvidia-smi).
• Установите NVIDIA Container Toolkit (nvidia-docker2) на хост и перезапустите Docker.
• Запускайте контейнеры с флагом –gpus (например –gpus all) или вручную добавляйте устройства.
• Для быстрого старта используйте официальные образы nvidia/cuda или добавьте CUDA в свой образ по инструкции от NVIDIA.

Быстрые ссылки

• Как заставить GPU работать в Docker
• Установка драйверов NVIDIA на хост
• Запуск контейнера с доступом к GPU
• Выбор базового образа
• Ручная конфигурация образа
• Как это работает
• Критерии приёмки

Важно: контейнеры Docker по умолчанию не «видят» GPU хоста — нужно дополнительно установить контейнерный тулкит и запускать контейнеры с опцией предоставления устройств GPU.

Обзор: почему это нужно

Контейнеры разделяют ядро хоста, но несут свое окружение и набор пакетов. В отличие от хоста, внутри образа обычно нет драйверов NVIDIA и утилит для работы с GPU. Более того, Docker по умолчанию не добавляет устройства GPU в контейнер — поэтому обычный docker run ничего не увидит.

Обобщённо задача решается двумя шагами:

1. На хосте: убедиться, что драйверы NVIDIA установлены и рабочие (nvidia-smi).
2. На хосте: установить NVIDIA Container Toolkit, затем запускать контейнеры с указанием GPU (флаг –gpus или эквивалент для вашего рантайма).

Эти инструкции ориентированы на современные версии CUDA и Docker. Последние выпуски NVIDIA Container Toolkit поддерживают сочетания CUDA 10+ и Docker Engine 19.03 и новее. Старые версии CUDA/Docker/NVIDIA-драйверов могут требовать дополнительных шагов.

Предварительные проверки на хосте

1. Проверьте, что ядро и драйверы установлены корректно:

nvidia-smi

Ожидаемый результат: в выводе видна модель GPU, версия драйвера и версия CUDA (если установлена). Если команда не найдена или возвращает ошибку — сначала исправьте драйверы на хосте.

Если nvidia-smi не запускается:

• Проверьте, что установлен проприетарный драйвер NVIDIA (не nouveau).
• Убедитесь, что модуль ядра загружен (lsmod | grep nvidia).
• Посмотрите журналы dmesg и системный журнал (journalctl -u nvidia-* или journalctl -xe).

Установка NVIDIA Container Toolkit на хост

NVIDIA Container Toolkit интегрируется с Docker Engine и автоматизирует проброс GPU в контейнеры.

Пример для дистрибутивов на базе Debian/Ubuntu (следуйте официальной документации для вашего дистрибутива):

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)

curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -

curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

После перезапуска Docker демон должен быть готов работать с NVIDIA runtime. Проверьте статус:

sudo systemctl status docker

Если пакет nvidia-docker2 установлен успешно, вы готовы запускать тестовые контейнеры.

Запуск контейнера с доступом к GPU

Docker не добавляет GPU автоматически — указывайте флаг –gpus при запуске. Примеры:

• Все GPU:

docker run -it --gpus all nvidia/cuda:11.4.0-base-ubuntu20.04 nvidia-smi

• Конкретное количество (например 2 устройства):

docker run -it --gpus "device=0,1" nvidia/cuda:11.4.0-base-ubuntu20.04 nvidia-smi

Ожидаемый вывод внутри контейнера должен совпадать с выводом на хосте (модель GPU, драйвер). Версия CUDA внутри образа может отличаться от версии на хосте — это нормально, если только несовместимости не мешают вашему ПО.

Если контейнер не видит GPU, см. раздел «Устранение проблем».

Выбор базового образа

Самый быстрый способ — использовать официальные образы nvidia/cuda. Они выпускаются в разных сочетаниях: версия CUDA, «flavor» образа и версия ОС.

Формат тега:

11.4.0-base-ubuntu20.04

• 11.4.0 — версия CUDA.
• base — тип образа (flavor).
• ubuntu20.04 — версия ОС внутри образа.

Доступные flavor:

• base — минимальный образ с необходимыми runtime-бинарями CUDA.
• runtime — дополнительно включает CUDA math libraries и NCCL для меж-GPU коммуникации.
• devel — включает заголовки и инструменты для разработки и сборки (используется для сборки собственных CUDA-приложений).

Пример Dockerfile на основе официального образа:

FROM nvidia/cuda:11.4.0-base-ubuntu20.04

RUN apt-get update && \
    apt-get install -y python3 python3-pip && \
    rm -rf /var/lib/apt/lists/*

RUN pip3 install tensorflow-gpu

COPY tensor-code.py .

ENTRYPOINT ["python3", "tensor-code.py"]

Сборка и запуск этого образа с –gpus запустит вашу Tensor-программу с доступом к GPU.

Примечание: многие ML-фреймворки сейчас поставляют отдельные пакеты для работы без явного тега “-gpu”; уточняйте совместимость версии фреймворка и CUDA.

Ручная конфигурация образа (если нужен нестандартный базовый образ)

Если вы хотите создать свой образ на другой базе, можно установить CUDA внутри образа по официальным Dockerfile от NVIDIA. Основные шаги:

1. Добавить репозиторий пакетов NVIDIA (аналогично шагам на хосте, но внутри Dockerfile).
2. Установить CUDA runtime (или toolkit) и нужные библиотеки.
3. Настроить переменные окружения, чтобы контейнер корректно использовал драйверы хоста.

Ключевые переменные окружения, которые обычно добавляются в Dockerfile:

ENV NVIDIA_VISIBLE_DEVICES all
ENV NVIDIA_DRIVER_CAPABILITIES compute,utility

• NVIDIA_VISIBLE_DEVICES — какие устройства будут видимы (all, список или none).
• NVIDIA_DRIVER_CAPABILITIES — какие возможности драйвера требуются (compute, utility, video, graphics и т.д.).

Ручная сборка дает гибкость, но вы берёте на себя поддержку совместимости при обновлении CUDA и драйверов.

Как это работает под капотом

NVIDIA Container Toolkit — это набор пакетов, которые завертывают рантаймы контейнеров (Docker, containerd и т.п.) интерфейсом к драйверу NVIDIA на хосте.

Компоненты и их роль:

• libnvidia-container — библиотека и CLI, предоставляющие API для проброса устройств, библиотек и настроек в контейнер.
• nvidia-container-toolkit — реализует hook для рантайма (prestart), формирующий необходимые параметры при создании контейнера.
• nvidia-container-runtime — обёртка для реального контейнерного рантайма (runc/containerd), которая гарантирует вызов prestart hook.

При запуске контейнера с поддержкой NVIDIA toolkit:

1. Рантайм вызывает prestart hook (nvidia-container-toolkit).
2. Hook обращается к libnvidia-container, чтобы подготовить список устройств, монтирования и переменных окружения.
3. После выполнения hook реальный рантайм продолжает запуск контейнера, теперь с проброшенными GPU-дисками и библиотеками.

В конфигурации Docker daemon вы увидите опцию runtime с nvidia в качестве одного из доступных рантаймов.

Устранение проблем (Troubleshooting)

Распространённые ошибки и шаги диагностики:

1. “CUDA driver version is insufficient” или несовместимость версий:

   • Убедитесь, что версия драйвера на хосте поддерживает нужную версию CUDA в контейнере.
   • При необходимости используйте образ с более старой версией CUDA или обновите драйвер на хосте.

2. “nvidia-container-cli: initialization error” или “no such file or directory”:

   • Проверьте, что nvidia-container-toolkit и libnvidia-container установлены и видимы рантаймом.
   • journalctl -u docker и /var/log/syslog могут содержать подробности.

3. Контейнер запускается, но nvidia-smi внутри возвращает пустой список:

   • Проверьте, что контейнер запущен с –gpus.
   • Проверьте значение переменных NVIDIA_VISIBLE_DEVICES.
   • Убедитесь, что драйверы не находятся в конфликтном состоянии на хосте.

4. Проблемы с правами доступа к /dev/nvidia*:

   • Убедитесь, что ваш пользователь запускает Docker с правильными привилегиями.
   • Проверьте настройки cgroup и политики безопасности (SELinux/AppArmor) — иногда требуется дополнительная конфигурация.

Диагностические команды:

# Проверка драйвера на хосте
nvidia-smi

# Проверка установки nvidia-docker2
docker info | grep -i nvidia

# Журналы Docker
sudo journalctl -u docker -b --no-pager

Если ошибка неясна — скопируйте полные логи и ищите текст ошибок в репозиториях NVIDIA и issue-трекерах.

Примеры отказов и когда это не сработает

• Старые проприетарные драйверы или ядра, несовместимые с текущим libnvidia-container.
• Среды с ограниченным доступом к устройствам (managed cloud images с кастомной политикой безопасности).
• Использование альтернативного контейнерного рантайма без поддержки hook’ов — потребуется ручная интеграция.

Альтернативные подходы

• Kubernetes + NVIDIA Device Plugin — если вы оркестрируете контейнеры, используйте device plugin от NVIDIA для автоматического распределения GPU.
• Использование виртуализации (VM) с явным присоединением GPU (passthrough) — полезно, если нужна изоляция сильнее, чем у контейнеров.

Чек-лист для ролей

Для разработчика:

• Локально проверить nvidia-smi на хосте.
• Запустить образ nvidia/cuda и убедиться в доступности GPU.
• Добавить тесты внутри CI, которые запускают небольшой GPU-тайпичный workload.

Для системного администратора / DevOps:

• Установить и поддерживать nvidia-docker2 на узлах.
• Обновлять драйверы централизованно и отслеживать совместимость.
• Настроить мониторинг (метрики GPU, загрузка, температура).

Критерии приёмки

Минимальные критерии, чтобы считать интеграцию успешной:

1. На хосте корректно работает nvidia-smi и видны GPU.
2. Docker демон перезапущен после установки nvidia-docker2 и не содержит ошибок в логах.
3. Контейнер, запущенный с –gpus all, показывает те же устройства в nvidia-smi, что и хост.
4. Приложение выполняет GPU-ускорённую задачу без ошибок и без падений драйвера.

Тестовые случаи и приемочные тесты

1. Запуск базового теста:

docker run --rm --gpus all nvidia/cuda:11.4.0-base-ubuntu20.04 nvidia-smi

Ожидается: вывод с информацией по GPU и драйверу.

2. Простой CUDA-пример: собрать и запустить CUDA sample внутри контейнера (для devel образа).
3. ML-сложность: запустить небольшой батч обучения/инференса и убедиться, что загрузка GPU > 0%.

Безопасность и привилегии

• Контейнер, имеющий доступ к устройствам GPU, всё равно ограничен пространством процессов контейнера, но доступ к драйверу может дать дополнительные возможности по сбору информации о системе.
• Следите за правами доступа к /dev/nvidia* и политиками AppArmor/SELinux.

Совместимость и заметки по миграции

• NVIDIA Toolkit интегрируется с Docker Engine 19.03+ с поддержкой флага –gpus.
• Если вы используете более старые версии Docker, нужно применять nvidia-container-runtime напрямую или обновить Docker.
• При обновлении драйверов проверяйте совместимость с версиями CUDA в ваших образах.

Decision flow (помогает выбрать путь)

flowchart TD
  A[Начало] --> B{nvidia-smi на хосте работает?}
  B -- Да --> C{Требуется Kubernetes?}
  B -- Нет --> Z[Установить/исправить драйверы на хосте]
  C -- Да --> D[Использовать NVIDIA Device Plugin для K8s]
  C -- Нет --> E[Установить NVIDIA Container Toolkit на хост]
  E --> F[Запуск контейнера с --gpus]
  F --> G{Контейнер видит GPU?}
  G -- Да --> H[Готово]
  G -- Нет --> I[Диагностика: логи, права, совместимость версий]

Примеры конфигураций и сниппеты (cheat sheet)

• Быстрая проверка установки на хост:

nvidia-smi
docker info | grep -i nvidia

• Быстрый тест контейнера:

docker run --rm --gpus all nvidia/cuda:11.4.0-runtime-ubuntu20.04 nvidia-smi

• Dockerfile для сборки с CUDA (devel):

FROM nvidia/cuda:11.4.0-devel-ubuntu20.04
# Сборка вашего C/C++/CUDA приложения

Краткое резюме

Использование NVIDIA GPU внутри Docker-контейнера требует:

1. Рабочего драйвера NVIDIA на хосте.
2. Установки NVIDIA Container Toolkit (nvidia-docker2) и перезапуска Docker.
3. Запуска контейнеров с флагом –gpus или настройки переменных окружения и рантайма в образе.

Официальные образы nvidia/cuda упрощают старт. Для production-окружений проверьте совместимость версий драйвера и CUDA, автоматизируйте установку toolkit’а и добавьте проверки в CI.

FAQ

Нужно ли встраивать драйвер NVIDIA внутрь образа?

Нет. Обычно драйверы остаются на хосте; в контейнере устанавливаются только runtime-библиотеки CUDA. Полный драйвер в образе не обязателен и часто не нужен.

Можно ли использовать несколько версий CUDA одновременно?

Да. Контейнер может содержать свою версию CUDA runtime, а хост — свою версию драйвера. Важно, чтобы драйвер на хосте поддерживал CUDA runtime в контейнере.

Как автоматизировать выделение GPU в Kubernetes?

Используйте NVIDIA Device Plugin для Kubernetes — он интегрируется с kubelet и позволяет запрашивать GPU как ресурс при создании Pod.