There are several types of commands that are working with the Docker registries and require the appropriate authorization:
- During the building process, werf may pull base images from the Docker registry and pull/push stages in distributed builds.
- During the cleaning process, werf deletes images and stages from the Docker registry.
- During the deploying process, werf requires access to the images from the Docker registry and to the stages that could also be stored in the Docker registry.
NOTE You should specify your implementation by --repo-implementation
CLI option.
Supported implementations
Build | Cleanup | |
---|---|---|
AWS ECR | ok | ok (with native API) |
Azure CR | ok | ok (with native API) |
Default | ok | ok |
Docker Hub | ok | ok (with native API) |
GCR | ok | ok |
GitHub Packages | ok | ok (with native API and only in private GitHub repositories) |
GitLab Registry | ok | ok |
Harbor | ok | ok |
JFrog Artifactory | ok | ok |
Quay | ok | ok |
In the nearest future we will add support for Nexus Registry
The following implementations are fully supported and do not require additional actions except docker authorization:
- Default.
- GCR.
- GitLab Registry.
- Harbor.
Azure CR, AWS ECR, Docker Hub and GitHub Packages implementations provide Docker Registry API but do not implement the delete tag method and offer it with native API. Therefore, werf may require extra credentials for cleanup commands.
AWS ECR
Working with AWS ECR is not different from the rest implementations. The user can use both images repo modes but should manually create repositories before using werf.
werf deletes tags from AWS ECR with AWS SDK. Therefore, before using cleanup commands the user should:
- Set up AWS CLI installation (
aws configure
) or - Define
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
environment variables.
Azure CR
The user should do the next steps to enable tag deletion with werf:
- Install Azure CLI (
az
). - Sign in with relevant credentials (
az login
).
The user must have one of the following roles:
Owner
,Contributor
orAcrDelete
(more about Azure CR roles and permissions)
Docker Hub
To delete tags from Docker Hub repository werf uses Docker Hub API and requires extra user credentials.
The user should specify token or username and password. The following script can be used to get the 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)
Be aware that access to the resources is forbidden with a personal access token
To define credentials check options and related environments:
--repo-docker-hub-token
or--repo-docker-hub-username
and--repo-docker-hub-password
.
GitHub Packages
To delete versions of a private package we are using GraphQL and need GitHub token with read:packages
, write:packages
, delete:packages
and repo
scopes.
Be aware that GitHub only supports deleting in private repositories
To define credentials check --repo-github-token
option and related environment.
Docker Authorization
werf commands do not perform authorization and use the predefined docker config to work with the Docker registry.
Docker config is a directory with the authorization data for registries and other settings.
By default, werf uses the same docker config as the Docker utility: ~/.docker
.
The Docker config directory can be redefined by setting a --docker-config
option, $DOCKER_CONFIG
, or $WERF_DOCKER_CONFIG
environment variables.
The option and variables are the same as the docker --config
regular option.
To define the docker config, you can use login
— the regular directive of a Docker client, or, if you are using a CI system, ci-env command in werf (learn more about how to plug werf into CI systems).
In the case of several CI jobs running simultaneously, executing
docker login
can lead to failed jobs because of a race condition and conflicting temporary credentials. One job affects another job by overriding temporary credentials in the Docker config. Therefore, the user should provide an individual Docker config for each job via thedocker --config
or by using theci-env
command instead