Supported registry implementations

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

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 and AWS_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 or AcrDelete (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 the docker --config or by using the ci-env command instead