NATS — 一个 Aggregate,两个目标,可选身份验证
本示例将一个 NATS 消息服务器(发布-订阅、请求-应答、队列)从一个由开发者编写的 Aggregate 编译为两种实现:
- 用于本地开发的 Docker Compose,以及
- 合成的 helm Recipe,直接在 Kubernetes 上运行官方上游
nats镜像 (无外部 chart)。
合成的 helm Recipe 是首选的 Kubernetes 路径:它只依赖 官方镜像标签而非第三方 chart,其渲染出的资源 集合与 workload 声明的内容完全一致。
同一个 aggregate.yaml 驱动两者。每种实现只改变由
Manifest 选择的 Recipe 层。第二个 Aggregate aggregate-auth.yaml
展示了同一服务器,并为 Compose 路径附加了 inject-value 密码凭据;
aggregate-helm-synth-auth.yaml 则为合成的 helm 路径附加了可引用凭据。
文件
| 文件 | 角色 |
|---|---|
aggregate.yaml | 开发者意图:一个类型为 core/messaging/nats 的 bus 组件,无凭据——服务器在无身份验证的情况下运行。 |
aggregate-auth.yaml | 同一服务器,在组件可选的 password 槽位上附加了 inject-value 密码凭据(Compose 路径)。 |
aggregate-helm-synth-auth.yaml | 同一服务器,为合成的 helm 路径附加了可引用凭据——该值被物化为 Deployment 所引用的 Kubernetes Secret。 |
manifest-compose.yaml | 将 NATS 类型映射到 Compose Recipe(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 清单,无需 外部 chart。渲染出的资源集与 Workload 的声明完全一致。 由于 Compose Recipe 和合成的 helm Recipe 都使用名称nats,Manifests 以 provider 作用域的形式引用它们:compose/nats和helm/nats。 - 可选身份验证,两种情况均具确定性。 NATS 身份验证 默认关闭。未附加凭据时,两种实现都不启用 身份验证,且多次运行的渲染结果逐字节相同。附加凭据时, 注入的值会在两种实现上启用用户名/密码身份验证。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example nats-messaging然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd nats-messaging构建
此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志;--auto-pull 会在构建期间写入新克隆所缺少的锁文件:
# 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/ 下。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `nats-messaging` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `nats-messaging`,不设 `dir`:它会把示例写入一个新的 `nats-messaging` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`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 通过环境变量 secretKeyRef 引用它,
服务器以读取该环境变量的 --user/--pass 标志启动。
因此明文密码从不出现在 Deployment
清单中——只出现在 Secret 中。
带身份验证的 Aggregates 中的 origin 值是开发用占位符;
任何真实部署都应通过你的凭据源提供真实值。