跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

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.yamlDeveloper 意图:一个类型为 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 助手替你构建。

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example valkey-cache

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd valkey-cache

构建

此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志;--auto-pull 会在构建期间写入新克隆所缺少的锁文件:

Terminal window
# Local development (Docker Compose), no authentication
aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized helm Recipe, official image), no authentication
aggrega build --release release-helm-synth.yaml --auto-pull
# The same realizations with authentication enabled
aggrega build --release release-compose-auth.yaml --auto-pull
aggrega 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 值是开发用占位符; 任何真实部署都应通过你的凭据源提供真实值。