Модуль 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/<ПЛАГИН> (один сегмент пути для <ПЛАГИН>)

Артефакты Deckhouse CLI могут находиться в одном из двух мест. Официальный реестр публикует их один раз для всех редакций: в корне реестра, на уровень выше репозитория редакции кластера. Реестр, заполненный командой d8 mirror push, хранит их прямо под репозиторием кластера, ровно так, как они были загружены.

Прокси берёт репозиторий из секрета d8-system/deckhouse-registry и пробует кандидатов по очереди: сначала репозиторий как есть, затем репозиторий без завершающего сегмента редакции (ce, be, se, se-plus, ee, fe). Ответивший корень запоминается и в дальнейшем проверяется первым; ошибка 404 на запомненном корне или смена репозитория в секрете запускает повторный поиск. Например, кластер с репозиторием registry.deckhouse.io/deckhouse/ee читает образы из registry.deckhouse.io/deckhouse/deckhouse-cli и registry.deckhouse.io/deckhouse/deckhouse-cli/plugins/<ПЛАГИН>, а кластер, зеркалированный в registry.local/dest/ee, читает их из registry.local/dest/ee/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 МиБ.