Docker Registry API — список изображений и тегов

1. Обзор

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

Это полезно для того, чтобы узнать, какие версии конкретного образа доступны в реестре, и решить, какую из них использовать.

2. API реестра Docker

Реестр Docker предоставляет API для взаимодействия с реестром. Этот API содержит различные конечные точки, используемые в фоновом режиме интерфейсом командной строки Docker для выполнения различных задач, таких как извлечение, отправка и пометка изображений.

Мы также можем использовать эти конечные точки напрямую для взаимодействия с реестром без использования интерфейса командной строки Docker.

Давайте посмотрим на формат конечной точки API реестра:

/<api-version>/<repository-name>/<resource>/<params>

Давайте рассмотрим различные компоненты этой конечной точки:

• Версия API — версия API. Например, текущая версия — v2 .
• Имя репозитория (изображения) — имя изображения. Имя также может содержать путь, разделенный косой чертой, если это вложенный репозиторий. Например, /ubuntu/nginx или /redis .
• Ресурс — подразделение API, с которым мы хотим взаимодействовать. Например, манифесты будут работать с манифестами определенного изображения.
• Параметры — это необязательные параметры, которые можно использовать для дальнейшего уточнения операции. Например, manifests/latest будет получать манифест для последнего тега.

Основываясь на приведенных выше правилах, ниже приведен конкретный пример конечной точки:

GET /v2/ubuntu/nginx/manifests/latest

3. API реестра Docker V2

На момент написания V2 является текущей версией Registry API. Давайте рассмотрим, как использовать его для получения списка изображений и тегов из удаленного реестра.

Предположим, у нас есть реестр, развернутый по адресу https://my-registry.io. Мы будем использовать curl для выполнения HTTP-запросов.

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

Чтобы перечислить образы в реестре, мы можем использовать конечную точку каталога _/ :

$ curl -X GET my-registry.io/v2/_catalog
{"repositories":["centos","ubuntu"]}

Следует отметить, что для доступа к определенным репозиториям может потребоваться аутентификация, если она была включена. В таких случаях мы можем передать имя пользователя и пароль в качестве параметров команде curl , используя параметр -u .

$ curl -u user:password -X GET my-registry.io/v2/_catalog 
{"repositories":["centos","ubuntu"]}

3.2. Список изображений с разбивкой на страницы

Иногда в реестре может быть большое количество образов. В таких случаях мы можем добавить параметр n=<number of results> к конечной точке каталога _/ , чтобы получить ответ с разбивкой на страницы:

$ curl -X GET my-registry.io/v2/_catalog?n=1
{"repositories":["centos"]}

Ответ теперь содержит только первое изображение.

Мы можем использовать ответ на первый запрос, чтобы получить следующую страницу результатов. Для этого нужно внести два изменения в команду curl:

• Последний параметр конечной точки каталога _/ , содержащий имя последнего изображения, возвращенное в предыдущем запросе.
• Заголовок, связывающий новый запрос с предыдущим. Заголовок имеет следующий формат:

Link: <my-registry.io/v2/_catalog?n=1&last=centos>; rel="next"

Скобки вокруг URL обязательны. URL-адрес совпадает с URL-адресом нового запроса. Заголовок rel="next" указывает, что новый запрос является продолжением предыдущего в соответствии с RFC 5988 .

Итак, давайте сделаем следующий запрос:

$ curl -H 'Link: <my-registry.io/v2/_catalog?n=1&last=centos>; rel="next"' -X GET "my-registry.io/v2/_catalog?n=1&last=centos"
{"repositories":["ubuntu"]}

Ответ возвращает следующую страницу результатов, содержащую одно изображение.

3.3. Список тегов

Чтобы перечислить теги изображения , мы можем использовать конечную точку /tags/list :

$ curl -X GET my-registry.io/v2/ubuntu/tags/list
{"name":"ubuntu","tags":["latest","16.04"]}

Ответ содержит имя изображения и массив связанных с ним тегов.

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

4. API реестра Docker V1

Registry API v1 устарел в Docker 17.06 и удален в Docker 17.12. Однако, если мы столкнемся с реестром, размещенным до устаревания, мы можем использовать API версии 1. Давайте посмотрим, как в этом случае меняются наши запросы.

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

В v1 нет прямой конечной точки для перечисления изображений. Вместо этого мы можем использовать команду docker search для поиска изображений, содержащих заданную строку:

$ docker search my-registry.io/centos

Это возвращает список изображений, которые содержат строку «centos» в своем имени или описании.

Если мы не укажем реестр, поиск будет выполняться в реестре по умолчанию. Репозиторий по умолчанию — репозиторий Docker Hub.

Например, на изображении ниже показан вывод, когда мы ищем термин «ubuntu» без указания репозитория.

4.2. Список тегов

Метод перечисления тегов аналогичен v2 API. Однако в этом случае результат будет другим:

$ curl -X GET https://registry.hub.docker.com/v1/repositories/foreach/mesos-marathon-demo/tags
[{"layer": "", "name": "32"}, {"layer": "", "name": "33"}, {"layer": "", "name": "34"}]

Как мы видим, вместо одного массива тегов у нас есть массив объектов. Каждый объект включает имя тега и идентификатор слоя изображения.

При необходимости мы можем преобразовать ответ в массив. Для этого давайте направим вывод в команду jq и проанализируем JSON:

$ curl -s GET https://registry.hub.docker.com/v1/repositories/foreach/mesos-marathon-demo/tags | jq -r '[.[].name]'
[
  "32",
  "33",
  "34"
]

Давайте разберемся с командой jq и используемыми здесь выражениями:

• Флаг -r возвращает вывод в виде необработанного текста.
• Выражение .[].name возвращает свойство name для каждого объекта из вывода curl .
• Квадратные скобки [] вокруг выражения указывают на то, что мы хотим собрать вывод в массив.

Наконец, флаг -s , используемый с командой curl, необходим для подавления вывода индикатора выполнения.

5. Вывод

В этой статье мы рассмотрели, как использовать Docker Registry API для перечисления образов и тегов в удаленном реестре.

Мы также рассмотрели, как отправлять запросы изображений и тегов с разбивкой на страницы и как анализировать ответы JSON.