Dependency Proxy в GitLab: настройка и эксплуатация

Быстрые ссылки

• Включение Dependency Proxy

• Использование Dependency Proxy

• Как работает Dependency Proxy

• Настройка параметров хранилища

• Освобождение места

• Заключение

Что такое Dependency Proxy — коротко

Dependency Proxy — это встроенный в GitLab прокси-реестр, который кэширует образы Docker из Docker Hub и предоставляет их вашим CI-пайплайнам и разработчикам через локальный URL GitLab. Раньше это была платная функция; с релиза GitLab 13.6 (ноябрь 2020) она стала доступна во всех версиях.

Определение: pull-through cache — прокси, который при отсутствии локальной копии загружает артефакт с внешнего реестра, сохраняет его и отдаёт клиенту.

Преимущества:

• Ускоряет сборки и уменьшает задержки.
• Снижает частоту скачиваний из Docker Hub и помогает не превышать лимиты.
• Позволяет продолжать сборки из кеша при временных проблемах с Docker Hub.

Включение Dependency Proxy

Важно: переключение доступности Dependency Proxy контролируется на уровне инстанса. Включение требует перезапуска конфигурации GitLab и повлечёт краткий простой сервиса.

1. Откройте файл конфигурации Omnibus: /etc/gitlab/gitlab.rb.

2. Добавьте строку:

gitlab_rails["dependency_proxy_enabled"] = true

3. Сохраните файл и выполните в терминале:

sudo gitlab-ctl reconfigure

Примечание для установок из исходников: в случае source-инсталляции опция включается в config/gitlab.yml — секция dependency_proxy.

Важно

• Перенастройка остановит сервисы на короткое время. Планируйте окно техобслуживания.
• Если GitLab запущен в кластере или управляемой среде, синхронизируйте смену конфигурации с командой SRE.

Как использовать Dependency Proxy в CI и вручную

Dependency Proxy работает только на уровне групп GitLab. Он не доступен для отдельных личных проектов вне группы.

Обычно прокси используется внутри CI-скриптов. Когда нужно ссылаться на образ Docker в пайплайне, добавьте префикс CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX перед именем образа. Эта переменная автоматически разворачивается в URL Dependency Proxy вашей активной группы.

image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/nodejs:latest

При выполнении пайплайна образ будет подтянут через Dependency Proxy. Если образ уже закеширован, GitLab отдаст локальную копию и не будет обращаться к Docker Hub, если upstream-образ не изменился.

Вручную (вне GitLab CI) вы тоже можете использовать прокси. Сначала авторизуйтесь через docker login, используя имя пользователя GitLab и пароль либо PAT (personal access token) с правами api и/или registry:

docker login gitlab.example.com --username username --password password

После успешной авторизации можно выполнить docker pull. Пример (замените example-group на имя вашей группы):

docker pull gitlab.example.com/example-group/dependency_proxy/containers/nodejs:latest

Отличие от Container Registry: Dependency Proxy использует тот же хостнейм, что и веб-интерфейс GitLab. Container Registry обычно доступен на отдельном поддомене, например registry.example.com.

Как работает Dependency Proxy — детально

Dependency Proxy представляет себя как Docker Registry. Клиент делает docker login и docker pull как обычно.

1. Если образ уже закеширован — прокси отдаёт его сразу.
2. Если нет — прокси обращается к Docker Hub, скачивает образ, помещает в кеш и возвращает клиенту.

GitLab при каждом docker pull проверяет свежесть кеша, выполняя запросы HEAD/manifest к Docker Hub. Такие запросы бесплатны и служат для сравнения версий. Если Docker Hub указывает, что образ устарел, GitLab подтянет новую версию — это уже будет учитываться в лимитах Docker Hub.

Следствие

• Повторные pulls в CI можно выполнять безопасно: большинство вызовов будут обслуживаться из кеша и не увеличат счётчик ограничений Docker Hub.
• При реальных изменениях upstream-образа прокси обновляет кеш и вернёт свежую версию.

Когда это особенно полезно

• Для команд с большим количеством ежедневных пайплайнов.
• Для сред с нестабильным внешним доступом к Docker Hub.

