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

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.yaml
manifest-compose.yaml
aggrega build
docker-compose.yaml

在 Kubernetes 集群上

release-helm-synth.yaml
manifest-helm-synth.yaml
aggrega build

Kubernetes 清单

每个平台都由各自的 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,其每副本卷声明模板承载数据目录,同时还有管理它的 Headless Service,以及供使用方连接的 ClusterIP Service。
  • 凭据子系统。 数据库密码附加在 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-chart provider 组合出一个伞形 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 助手替你构建。

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

Terminal window
aggrega scaffold --example mariadb-adminer

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

Terminal window
cd mariadb-adminer

构建

每个目标都是一个 Release,每次运行构建一个;pull 写入构建所读取的锁文件。先构建 Docker Compose——下文每个目标的章节给出各自的命令:

Terminal window
aggrega pull --release release-compose.yaml
aggrega 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: host

web 声明了对 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,构建会读取它:

Terminal window
aggrega pull --release release-compose.yaml
aggrega 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 服务名)。

运行:

Terminal window
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 的一个属性,而不是 另一个组件。

Terminal window
aggrega pull --release release-helm-synth.yaml
aggrega build --release release-helm-synth.yaml

输出位于 dist/app/helm/ 下:

db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysql
db-default-service.yaml # ClusterIP Service "db-default" on 3306
db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceName
web-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-default
web-default-service.yaml # NodePort Service "web-default" on 8080

注意 ADMINER_DEFAULT_SERVER: db-default——对于 Kubernetes,数据库 Recipe 生成的是集群内 Service 的 DNS 名称,因此同一条 Aggregate 边在此目标上解析为 一个可路由的地址。

应用并打开它:

Terminal window
kubectl apply -f dist/app/helm/
kubectl rollout status statefulset/db
kubectl 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" }

构建它:

Terminal window
aggrega pull --release release-helm-chart.yaml
aggrega build --release release-helm-chart.yaml

dist/app/helm-chart/ 下的输出:

Chart.yaml # umbrella; lists db and web as sub-chart dependencies
values.yaml # alias-keyed: db.* and web.* value blocks
charts/
├── 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):

Terminal window
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 始终不变。