共享的 schema 库和映射库:一个 MariaDB Component
本页解释一个思路,即把 Component 的 schema 和 Recipe 的映射的大部分放在由多个实体共享的库中,它不是一个可运行的工作区。MariaDB + Adminer — 一个可运行的双目标示例 用一个 schema 库组合其数据库的存储设置;用以下命令将它写入你自己的文件夹:
aggrega scaffold --example mariadb-adminer然后它会打印接下来要运行的命令:
cd mariadb-admineraggrega pull --release release-compose.yamlaggrega build --release release-compose.yaml本页的实体是你自己的一个目录,位于命名空间 my-org 中;每个实体的形态,就是一个生产级 MariaDB Component、它的 Recipe 以及其背后的两个库所采用的形态。
由 schema 库承载形态
SchemaLibrary 声明命名 schema,以紧凑形式编写——每个字段一行,带有其类型、约束和默认值——构建会在用它们检查任何值之前,将其编译为 JSON Schema 2020-12。节选如下:
apiVersion: aggrega.ai/v1beta1kind: SchemaLibrarymetadata: name: Datastores version: 1.0.0spec: schemas: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "250m" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "512Mi" } NodePool: replicaCount: { type: integer, min: 1, max: 9, default: 1 } resources: { $ref: "Datastores#/schemas/PodResources" } MariaDBPayload: architecture: { type: string, enum: [standalone, replication], default: standalone } image: tag: { type: string, validate: '{{ ne . "latest" }}', validateMessage: "image.tag must name a version: latest moves with every chart release" } primary: { $ref: "Datastores#/schemas/NodePool", required: true } secondary: when: '{{ eq $.architecture "replication" }}' required: true properties: replicaCount: { type: integer, min: 2, max: 8, default: 2 }引用通过库的 metadata.name 来指定库——Datastores#/schemas/<entry>——而从不通过库的存放位置,在库内部也是如此,因此无论库位于工作区的目录中,还是发布到注册表,同一个引用都能解析。validate: 和 validateMessage: 为字段添加其自身的检查;when: 使整个对象成为条件性的,因此次级池的约束只在架构解析为 replication 时生效。跨文档的 $ref: 旁边只允许出现 properties、required 和 description,这就是为什么次级池是完整写出的,而不是引用 NodePool。
Component 引用它
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-org/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-server component.aggrega.ai/category: datastorespec: schema: values: $ref: Datastores#/schemas/MariaDBPayload infra: cpu_arch: { type: string, enum: [amd64, arm64], default: amd64 } provides: host: { type: string, format: hostname } port: { type: integer, min: 1024, max: 65535 } featuresSchema: root_credentials: required: true inject: [] replication_credentials: required: false inject: [] assertions: replication-needs-credentials: | {{- if eq .values.architecture "replication" -}} {{- if not (hasKey .features "replication_credentials") -}} {{- fail "architecture=replication requires replication_credentials secret to be supplied" -}} {{- end -}} {{- end -}}values 支柱只有一行 $ref:;体量小、特定于 Component 的 infra 和 provides 保持内联。断言承载 Component 契约中无法用任何 schema 关键字表达的规则,无论由哪个 Recipe 实现它。
由映射库承载转换
MappingLibrary 承载 Recipe 导入的模板片段。其中一个条目渲染 chart 的 values,并用 define 声明一个辅助模板,针对每个节点池用 template 调用它:
apiVersion: aggrega.ai/v1beta1kind: MappingLibrarymetadata: name: BitnamiHelpers version: 1.0.0spec: mappings: MariaDBBitnamiCore: | {{- define "BitnamiNodePool" }} resources: requests: cpu: {{ .pool.resources.requests.cpu | quote }} memory: {{ .pool.resources.requests.memory | quote }} {{- end }} {{- with .values -}} fullnameOverride: {{ $.context.rendered_name | quote }} architecture: {{ .architecture }} primary: name: primary {{- template "BitnamiNodePool" (dict "pool" .primary) }} {{- end }}辅助模板声明在使用它的条目内部,因为 Recipe 只导入一个条目,而定义随包含它的条目一起传递。该片段由 Aggrega 的渲染器求值,因此它使用 Sprig 的函数,以及 Aggrega 用于可能缺失的键的 optional(参见 sprig-functions.md);Helm 的 include 不在其中,而 template 会将输出原样写在其所在位置。
Recipe 导入它
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-bitnami version: 1.0.0spec: capability: helm implements: my-org/datastore/mariadb:^1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "25.0.8" valuesMapping: $import: BitnamiHelpers#/mappings/MariaDBBitnamiCore provides: host: "{{ .context.rendered_name }}{{ if eq .values.architecture `replication` }}-primary{{ end }}" port: "3306"Recipe 很小:映射位于库中,Recipe 保留属于它自己的内容——它渲染的 chart 以及它发布的地址。由于映射将 chart 的 fullnameOverride 固定为 .context.rendered_name,Recipe 可以计算出主节点的 Service 名称,而不必假定它。
库带来的好处
如果写成 JSON Schema,每个字段的单行映射会变成嵌套块,每个对象都要加上 type: object、properties: 和一个 required: 列表;when: 和 validate: 在 JSON Schema 中没有对应的关键字。紧凑形式涵盖了这个 Component 所需的一切,无需 $jsonschema: 逃生舱口。共享越多,节省越多:库只需编写一次,此后每个 Component 的 values 支柱都只是一行 $ref:。