Введение

Контейнеризация — краеугольный камень современной DevOps-инфраструктуры. Docker стал стандартом де-факто для изоляции приложений и управления средами. Однако, когда требуется более гибкое и программируемое управление контейнерами, в дело вступает Docker SDK for Python, более известный как docker-py.

Эта библиотека позволяет напрямую взаимодействовать с Docker-демоном через Python-код, управляя контейнерами, образами, сетями, томами и всем, что обычно делается из CLI. Благодаря этому docker-py широко используется в CI/CD пайплайнах, автоматизации, тестировании и динамическом оркестрационном контроле.

В этой статье — полный разбор возможностей Docker SDK for Python: от теории и структуры до методов, кейсов, конфигураций и интеграций.

Основная часть

Установка и подключение

Установка

pip install docker

Импорт и инициализация клиента

import docker
client = docker.from_env()

Клиент автоматически подключается к локальному Docker-демону через DOCKER_HOST, DOCKER_TLS_VERIFY и другие переменные окружения.

Архитектура библиотеки

docker-py — обёртка над REST API Docker Engine. Она предоставляет как высокоуровневые (через docker.from_env()), так и низкоуровневые интерфейсы (docker.APIClient).

Основные компоненты:

• containers — управление контейнерами

• images — работа с образами

• volumes — тома данных

• networks — пользовательские сети

• services, tasks — для Swarm Mode

Работа с контейнерами

Создание и запуск контейнера

container = client.containers.run("nginx", detach=True, ports={"80/tcp": 8080})

Остановка и удаление

container.stop()
container.remove()

Просмотр логов и статуса

print(container.logs())
print(container.status)

Список всех контейнеров

for c in client.containers.list(all=True):
    print(c.name, c.status)

Работа с образами

Скачивание образа

client.images.pull("ubuntu")

Построение образа

image, logs = client.images.build(path=".", tag="myapp:latest")
for line in logs:
    print(line.get('stream'))

Удаление образа

client.images.remove("myapp:latest")

Список образов

for image in client.images.list():
    print(image.tags)

Работа с томами (volumes)

Создание тома

volume = client.volumes.create(name="myvolume")

Список и удаление

for v in client.volumes.list():
    print(v.name)
volume.remove()

Использование в контейнере

client.containers.run("redis", volumes={"myvolume": {'bind': '/data', 'mode': 'rw'}}, detach=True)

Работа с сетями

Создание сети

network = client.networks.create("mynet", driver="bridge")

Подключение контейнеров

network.connect(container)

Отключение и удаление

network.disconnect(container)
network.remove()

Продвинутые возможности

Использование exec_run

exit_code, output = container.exec_run("ls /")
print(output.decode())

Интерактивный attach

for line in container.attach(stream=True, logs=True):
    print(line.decode())

Подписка на события

for event in client.events(decode=True):
    print(event)

Docker Compose через Python

Хотя docker-compose не является частью docker-py, можно управлять составными сервисами с помощью docker-compose.yml через сторонние обёртки (например, compose.cli из Docker CLI).

Ошибки и отладка

Обработка ошибок

from docker.errors import NotFound, APIError
try:
    container = client.containers.get("nonexistent")
except NotFound:
    print("Контейнер не найден")

Ведение логов

import logging
logging.basicConfig(level=logging.DEBUG)

Использование в CI/CD

Docker SDK используется в:

• GitHub Actions (через кастомные Python-скрипты)

• Jenkins Pipelines

• GitLab CI с Python-обёртками

• Внутренних утилитах деплоя

Пример автосборки и деплоя

client.images.build(path=".", tag="myciapp")
container = client.containers.run("myciapp", detach=True)
print(container.logs())

Сравнение с CLI и альтернативами

Производственные кейсы

Тестирование окружений

Изолированный запуск тестов в CI перед мержем pull request'а.

Автоматизация деплоя

Пайплайн с автосборкой, пушем в DockerHub и запуском контейнеров.

Мониторинг и кастомные панели

Подключение к событиям и создание дашбордов в реальном времени.

Основные модули Docker SDK

1. docker.DockerClient – основной клиент для работы с Docker.

2. docker.models.containers – управление контейнерами.

3. docker.models.images – управление образами.

4. docker.models.networks – управление сетями.

5. docker.models.volumes – управление томами.

6. docker.api – низкоуровневый API.

1. docker.DockerClient – подключение к Docker

Основной класс для взаимодействия с Docker Engine.

Основные методы

Пример

import docker

client = docker.from_env()
print(client.ping())  # Проверка соединения
print(client.version())  # Версия Docker
client.close()

2. docker.models.containers – управление контейнерами

Класс Container и методы для работы с контейнерами.

Основные методы

Пример

container = client.containers.run(
    "nginx:latest",
    detach=True,
    ports={'80/tcp': 8080}
)
print(container.id)

# Получение логов
print(container.logs())

# Остановка и удаление
container.stop()
container.remove()

3. docker.models.images – управление образами

Класс Image и методы для работы с Docker-образами.

Основные методы

Пример

# Загрузка образа
image = client.images.pull("nginx:latest")

# Сборка образа
image = client.images.build(
    path=".",  # Путь к Dockerfile
    tag="myapp:latest"
)

# Удаление образа
client.images.remove("nginx:latest")

4. docker.models.networks – управление сетями

Класс Network и методы для работы с Docker-сетями.

Основные методы

Пример

network = client.networks.create("mynetwork", driver="bridge")
print(network.id)

# Подключение контейнера
network.connect(container.id)

# Удаление сети
network.remove()

5. docker.models.volumes – управление томами

Класс Volume и методы для работы с Docker-томами.

Основные методы

Пример

volume = client.volumes.create(name="mydata")
print(volume.id)

# Удаление тома
volume.remove()

6. docker.api – низкоуровневый API

Прямой доступ к Docker API (аналогично docker engine API).

Основные модули

Пример

from docker import APIClient

low_level_client = APIClient(base_url='unix://var/run/docker.sock')
container_id = low_level_client.create_container("nginx:latest")["Id"]
low_level_client.start(container_id)

7. Дополнительные функции

1. docker.types – вспомогательные классы

from docker.types import Mount, Ulimit

mount = Mount(target="/data", source="mydata", type="volume")
ulimit = Ulimit(name='nofile', soft=100, hard=200)

client.containers.run(
    "nginx",
    mounts=[mount],
    ulimits=[ulimit]
)

2. docker.errors – обработка ошибок

from docker.errors import DockerException, ImageNotFound

try:
    client.images.get("nonexistent-image")
except ImageNotFound:
    print("Образ не найден!")

3. docker.auth – аутентификация в реестре

from docker.auth import load_config

auth_config = load_config()
client.images.push("myrepo/myimage", auth_config=auth_config)

Пример: сборка, запуск и мониторинг контейнера

import docker

client = docker.from_env()

# Сборка образа
image, logs = client.images.build(path=".", tag="myapp")

# Запуск контейнера
container = client.containers.run(
    "myapp",
    detach=True,
    ports={'5000/tcp': 5000}
)

# Мониторинг ресурсов
stats = container.stats(stream=False)
print(stats["memory_stats"]["usage"])

# Остановка и удаление
container.stop()
container.remove()
client.close()

Заключение

Docker SDK for Python — мощный инструмент, позволяющий автоматизировать все аспекты работы с контейнерами. Его простота, гибкость и глубина управления делают его незаменимым для DevOps-инженеров, разработчиков, QA и системных администраторов. Он полностью заменяет CLI в контексте автоматизированных решений.