Работа с Docker registries

Некоторые категории команд работают с Docker registry, и требуют соответствующей авторизации:

Во время процесса сборки werf может делать pull образов из Docker registry.
Во время процесса публикации werf создает и обновляет образы в Docker registry.
Во время процесса очистки werf удаляет образы из Docker registry.
Во время процесса деплоя werf требует доступа к образам в Docker registry и стадиям, которые также могут находиться в Docker registry.

Поддерживаемые имплементации

	Build и Publish	Cleanup
AWS ECR	ок	ок (с нативным API)
Azure CR	ок	ок (с нативным API)
Default	ок	ок
Docker Hub	ок	ок (с нативным API)
GCR	ок	ок
GitHub Packages	ок	ок (с нативным API и только в приватных GitHub репозиториях)
GitLab Registry	ок	ок
Harbor	ок	ок
JFrog Artifactory	ок	ок
Quay	ок	ок

В ближайшее время планируется добавить поддержку для Nexus Registry

Следующие имплементации полностью поддерживаются и от пользователя требуется только выполнить авторизацию Docker:

Default.
GCR.
GitLab Registry.
Harbor.

Azure CR, AWS ECR, Docker Hub и GitHub Packages имплементации поддерживают Docker Registry API, но не полностью. Для перечисленных имплементаций необходимо использовать нативное API для удаления тегов. Поэтому при очистке для werf может потребоваться дополнительные пользовательские данные.

Часть имплементаций не поддерживает вложенные репозитории (Docker Hub, GitHub Packages и Quay) или как в случае с AWS ECR пользователь должен создать репозитории вручную, используя UI или API, перед использованием werf.

Как хранить образы

Параметры images repo и images repo mode определяют где и как хранятся образы в репозитории (подробнее в разделе именование образов).

Параметр images repo может быть как адресом registry, так и repository.

Конечное имя Docker-образа зависит от images repo mode:

IMAGES_REPO:IMAGE_NAME-TAG шаблон для monorepo мода;
IMAGES_REPO/IMAGE_NAME:TAG шаблон для multirepo мода.

Docker-образы не могут храниться в registry. Поэтому комбинация registry и monorepo не имеет никакого смысла. Также, по той же причине, пользователь должен быть внимательным и не использовать registry с безымянным образов (image: ~).

При переходе на использование registry с multirepo важно не забыть переименовать безымяный образ в werf.yaml и удалить связанный managed image (werf managed-images rm '~')

Таким образом, остаётся три возможных комбинации использования images repo и images repo mode.

	registry + multirepo	repository + monorepo	repository + multirepo
AWS ECR	ок	ок	ок
Azure CR	ок	ок	ок
Default	ок	ок	ок
Docker Hub	ок	ок	не поддерживается
GCR	ок	ок	ок
GitHub Packages	ок	ок	не поддерживается
GitLab Registry	ок	ок	ок
Harbor	ок	ок	ок
JFrog Artifactory	ок	ок	ок
Quay	ок	ок	не поддерживается

Большинство имплементаций поддерживают вложенные репозитории и по умолчанию используют multirepo images repo mode. Для остальных имплементаций значение по умолчанию зависит от указанного images repo.

AWS ECR

Как хранить образы

Хранение образов в AWS ECR не отличается от остальных имплементаций, но пользователь должен самостоятельно создать репозитории перед использованием werf.

Как чистить stages и images

werf использует AWS SDK для удаления тегов, поэтому перед использованием команд очистки пользователь должен:

Установить AWS CLI и выполнить конфигурацию (aws configure) или
Определить AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY переменные окружения.

Azure CR

Как чистить stages и images

Для того, чтобы werf начал удалять теги, пользователю необходимо выполнить следующие шаги:

Установить Azure CLI (az).
Выполнить авторизацию (az login).

Для удаления тегов пользователь должен иметь одну из следующих ролей: Owner, Contributor или AcrDelete (подробнее Azure CR roles and permissions)

Docker Hub

Как хранить образы

Если используется один Docker Hub аккаунт для всего проекта и есть необходимость хранения образов в отдельных репозиториях, то в качестве images repo необходимо указывать аккаунт:

<ACCOUNT> # к примеру, library или index.docker.io/library

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

При переходе на такой подход пользователь должен переименовать безымянный образ в werf.yaml и удалить соответствующий managed image в stages storage (werf managed-images rm '~'), если имеется

Если в werf конфигурации используется безымянный образ (image: ~) или пользователь хочет хранить все образы в одном репозитории, то необходимо использовать конкретный репозиторий в качестве параметра для images repo:

<ACCOUNT>/<REPOSITORY> # к примеру, library/alpine или index.docker.io/library/alpine

Пример

Пользователь имеет следующее:

Два образа в werf.yaml: frontend, backend.
Docker Hub аккаунт: foo.

Есть два возможных способа хранения конечных образов:

Параметр images repo foo приведёт к следующим тегам: foo/frontend:tag и foo/backend:tag.
```
 werf build-and-publish -s=:local -i=foo --tag-custom=tag
```
Параметр images repo foo/project приведёт к следующим тегам: foo/project:frontend-tag и foo/project:backend-tag.
```
 werf build-and-publish -s=:local -i=foo/project --tag-custom=tag
```

Как чистить stages и images

Для чистки тегов в Docker Hub репозитории werf использует Docker Hub API и для работы требуются дополнительные параметры.

Пользователь должен определить token или username и password.

