Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Стек Harbor — реестр контейнеров, развёртываемый как один релиз

Этот пример компилирует настоящий реестр контейнеров в манифесты Kubernetes из одной сущности Aggregate, написанной разработчиком.

Реестр контейнеров — это множество взаимодействующих сервисов: плоскость управления из API и сервиса токенов, хранилище блобов OCI и его контроллер, веб-консоль, уровень асинхронных обработчиков, сканер уязвимостей, реляционная база данных, кэш «ключ — значение» и обратный прокси перед ними. Каталог описывает всё это как один Component, потому что сами мейнтейнеры реестра публикуют Helm-чарт, который развёртывает его целиком как единый релиз в том порядке, который нужен его сервисам. Component объявляет реестр; Recipe оборачивает этот чарт.

Реестр импортируется как модуль: повторно используемый подагрегат, который компонует Component и экспортирует его опубликованный адрес. Aggregate верхнего уровня импортирует модуль по имени и передаёт ему три ключа реестра; оператор задаёт размеры компонента модуля в Release.

Файлы

ФайлРоль
aggregate.yamlНамерение разработчика: импортирует модуль реестра контейнеров (core/harbor) и передаёт ему три ключа реестра из собственных параметров.
manifest-helm-synth.yamlСопоставляет тип компонента реестра с сущностью Recipe, которая оборачивает его Helm-чарт, а сущность Feature для учётных данных — с реализацией, читающей Secret, уже существующий в пространстве имён, — кроме пароля администратора, который привязывается по имени к реализации, создающей Secret из параметра модуля.
release-helm-synth.yamlЗапись оператора для целевой платформы Kubernetes. Называет объекты Secret, содержащие три ключа, которые передаёт вниз сущность Aggregate, задаёт размеры компонента модуля по его ID в области видимости модуля и подключает к нему ключ подписи токенов, общий секрет сервисов и ключ, которым шифруются хранимые учётные данные, называя содержащие их объекты Secret; всё остальное определяется значениями по умолчанию из схемы.

