Модуль registry-packages-proxy

Модуль registry-packages-proxy предоставляет сервис HTTP-прокси внутри кластера для доступа к пакетам из хранилищ образов контейнеров (container registry). Он выступает в качестве посредника между компонентами кластера и внешними или внутренними хранилищами образов контейнеров с функциями кеширования для оптимизации использования пропускной способности сети и повышения производительности при загрузке пакетов.

Этот модуль — критически важный компонент инфраструктуры, который работает на master-узлах и используется во время загрузки кластера и операций в процессе работы кластера для извлечения пакетов из хранилищ образов контейнеров.

Модуль развёртывает высокодоступный прокси-сервис, который:

• Работает как deployment на master-узлах с включенным hostNetwork для обеспечения доступности во время загрузки, когда CNI ещё недоступен.
• Прослушивает порт 4219 (HTTPS) на IP-адресе каждого master-узла.
• Предоставляет эндпоинт /package для извлечения пакетов из хранилища образов контейнеров по дайджесту.
• Реализует локальное кеширование извлечённых пакетов (до 1 ГБ) для снижения сетевого трафика и улучшения производительности.
• Следит за кастомными ресурсами ModuleSource для получения учётных данных хранилищ образов контейнеров.
• Использует kube-rbac-proxy для защиты доступа к прокси и эндпоинтам метрик.
• Предоставляет публичный HTTPS API (через Ingress) для исполняемых файлов и плагинов Deckhouse CLI.
• Предоставляет внутрикластерный HTTPS API для иконок пакетов (без публикации через Ingress).

Архитектура

Прокси-сервис состоит из двух контейнеров:

1. registry-packages-proxy — основное приложение прокси, которое:
   • извлекает пакеты из удалённых хранилищ образов контейнеров с использованием дайджестов;
   • кеширует пакеты локально в эфемерном volume (максимум 1 ГБ);
   • поддерживает аутентификацию в хранилищах образов контейнеров через учётные данные из ресурсов ModuleSource;
   • предоставляет проверки работоспособности и метрики Prometheus;
   • прослушивает 127.0.0.1:5080 (HTTP, внутренний).
