Поиск по сайту:

Как начать работу с API Docker Engine


Docker Engine предоставляет REST API, который вы можете использовать для управления своими контейнерами без интерфейса командной строки docker. API предоставляет эквивалентную функциональность, используя сетевые вызовы HTTP. Вы можете создавать стандартные операции Docker, используя свой любимый язык программирования, или удаленно управлять одним из ваших хостов. CLI внутренне полагается на тот же API для предоставления своих встроенных команд.

В этой статье мы рассмотрим основы включения и использования API. Если вы имеете в виду конкретный вариант использования, обратитесь к справочной документации по API, чтобы определить нужные вам конечные точки.

Включение API Docker Engine

API интегрирован с Docker Engine. Любой функционирующий хост Docker уже подготовлен для взаимодействия с API. Чтобы предоставить сервис, вам нужно привязать демон Docker к сокету TCP, а также к сокету Unix по умолчанию или вместо него. Запустите dockerd с флагом -H, чтобы указать сокеты для прослушивания:

sudo dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375

Эта команда предоставляет API на порту 2375. Сокет Unix по умолчанию сохраняется, поэтому интерфейс командной строки Docker продолжит работу без какой-либо перенастройки. Порт 2375 используется для Docker по соглашению; не стесняйтесь изменять его в соответствии с вашей средой.

Вы можете сделать так, чтобы Docker всегда запускался с этими настройками, отредактировав файл конфигурации службы systemd. Отредактируйте или создайте /etc/systemd/system/docker.service.d/options.conf, найдите строку ExecStart и измените ее, чтобы включить дополнительные флаги:

[Service]
ExecStart=/usr/bin/dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375

Перезагрузите конфигурацию systemd, чтобы применить изменения:

sudo systemctl daemon-reload

Теперь вы готовы взаимодействовать с API Docker Engine по адресу 127.0.0.1:2375.

Примечание о безопасности

Приведенные выше шаги предоставляют API без какой-либо защиты. Любой, у кого есть доступ к порту 2375 на вашем хосте, может отправлять произвольные команды демону Docker, запускать новые контейнеры, заполнять ваш диск образами или уничтожать существующие рабочие нагрузки.

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

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

curl https://127.0.0.1:2375/v1.41/containers/json --cert client-cert.pem --key client-key.pem

Возможно, вам вообще не нужно привязывать TCP-сокет в зависимости от вашего варианта использования. Если ваш клиент поддерживает сокеты Unix, вы можете использовать существующий сокет Docker для подключения:

curl --unix-socket /var/run/docker.sock http://localhost/v1.41/containers

Это может быть более безопасным выбором, чем риск непреднамеренного раскрытия TCP-сокета.

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

API использует версионные конечные точки, поэтому вы можете привязываться к определенным версиям форматов запросов и ответов. Вы должны указать версию, которую вы используете, в начале каждого URL-адреса конечной точки. v1.41 — это последний выпуск, присутствующий в производственных сборках Docker на момент написания.

http://127.0.0.1:2375/v1.41

Конечные точки API сгруппированы в функциональные блоки REST. Они соответствуют основным типам объектов Docker, таким как контейнеры, изображения и тома. Обычно вы можете найти API для определенного типа объекта в базовом URL-адресе, который начинается с его имени:

# APIs related to container operations
http://127.0.0.1:2375/v1.41/containers

API использует JSON для всех обменов данными с вашим HTTP-клиентом. Конечные точки принимают тела запросов JSON и в ответ выдают ответы JSON. Это должно упростить обработку данных внутри ваших приложений, поскольку вы можете использовать библиотеку JSON, включенную в вашу среду программирования. Такие инструменты, как jq, можно использовать для сжатия, фильтрации и сортировки ответов, если вы экспериментируете в своем терминале.

Общие конечные точки

Поскольку API повторяет функциональность интерфейса командной строки Docker, существует слишком много возможных конечных точек, чтобы охватить их все здесь. Вместо этого мы продемонстрируем несколько наиболее часто используемых опций, относящихся к основным функциям Docker.

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

Полный список контейнеров на хосте можно получить из конечной точки /containers/json:

curl http://127.0.0.1:2375/v1.41/containers/json

По умолчанию он отображает только запущенные контейнеры. Добавьте all=true в строку запроса, чтобы также включить остановленные контейнеры. Ограничьте общее количество возвращаемых контейнеров с помощью параметра limit, например limit=10. Будут включены только 10 последних созданных контейнеров.

Доступно несколько различных фильтров для сокращения списка до контейнеров с определенными атрибутами. Они устанавливаются со следующим синтаксисом:

curl http://127.0.0.1:2375/v1.41/containers/json?filters={"name":"demo"}

Этот URL-адрес возвращает информацию, связанную с контейнером demo. Другие фильтры могут быть выражены аналогичным образом, например {\status\:[\running\,\paused\]} для запуска и приостановки контейнеров или { \health=[\healthy\]} только для исправных контейнеров.

Запуск нового контейнера

Запуск контейнера — это двухэтапный процесс при использовании API. Сначала вам нужно создать контейнер, а затем запустить его в отдельном вызове API.

Создайте контейнер, отправив запрос POST в конечную точку /containers/create. Для этого требуется тело JSON с полями, соответствующими флагам, принимаемым командой CLI docker run.

Вот минимальный пример создания контейнера:

