Valkey — 一个 Aggregate,两个目标,可选身份验证
这个精简示例从一个由 Developer 编写的 Aggregate 编译出单个 Valkey 内存缓存(Redis 线路协议),并生成两种实现:
- 用于本地开发的 Docker Compose,以及
- 合成的 helm Recipe,直接在 Kubernetes 上运行官方上游
valkey/valkey镜像(无外部 chart)。
合成的 helm Recipe 是 Kubernetes 路径:它只依赖官方镜像标签, 而非第三方 chart,其渲染出的资源 集合与 workload 声明的内容完全一致。
同一个 aggregate.yaml 驱动两者。每种实现只改变由 Manifest 选定的 Recipe 层。另外两个 Aggregates 展示了附加可选密码凭据的同一缓存:aggregate-auth.yaml 用于 Compose 路径(服务器以之启动的 inject-value 凭据),aggregate-helm-synth-auth.yaml 用于合成的 helm 路径(被具体化为 Kubernetes Secret 的可引用凭据)。
文件
| 文件 | 角色 |
|---|---|
aggregate.yaml | Developer 意图:一个类型为 core/datastore/valkey 的 cache 组件,无凭据——缓存在无身份验证的情况下运行。 |
aggregate-auth.yaml | 同一缓存,其密码凭据附加到组件的可选 password 槽位(Compose 路径)。 |
aggregate-helm-synth-auth.yaml | 同一缓存,为合成的 helm 路径附加了可引用凭据——其值被具体化为 Deployment 所引用的 Kubernetes Secret。 |
manifest-compose.yaml | 将 Valkey 类型映射到 Compose Recipe(compose/valkey),并将凭据映射到 dotenv-secret。 |
manifest-helm-synth.yaml | 将 Valkey 类型映射到合成的 helm Recipe(helm/valkey),并将凭据映射到 k8s-secret-from-parameter。 |
release-compose.yaml / release-helm-synth.yaml | 两种实现的运维记录,无身份验证。 |
release-compose-auth.yaml / release-helm-synth-auth.yaml | 启用身份验证的运维记录。 |
演示内容
- 一个编写界面,多个目标。 单个 Aggregate 是栈是什么的 唯一事实来源。每个 Manifest 说明如何实现它。
- 缓存角色的数据存储。 此处 Valkey 用作内存缓存,
不持久存储任何内容,因此组件的类型是普通的
server,而非stateful-server。在 Kubernetes 上,合成的 helm Recipe 渲染一个 Deployment,而非 StatefulSet,且不申请持久卷;在 Compose 上,服务不声明数据卷。 - Workload 合成(Kubernetes)。 合成的 helm Recipe 声明一个
Workload——一个 Deployment 加一个 ClusterIP Service,运行官方
valkey/valkey镜像——由 helm provider 将其转换为 Kubernetes 清单,无需外部 chart。渲染出的资源集合与 Workload 声明的内容完全一致。由于 Compose Recipe 和合成的 helm Recipe 都名为valkey,Manifests 以 provider 作用域方式将它们引用为compose/valkey和helm/valkey。 - 通过凭据槽位实现可选身份验证。 组件在其
featuresSchema中声明一个可选的password槽位。未附加凭据时(基础 Aggregate),Recipe 渲染的缓存禁用身份验证——与没有槽位的 Recipe 逐字节相同。附加凭据时,两个目标都以--requirepass启动 Valkey,因此服务器要求密码:在 Compose 上,该值通过镜像的VALKEY_EXTRA_FLAGS变量到达服务器;在 Kubernetes 上,合成的 helm 路径将其具体化为 Deployment 所引用的 Secret。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example valkey-cache然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd valkey-cache构建
此工作区不带 .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 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `valkey-cache` 文件夹,请调用一次 `scaffold` 工具,将 `example` 设为 `valkey-cache`,且不设 `dir`:它会把示例写入新的 `valkey-cache` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-compose.yaml`、`release-helm-synth.yaml`、`release-compose-auth.yaml` 和 `release-helm-synth-auth.yaml`——每次都将 `workspace_root` 设为 `valkey-cache`,`release` 设为该文件,`auto_pull` 设为 true,`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `valkey-cache/dist/` 下。凭据传递说明
在 Compose 路径上,凭据是一个注入值型 secret(aggregate-auth.yaml):其值通过组件的环境管道,以其 values.key 指定的变量 VALKEY_PASSWORD 传递,Recipe 再通过镜像的 VALKEY_EXTRA_FLAGS 变量将其作为 --requirepass 交给服务器,因此它出现在服务的环境中,而不出现在其命令行上。镜像的启动脚本会不加引号地展开该变量,因此含空格的密码会使服务器在启动时停止,而含 *、? 或 [ 的密码会与服务器数据目录中的文件名进行匹配,所以编写密码时请两者都避免。如果密码附加项的值没有以 Recipe 读取的任何变量到达 Recipe,构建会中止并指出该槽位,而不是渲染出不受保护的缓存。
合成的 helm 路径使用可引用凭据
(aggregate-helm-synth-auth.yaml):其值被具体化为 Kubernetes
Secret,Deployment 通过 env secretKeyRef 引用它,Valkey 以
读取该环境变量的 --requirepass 启动。因此明文
密码从不出现在 Deployment 清单中——只出现在
Secret 中。正是这一点在官方
valkey/valkey 镜像上真正启用了身份验证,因为该镜像本身不会
从环境中读取密码。
带身份验证的 Aggregates 中的 origin 值是开发用占位符;
任何真实部署都应通过你的凭据源提供真实值。