Что демонстрирует пример

  • Многосервисный продукт как один Component. Реестр становится одним Component, а не несколькими, не из-за своего размера, а из-за того, где поддерживается его связывание: маршрутизация обратного прокси, ключ сервиса токенов, по которому управляющий уровень проверяет каждый pull и push, параметры подключения к бэкенду и кешу, которые читает каждый сервис, разделение логических баз данных, разводящее пространства ключей кеша сервисов, и порядок запуска — всё это согласуют с продуктом люди, которые его выпускают, внутри чарта. Потребитель объявляет реестр и получает всё это в согласованном виде.
  • Обёрнутый чарт. Recipe указывает чарт в source: и накладывает на него valuesMapping: — шаблон значений и есть вся реализация, а провайдер Helm отрисовывает собственные шаблоны чарта на его основе. Рабочая нагрузка здесь не синтезируется.
  • Закреплённый внешний вход. Чарт — это вход, который загружает сборка, поэтому он закрепляется, как любая зависимость: lock-файл записывает версию чарта, его разрешённый URL и дайджест архива в source_artifacts. Сборка с заполненным lock-файлом берёт чарт из хранилища содержимого и проверяет его по этому дайджесту.
  • Один опубликованный адрес для всей платформы. Обратный прокси чарта направляет путь браузера / в консоль, а пути реестра и API (/v2/, /api/, /service/, /c/) — в управляющий уровень, поэтому контейнерный клиент выполняет вход, push и pull на том же хосте, на котором браузер открывает консоль. Именно этот Service публикует provides.host, и потребителю не нужен второй адрес, чтобы обратиться к любому из наборов путей.
  • Два публичных имени для него. Модуль экспортирует этот единственный адрес как registry, конечную точку, с которой работают клиенты образов и API, и как ui, веб-точку. Оба имени разрешаются в адрес, обслуживающий оба набора путей, поэтому потребитель подключается к тому имени, которое описывает его намерение.
  • Задание размеров компонента модуля оператором. Release обращается к компоненту модуля по его идентификатору в области модуля (harbor.registry), чтобы задать вычислительные ресурсы, и Aggregate разработчика не приходится повторно указывать физические размеры.
  • Правила полноты для сгруппированного значения. infra.compute содержит ключ CPU и ключ памяти, и Recipe останавливает сборку на группе, в которой любой из них оставлен пустым. Управляющий уровень, отрисованный с лимитом CPU, но без лимита памяти, существенно отличается от описанного объявленными значениями по умолчанию сущности Component, и ничто в отрисованном выводе об этом не сообщит, — поэтому сборка останавливается и называет недостающий ключ. Ключ, опущенный в группе, получает значение по умолчанию сущности Component.
  • Шесть ключей без значения по умолчанию. Ключ, которым сервис токенов подписывает токены реестра, вместе с его сертификатом; три секрета, с помощью которых собственные сервисы реестра аутентифицируются друг перед другом и подписывают состояние загрузки; ключ защиты от подделки запросов; и ключ, которым управляющий уровень шифрует хранимые учётные данные, не имеют значения по умолчанию: ключ, известный каждому читателю каталога, позволил бы кому угодно выпускать токены, которым доверяет реестр, или читать то, что он хранит. Component объявляет эти слоты обязательными, поэтому сборка, оставившая один из них пустым, останавливается и называет слот. Сборка не читает и не отрисовывает ни одно из шести значений: каждая рабочая нагрузка читает каждое из Secret, который она указывает по имени.
  • Три ключа, которые подключает Release. Модуль не подключает ни ключ подписи токенов, ни общий секрет управляющего уровня, ни ключ, которым шифруются хранимые учётные данные, поэтому Release подключает все три к компоненту модуля: token_key, core_secret и secret_key, каждый через core/referenced-secret, где infra.origin указывает Secret, а Manifest связывает Feature с k8s-existing-secret. Управляющий уровень монтирует ключ подписи токенов и ключ шифрования из указанных для них Secret, а сервисы читают общий секрет из своего.
  • Учётные данные, которые заполняет модуль. Пароль учётной записи администратора, ключ защиты от межсайтовой подделки запросов, общий секрет уровня обработчиков и секрет состояния загрузки хранилища блобов — тоже слоты учётных данных в Component, и модуль заполняет каждый из собственного параметра (admin_password, csrf_key, jobservice_secret, registry_http_secret) через core/referenced-secret — Feature учётных данных, поэтому каждая рабочая нагрузка читает их из Secret по имени. Поскольку модуль подключает эту Feature, Manifest сопоставляет её. У трёх ключей нет значения по умолчанию и в модуле, поэтому Aggregate объявляет собственные параметры и передаёт их вниз через aggregates.harbor.parameters, Release заполняет их, а k8s-existing-secret читает каждый как имя Secret, уже существующего в пространстве имён; Release, не задавший значение, останавливает сборку с указанием параметра. В этом примере пароль администратора оставлен равным значению модуля по умолчанию для разработки, и Manifest связывает это единственное подключение по имени с k8s-secret-from-parameter, которая создаёт Secret, содержащий его. Остальные пароли записываются в конфигурацию, которую отрисовывает Release, поэтому их заменяют, задавая infra; если они не заданы, каждый принимает значение для разработки, указанное в Recipe.
  • Детерминированный вывод для чарта, который иначе генерировал бы материал. Предоставленный самому себе, этот чарт создаёт собственные секреты, если они не заданы: общий секрет и секрет подписи токенов управляющего уровня, секреты уровня обработчиков и хранилища блобов, ключ защиты от подделки запросов и хешированный пароль хранилища блобов, который он заново хеширует со свежей солью при каждой отрисовке. Вместо этого задаётся каждый из них: шесть ключей — всегда из Secret, указанных в Release, а пароли — из подключённых учётных данных по имени, если слот заполнен, и из фиксированного значения для разработки, если нет, поэтому две отрисовки идентичных входных данных дают побайтно идентичный результат.
  • Воспроизводимые образы. Каждый образ, запускаемый реестром, закреплён за явным тегом. Продукт выпускает их все с одним тегом, поэтому infra.engine_version выбирает их все сразу; infra.overrides.image заменяет закрепление одного сервиса, а infra.overrides.image_prefix переносит их все вместе для Release, загружающего образы из зеркала.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

Terminal window
aggrega scaffold --example harbor-stack

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd harbor-stack

Сборка

В этом рабочем пространстве нет .aggrega-config.yaml, поэтому сущности стандартной библиотеки разрешаются из реестра hub, hub.aggrega.ai, и флаг каталога не нужен. Recipe загружает чарт, поэтому сначала разрешите зависимости в lock-файл:

Terminal window
aggrega pull --release release-helm-synth.yaml
aggrega build --release release-helm-synth.yaml

Отрендеренные артефакты помещаются в dist/.

Перед их применением создайте шесть секретов Secret, которые называет Release, в пространстве имён, в которое развёртывается реестр: harbor-token-key с закрытым ключом RSA под ключом данных tls.key и сертификатом для этого ключа под tls.crt; harbor-core-secret с 16-символьным секретом под ключом данных secret; harbor-secret-key с 16-символьным ключом под secretKey; harbor-csrf-key с 32-символьным ключом под CSRF_KEY; а также harbor-jobservice-secret и harbor-registry-http-secret с 16-символьным секретом под JOBSERVICE_SECRET и REGISTRY_HTTP_SECRET соответственно. Например:

Terminal window
openssl req -x509 -newkey rsa:4096 -nodes -days 3650 -subj "/CN=harbor-token-ca" \
-keyout tls.key -out tls.crt
kubectl create secret tls harbor-token-key --key tls.key --cert tls.crt
kubectl create secret generic harbor-core-secret --from-literal=secret="$(openssl rand -hex 8)"
kubectl create secret generic harbor-secret-key --from-literal=secretKey="$(openssl rand -hex 8)"
kubectl create secret generic harbor-csrf-key --from-literal=CSRF_KEY="$(openssl rand -hex 16)"
kubectl create secret generic harbor-jobservice-secret --from-literal=JOBSERVICE_SECRET="$(openssl rand -hex 8)"
kubectl create secret generic harbor-registry-http-secret --from-literal=REGISTRY_HTTP_SECRET="$(openssl rand -hex 8)"