2. kube-rbac-proxy — обеспечивает контроль доступа на основе RBAC:
   • предоставляет сервис на порту 4219 (HTTPS);
   • защищает эндпоинт /metrics с авторизацией Kubernetes RBAC;
   • защищает эндпоинт /package, требуя соответствующих разрешений;
   • защищает /v1/images/* (загрузка Deckhouse CLI) с авторизацией Kubernetes RBAC;
   • позволяет доступ к /healthz без аутентификации.

HTTP API

После завершения развёртывания кластера (bootstrap) и настройки шаблона DNS-имен в параметре publicDomainTemplate, модуль создаёт Ingress для имени registry-packages-proxy, используя шаблон из publicDomainTemplate (например, registry-packages-proxy.company.my, для publicDomainTemplate: "%s.company.my").

Эндпоинты ниже доступны двумя способами:

• Публично (через Ingress на публичном имени registry-packages-proxy): только /v1/images/*.
• Только изнутри кластера (через Service registry-packages-proxy.d8-cloud-instance-manager.svc на порту 443, либо через :4219 на каждом master-узле в фазе bootstrap): все маршруты, включая /v1/packages/*.

Иконки пакетов (/v1/packages/) — только изнутри кластера

Иконки пакетов отдаются без аутентификации (kube-rbac-proxy исключает эти пути из RBAC), но доступны только изнутри кластера. Маршрут /v1/packages/* намеренно не публикуется через Ingress, поэтому публичное имя registry-packages-proxy.<publicDomain> иконки не отдаёт.

<РЕПОЗИТОРИЙ-ПАКЕТОВ> — это metadata.name кастомного ресурса PackageRepository; поле spec.registry.repo этого ресурса определяет, по какому пути в хранилище образов прокси читает иконку. Прокси читает иконку из OCI-образа <spec.registry.repo>/<ИМЯ-ПАКЕТА>:<ТЕГ>.

Прокси ищет внутри образа пакета следующие файлы в указанном порядке приоритета и возвращает первый найденный:

Если ни одного из этих файлов нет (или файл больше 4 МиБ), прокси возвращает 404 Not Found; вызывающий код должен использовать иконку по умолчанию. SVG предпочтительнее, так как не зависит от разрешения.

Пример запроса из пода внутри кластера:

curl -fsSk "https://registry-packages-proxy.d8-cloud-instance-manager.svc/v1/packages/my-repo/my-module/metadata/icon/"

Пример успешного ответа (когда в образе есть docs/icon.svg):

Content-Type: image/svg+xml
Content-Disposition: attachment; filename="<ИМЯ-ПАКЕТА>.svg"

Загрузка Deckhouse CLI (/v1/images/) — публичный

Эти эндпоинты доступны через публичный Ingress (registry-packages-proxy.<publicDomain>) и требуют действительный токен Kubernetes (или клиентский сертификат, принимаемый kube-rbac-proxy) и право RBAC get на subresource deployments/cli-binary с именем registry-packages-proxy в namespace d8-cloud-instance-manager.

Выдайте доступ через ClusterRole d8:registry-packages-proxy:cli-download (привяжите к пользователям или ServiceAccount через ClusterRoleBinding или RoleBinding).

Допустимые значения для <ОБРАЗ>:

• deckhouse-cli
• deckhouse-cli/plugins/<ПЛАГИН> (один сегмент пути для <ПЛАГИН>)

Пример:

curl -fsS -H "Authorization: Bearer ${TOKEN}" "https://registry-packages-proxy.example.com/v1/images/deckhouse-cli/tags"

Внутренний эндпоинт /package

Устаревший эндпоинт /package?digest=... (bootstrap и внутренние компоненты) по-прежнему защищён RBAC (subresource deployments/http). Через публичный Ingress не публикуется.

Поток извлечения пакетов

Когда компонент запрашивает пакет:

1. Запрос включает параметр digest (обязательный) и необязательные параметры repository и path.
2. Прокси проверяет локальный кеш на наличие запрошенного дайджеста.
3. Если запрашиваемый пакет есть в кеше, он извлекается из кеша.
4. Если запрашиваемый пакет отсутствует в кеше:
   • Прокси извлекает учётные данные для указанного хранилища образов из отслеживаемых ресурсов ModuleSource.
   • Пакет извлекается из удалённого хранилища образов.
   • Пакет передаётся клиенту с одновременным кешированием для будущих запросов.
5. Ответы включают соответствующие HTTP-заголовки для кеширования (Cache-Control, ETag, Content-Length).

Высокая доступность

Модуль обеспечивает высокую доступность через:

• Запуск нескольких реплик на master-узлах (в HA-конфигурациях).
• Правила anti-affinity для распределения подов по разным master-узлам.
• PodDisruptionBudget для предотвращения одновременного нарушения работы всех реплик.
• Поддержку Vertical Pod Autoscaler для автоматической настройки ресурсов.

Роли RBAC, создаваемые модулем

Ограничения

• Модуль работает исключительно на master-узлах.
• Требует hostNetwork: true для работы во время фазы загрузки.
• Размер кеша ограничен 1 ГБ на под.
• Большинство HTTP-эндпоинтов требуют RBAC Kubernetes; без аутентификации доступны только проверки работоспособности (health check) и иконки пакетов. Иконки пакетов дополнительно ограничены доступом только изнутри кластера (без маршрута через публичный Ingress).
• Иконки читаются из фиксированных путей внутри образа пакета (docs/icon.svg, docs/icon.png, docs/icon.jpg, docs/icon.jpeg); SVG предпочтительнее. Максимальный размер иконки — 4 МиБ.