NVIDIA GPU в Docker — настройка и запуск

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

Логотипы NVIDIA и Docker, графическая иллюстрация

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

Making GPUs Work In Docker
Adding the NVIDIA Drivers
Starting a Container With GPU Access
Selecting a Base Image
Manually Configuring an Image
How Does It Work?
Summary

Введение

Docker-контейнеры используют ядро хоста, но включают собственную файловую систему и набор пакетов. В итоге внутри контейнера изначально отсутствуют драйверы NVIDIA и инструменты CUDA — и Docker сам по себе не монтирует GPU в контейнеры. Поэтому простая команда docker run не увидит ваше графическое устройство.

Вкратце, процесс получения доступа к NVIDIA GPU в контейнере состоит из двух шагов:

Убедиться, что драйверы NVIDIA корректно установлены и работают на хосте (nvidia-smi показывает устройства).
Установить и настроить NVIDIA Container Toolkit на хосте и запускать контейнеры с параметрами, которые предоставляют доступ к устройствам GPU.

Ниже подробная инструкция, рекомендации по выбору базового образа, варианты ручной сборки образа и раздел с устранением неполадок.

Предварительные требования

Доступ администратора на хосте (sudo/root).
Совместимый драйвер NVIDIA, установленный на хосте.
Совместимая версия Docker Engine (рекомендуется Docker 19.03+).
Поддерживаемая версия CUDA в образе/на хосте, если вы используете CUDA-приложения.

Если вы не уверены в драйвере, выполните на хосте:

nvidia-smi

Ожидаемый результат — таблица с моделью GPU, версиями драйвера и CUDA.

Вывод команды nvidia-smi на хосте, показаны GPU и версии драйвера

Установка драйверов NVIDIA на хосте

Важно сначала убедиться, что драйверы NVIDIA корректно установлены и nvidia-smi возвращает ожидаемую информацию. Установка драйверов зависит от дистрибутива (Ubuntu, CentOS, Fedora и т.д.). На большинстве Ubuntu-систем последовательность выглядит так (пример):

# Обновить пакеты
sudo apt-get update
# Установить рекомендуемый драйвер (пример для Ubuntu)
sudo apt-get install -y nvidia-driver-470
# Перезагрузить систему при необходимости
sudo reboot

После перезагрузки снова проверьте:

nvidia-smi

Если команда возвращает данные о GPU — можно переходить к установке контейнерного тулкита.

Установка NVIDIA Container Toolkit (nvidia-docker)

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

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

# Определяем дистрибутив (пример)
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
# Добавляем GPG-ключ репозитория
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
# Перезапускаем Docker daemon
sudo systemctl restart docker

Если вы используете другой менеджер пакетов (yum/dnf) — используйте инструкции NVIDIA для вашей платформы.

После установки Toolkit можно проверить, что Docker корректно запускает контейнеры с GPU.

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

Docker не делает GPU доступными автоматически. Чтобы контейнер увидел GPU, запускать контейнер нужно с флагом –gpus. Можно указать конкретные устройства или keyword all.

Пример быстрой проверки с официальным образом nvidia/cuda:

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

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

Вывод nvidia-smi внутри Docker-контейнера, доступный GPU

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

Самый быстрый путь — использовать официальные образы nvidia/cuda. Теги образов содержат три компонента: версию CUDA, flavor и ОС.

Формат тега:

11.4.0-base-ubuntu20.04

11.4.0 — версия CUDA.
base — «flavor» образа (минимальный набор библиотек).
ubuntu20.04 — базовая операционная система.

Flavors:

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

Пример Dockerfile, использующий nvidia/cuda как базу (корректный синтаксис):

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

RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip3 install tensorflow-gpu

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

Соберите образ и запустите с –gpus:

docker build -t my-tensor-image .
docker run --rm -it --gpus all my-tensor-image

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

Если официальный образ не подходит, вы можете вручную добавить CUDA в свой образ. Лучший источник — официальные Dockerfile NVIDIA, которые показывают, какие пакеты и переменные окружения нужны.

Ключевые моменты:

Добавьте репозиторий CUDA и установите нужные библиотеки и зависимости.
Установите пути (LD_LIBRARY_PATH, PATH), если это требуется.
В Dockerfile укажите переменные окружения, используемые NVIDIA Container Toolkit:

ENV NVIDIA_VISIBLE_DEVICES all
ENV NVIDIA_DRIVER_CAPABILITIES compute,utility

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

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

Как это работает (технический обзор)

NVIDIA Container Toolkit включает компоненты, которые «оборачивают» контейнерный рантайм и взаимодействуют с драйвером NVIDIA на хосте.
libnvidia-container предоставляет API и CLI для монтирования нужных библиотек и устройств в контейнер.
nvidia-container-toolkit реализует prestart hook для рантайма контейнера: перед запуском контейнера этот хук вызывается и настраивает доступ к устройствам и библиотекам.
nvidia-container-runtime оборачивает реальный runtime (например, runc или containerd) так, чтобы prestart хук был выполнен.

