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

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

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

В ближайшее время планируется добавить поддержку для JFrog Container Registry и 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 ок ок ок
Quay ок ок не поддерживается

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

AWS ECR

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

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

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

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

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.

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

  1. Параметр images repo foo приведёт к следующим тегам: foo/frontend:tag и foo/backend:tag.
     werf build-and-publish -s=:local -i=foo --tag-custom=tag
    
  2. Параметр 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.

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

  1. Параметр 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
    
  2. Параметр 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.

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

  1. Параметр 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
    
  2. Параметр 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