コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

共有のスキーマライブラリとマッピングライブラリ:MariaDB の Component

このページは、Component のスキーマと Recipe のマッピングの大部分を、複数のエンティティが共有するライブラリに置くという 1 つの考え方を説明するもので、実行可能なワークスペースではありません。MariaDB + Adminer — 実行可能な 2 ターゲットの例 は、データベースのストレージ設定をスキーマライブラリから組み立てます。次のコマンドで、自分のフォルダーに書き出せます。

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、そしてそれらを支える 2 つのライブラリがとる形です。

スキーマライブラリが形を持つ

SchemaLibrary は名前付きスキーマを宣言します。スキーマはコンパクト形式(フィールドごとに 1 行で、型、制約、デフォルト値を記述)で書かれ、ビルドはいずれかの値を照合する前にそれを 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: の 1 行だけです。小さく Component 固有の infra と provides はインラインのままです。アサーションは、どのスキーマキーワードでも表現できない Component の契約のルールを保持し、どの Recipe がそれを実現するかを問いません。

マッピングライブラリが変換を持つ

MappingLibrary は、Recipe がインポートするテンプレートフラグメントを保持します。あるエントリはチャートの 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 がインポートするのは 1 つのエントリであり、定義はそれを含むエントリとともに移動するからです。フラグメントは 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 は自身のものだけを保持します。つまり、レンダリングするチャートと公開するアドレスです。マッピングがチャートの 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。