doc/user/packages/virtual_registry/container/_index.md
{{< details >}}
{{< /details >}}
{{< history >}}
container_virtual_registries. Disabled by default.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.
The GitLab container virtual registry is a local proxy you can use to cache container images from upstream registries. It acts as a pull-through cache, storing frequently-accessed images locally to reduce bandwidth usage and improve build performance.
Before you can use the container virtual registry:
When using the container virtual registry, remember the following restrictions:
5 container virtual registries per top-level group.5 upstreams to a given container virtual registry.{{< history >}}
ui_for_container_virtual_registries.container_virtual_registries. Feature flag ui_for_container_virtual_registries removed.{{< /history >}}
Manage container virtual registries for your group.
You can also use the API.
To create a container virtual registry:
Manage upstream container registries in a virtual registry.
Create a container upstream registry to connect to the virtual registry.
Prerequisites:
To create a container upstream registry:
In the top bar, select Search or go to and find your group. This group must be at the top level.
Select Deploy > Virtual registry.
Under Registry types, select View registries.
Under the Registries tab, select a registry.
Select Add upstream. If the virtual registry has existing upstreams, from the dropdown list, select either:
Complete the fields.
Include both a username and password, or neither. If not set, a public (anonymous) request is used to access the upstream.
If you want to connect the upstream to Docker Hardened Images, use the following as the Upstream URL:
https://dhi.io
Artifact caching period defaults to 24 hours. Set to 0 to disable cache entry checks.
If you want to test the upstream connection before you create it, select Test upstream.
Select Create upstream.
For more information about cache validity settings, see Set the cache validity period.
The container virtual registry stores and associates container images in a registry associated with your top-level group. To access container images, you must authenticate with your group's container virtual registry.
To authenticate manually, run the following command:
echo "$CONTAINER_REGISTRY_PASSWORD" | docker login gitlab.example.com/virtual_registries/container/1 --username <your_username> --password-stdin
Or, configure authentication with any of the methods described in Authenticate to the virtual registry.
The container virtual registry follows the Docker v2 token authentication flow:
To pull a container image through the virtual registry:
Authenticate with the virtual registry.
Use the virtual registry URL format to pull images:
gitlab.example.com/virtual_registries/container/<registry_id>/<image_path>:<tag>
For example:
Pull an image by its tag:
docker pull gitlab.example.com/virtual_registries/container/1/library/alpine:latest
Pull an image by digest:
docker pull gitlab.example.com/virtual_registries/container/1/library/alpine@sha256:c9375e662992791e3f39e919b26f510e5254b42792519c180aad254e6b38f4dc
Pull an image in a Dockerfile:
FROM gitlab.example.com/virtual_registries/container/1/library/alpine:latest
Pull an image in a .gitlab-ci.yml file:
image: gitlab.example.com/virtual_registries/container/1/library/alpine:latest
When you pull an image, the virtual registry:
cache_validity_hours setting, the image is served from the cache.An image tag like alpine:latest always pulls the most recent version of the image. The new version contains an updated image manifest. The container virtual registry does not pull a new image when the manifest changes.
Instead, the container virtual registry:
cache_validity_hours setting in the upstream to determine when an image manifest is invalid.For example, if your pipeline pulls node:latest and you've set the cache_validity_period to 24 hours, the virtual registry caches the image and updates it either when the cache expires or node:latest changes in the upstream.
HTTP Basic: Access DeniedIf you receive an HTTP Basic: Access denied error when authenticating against the virtual registry,
refer to two-factor authentication troubleshooting.
If a service alias is not set, the docker:20.10.16 image is unable to find the
dind service, and an error like the following is thrown:
error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host
To resolve this error, set a service alias for the Docker service:
services:
- name: docker:20.10.16-dind
alias: docker
GitLab Runner authenticates automatically using the CI/CD job token. However, the underlying Docker engine is still subject to its authorization resolving process.
Misconfigurations in the authentication mechanism may cause HTTP Basic: Access denied and 403: Access forbidden errors.
You can use the job logs to view the authentication mechanism used to authenticate against the virtual registry:
Authenticating with credentials from $DOCKER_AUTH_CONFIG
Authenticating with credentials from /root/.docker/config.json
Authenticating with credentials from job payload (GitLab Registry)
Make sure you are using the expected authentication mechanism.
Not Found or 404 error when pulling imageErrors like these might indicate that:
Example error messages:
ERROR: gitlab.example.com/virtual_registries/container/1/library/alpine:latest: not found
ERROR: Job failed: failed to pull image "gitlab.example.com/virtual_registries/container/1/library/alpine:latest" with specified policies [always]:
Error response from daemon: error parsing HTTP 404 response body: unexpected end of JSON input: "" (manager.go:237:1s)
To resolve these errors: