GPU в Docker Compose: включение и настройка

Логотип Docker

TL;DR

Docker Compose может передавать GPU в контейнеры через поля резервирования устройств в разделе deploy.resources. Перед этим подготовьте хост (NVIDIA Container Toolkit), используйте образ с поддержкой CUDA и согласуйте версии драйвера/CUDA. Для Compose нужен v1.28+; старые версии либо не поддерживают GPU, либо используют устаревшую структуру.

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

Подготовка хоста
Подготовка образа
Доступ к GPU в Docker Compose
Работа с несколькими GPU
Рекомендации и отладка

К чему это подходит

Контейнеризация тяжёлых задач — обучение моделей, инференс, аналитика — требует доступа к GPU. Docker не даёт GPU в контейнер по умолчанию. Варианты: флаг –gpus для docker run или поля в docker-compose.yml для Compose.

Важно: текущая интеграция Moby/Compose официально поддерживает NVIDIA GPU через nvidia-container-toolkit. Попытки подключить Intel/AMD через тот же механизм обычно приводят к ошибкам сегодня.

Подготовка хоста

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

Установить его можно последовательностью команд (пример для 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 update

sudo apt install -y nvidia-docker2

sudo systemctl restart docker

Эта надстройка оборачивает runtime Docker и добавляет интерфейс к драйверу NVIDIA на хосте. После установки проверьте /etc/docker/daemon.json — runtime должен быть настроен на nvidia-container-runtime.

$ cat /etc/docker/daemon.json

{

"runtimes": {

  "nvidia": {

    "path": "nvidia-container-runtime",

    "runtimeArgs": []

  }

}

}

Примечание: команды установки и содержимое daemon.json зависят от дистрибутива. Для RHEL/CentOS и других систем процесс аналогичен, но пакеты/репозитории отличаются.

Подготовка образа

Контейнерный образ должен содержать библиотеки CUDA и сопутствующие компоненты. Проще всего использовать официальный базовый образ NVIDIA, например nvidia/cuda. Устанавливайте только те пакеты и версии, которые совместимы с версией CUDA на хосте.

Пример Dockerfile (искать соответствие с вашей версией CUDA):

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

RUN apt update &&\

apt-get install -y python3 python3-pip &&\

pip install tensorflow-gpu

COPY tensor.py .

ENTRYPONT [“python3”, “tensor.py”]

Подсказка: используйте ту же версию CUDA, что и хост. Проверить текущую версию драйвера и CUDA можно с помощью nvidia-smi:

$ nvidia-smi

Tue May 10 19:15:00 2022

+—————————————————————————–+

| NVIDIA-SMI 470.103.01 Driver Version: 470.103.01 CUDA Version: 11.4 |

|——————————-+———————-+———————-+

…

Если версии не совпадают, либо используйте образ с другой версией CUDA, либо обновите драйвер на хосте (с учётом совместимости с GPU и ОС).

Доступ к GPU в Docker Compose

В Compose (v1.28+) GPU указывают через поле deploy.resources.reservations.devices в секции сервисов. Это позволяет задать драйвер и требуемые возможности (capabilities).

Пример docker-compose.yml, который запускает контейнер на базе nvidia/cuda и выводит информацию о GPU:

services:

app:

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

command: nvidia-smi

deploy:

resources:

reservations:

devices:

  - driver: nvidia

    capabilities: [gpu]

Поле deploy.resources.reservations.devices указывает, какие устройства можно зарезервировать. Установка драйвера в nvidia и добавление capability gpu определяют графический процессор.

Запустите сервис:

$ docker compose up

Ожидаемый вывод при успешном подключении будет включать блок nvidia-smi с версиями драйвера и CUDA. Эти версии соответствуют хосту.

Работа с несколькими GPU

По умолчанию контейнер получает доступ ко всем GPU хоста. Для ограничения доступа можно использовать одно из двух решений: count или device_ids.

Резервирование фиксированного количества устройств

Поле count резервирует указанное число устройств. В системе с двумя GPU count: 1 передаст контейнеру ровно одно GPU (какое — не определено, выбор произвольный).

services:

app:

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

command: nvidia-smi

deploy:

resources:

reservations:

devices:

  - driver: nvidia

    count: 1

    capabilities: [gpu]

Выбор конкретных устройств

Поле device_ids принимает массив ID устройств (0‑индексированных). ID можно посмотреть через nvidia-smi –list-gpus:

$ nvidia-smi --list-gpus

GPU 0: NVIDIA GeForce GTX 1080 Ti (UUID: GPU-5ba4538b-234f-2c18-6a7a-458d0a7fb348)

GPU 1: NVIDIA GeForce GTX 1080 Ti (UUID: GPU-d5ce9af3-710c-4222-95f8-271db933d438)

GPU 2: NVIDIA GeForce GTX 1080 Ti (UUID: GPU-50d4eb4f-7b08-4f8f-8d20-27d797fb7f19)

GPU 3: NVIDIA GeForce GTX 1080 Ti (UUID: GPU-bed2d40a-c6e7-4547-8d7d-a1576c5247b2)

Чтобы предоставить контейнеру только два последних GPU, используйте их ID:

services:

app:

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

command: nvidia-smi

deploy:

resources:

reservations:

devices:

  - driver: nvidia

    device_ids: ["2", "3"]

    capabilities: [gpu]

Нельзя одновременно указывать и count, и device_ids — это приведёт к ошибке. Также недопустимо задавать count больше числа доступных GPU или указывать несуществующие device_id.

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

Контейнер не видит GPU

Проверьте nvidia-container-toolkit на хосте и что daemon.json содержит runtime nvidia.
Убедитесь, что образ основан на nvidia/cuda или содержит необходимые библиотеки.
Выполните docker compose up без daemon options и посмотрите логи.

Несовместимость версий CUDA/драйвера

nvidia-smi показывает версию CUDA, поддерживаемую драйвером. Образ должен использовать совместимую версию CUDA.
Обновление драйвера на хосте или переключение образа — решение.

Ошибка при указании device_ids

Проверьте вывод nvidia-smi –list-gpus.
Убедитесь, что используете строки в массиве, как в примере [“0”,”1”].

Compose не распознаёт deploy

В Docker Compose v1 (docker-compose) секция deploy игнорируется локально. Для тестирования локально используйте “docker compose” (плагин v2) или переменные среды и флаги runtime. В продакшн-средах (Swarm) deploy применяется иначе.

Важно: deploy влияет на поведение в Docker Swarm; локально некоторые реализации Compose могут пропускать deploy. Проверяйте версию compose и используйте рекомендованную команду: docker compose up.

Когда это не сработает

На Windows с Docker Desktop и WSL2 интеграция может отличаться. Требуется поддержка GPU в WSL и включение соответствующих опций.
Если вы используете нестандартный runtime, несовместимый с nvidia-container-runtime.
Если на хосте нет драйверов NVIDIA — ничего не подключится.

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

docker run –gpus all — короткий путь для одиночных контейнеров, когда не нужен Compose.
Kubernetes + device-plugin для NVIDIA — когда нужна оркестрация на уровне кластера.
Для ML-пайплайнов рассмотрите use-case: если нужно масштабирование по GPU, лучше сразу использовать Kubernetes.

Практическая методология (SOP) для команды

Проверка хоста: nvidia-smi, версии драйвера.
Установка nvidia-docker2 / nvidia-container-toolkit.
Подготовка образа: базовый образ nvidia/cuda с нужной версией.
Создание docker-compose.yml с deploy.resources.reservations.devices.
Локальное тестирование: docker compose up, проверка nvidia-smi в контейнере.
Документирование и фиксация версий драйверов и образов в репозитории.

Роли и чек-листы

DevOps

Установить nvidia-container-toolkit на всех хостах.
Зафиксировать в CI тест на доступ к GPU (простой контейнер с nvidia-smi).
Обновлять драйверы планово и проверять совместимость.

Data Scientist

Указывать точную версию CUDA в Dockerfile.
Проверять, что зависимости (PyTorch, TensorFlow) собраны под нужную CUDA.
Добавлять тестовые скрипты, которые быстро выполняют небольшую операцию на GPU.

QA/Тестирование

Автоматизировать smoke-тест, который запускает контейнер и проверяет вывод nvidia-smi.
Тестировать поведение при отсутствии GPU (эмуляция/флажок в CI).

Фактбокс — ключевые числа и версии

Compose: поддержка GPU — v1.28 и новее.
Старые Compose: v1.18 и ниже — без поддержки; v1.19–v1.27 — устаревшая структура.
Пример драйвера в примерах: NVIDIA-SMI 470.103.01, CUDA 11.4.

Таблица совместимости (приблизительная)

Компонент	Минимальная рекомендация	Примечание
Docker Compose	v1.28+	Для надежной работы с deploy.resources
nvidia-container-toolkit	актуальная	Совместимость с драйвером NVIDIA
Драйвер NVIDIA	см. документацию	Версия драйвера определяет максимальную поддерживаемую CUDA
CUDA в образе	совпадает с хостом	Несоответствие вызывает ошибки в runtime

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

Контейнеры получают доступ к устройствам хоста. Ограничивайте доступ только тем сервисам, которым он нужен.
В системах с разделением ответственности следите за правами доступа к Docker сокету и образам.
Если контейнер обрабатывает персональные данные, применяйте обычные меры: шифрование данных в покое и в движении, логирование с маскированием, ротация ключей.

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

Контейнер запускается и nvidia-smi внутри контейнера показывает доступные GPU.
Образ использует заявленную версию CUDA, совпадающую с хостом.
Для сервисов указаны device_ids или count, и это соответствует ожиданиям заказчика.

Тесты и приемочные примеры

Smoke: docker compose up — контейнер выводит NVIDIA-SMI.
Negative: указать device_id вне диапазона — команда должна вернуть понятную ошибку.
Compatibility: сменить образ с CUDA 11.4 на 11.2 при драйвере, поддерживающем 11.4 — проверить поведение.

Частые вопросы

Можно ли использовать этот метод для Intel/AMD GPU?

Нет. На момент написания официальная интеграция через nvidia-container-toolkit поддерживает только NVIDIA. Попытки подключить другие вендоры этим способом приведут к ошибке.

Требуется ли Docker Swarm для deploy?

Не обязательно. deploy — это поле, которое используется в разных контекстах (Swarm/Compose). Некоторые реализации локально игнорируют deploy. Для локальной работы используйте “docker compose” (плагин v2) и проверяйте поддержку.

Как надежно указать конкретный GPU в мульти-GPU-системе?

Используйте device_ids с 0‑индексированными ID, как в выводе nvidia-smi –list-gpus.

Резюме

Docker Compose позволяет явно резервировать GPU для сервисов через deploy.resources.reservations.devices. Необходимо подготовить хост (nvidia-container-toolkit), согласовать версии CUDA/драйвера и использовать GPU-совместимый образ. Для продакшн-оркестрации, масштабирования и тонкого управления ресурсами рассмотрите Kubernetes и плагин NVIDIA device-plugin.