共有のスキーマライブラリとマッピングライブラリ:MariaDB の Component
このページは、Component のスキーマと Recipe のマッピングの大部分を、複数のエンティティが共有するライブラリに置くという 1 つの考え方を説明するもので、実行可能なワークスペースではありません。MariaDB + Adminer — 実行可能な 2 ターゲットの例 は、データベースのストレージ設定をスキーマライブラリから組み立てます。次のコマンドで、自分のフォルダーに書き出せます。
aggrega scaffold --example mariadb-adminerその後、次に実行するコマンドを表示します。
cd mariadb-admineraggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlこのページのエンティティは、名前空間 my-org にある独自のカタログです。それぞれの形は、本番グレードの MariaDB の Component、その Recipe、そしてそれらを支える 2 つのライブラリがとる形です。
スキーマライブラリが形を持つ
SchemaLibrary は名前付きスキーマを宣言します。スキーマはコンパクト形式(フィールドごとに 1 行で、型、制約、デフォルト値を記述)で書かれ、ビルドはいずれかの値を照合する前にそれを 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: の 1 行だけです。小さく Component 固有の infra と provides はインラインのままです。アサーションは、どのスキーマキーワードでも表現できない Component の契約のルールを保持し、どの Recipe がそれを実現するかを問いません。
マッピングライブラリが変換を持つ
MappingLibrary は、Recipe がインポートするテンプレートフラグメントを保持します。あるエントリはチャートの 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 がインポートするのは 1 つのエントリであり、定義はそれを含むエントリとともに移動するからです。フラグメントは 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 は自身のものだけを保持します。つまり、レンダリングするチャートと公開するアドレスです。マッピングがチャートの fullnameOverride を .context.rendered_name に固定するため、Recipe はプライマリの Service 名を推測せずに計算できます。
ライブラリがもたらすもの
JSON Schema として書くと、各フィールドの 1 行のマップはネストしたブロックになり、すべてのオブジェクトに type: object、properties:、そして required: リストが加わります。when: と validate: には対応する JSON Schema のキーワードがありません。コンパクト形式は、$jsonschema: というエスケープハッチなしで、この Component に必要なすべてをカバーします。節約は共有とともに大きくなります。ライブラリは一度書けばよく、以降の各 Component の values の柱は $ref: の 1 行だけです。
リファレンス:コンパクト形式でのオーサリング、ドキュメント間の $ref:、アサーションブロック、SchemaLibrary、MappingLibrary。