После установки и активации Toolkit в конфиге Docker вы увидите указание NVIDIA runtime в секции runtimes.

Отладка и распространённые проблемы

nvidia-smi в контейнере показывает, но приложения не используют GPU
- Проверьте, что в контейнере установлены необходимые CUDA-библиотеки или совместимые версии фреймворков (TensorFlow/PyTorch).
- Убедитесь, что версия CUDA в образе совместима с версией драйвера на хосте.
Ошибка: no devices found или контейнер не видит GPU
- Убедитесь, что контейнер запускается с –gpus.
- Проверьте, установлен ли nvidia-docker2/nvidia-container-toolkit и перезапущен ли Docker.
- Проверьте права доступа к /dev/nvidia* и режим безопасности (SELinux/AppArmor).
Проблемы с версиями драйверов
- Драйверы устанавливаются на хосте. Внутри контейнера должны присутствовать CUDA-библиотеки, но сам драйвер всегда берётся из пространства хоста.
Если вы используете Kubernetes, настройка проходит через device plugin или CRI-O/containerd интеграции; это отдельная тема.

Полезные команды для диагностики

# Состояние драйверов на хосте
nvidia-smi

# Проверить наличие устройств /dev
ls -l /dev/nvidia*

# Логи Docker daemon
sudo journalctl -u docker.service --since "1 hour ago"

# Проверить установлен ли пакет
dpkg -l | grep nvidia-docker

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

Монтирование /dev/nvidia* вручную в контейнер: возможно в простых сценариях, но лишает автоматизации и корректного подключения библиотек.
Использование Singularity/Apptainer вместо Docker: часто применяется в HPC-кластерах; Singularity нативно интегрирует GPU, если хост настроен.
Kubernetes с Device Plugin: для продакшн-оркестрации и автоматического распределения GPU между подами.

Когда это не сработает (контрпримеры)

Сломанный или неподдерживаемый драйвер на хосте — контейнер не сможет воспользоваться GPU.
Неправильные права доступа к устройствам или ограничения безопасности, которые блокируют /dev.
Старые версии Docker или несовместимые версии NVIDIA Container Toolkit.

Практическое SOP для развёртывания (минимальный план действий)

Проверить совместимость GPU, драйвера и Docker.
Установить/обновить драйверы NVIDIA на хосте.
Проверить nvidia-smi на хосте.
Установить nvidia-docker2 / nvidia-container-toolkit и перезапустить Docker.
Запустить тестовый контейнер nvidia/cuda с –gpus all и проверить nvidia-smi внутри.
Выбрать или собрать базовый образ (nvidia/cuda или собственный) и задеплоить приложение.
Настроить мониторинг и тесты производительности.

Роли и обязанности (чеклист)

Инженер по инфраструктуре:
- Установить драйверы на хосты.
- Установить и поддерживать NVIDIA Container Toolkit.
- Обеспечить обновление и совместимость.
Разработчик/ML-инженер:
- Выбрать или собрать корректный Dockerfile с CUDA-библиотеками.
- Тестировать модель в контейнере и проверять использование GPU.
Операции/DevOps:
- Автоматизировать развёртывание образов и запуск контейнеров с параметром –gpus.
- Настроить мониторинг и alerting для GPU.

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

nvidia-smi в контейнере показывает ожидаемую модель GPU и драйвер хоста.
Приложение достигает ожидаемого ускорения по сравнению с CPU-режимом (базовые тесты).
Контейнеры запускаются автоматически в оркестраторе (если используется), с выделением GPU.

Короткий глоссарий (1 строка определения каждой термины)

CUDA — платформа и программный интерфейс NVIDIA для параллельных вычислений на GPU.
nvidia-smi — утилита NVIDIA для просмотра состояния GPU и драйверов.
NVIDIA Container Toolkit — набор компонентов для интеграции Docker с NVIDIA драйвером.
nvidia-docker2 — пакет/мета-пакет, который устанавливает интеграцию Docker и NVIDIA runtime.
NVIDIA_VISIBLE_DEVICES — переменная окружения, определяющая, какие GPU видимы в контейнере.

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

Использование NVIDIA GPU в Docker требует двух действий: корректных драйверов на хосте и установки NVIDIA Container Toolkit. После этого запускайте контейнеры с параметром –gpus и по возможности используйте официальные образы nvidia/cuda как базу. При необходимости можно собрать собственный образ, задав нужные переменные окружения. Важны совместимость версий, права доступа и корректная настройка безопасности.

Важно: следите за официальной документацией NVIDIA при обновлениях драйверов, Docker Engine и Toolkit.

Дополнительные материалы и ссылки (на официальную документацию рекомендуется смотреть при выполнении установки):