diff options
Diffstat (limited to 'doc/user/packages/dependency_proxy/index.md')
| -rw-r--r-- | doc/user/packages/dependency_proxy/index.md | 109 |
1 files changed, 23 insertions, 86 deletions
diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 5e5aadfae2b..fd75df513c7 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -7,9 +7,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Proxy > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 13.6. -> - [Support for private groups](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. -> - Anonymous access to images in public groups is no longer available starting in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 13.6. +> - [Support for private groups](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Free](https://about.gitlab.com/pricing/) 13.7. +> - Anonymous access to images in public groups is no longer available starting in [GitLab Free](https://about.gitlab.com/pricing/) 13.7. +> - [Support for pull-by-digest and Docker version 20.x](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) in [GitLab Free](https://about.gitlab.com/pricing/) 13.9. The GitLab Dependency Proxy is a local proxy you can use for your frequently-accessed upstream images. @@ -17,11 +18,6 @@ upstream images. In the case of CI/CD, the Dependency Proxy receives a request and returns the upstream image from a registry, acting as a pull-through cache. -NOTE: -The Dependency Proxy is not compatible with Docker version 20.x and later. -If you are using the Dependency Proxy, Docker version 19.x.x is recommended until -[issue #290944](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) is resolved. - ## Prerequisites The Dependency Proxy must be [enabled by an administrator](../../../administration/packages/dependency_proxy.md). @@ -60,11 +56,11 @@ Prerequisites: ### Authenticate with the Dependency Proxy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Free](https://about.gitlab.com/pricing/) 13.7. > - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. > - It's enabled on GitLab.com. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](../../../administration/packages/dependency_proxy.md#disabling-authentication). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](../../../administration/packages/dependency_proxy.md#disabling-authentication). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -91,33 +87,29 @@ You can authenticate using: #### Authenticate within CI/CD -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280582) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280582) in GitLab 13.7. +> - Automatic runner authentication [added](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27302) in GitLab 13.9. -To work with the Dependency Proxy in [GitLab CI/CD](../../../ci/README.md), you can use: +Runners log in to the Dependency Proxy automatically. To pull through +the Dependency Proxy, use the `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` +environment variable: + +```yaml +# .gitlab-ci.yml +image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:latest +``` + +There are other additional predefined environment variables you can also use: - `CI_DEPENDENCY_PROXY_USER`: A CI user for logging in to the Dependency Proxy. - `CI_DEPENDENCY_PROXY_PASSWORD`: A CI password for logging in to the Dependency Proxy. - `CI_DEPENDENCY_PROXY_SERVER`: The server for logging in to the Dependency Proxy. - `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`: The image prefix for pulling images through the Dependency Proxy. -This script shows how to use these variables to log in and pull an image from the Dependency Proxy: - -```yaml -# .gitlab-ci.yml - -dependency-proxy-pull-master: - # Official docker image. - image: docker:latest - stage: build - services: - - docker:dind - before_script: - - docker login -u "$CI_DEPENDENCY_PROXY_USER" -p "$CI_DEPENDENCY_PROXY_PASSWORD" "$CI_DEPENDENCY_PROXY_SERVER" - script: - - docker pull "$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX"/alpine:latest -``` - -`CI_DEPENDENCY_PROXY_SERVER` and `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` include the server port. So if you use `CI_DEPENDENCY_PROXY_SERVER` to log in, for example, you must explicitly include the port in your pull command and vice-versa: +`CI_DEPENDENCY_PROXY_SERVER` and `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` +include the server port. If you explicitly include the Dependency Proxy +path, the port must be included, unless you have logged into the Dependency +Proxy manually without including the port: ```shell docker pull gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:latest @@ -125,61 +117,6 @@ docker pull gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:l You can also use [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) to store and access your personal access token or other valid credentials. -##### Authenticate with `DOCKER_AUTH_CONFIG` - -You can use the Dependency Proxy to pull your base image. - -1. [Create a `DOCKER_AUTH_CONFIG` environment variable](../../../ci/docker/using_docker_images.md#define-an-image-from-a-private-container-registry). -1. Get credentials that allow you to log into the Dependency Proxy. -1. Generate the version of these credentials that will be used by Docker: - - ```shell - # The use of "-n" - prevents encoding a newline in the password. - echo -n "my_username:my_password" | base64 - - # Example output to copy - bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= - ``` - - This can also be a [personal access token](../../../user/profile/personal_access_tokens.md) such as: - - ```shell - echo -n "my_username:personal_access_token" | base64 - ``` - -1. Create a [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) -named `DOCKER_AUTH_CONFIG` with a value of: - - ```json - { - "auths": { - "https://gitlab.example.com": { - "auth": "(Base64 content from above)" - } - } - } - ``` - - To use `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` when referencing images, you must explicitly include the port in your `DOCKER_AUTH_CONFIG` value: - - ```json - { - "auths": { - "https://gitlab.example.com:443": { - "auth": "(Base64 content from above)" - } - } - } - ``` - -1. Now reference the Dependency Proxy in your base image: - - ```yaml - # .gitlab-ci.yml - image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:latest - ... - ``` - ### Store a Docker image in Dependency Proxy cache To store a Docker image in Dependency Proxy storage: @@ -221,7 +158,7 @@ the [Dependency Proxy API](../../../api/dependency_proxy.md). ## Docker Hub rate limits and the Dependency Proxy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in [GitLab Free](https://about.gitlab.com/pricing/) 13.7. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch how to [use the Dependency Proxy to help avoid Docker Hub rate limits](https://youtu.be/Nc4nUo7Pq08). |