Используя следующий скрипт, пользователь может получить token самостоятельно:

HUB_USERNAME=USERNAME
HUB_PASSWORD=PASSWORD
HUB_TOKEN=$(curl -s -H "Content-Type: application/json" -X POST -d '{"username": "'${HUB_USERNAME}'", "password": "'${HUB_PASSWORD}'"}' https://hub.docker.com/v2/users/login/ | jq -r .token)

В качестве токена нельзя использовать personal access token, т.к. удаление ресурсов возможно только при использовании основных учётных данных

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

Для stages storage: --stages-storage-repo-docker-hub-token или --stages-storage-repo-docker-hub-username и --stages-storage-repo-docker-hub-password.
Для images repo: --images-repo-docker-hub-token или --images-repo-docker-hub-username и --images-repo-docker-hub-password.
И то и другое: --repo-docker-hub-token или --repo-docker-hub-username и --repo-docker-hub-password.

GitHub Packages

Как хранить образы

Если есть необходимость хранения образов в отдельных packages, то пользователь не должен указывать package в images repo:

docker.pkg.github.com/<ACCOUNT>/<PROJECT> # к примеру, docker.pkg.github.com/flant/werf

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

При переходе на такой подход, пользователь должен переименовать безымянный образ в werf.yaml и удалить соответствующий managed image в stages storage (werf managed-images rm '~'), если имеется

Если в werf конфигурации используется безымянный образ (image: ~) или пользователь хочет хранить все образы в одном package, то необходимо использовать конкретный package в качестве параметра для images repo:

docker.pkg.github.com/<ACCOUNT>/<PROJECT>/<PACKAGE> # к примеру, docker.pkg.github.com/flant/werf/image

Пример

Пользователь имеет следующее:

Два образа в werf.yaml: frontend, backend.
GitHub репозиторий: github.com/company/project.

Есть два возможных способа хранения конечных образов:

Параметр images repo docker.pkg.github.com/company/project приведёт к следующим тегам: docker.pkg.github.com/company/project/frontend:tag и docker.pkg.github.com/company/project/backend:tag.
```
 werf build-and-publish -s=:local -i=docker.pkg.github.com/company/project --tag-custom=tag
```
Параметр images repo docker.pkg.github.com/company/project/app приведёт к следующим тегам: docker.pkg.github.com/company/project/app:frontend-tag и docker.pkg.github.com/company/project/app:backend-tag.
```
 werf build-and-publish -s=:local -i=docker.pkg.github.com/company/project/app --tag-custom=tag
```

Как чистить stages и images

Для удаления версий package приватного репозитория используется GraphQL. От пользователя требуется token с read:packages, write:packages, delete:packages и repo scopes.

GitHub не поддерживает удание версий package в публичных репозиториях

Для stages storage: --stages-storage-repo-github-token.
Для images repo: --images-repo-github-token.
И то и другое: --repo-github-token.

Quay

Как хранить образы

Если есть необходимость хранения образов в отдельных репозиториях, то не нужно указывать репозиторий images repo:

quay.io/<USER or ORGANIZATION> # к примеру, quay.io/werf

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

При переходе на такой подход, пользователь должен переименовать безымянный образ в werf.yaml и удалить соответствующий managed image в stages storage (werf managed-images rm '~'), если имеется

Если в werf конфигурации используется безымянный образ (image: ~) или пользователь хочет хранить все образы в одном репозиторий, то необходимо использовать конкретный репозиторий в качестве параметра для images repo:

quay.io/<USER or ORGANIZATION>/<REPOSITORY> # к примеру, quay.io/werf/image

Пример

Пользователь имеет следующее:

Два образа в werf.yaml: frontend, backend.
Организацию company в quay.io: quay.io/company.

Есть два возможных способа хранения конечных образов:

Параметр images repo quay.io/company приведёт к следующим тегам: quay.io/company/frontend:tag и quay.io/company/backend:tag.
```
 werf build-and-publish -s=:local -i=quay.io/company --tag-custom=tag
```
Параметр images repo quay.io/company/app приведёт к следующим тегам: quay.io/company/app:frontend-tag и quay.io/company/app:backend-tag.
```
 werf build-and-publish -s=:local -i=quay.io/company/app --tag-custom=tag
```

Авторизация Docker

Все команды, требующие авторизации в Docker registry, не выполняют ее сами, а используют подготовленную конфигурацию Docker.

Конфигурация Docker — это папка, в которой хранятся данные авторизации используемые для доступа вразличные Docker registry и другие настройки Docker. По умолчанию, werf использует стандартную для Docker папку конфигурации: ~/.docker. Другую используемую папку конфигурации можно указать с помощью параметра --docker-config, либо с помощью переменных окружения $DOCKER_CONFIG или $WERF_DOCKER_CONFIG. Все параметры и опции в файле конфигурации стандартны для Docker, их список можно посмотреть с помощью команды docker --config.

Для подготовки конфигурации Docker вы можете использовать команду docker login, либо, если вы выполняете werf в рамках CI-системы, вызвать команду werf ci-env (более подробно о подключении werf к CI-системам читай в соответствующем разделе).

Использование docker login при параллельном выполнении заданий в CI-системе может приводить к ошибкам выполнения заданий из-за работы с временными правами и состояния race condition (одно задание влияет на другое, переопределяя конфигурацию Docker). Поэтому, необходимо обеспечивать независимую конфигурацию Docker между заданиями, используя docker --config или werf ci-env