Настройка хранения кэша

Кеш Dependency Proxy может занимать значительный объём диска, особенно если вы подтягиваете большие образы. GitLab позволяет изменить путь хранения и использовать объектное хранилище.

Omnibus: изменение локального пути хранения в /etc/gitlab/gitlab.rb:

gitlab_rails["dependency_proxy_storage_path"] = "/mnt/my-storage-drive"

Source: укажите storage_path в секции dependency_proxy файла config/gitlab.yml.

Пример включения object storage (Omnibus) — сохранение артефактов в S3-подобное хранилище:

gitlab_rails["dependency_proxy_object_store_enabled"] = true

gitlab_rails[“dependency_proxy_object_store_remote_directory”] = “gitlab-dependency-proxy”

gitlab_rails[“dependency_proxy_object_store_connection”] = {

“provider” => “AWS”,

“region” => “eu-west-1”,

“aws_access_key_id” => “AWS_ACCESS_KEY_ID”,

“aws_secret_access_key” => “AWS_SECRET_ACCESS_KEY”

}

GitLab кэширует образы локально для повышения производительности и затем фоновой задачей загружает их в S3. Если вы хотите, чтобы загрузка шла напрямую в объектное хранилище, включите прямую загрузку:

gitlab_rails["dependency_proxy_object_store_direct_upload"] = true

После изменения настроек хранилища выполните sudo gitlab-ctl reconfigure.

Рекомендации по дисковой подсистеме

• Для локального кеша используйте быстрые SSD, если образы часто читаются.
• Если выбран объектный сторедж, учитывайте задержку при первом чтении образа до загрузки в кеш.
• Настройте мониторинг места на диске и алерты, чтобы избежать переполнения.

Освобождение места и управление кешем

GitLab не удаляет автоматически кеш Dependency Proxy. В UI группы вы можете просмотреть содержимое кеша и общий размер, но кнопки очистки отдельных бинарных blob нет.

Очистка кеша выполняется через API. Шаги:

1. Создайте Personal Access Token: профиль → Access Tokens. Дайте токену scope api.

2. Узнайте Group ID: откройте домашнюю страницу группы — ID отображается рядом с именем.

3. Выполните DELETE-запрос API для очистки кеша группы:

curl --request DELETE --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/groups//dependency_proxy/cache

Важно

• Команда удалит весь кеш для указанной группы. Откат невозможен.
• Планируйте очистку в низконагруженное время, если команды активно работают с образами.

Критерии приёмки

• Dependency Proxy включён на инстансе и подтверждён через gitlab-ctl status.
• CI-пайплайн использует ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX} и успешно подтягивает образы.
• При попытке pull образа он сначала появляется в UI группы и занимает место в кеше.
• Очистка кеша через API удаляет содержимое и возвращает место на диске.
• Логи не содержат критических ошибок при обращении к Docker Hub.

Проверка и отладка — шаги

1. Убедитесь, что вы успешно выполнили sudo gitlab-ctl reconfigure после изменений.
2. Проверьте логи GitLab и gitlab-rails/production.log на предмет ошибок dependency proxy.
3. Выполните docker login gitlab.example.com и затем docker pull конкретного образа, чтобы просмотреть HTTP-ответы.
4. Проверьте наличие объекта в UI группы (Packages & Registries → Dependency Proxy).
5. Если образ не кэшируется, проверьте права группы и переменные окружения CI.

Когда Dependency Proxy не решит проблему (контрпримеры)

• Если ограничение Docker Hub связано с аутентификацией конкретного пользователя (rate limit per IP и пр.), прокси поможет лишь косвенно. Он уменьшит обращения, но первичный трафик на обновление образов всё равно идёт к Docker Hub.
• Если вы используете частные реестры, которые требуют собственного логина и авторизации, Dependency Proxy не заменит их полностью.
• Для артефактов, отличных от Docker (например, npm-пакеты), Dependency Proxy не применим — используйте специализированные кеши/зеркала.

Альтернативы и дополнения

