MariaDB + Adminer — 一个可运行的双目标示例
本示例将一个小型的真实技术栈(一个 MariaDB 数据库,前面配有一个 Adminer Web UI)从单个由 Developer 编写的 Aggregate 编译到两个平台:
- 用于本地开发的 Docker Compose,以及
- 用于本地集群(kind / minikube / k3d)的 Kubernetes,以三种方式渲染。
同一个 Aggregate 驱动这两个平台,只有 Release、它的 Manifest 以及构建时加载的 Recipe 层会变化。这里的每个文件都能用随附的 aggrega CLI 编译,且渲染输出可以运行:启动该技术栈,在浏览器中打开 Adminer,并登录到正在运行的数据库。
aggregate.yaml只编写一次
在笔记本电脑上
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yaml在 Kubernetes 集群上
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildKubernetes 清单
每个平台都由各自的 Release 和 Manifest 构建。描述你的应用的 Aggregate 保持不变。
演示内容
- 一个编写界面,多个目标。 单个
aggregate.yaml是该技术栈是什么的唯一事实来源。每个目标都是一个精简的目录层,说明如何实现它。 - 字符串管道(String Pipe)。 Adminer 声明了对 MariaDB 的
databases使用;数据库 Recipe 的provides.host通过管道传入 Adminer 的ADMINER_DEFAULT_SERVER环境变量。编译器路由该字符串而不解释它——因此基于同一条边,compose 构建接入的是 compose 服务名,而 Kubernetes 构建接入的是 Service DNS 名称。 - Workload 合成。 compose 和自包含 Kubernetes 的 Recipes 声明一个与能力无关的
Workload;provider 会合成一个docker-compose.yaml服务,或者合成该 Workload 的form所要求的 Kubernetes 对象——对无状态的 Web UI 是一个Deployment和一个Service;对form: stateful的数据库则是一个StatefulSet,其每副本卷声明模板承载数据目录,同时还有管理它的 HeadlessService,以及供使用方连接的ClusterIPService。 - 凭据子系统。 数据库密码附加在 component 的
features:支柱中——每个都是一个带有feature.aggrega.ai/kind: secret标签的Feature,与应用的values分开存放。该 Component 的featuresSchema声明了两种槽位类型,本示例两者都用到了:一种是黑盒槽位,其 FeatureRecipe 在内部交付值;另一种是透明槽位,其值由开发者在附加项上用inject:块显式交付。 - 远程 chart 来源。 托管 Kubernetes 目标通过 OCI 引用获取上游的 Bitnami MariaDB chart。
aggrega pull在锁文件中固定该 chart,并将其拉取到按内容寻址的缓存中;aggrega build从该缓存渲染,因此锁定时和构建时解析到的是同一个 chart。chart 版本在 Release 固定了运维人员的infra.source_version时取自该值,否则取自开发者编写的值(一个流入来源解析的值)。每个 release 的锁文件固定实体标识和摘要:在目录实体被重命名或其内容发生变化后,使用aggrega pull --release release-<variant>.yaml刷新过时的本地锁文件。每个 release 变体都根据其自身的同级目录进行解析,该目录由.aggrega-config.yaml在workspace.releases下为其指定,因此无论在终端、编辑器中还是通过助手,都不需要--catalog。 - 以注解记录来源。 每个渲染出的 Kubernetes 对象都带有一个
aggrega.ai/recipe-uri注解,记录生成它的 Recipe——使用注解而非标签,是因为 URI 值包含 Kubernetes 标签值不允许的字符。 - Chart 组合(对比合成)。 同一个 Aggregate 可以生成一个可再分发的 Helm chart,而不是渲染后的清单。
helm-chartprovider 组合出一个伞形 chart:每个 component 的本地子 chart 被原样复制进来(其 Helm{{ }}保持不变),伞形 chart 的values.yaml将每个 component 映射后的值——包括通过管道传入的数据库主机——路由到该 component 的别名之下。 - 按组件类型选择 Provider。 渲染每个组件的 Recipe,是目标的 Manifest 将该组件类型映射到的那个 Recipe,取自本次构建所加载的任一 catalog 层。
编写与使用——混合工作区
本示例同时涉及目录的两端:它在本地编写一些实体,并从 Aggrega 的标准库中使用另一些实体。MariaDB 数据库 Component、它的凭据 Features 以及各目标的 Recipes 都在本地的 catalog-*/ 目录中从零构建——一个 Aggregate 将这个在本地编写的数据库渲染到四个目标上。相比之下,Adminer Web UI 是被使用的:web 组件直接引用随附的 core/devtool/adminer Component,每个目标只在本地编写一个实现它的 Recipe。因此,同一个工作区既展示了数据库一侧的实体编写,也展示了 UI 一侧的目录使用。你在这里构建的实体与标准库中随附的实体属于同一种类:一个数据库 Component、凭据 Features、provider Recipes。
catalog-only 示例位于同一课程中纯使用的一端:它通过引用标准库实体来组装完全相同的技术栈——一个带有 Adminer UI 的 MariaDB 数据库——而不编写任何自己的实体。阅读本示例的数据库部分,可以了解目录实体是如何构建的;阅读使用类示例,可以了解如何从随附的目录中使用整个技术栈。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example mariadb-adminer然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd mariadb-adminer构建
每个目标都是一个 Release,每次运行构建一个;pull 写入构建所读取的锁文件。先构建 Docker Compose——下文每个目标的章节给出各自的命令:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yaml借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `mariadb-adminer` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `mariadb-adminer`,不设 `dir`:它会把示例写入一个新的 `mariadb-adminer` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `mariadb-adminer`、`release` 设为 `release-compose.yaml`、`auto_pull` 设为 true、`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `mariadb-adminer/dist/` 下。目录结构
mariadb-adminer/├── aggregate.yaml # Developer intent — shared by every target│├── manifest-compose.yaml # Ops mapping, Docker Compose target├── release-compose.yaml # Operator release, Docker Compose target├── catalog-compose/ # Recipe layer: compose│├── manifest-helm-synth.yaml # Ops mapping, self-contained Kubernetes target├── release-helm-synth.yaml # Operator release, self-contained Kubernetes target├── catalog-helm-synth/ # Recipe layer: helm (Workload synthesis)│├── manifest-helm-bitnami.yaml # Ops mapping, managed-chart Kubernetes target├── release-helm-bitnami.yaml # Operator release, managed-chart Kubernetes target├── catalog-helm-bitnami/ # Recipe layer: helm (upstream Bitnami chart)│├── manifest-helm-chart.yaml # Ops mapping, composed-Helm-chart target├── release-helm-chart.yaml # Operator release, composed-Helm-chart target└── catalog-helm-chart/ # Recipe layer: helm-chart (umbrella composition)每个 catalog-* 目录都包含本地编写的 MariaDB Component 和 Feature 定义,以及该目标对应的 Recipes。Adminer Component 不在其中——它从标准库解析。一次构建会在标准库之上加载一个 catalog-* 层,目标的 Manifest 将每种 component 类型映射到该层中的一个 Recipe。
Release、其 aggregate: 和其 manifest: 位于此
目录中的同一层级;每个 Release 构建所针对的 catalog 目录在
.aggrega-config.yaml 中为其指定。
共享的 Aggregate
spec: components: db: type: core/datastore/mariadb values: database: appdb user: appuser charset: utf8mb4 collation: utf8mb4_general_ci chart_version: "25.0.8" # the managed-chart target's chart, absent an operator pin features: root_password: # black-box slot: the FeatureRecipe delivers it type: core/secret-value values: { key: MARIADB_ROOT_PASSWORD, origin: dev-root-pw-change-me } user_password: # transparent slot: the developer delivers it type: core/secret-provided values: { origin: dev-app-pw-change-me } inject: env: [{ in: MARIADB_PASSWORD, from: value }]
web: type: core/devtool/adminer values: design: pepa-linha-dark uses: databases: db: target: db inject: env: - in: ADMINER_DEFAULT_SERVER from: hostweb 声明了对 db 的一个 databases 使用。inject 块将数据库 Recipe 的 provides.host 绑定到 Adminer 容器上的 ADMINER_DEFAULT_SERVER 环境
变量。Aggregate 中没有任何内容指定 provider;
这一选择完全取决于构建所加载的目录层。
关于凭据的说明
MariaDB 镜像需要一个 root 密码才能启动,应用用户也需要自己的密码。两者都附加在数据库 component 的 features: 支柱中(与应用的 values 分开),作为标记为 feature.aggrega.ai/kind: secret 的 Features。core/datastore/mariadb Component 的 featuresSchema 为每个密码声明一个槽位,本示例演练了两种交付模型:
root_password是一个黑盒槽位(inject: []):FeatureRecipe 将值交付到 component 的管道中。开发者不会(也不能) 规定交付方式。user_password是一个透明槽位(inject: [env, file]): 凭据公开其值,开发者通过附加项上的inject:块将其映射到一个环境 变量。
这里的值是内联字面量,因此整个栈只需一条命令即可运行, 适用于本地开发和演示。对于共享环境或生产环境, 相同的附加项会从密钥存储中解析其值: 目标的目录会加载一个获取这些值的 FeatureRecipe,而 Aggregate 无需 改动。
目标 1 — Docker Compose
先拉取,再构建——拉取会写入 release-compose.lock,构建会读取它:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yaml输出:dist/app/compose/docker-compose.yaml — 同一网络上的两个服务。
db 运行 mariadb:11.4,带有数据库、用户、字符集和注入的
密码;web 运行 adminer:4,发布端口 8080,依赖于 db,并
携带 ADMINER_DEFAULT_SERVER: db(数据库 Recipe 输出的 compose 服务名)。
运行:
docker compose -f dist/app/compose/docker-compose.yaml up -d打开 http://localhost:8080 并登录:
| 字段 | 值 |
|---|---|
| 系统 | MySQL / MariaDB |
| 服务器 | db(已预先填写) |
| 用户名 | appuser |
| 密码 | dev-app-pw-change-me |
| 数据库 | appdb |
(或使用 root / dev-root-pw-change-me)。使用
docker compose -f dist/app/compose/docker-compose.yaml down -v 拆除。
目标 2 — Kubernetes(自包含)
此目标直接从 Workload 渲染纯 Kubernetes manifest,
不使用外部 chart——一次离线构建即可完成。
数据库的 Workload 声明了 form: stateful,因此它合成一个
StatefulSet,其数据目录是按副本划分的卷声明模板,而不是
共享同一个声明的 Deployment。该形式附带两个配套项:
卷被声明为 persistentTemplate,并由一个 Headless Service 提供
StatefulSet 作为其管理服务所指定的、稳定的按 Pod DNS 标识。Adminer 不保存状态,因此它的 Workload 让 form 保持默认值,
仍然是一个 Deployment——持久化是 Workload 的一个属性,而不是
另一个组件。
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yaml输出位于 dist/app/helm/ 下:
db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysqldb-default-service.yaml # ClusterIP Service "db-default" on 3306db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceNameweb-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-defaultweb-default-service.yaml # NodePort Service "web-default" on 8080注意 ADMINER_DEFAULT_SERVER: db-default——对于 Kubernetes,数据库 Recipe
生成的是集群内 Service 的 DNS 名称,因此同一条 Aggregate 边在此目标上解析为
一个可路由的地址。
应用并打开它:
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080打开 http://localhost:8080,使用服务器 db-default、用户名
appuser、密码 dev-app-pw-change-me、数据库 appdb 登录。使用
kubectl delete -f dist/app/helm/ 将其删除。
目标 3 — Kubernetes(托管的 Bitnami chart)
第三层基于上游的 Bitnami MariaDB Helm chart 实现同一个 core/datastore/mariadb Component,而不是合成清单。该 Recipe 通过 OCI 引用获取 chart,并将该
Component 的值映射到 chart 的值 schema 上:
spec: capability: helm implements: core/datastore/mariadb source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "{{ optional .infra `source_version` .values.chart_version }}" # operator pin, else the value valuesMapping: | auth: database: "{{ .values.database }}" rootPassword: "{{ .context.inject.env.MARIADB_ROOT_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}" username: "{{ .values.user }}" password: "{{ .context.inject.env.MARIADB_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}" primary: persistence: size: "{{ .infra.storage.size }}" # … resources, read replicas, metrics mapped from infra …该 Recipe 的 source.version 优先使用运维人员的 infra.source_version,
并回退到开发者编写的 .values.chart_version。固定 chart 版本属于基础设施关注点,因此只要某个
Release 设置了固定版本,运维人员的固定版本就会胜出;本 Release 有意不设置固定版本,因此 .values 键就是
实际解析出的版本——这正是该目标的全部意义,因为只有在运维固定版本缺失时,
开发者的值参与源解析才能在渲染输出中被观察到。在 release-helm-bitnami.yaml 中为 db
组件固定 source_version,渲染出的 helm.sh/chart 标签
就会改为跟随该版本。
optional 按名称而非点分路径读取固定版本,正因如此,
缺失的固定版本才会回落到开发者的值,而不是解析为空
版本——关于存在性检查的语义,参见 optional。
构建此目标分两步:aggrega pull 解析 chart,
将其固定在 release-helm-bitnami.lock 中,并将其拉取到内容寻址的
构建缓存中(唯一需要联网的步骤);随后 aggrega build 从缓存渲染,
因此锁定时和构建时解析出的是完全相同的 chart。注入的凭据
流入 chart 的 auth 值,chart 生成数据库读取的 Kubernetes
Secret。Adminer 由与目标 2 相同的合成 Recipe 渲染,
并连接 chart 的主 Service(db-mariadb)。上面两个
自包含目标是端到端运行该技术栈的零依赖方式。
目标 4 — Kubernetes(组合式 Helm chart)
第四层针对 helm-chart
provider 实现同样的组件,该 provider 组合出一个可再分发的 Helm 伞形 chart,而不是
渲染清单(目标 2)或渲染上游 chart(目标 3)。每个
Recipe 都以一个小型本地 chart 作为来源:
spec: capability: helm-chart implements: core/datastore/mariadb source: ./charts/mariadb # copied as the sub-chart, bar its own name valuesMapping: | { "database": "{{ .values.database }}", "rootPassword": "{{ .context.inject.env.MARIADB_ROOT_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}", "serviceName": "{{ .context.instance_id }}-mariadb" }构建它:
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamldist/app/helm-chart/ 下的输出:
Chart.yaml # umbrella; lists db and web as sub-chart dependenciesvalues.yaml # alias-keyed: db.* and web.* value blockscharts/├── db/ # the local ./charts/mariadb; its Chart.yaml name is `db`│ ├── Chart.yaml│ ├── values.yaml│ └── templates/│ ├── deployment.yaml│ ├── service.yaml│ ├── pvc.yaml│ └── netpol.yaml # injected artifact (see below)└── web/ # the local ./charts/adminer; its Chart.yaml name is `web` [… omitted: web's own Chart.yaml, values.yaml, and a templates/ holding deployment.yaml and service.yaml — Adminer keeps no state, so it has no pvc.yaml, and the injected netpol.yaml is db's alone]安装它(子 chart 已 vendor 到 charts/ 下,因此无需先执行
helm dependency build):
helm install mariadb-adminer dist/app/helm-chart/伞形 chart 的 values.yaml 已经携带每个组件解析后的值,因此
数据库启动时即带有其凭据,Adminer 也已连接到 MariaDB
Service——与其他目标所表达的连接相同,只是现在以一个
可以安装或 vendor 的 chart 交付。
这里适用两套不同的定界符机制,二者互不重叠:
- 作为来源的子 chart 会被原样复制,只有其自身名称例外。
./charts/mariadb和./charts/adminer下的文件 会原封不动地打包进伞形 chart——其中的 Helm{{ }}指令不会被编译器改动, 而是在helm install时解析。组合器在这里只负责组装,不负责 模板渲染。它唯一会设置的字段是每个放置后的Chart.yaml的name, 该字段成为组件实例的标识(db、web),这样即使两个 组件 vendor 的 chart 声明了同一个名称,也仍可区分;参见providers/helm-chart.md。 $import:制品使用双定界符。 Recipe 可以通过artifacts: { name: { $import: ... } }注入额外的模板 文件。这些文件——且仅限这些文件——在落地之前会由编译器使用[[ ]]定界符 预先渲染,而其中的{{ }}则保留给 Helm。netpol.yaml制品—— 键为netpol.yaml,从./extras/mariadb-netpol.yaml导入,因为 键决定输出文件的名称,而导入选择其内容——展示了这种混合:[[ .context.instance_id ]](在构建时填充)和{{ .Release.Namespace }}(留到安装时处理)。
String Pipe 以 chart 的方式表达:Adminer 对 MariaDB 的 databases 使用
会将数据库 Recipe 的 provides.host 解析到伞形 chart 的 values.yaml 中
web 别名之下(adminerDefaultServer: db-mariadb),Adminer
子 chart 以 {{ .Values.adminerDefaultServer }} 读取它。同一个值也命名了
MariaDB 子 chart 的 Service,因此连接关系在安装时能够一致地解析。
输出是一个用于 helm install 或 vendor 的 chart——而不是一组已应用的清单。
如何选择目标
Recipe 按组件类型选择:每个目标的 Manifest 将每种类型映射到其 Release 所加载的目录层中的一个 Recipe,因此 manifest-compose.yaml 将 core/datastore/mariadb 绑定到 compose Recipe,而 manifest-helm-synth.yaml 将其绑定到 Kubernetes 的那个 Recipe。Manifest 未映射的类型会使构建中止,并列出实现该类型的 Recipes,即使所加载的层中只有一个也是如此。渲染某个节点的 provider 是所绑定 Recipe 的 spec.capability。切换目标就是切换 Release,连同它的 Manifest 以及 .aggrega-config.yaml 为它指定的目录——Aggregate 始终不变。