Реестр, сервисы которого не могут найти эти секреты Secret, не запускается.

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочей области ещё нет папки `harbor-stack`, вызовите инструмент `scaffold` один раз, задав `example` равным `harbor-stack` и не указывая `dir`: он запишет пример в новую папку `harbor-stack`. Затем вызовите инструмент `build`, задав `workspace_root` равным `harbor-stack`, `release` равным `release-helm-synth.yaml`, `auto_pull` равным true и `write` равным true. Сообщите мне, какие файлы записала сборка; они находятся в `harbor-stack/dist/`.

Как выглядит собранный реестр

Сборка выдаёт ресурсы, которые чарт определяет для этой конфигурации: Deployments для обратного прокси, консоли, плоскости управления, уровня обработчиков и хранилища блобов; StatefulSets для бэкенда, кэша и сканера; persistent volume claims для хранилища блобов и для журналов уровня обработчиков; ConfigMaps и Secrets, которые читает каждый сервис; и Services перед ними. Помимо них, сущность Feature для учётных данных выдаёт один Secret, harbor-zdregistry-admin-password, содержащий значение по умолчанию модуля для разработки для пароля администратора, которое плоскость управления читает из него, а не из собственного Secret чарта. Ни для одного из шести ключей Secret не выдаётся: плоскость управления монтирует ключ подписи токенов из harbor-token-key и ключ шифрования из harbor-secret-key, а сервисы читают остальные из harbor-core-secret, harbor-csrf-key, harbor-jobservice-secret и harbor-registry-http-secret — Secrets, которые называет сущность Release.

Ровно один из этих Services является адресом, к которому подключаются потребители, — dist/app/helm/harbor.registry-service-default-harbor-zdregistry.yaml:

apiVersion: v1
kind: Service
metadata:
name: harbor-zdregistry
[… omitted: the namespace, the chart's labels, and the labels and annotations every rendered document carries]
spec:
type: ClusterIP
ports:
- name: http
port: 80
targetPort: 8080
selector:
release: harbor-zdregistry
app: "harbor"
component: nginx

Его селектор указывает на обратный прокси, и именно это даёт реестру один адрес. port следует за infra.port; прокси за ним слушает порт, который фиксирует чарт, и Service перенаправляет на него, поэтому изменение infra.port меняет опубликованный адрес, а не слушающий порт.

Именование: параметр, публикующий адрес, — не тот параметр, который задаёт имена ресурсов

Этот чарт выводит большинство имён своих ресурсов из параметра имени верхнего уровня, а затем добавляет к ним суффиксы: сервис управляющего уровня называется <instance>-core, сервис консоли — <instance>-portal, сервис хранилища блобов — <instance>-registry, и так же для уровня обработчиков, сканера, бэкенда и кэша. Ничто не называется просто этим именем.

Публикуемый сервис именуется отдельным параметром, относящимся к публикации, значение которого по умолчанию — фиксированная строка, не зависящая от имени верхнего уровня. Recipe, закрепляющий только параметр верхнего уровня, опубликовал бы адрес, на который не отвечает ни один сервис, а два экземпляра в одном пространстве имён оба создали бы сервис с этим фиксированным именем, и возник бы конфликт. Поэтому Recipe задаёт оба параметра из ID экземпляра — именно поэтому созданный сервис выше назван по экземпляру и provides.host указывает на существующий адрес.

Это стоит внимательно изучить при оборачивании любого платформенного чарта: provides.host должен указывать на сервис, который чарт действительно создаёт, а то, какой параметр это определяет, — свойство конкретного чарта, а не соглашение, общее для всех чартов.

Что не входит в эту конфигурацию

Ingress чарта оставлен выключенным, а обратный прокси вместо этого открыт как внутрикластерный Service, потому что сущность Component публикует внутрикластерный адрес, а не внешнее имя хоста. Единая внешняя точка входа собирается на уровне ingress и направляет трафик на адрес, который экспортирует этот модуль. Защита транспорта выключена, потому что собственный источник сертификатов чарта генерирует центр сертификации и подписанный сертификат во время рендеринга, а два рендеринга одинаковых входных данных не воспроизвели бы их. Монитор Prometheus-operator выключен.

Метрики реестра тоже выключены. Параметр values.metrics_enabled сущности Component включает их для плоскости управления, уровня воркеров, хранилища блобов и добавленного экспортёра и публикует четыре Service, чтобы их мог обнаружить сборщик метрик; та же настройка чарта также открывает отладочный слушатель хранилища блобов — профилирование, трассировки выполнения и переменные среды выполнения без проверки вызывающей стороны — для любого вызывающего внутри кластера. Модуль оставляет это значение по умолчанию равным false, поэтому этот пример не рендерит метрик; сущность Aggregate, которая сама объявляет Component, может его задать. Образ экспортёра тем не менее закреплён вместе с остальными.