• Локальные mirror-реестры, такие как Sonatype Nexus или Harbor, дают более широкий контроль над репозиториями и политиками хранения.
• Использование приватного Docker Registry (Docker Distribution) под вашу команду — даёт полный контроль, но требует администрирования и репликации.
• Для пакетов (npm, Maven, PyPI) используйте artefact registry или proxy-репозитории в Nexus/Artifactory.

Роль‑ориентированные чек‑листы

Администратор GitLab:

• Включить dependency proxy в конфигурации инстанса.
• Обновить конфигурацию и перезапустить сервис.
• Настроить storage path или object storage.
• Настроить мониторинг диска и алерты.

DevOps/Инженер SRE:

• Проверить доступность proxy из CI-раннеров.
• Настроить прямую/фоновые загрузки в object storage по потребностям.
• Автоматизировать периодические проверки размеров кеша.

Разработчик:

• Использовать ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX} в pipeline.
• Логиниться в прокси при локальной работе с образами.
• Документировать используемые образы и версии.

Инженер безопасности:

• Проверить, какие образы попадают в кеш.
• Настроить сканирование уязвимостей построенных/кешированных образов.
• Контролировать доступ к API для удаления кеша.

Мини‑методология внедрения (шаги для команды)

1. Оцените текущие обращения к Docker Hub и потребности в хранении образов.
2. Решите, где хранить кеш: локальный диск или объектный сторедж.
3. Включите Dependency Proxy в тестовом окружении и проверьте поведение CI.
4. Мониторьте использование места и логи в течение 1–2 недель.
5. Разверните в production и оповестите команду о новой переменной CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX.
6. Настройте регулярную процедуру очистки и резервирования при необходимости.

Безопасность и соответствие требованиям приватности

• Access tokens: выдавайте PAT минимально необходимых прав. Для очистки кеша требуется scope api.
• Доступ к объектному хранилищу должен быть ограничен ролями и ключами с минимальными правами.
• Если в образах есть чувствительные данные, рассмотрите политику удаления и ограничения публики этих образов.

Юридические/конфиденциальные соображения

• Сторонние образы могут иметь лицензии и зависимости, которые нужно учитывать. Кеширование не освобождает от требований лицензирования.

Типичные сценарии проблем и способы исправления

Проблема: После включения прокси пайплайн всё ещё обращается к Docker Hub часто.

• Проверьте, используется ли в pipeline префикс ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}.
• Убедитесь, что runners используют ту же группу и аутентификацию.

Проблема: Образы не отображаются в UI группы.

• Проверьте логи GitLab, есть ли ошибки при записи в storage.
• Убедитесь, что object storage правильно настроен и доступны права на запись.

Проблема: Очистка кеша через API возвращает ошибку авторизации.

• Проверьте, что PAT имеет scope api.
• Убедитесь, что URL и Group ID указаны верно.

Шаблон SOP: включение и проверка Dependency Proxy

1. Создать тикет на изменения конфигурации с указанием окна обслуживания.
2. Сделать бэкап текущего файла /etc/gitlab/gitlab.rb.
3. Внести изменение: gitlab_rails["dependency_proxy_enabled"] = true.
4. Выполнить sudo gitlab-ctl reconfigure.
5. Проверить статус сервисов: sudo gitlab-ctl status.
6. Запустить тестовый CI-пайплайн с image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/alpine:latest.
7. Подтвердить, что образ отдался из кеша (проверить UI группы и логи).
8. Документировать изменения и оповестить команду.

Краткая сводка (Summary)

• Dependency Proxy кэширует образы Docker из Docker Hub и ускоряет CI.
• Включение требует изменения конфигурации инстанса и перезапуска (reconfigure).
• Хранение кеша можно настроить локально или в объектном сторедже (S3).
• Очистка кеша выполняется через API; UI не предоставляет кнопку удаления.

Заключение

Dependency Proxy — простой и эффективный инструмент для команд, которые активно используют образы Docker в CI. Он уменьшает зависимость от Docker Hub, ускоряет сборки и помогает избежать превышения лимитов. Планируйте включение с учётом окна обслуживания, настройте надежное хранение и процедуры очистки, и вы получите более устойчивую и предсказуемую CI-инфраструктуру.