curl http://127.0.0.1:2375/v1.41/containers/create 
    -X POST 
    -H "Content-Type: application/json" 
    -d '{"Image": "example-image:latest"}'

Ответ JSON будет включать в себя идентификатор нового контейнера и все предупреждения, связанные с его созданием. Отправьте идентификатор в вызове на конечную точку /containers/:id/start:

curl http://127.0.0.1:2375/v1.41/containers/abc123/start -X POST

Контейнер теперь будет работать на хосте Docker.

Очистка контейнеров

Удалите остановленные контейнеры, отправив запрос POST в конечную точку /containers/prune:

curl http://127.0.0.1:2375/v1.41/containers/prune -X POST

Вам будет выдан ответ JSON с полями ContainersDeleted и SpaceReclaimed. ContainersDeleted — это массив идентификаторов контейнеров, которые были успешно удалены. SpaceReclaimed информирует вас об общем объеме свободного места для хранения в байтах.

Эта конечная точка принимает два параметра строки запроса для ограничения операции. Параметр until ограничивает удаление контейнерами, созданными до заданного времени, например until=10m или until=2022-03-01. Опция label фильтрует контейнеры с заданными метками или без них; установка label=demo=example удалит только контейнеры с меткой demo=example.

Список изображений

Конечная точка /images/json используется для перечисления изображений, хранящихся на хосте Docker:

curl http://127.0.0.1:2375/v1.41/images/json

Вы можете использовать фильтры, чтобы изменить содержимое ответа. Они предоставляются в виде объекта JSON в параметре строки запроса filters, аналогично API списка контейнеров. Одной из заслуживающих внимания опций является reference, которая выбирает изображение с заданным тегом: filters={\reference\:\hello-world:latest\}.

Изображения зданий

Вы можете использовать API для создания новых образов Docker из Dockerfiles. На конечную точку /build должен быть отправлен архив tar. Содержимое этого архива будет использоваться в качестве контекста сборки образа. В архиве должен быть Dockerfile с инструкциями по сборке.

cat context.tar | curl http://127.0.0.1:2375/v1.41/build?t=example-image:latest -X POST

Приведенная выше команда отправит context.tar демону Docker и создаст образ, используя Dockerfile внутри. Изображение будет помечено как example-image:latest и сохранено на хосте Docker.

Эта конечная точка принимает множество дополнительных параметров строки запроса, которые соответствуют функциональности интерфейса командной строки docker build. К ним относятся dockerfile=path/to/dockerfile, чтобы указать путь к Dockerfile контекста сборки, rm=true, который удаляет промежуточные контейнеры, созданные сборкой, и pull=true, чтобы попытаться получить обновленные версии образов, на которые ссылается Dockerfile.

API требует, чтобы ваш клиент оставался на связи до завершения сборки. Сборка будет отменена, если сеть прервется и соединение будет закрыто.

Список журналов событий демона

API /events отображает данные журнала событий демона, которые также доступны с помощью команды CLI docker events. Эта конечная точка передает события в режиме реального времени по мере их возникновения.

curl http://127.0.0.1:2375/v1.41/events

Предоставляется несколько различных типов событий, включая создание контейнеров, теги образов, монтирование томов и изменения сети. Вы можете отфильтровать события определенного типа, используя поле type параметра запроса filters:

# Only get container events
curl http://127.0.0.1:2375/v1.41/events?filters={'type':'container'}

Также можно ограничить события, относящиеся к конкретному объекту:

# Get events pertaining to the container with ID abc123
curl http://127.0.0.1:2375/v1.41/events?filters={'container':'id'}

Два других параметра строки запроса, since и until, позволяют указать диапазон отметок времени для отображения исторических событий внутри.

Получение информации о системе

API Docker Engine можно использовать для получения информации о физическом хосте, на котором он работает:

curl http://127.0.0.1:2375/v1.41/info

Эта конечная точка предоставляет подробные сведения, описывающие текущее состояние и конфигурацию хоста и демона Docker. Поля в ответе включают количество запущенных, приостановленных и остановленных контейнеров, путь к каталогу установки Docker, сведения об оборудовании и ОС, а также конфигурацию сервера Swarm, когда он работает в кластере.

Заключение

API Docker Engine дает вам возможность отправлять команды демону Docker вашего хоста через HTTP. Это упрощает создание сценариев программных взаимодействий, не полагаясь на определенное поведение Docker CLI. API также можно использовать для удаленного управления серверами Docker для улучшения мониторинга и простоты обслуживания.

Хотя вызов API должен быть простым, вам необходимо обратить внимание на защиту вашего TCP-сокета. Старайтесь не открывать сокет в своей сети, если только он не защищен с помощью TLS, чтобы к нему могли подключаться только утвержденные клиенты. Пропуск этого дополнительного этапа настройки может дорого обойтись, если злоумышленник обнаружит ваш экземпляр демона и начнет выдавать команды.

Вы можете еще больше упростить использование API в своих приложениях, приняв один из SDK. Для всех популярных языков программирования, включая C, C#, C++, Go, Java, NodeJS, PHP, Python и Ruby, доступен либо официальный, либо предоставленный сообществом вариант. Пакеты SDK объединяют конечные точки API в удобные классы и функции для вызова из кода, уменьшая количество шаблонов, необходимых для взаимодействия с установкой Docker.