MySQL — 一个 Aggregate,两个目标
这个精简示例将开发者编写的 Aggregate 中的单个 MySQL 数据库编译到两个目标:
- Kubernetes,通过 helm provider 的 Workload 合成(直接基于官方
mysql镜像渲染的 StatefulSet, 不使用外部 chart),以及 - 用于本地开发的 Docker Compose。
同一份开发者意图驱动每个目标。随目标变化的只有 Manifest 所选的 Recipe 层。
文件
| 文件 | 角色 |
|---|---|
aggregate-helm-synth.yaml | Kubernetes 基础变体的开发者意图:一个类型为 core/datastore/mysql 的 db component、其 values,以及仅必需的 root_password 凭据。 |
aggregate-helm-synth-auth.yaml | Kubernetes 完整变体的开发者意图:同时包含 root_password 和 user_password 两个凭据槽。 |
manifest-helm-synth.yaml | 将 MySQL 类型映射到合成的 helm Recipe(helm/mysql),并将每个凭据映射到其 FeatureRecipe(env-secret、k8s-secret-from-parameter)。 |
release-helm-synth.yaml | Kubernetes 基础变体的运维记录,包含运维规格配置(engine_version、storage)。 |
release-helm-synth-auth.yaml | Kubernetes 完整变体的运维记录。 |
aggregate.yaml | 本地 Compose 目标的开发者意图:同一个 db component,两个凭据槽均以 inject-value 凭据交付。 |
manifest-compose.yaml | 将 MySQL 类型映射到 Compose Recipe(mysql),并将凭据映射到 dotenv-secret。 |
release-compose.yaml | 本地 Compose 目标的运维记录,包含一个固定精确容器镜像的 provider 特定 infra.overrides 条目。 |
演示内容
- 一个编写界面,多个目标。 Aggregate 是技术栈是什么的 唯一事实来源。每个 Manifest 说明如何实现它。
- Kubernetes 上的 Workload 合成(首选)。
helm/mysqlRecipe 声明一个与能力无关的Workload,并设置form: stateful;helm provider 合成一个 StatefulSet、一个 ClusterIP Service、一个 Headless Service (StatefulSet 的稳定网络标识),以及一个用于数据目录的 volumeClaimTemplate。容器的环境包含MYSQL_DATABASE、MYSQL_USER、MYSQL_ROOT_PASSWORD和MYSQL_PASSWORD。字符集和 排序规则以mysqld服务器命令行参数 (--character-set-server、--collation-server)的形式生效,因为官方mysql镜像将它们作为服务器标志而非环境变量接收。 - Compose 上的 Workload 合成。 Compose Recipe 声明一个
与能力无关的
Workload;compose provider 合成一个docker-compose.yaml服务,包含 MySQL 镜像、其环境、一个具名 数据卷和一个健康检查。 - 运维逃生舱口。 Compose release 设置
infra.overrides.image, 这是用于 Component 自身 schema 未命名的 provider 特定事实的开放支柱, 渲染出的服务运行的正是该镜像引用。参见 Provider 特定覆盖。 - 双槽凭据模型。 密码是 component 的
features:支柱上的附件,每个都是标记为feature.aggrega.ai/kind: secret的 Feature, 与应用values分开存放。Component 的featuresSchema声明一个黑盒root_password槽和一个透明的user_password槽。
Kubernetes 凭据交付
root_password 是一个黑盒槽(inject: []):由 Recipe 控制
交付。所附的 inject-value 凭据将值放到 component 的
inject 管道上,Recipe 以
.context.inject.env.MYSQL_ROOT_PASSWORD 读取它,并输出一个普通的容器环境变量。
不会为它生成 Kubernetes Secret。
user_password 是一个透明槽(inject: [env, file])。完整
变体附加一个可引用凭据,它会实体化一个 Kubernetes
Secret 并发布其标识;Recipe 通过
containers.attachments 引用该槽,合成器将其渲染为环境变量 secretKeyRef。
生成的 Secret 与容器的引用指向同一资源,因为
二者都读取 .features.user_password.provides.name。不附加 user_password
(基础变体)同样有效:Recipe 回退到内联的
开发默认值(MYSQL_PASSWORD: apppass),且不生成 Secret,因此
最小部署依然能够渲染并运行。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example mysql-standalone然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd mysql-standalone构建
此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志;--auto-pull 会在构建期间写入新克隆所缺少的锁文件:
# Kubernetes — synthesized helm StatefulSet (base: root credential only)aggrega build --release release-helm-synth.yaml --auto-pull
# Kubernetes — synthesized helm StatefulSet (full: both credential slots)aggrega build --release release-helm-synth-auth.yaml --auto-pull
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pull渲染产物位于 dist/ 下。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `mysql-standalone` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `mysql-standalone`,不设 `dir`:它会把示例写入一个新的 `mysql-standalone` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-helm-synth.yaml`、`release-helm-synth-auth.yaml` 和 `release-compose.yaml`——每次都将 `workspace_root` 设为 `mysql-standalone`、`release` 设为该文件、`auto_pull` 设为 true、`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `mysql-standalone/dist/` 下。运维规格配置
Kubernetes releases 按环境填充运维规格支柱:
容器镜像标签来自 infra.engine_version(mysql:8.4),
volumeClaimTemplate 的请求量和存储类来自 infra.storage。
开发者的 Aggregate 从不包含这些字段。
Provider 特定覆盖
规格支柱是具名字段:Component 声明了 engine_version 和
storage,因此运维人员设置其中任一项,都是在填写 Component
预先设想的字段。infra.overrides 是用于 Component 无法预先设想之内容的支柱——
它被声明为接受任意嵌套结构的对象,
每个 Recipe 会说明它读取哪些键。
release-compose.yaml 使用了它。Compose Recipe 读取一个键 image,
设置该键时,容器运行的正是该引用,而不是
Recipe 根据 engine_version 组合出的引用:
infra: engine_version: "8.4" overrides: image: "registry.internal.example/library/mysql:8.4"渲染出的服务原样保留该覆盖:
services: db: image: registry.internal.example/library/mysql:8.4 [… omitted: the service's environment, labels, volume, network and health check]这是使用同一服务器版本的镜像仓库镜像构建或摘要固定构建的途径——
这是属于目标环境的部署事实,而不属于
Component 的契约。由于键集按 Recipe 而非
按 Component 定义,应查看 Recipe 来确定适用哪些键:这里的 Compose
Recipe 读取 image,不读取任何键的 Recipe 也会如此说明。