NATS — один Aggregate, две целевые платформы, необязательная аутентификация
Этот пример компилирует один сервер обмена сообщениями NATS (pub-sub, request-reply, очереди) из одного Aggregate, написанного разработчиком, в две реализации:
- Docker Compose для локальной разработки и
- синтезированный helm Recipe, запускающий официальный образ
natsнепосредственно в Kubernetes (без внешнего чарта).
Синтезированный helm Recipe — предпочтительный путь для Kubernetes: он зависит только от тега официального образа, а не от стороннего чарта, и его набор отрендеренных ресурсов в точности соответствует тому, что объявляет рабочая нагрузка.
Один и тот же aggregate.yaml управляет обеими. Для каждой реализации меняется только слой Recipe,
выбранный в Manifest. Второй Aggregate, aggregate-auth.yaml,
показывает тот же сервер с подключёнными учётными данными-паролем типа inject-value для
пути Compose; aggregate-helm-synth-auth.yaml подключает ссылочные
учётные данные для пути синтезированного helm.
Файлы
| Файл | Роль |
|---|---|
aggregate.yaml | Намерение разработчика: один компонент bus типа core/messaging/nats, без учётных данных — сервер работает без аутентификации. |
aggregate-auth.yaml | Тот же сервер с учётными данными-паролем типа inject-value, подключёнными к необязательному слоту password компонента (путь Compose). |
aggregate-helm-synth-auth.yaml | Тот же сервер со ссылочными учётными данными, подключёнными для пути синтезированного helm, — значение материализуется как Kubernetes Secret, на который ссылается Deployment. |
manifest-compose.yaml | Сопоставляет тип NATS с Recipe для Compose (compose/nats), а учётные данные — с dotenv-secret. |
manifest-helm-synth.yaml | Сопоставляет тип NATS с синтезированным helm Recipe (helm/nats), а учётные данные — с k8s-secret-from-parameter. |
release-compose.yaml / release-helm-synth.yaml | Записи оператора для двух реализаций, без аутентификации. |
release-compose-auth.yaml / release-helm-synth-auth.yaml | Записи оператора, включающие аутентификацию. |
Что демонстрирует пример
- Одна поверхность описания, много целевых платформ. Единственный Aggregate — источник истины о том, что представляет собой стек. Каждый Manifest описывает, как его реализовать.
- Сервер обмена сообщениями без состояния. В этой минимальной конфигурации NATS маршрутизирует субъекты в
памяти с отключённым файловым хранилищем JetStream, поэтому компонент имеет тип
server. В Kubernetes синтезированный Recipe рендерит Deployment с одной репликой без постоянного тома; сервис Compose открывает доступ к серверу для локальной разработки. - Синтез Workload (Kubernetes). Синтезированный helm Recipe объявляет
Workload — Deployment и ClusterIP Service, запускающие официальный образ
nats, — который helm provider транслирует в манифесты Kubernetes без внешнего чарта. Отрендеренный набор ресурсов в точности соответствует объявленному в Workload. Поскольку и Recipe для Compose, и синтезированный helm Recipe носят имяnats, сущности Manifests ссылаются на них с указанием провайдера:compose/natsиhelm/nats. - Необязательная аутентификация, детерминированная в любом случае. Аутентификация NATS по умолчанию отключена. Если учётные данные не подключены, ни одна реализация не включает аутентификацию, и результат рендеринга побайтно идентичен между запусками. Если учётные данные подключены, внедрённое значение включает аутентификацию по имени пользователя и паролю в обеих реализациях.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example nats-messagingЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd nats-messagingСборка
В этом рабочем пространстве нет .aggrega-config.yaml, поэтому сущности стандартной библиотеки разрешаются из реестра hub, hub.aggrega.ai, и флаг каталога не нужен; --auto-pull во время сборки записывает lock-файл, которого нет в свежем клоне:
# Local development (Docker Compose), no authenticationaggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized helm Recipe, official image), no authenticationaggrega build --release release-helm-synth.yaml --auto-pull
# The same realizations with authentication enabledaggrega build --release release-compose-auth.yaml --auto-pullaggrega build --release release-helm-synth-auth.yaml --auto-pullОтрендеренные артефакты помещаются в dist/.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочего пространства ещё нет папки `nats-messaging`, вызовите инструмент `scaffold` один раз, задав для `example` значение `nats-messaging`, без `dir`: он запишет пример в новую папку `nats-messaging`. Затем вызовите инструмент `build` один раз для каждого файла Release в таком порядке — `release-compose.yaml`, `release-helm-synth.yaml`, `release-compose-auth.yaml` и `release-helm-synth-auth.yaml` — каждый раз задавая для `workspace_root` значение `nats-messaging`, для `release` — этот файл, для `auto_pull` — true и для `write` — true. Сообщите, какие файлы записала каждая сборка; они находятся в `nats-messaging/dist/`.Примечание о передаче учётных данных
На пути Compose учётные данные — это секрет типа inject-value
(aggregate-auth.yaml): его значение передаётся через канал переменных окружения компонента,
а сервер запускается с флагами аутентификации по имени пользователя и паролю.
Путь синтезированного helm использует ссылочные учётные данные
(aggregate-helm-synth-auth.yaml): значение материализуется как Kubernetes
Secret, Deployment ссылается на него через env secretKeyRef, а
сервер запускается с флагами --user/--pass, читающими эту переменную
окружения. Поэтому пароль в открытом виде никогда не появляется в манифесте Deployment
— только в Secret.
Значение origin в сущностях Aggregates с аутентификацией — заглушка для разработки;
для любого реального развёртывания задайте настоящее значение через свой источник учётных данных.