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

共享的 schema 库和映射库:一个 MariaDB Component

本页解释一个思路,即把 Component 的 schema 和 Recipe 的映射的大部分放在由多个实体共享的库中,它不是一个可运行的工作区。MariaDB + Adminer — 一个可运行的双目标示例 用一个 schema 库组合其数据库的存储设置;用以下命令将它写入你自己的文件夹:

Terminal window
aggrega scaffold --example mariadb-adminer

然后它会打印接下来要运行的命令:

Terminal window
cd mariadb-adminer
aggrega pull --release release-compose.yaml
aggrega build --release release-compose.yaml

本页的实体是你自己的一个目录,位于命名空间 my-org 中;每个实体的形态,就是一个生产级 MariaDB Component、它的 Recipe 以及其背后的两个库所采用的形态。

由 schema 库承载形态

SchemaLibrary 声明命名 schema,以紧凑形式编写——每个字段一行,带有其类型、约束和默认值——构建会在用它们检查任何值之前,将其编译为 JSON Schema 2020-12。节选如下:

apiVersion: aggrega.ai/v1beta1
kind: SchemaLibrary
metadata:
name: Datastores
version: 1.0.0
spec:
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/v1beta1
kind: Component
metadata:
name: my-org/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
component.aggrega.ai/category: datastore
spec:
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/v1beta1
kind: MappingLibrary
metadata:
name: BitnamiHelpers
version: 1.0.0
spec:
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/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
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:。

参考:紧凑形式编写、跨文档 $ref:、断言块、SchemaLibrary 和 MappingLibrary。