NVIDIA no Docker com NVIDIA Container Toolkit

O Docker não possui suporte nativo a GPUs NVIDIA sem integração adicional. O acesso à GPU exige o uso do NVIDIA Container Toolkit, responsável por expor drivers, bibliotecas CUDA e dispositivos /dev/nvidia* aos contêineres.

Esse modelo permite executar aplicações aceleradas por GPU dentro de ambientes isolados, mantendo compatibilidade com CUDA, TensorRT, PyTorch, TensorFlow e outras bibliotecas de computação paralela.

Requisitos

Antes da configuração, o host deve possuir:

• GPU NVIDIA compatível
• Driver NVIDIA instalado no host
• Docker instalado
• Kernel Linux compatível com os drivers NVIDIA

Verifique se o driver está funcional:

nvidia-smi

Saída esperada:

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 555.xx.xx              Driver Version: 555.xx.xx        CUDA Version: 12.x   |
+-----------------------------------------------------------------------------------------+

Sem funcionamento correto do nvidia-smi, o Docker não conseguirá acessar a GPU.

Instalação do NVIDIA Container Toolkit

Debian/Ubuntu

Adicionar repositório oficial:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

Atualizar índices:

sudo apt update

Instalar toolkit:

sudo apt install -y nvidia-container-toolkit

Configuração do Docker

Configurar integração com o runtime NVIDIA:

sudo nvidia-ctk runtime configure --runtime=docker

Reiniciar o Docker:

sudo systemctl restart docker

Teste de Funcionamento

Executar contêiner CUDA oficial:

docker run --rm --gpus all nvidia/cuda:12.5.0-base-ubuntu22.04 nvidia-smi

Se configurado corretamente, o contêiner exibirá as GPUs disponíveis do host.

Uso de GPUs no Docker

Expor todas as GPUs

docker run --rm --gpus all ubuntu nvidia-smi

Expor GPU específica

docker run --rm --gpus '"device=0"' ubuntu nvidia-smi

Múltiplas GPUs:

docker run --rm --gpus '"device=0,1"' ubuntu nvidia-smi

Uso com Docker Compose

Exemplo com docker-compose.yml:

services:
  app:
    image: nvidia/cuda:12.5.0-base-ubuntu22.04
    command: nvidia-smi

    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Em ambientes não-Swarm, muitos projetos utilizam:

services:
  app:
    image: nvidia/cuda:12.5.0-base-ubuntu22.04
    runtime: nvidia

Entretanto, runtime: nvidia é considerado legado em versões recentes do Docker.

Variáveis de Ambiente NVIDIA

Seleção de GPUs

-e NVIDIA_VISIBLE_DEVICES=0

Valores comuns:

Capacidades do Driver

-e NVIDIA_DRIVER_CAPABILITIES=compute,utility

Capacidades disponíveis:

Imagens CUDA Oficiais

A NVIDIA mantém imagens oficiais no Docker Hub.

Principais variantes:

Exemplo:

docker pull nvidia/cuda:12.5.0-devel-ubuntu22.04

Integração com IA e Machine Learning

Frameworks modernos utilizam CUDA diretamente dentro dos contêineres:

PyTorch

docker run --rm --gpus all pytorch/pytorch:latest python -c \
'import torch; print(torch.cuda.is_available())'

TensorFlow

docker run --rm --gpus all tensorflow/tensorflow:latest-gpu python -c \
'import tensorflow as tf; print(tf.config.list_physical_devices("GPU"))'

Compatibilidade CUDA e Driver

O driver NVIDIA do host deve ser compatível com a versão CUDA da imagem.

Regra prática:

• Driver mais novo normalmente suporta CUDA antiga
• CUDA nova pode exigir driver mais recente

Verificar compatibilidade:

nvidia-smi

A linha CUDA Version indica a versão máxima suportada pelo driver instalado.

Problemas Comuns

GPU não detectada

Erro:

could not select device driver "" with capabilities: [[gpu]]

Causas comuns:

• NVIDIA Container Toolkit não instalado
• Docker não reiniciado
• Driver NVIDIA ausente
• Runtime NVIDIA não configurado

nvidia-smi funciona no host mas não no container

Verificar runtime:

docker info | grep -i runtime

Saída esperada:

Runtimes: io.containerd.runc.v2 nvidia runc

Incompatibilidade de CUDA

Erro típico:

CUDA driver version is insufficient for CUDA runtime version

Resolver com:

• Atualização do driver NVIDIA
• Uso de imagem CUDA compatível

Segurança e Isolamento

Contêineres com acesso à GPU compartilham o driver do host. O isolamento não é equivalente ao de uma máquina virtual.

Riscos principais:

• Exposição parcial de telemetria da GPU
• Compartilhamento de memória GPU
• Dependência direta do kernel do host

Em ambientes multi-tenant, recomenda-se:

• Kubernetes com GPU Operator
• MIG (Multi-Instance GPU)
• Controle de quotas e isolamento por namespace

Vantagens

• Portabilidade de workloads CUDA
• Reprodutibilidade de ambientes
• Integração com CI/CD
• Escalabilidade em clusters GPU
• Simplificação de dependências CUDA

Desvantagens

• Dependência do driver do host
• Compatibilidade CUDA pode gerar conflitos
• Overhead operacional em ambientes heterogêneos
• Isolamento inferior ao de virtualização completa

Conclusão

O NVIDIA Container Toolkit é o mecanismo padrão para habilitar aceleração por GPU NVIDIA no Docker. Ele integra drivers do host ao runtime de contêineres, permitindo execução de workloads CUDA de forma portátil e isolada.

A configuração correta depende principalmente de três fatores:

• Driver NVIDIA funcional no host
• Compatibilidade CUDA
• Runtime NVIDIA integrado ao Docker

Com esses componentes alinhados, aplicações de IA, renderização, inferência e computação paralela podem utilizar GPUs diretamente dentro de contêineres.