MariaDB + Adminer — 実行可能なデュアルターゲットの例
この例では、小規模な実際のスタック(MariaDB データベースと、その前段に置かれる Adminer Web UI)を、Developer が作成した単一の Aggregate から 2 つのプラットフォームへコンパイルします。
- ローカル開発向けの Docker Compose、そして
- ローカルクラスタ(kind / minikube / k3d)向けの Kubernetes。3 通りの方法でレンダリングします。
同じ Aggregate が両方を駆動します。変わるのは Release、その Manifest、そしてビルド時に読み込まれる Recipe レイヤーだけです。ここにあるすべてのファイルは同梱の aggrega CLI でコンパイルでき、レンダリングされた出力は実際に動作します。スタックを起動し、ブラウザで Adminer を開いて、稼働中のデータベースにログインできます。
aggregate.yaml一度だけ記述
ノート PC 上で
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yamlKubernetes クラスター上で
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildKubernetes マニフェスト
各プラットフォームは、それぞれの Release と Manifest からビルドされます。アプリケーションを記述する Aggregate は同じままです。
示す内容
- 1 つのオーサリング面、複数のターゲット。 1 つの
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を、それを管理する HeadlessServiceおよびコンシューマーが接続するClusterIPServiceとともに合成します。 - 認証情報サブシステム。 データベースのパスワードは、component の
features:ピラーで付与されます。それぞれがfeature.aggrega.ai/kind: secretのラベルが付いたFeatureであり、アプリケーションのvaluesとは分離されています。Component のfeaturesSchemaは 2 種類のスロットを宣言しており、この例では両方を使用します。FeatureRecipe が値を内部で提供するブラックボックススロットと、アタッチメント上のinject:ブロックで開発者が値を明示的に提供する透過スロットです。 - リモートのチャートソース。 マネージド Kubernetes ターゲットは、上流の Bitnami MariaDB チャートを OCI 参照で取得します。
aggrega pullはチャートをロックファイルに固定し、コンテンツアドレス指定のキャッシュに取得します。aggrega buildはそのキャッシュからレンダリングするため、ロック時とビルド時に同じチャートが解決されます。チャートのバージョンは、Release が固定している場合はオペレーターのinfra.source_versionから、それ以外の場合は開発者が記述した値(ソース解決に流れ込む値)から取得されます。release ごとのロックファイルはエンティティの識別子とダイジェストを固定します。カタログエンティティの名前が変更された、または内容が変わった後は、aggrega pull --release release-<variant>.yamlで古くなったローカルのロックファイルを更新します。各 release バリアントは、.aggrega-config.yamlがworkspace.releasesの下で指定する専用の兄弟カタログディレクトリに対して解決されるため、ターミナル、エディター、アシスタントのいずれからでも--catalogは不要です。 - アノテーションとしての来歴。 レンダリングされたすべての Kubernetes オブジェクトには、それを生成した Recipe を記録する
aggrega.ai/recipe-uriアノテーションが付きます。ラベルではなくアノテーションなのは、URI の値に Kubernetes のラベル値では使えない文字が含まれるためです。 - チャートの合成(シンセシスとの対比)。 同じ Aggregate から、レンダリング済みマニフェストの代わりに再配布可能な Helm チャートを生成できます。
helm-chartprovider はアンブレラチャートを構成します。各 component のローカルサブチャートはそのままコピーされ(Helm の{{ }}は手を加えずに保持されます)、アンブレラのvalues.yamlは、パイプされたデータベースホストを含む各 component のマッピング済みの値を、その component のエイリアスの下にルーティングします。 - コンポーネントのタイプによる Provider の選択。 各コンポーネントをレンダリングする Recipe は、ターゲットの Manifest がそのコンポーネントのタイプをマッピングしている先の Recipe であり、ビルドが読み込むカタログレイヤーから取得されます。
作成と利用 — 混在したワークスペース
この例では、カタログの両端を同時に扱います。一部のエンティティはローカルで作成し、その他は Aggrega の標準ライブラリから利用します。MariaDB データベースの Component、その認証情報の Features、およびターゲットごとの Recipes は、ローカルの catalog-*/ ディレクトリでゼロから作成されています。1 つの Aggregate が、そのローカルで作成されたデータベースを 4 つのターゲットにわたってレンダリングします。一方、Adminer の Web UI は利用する側です。web コンポーネントは標準で提供される core/devtool/adminer Component を直接参照し、各ターゲットはそれを実装するローカルの Recipe だけを作成します。そのため、同じワークスペースで、データベース側のエンティティの作成と、UI 側のカタログの利用が並んで示されます。ここで作成するエンティティは、標準ライブラリで提供されるものと同じ種類です。つまり、データベースの Component、認証情報の Features、プロバイダの Recipes です。
catalog-only の例は、同じカリキュラムのうち純粋な利用の側に位置します。この例は、まさにこのスタック(Adminer UI を備えた MariaDB データベース)を、標準ライブラリのエンティティを参照することで組み立て、独自のエンティティは一切作成しません。カタログのエンティティがどのように作成されるかを学ぶにはこの例のデータベース側を読み、スタック全体が提供されるカタログからどのように使用されるかを学ぶには利用の例を読んでください。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example mariadb-adminerその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd mariadb-adminerビルド
各ターゲットは 1 つの Release で、1 回の実行につき 1 つずつビルドします。pull はビルドが読み込むロックファイルを書き出します。まず Docker Compose から始めます。以下の各ターゲットのセクションに、それぞれのコマンドがあります。
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlAI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `mariadb-adminer` フォルダーがない場合は、`example` を `mariadb-adminer` に設定し、`dir` を指定せずに `scaffold` ツールを一度呼び出してください。これにより、例が新しい `mariadb-adminer` フォルダーに書き込まれます。次に、`workspace_root` を `mariadb-adminer`、`release` を `release-compose.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。ファイルは `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 の定義に加えて、その 1 つのターゲット向けの Recipes が含まれます。Adminer の Component はその中にはなく、標準ライブラリから解決されます。ビルドは 1 つの catalog-* レイヤーをその標準ライブラリの上に読み込み、ターゲットの Manifest が各コンポーネントタイプをそのレイヤー内の Recipe にマッピングします。
Release、その aggregate:、その manifest: はこの
ディレクトリ内に並んで置かれています。各 Release のビルド対象となるカタログディレクトリは、
.aggrega-config.yaml でその Release に対して指定されています。
共有される 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: hostweb は db に対する databases 利用を宣言します。inject ブロックは、データベース Recipe の provides.host を Adminer コンテナの ADMINER_DEFAULT_SERVER 環境変数にバインドします。Aggregate の中にはプロバイダを指定するものは何もありません。
その選択は、すべてビルドが読み込むカタログレイヤーに置かれています。
認証情報についての注記
MariaDB イメージの起動には root パスワードが必要であり、アプリケーションユーザーにも専用のパスワードが必要です。どちらもデータベースコンポーネントの features: の柱に、アプリケーションの values とは分けて、feature.aggrega.ai/kind: secret のラベルが付いた Features として付与されます。core/datastore/mariadb Component の featuresSchema がそれぞれにスロットを宣言しており、この例では両方の提供モデルを使用します。
root_passwordはブラックボックススロット(inject: [])です。FeatureRecipe が 値をコンポーネントのパイプに届けます。その方法を開発者は指定せず、 また指定することもできません。user_passwordは透過的スロット(inject: [env, file])です。 認証情報はその値を公開し、開発者は付与に対するinject:ブロックで それを環境変数にマッピングします。
ここでの値はインラインのリテラルなので、スタックは単一のコマンドで実行できます。 これはローカル開発やデモに適しています。共有環境や本番環境では、 同じ付与がシークレットストアから値を解決します。 ターゲットのカタログがそれらを取得する FeatureRecipe を読み込み、Aggregate は 変更されません。
ターゲット 1 — Docker Compose
プルしてからビルドします。プルは release-compose.lock を書き出し、ビルドはそれを読み込みます:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yaml出力: dist/app/compose/docker-compose.yaml — 1 つのネットワーク上の 2 つのサービスです。
db は、データベース、ユーザー、文字セット、注入されたパスワードを設定して mariadb:11.4 を実行します。web は adminer:4 を実行し、ポート 8080 を公開し、db に依存し、ADMINER_DEFAULT_SERVER: db(データベースの
Recipe が出力した compose のサービス名)を持ちます。
実行します:
docker compose -f dist/app/compose/docker-compose.yaml up -dhttp://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 マニフェストをレンダリングします。オフラインの 1 回のビルドで完結します。
データベースの Workload は form: stateful を宣言しているため、1 つのクレームを共有する Deployment ではなく、データディレクトリがレプリカごとのボリュームクレームテンプレートである StatefulSet を合成します。この form には 2 つの付随要素が伴います。ボリュームは persistentTemplate として宣言され、Headless Service が、StatefulSet がガバニングサービスとして指定する、Pod ごとの安定した DNS アイデンティティを提供します。Adminer は状態を持たないため、その Workload は form をデフォルトのままにし、Deployment のままです。永続性は Workload のプロパティであり、別のコンポーネントではありません。
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamldist/app/helm/ 配下の出力:
db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysqldb-default-service.yaml # ClusterIP Service "db-default" on 3306db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceNameweb-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-defaultweb-default-service.yaml # NodePort Service "web-default" on 8080ADMINER_DEFAULT_SERVER: db-default に注目してください。Kubernetes では、データベースの Recipe がクラスタ内の Service DNS 名を出力するため、同じ Aggregate のエッジがこのターゲット上ではルーティング可能なアドレスに解決されます。
適用して開きます:
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080http://localhost:8080 を開き、サーバー db-default、ユーザー名 appuser、パスワード dev-app-pw-change-me、データベース appdb でログインします。削除するには
kubectl delete -f dist/app/helm/ を実行します。
Target 3 — Kubernetes(マネージドな Bitnami チャート)
3 番目のレイヤーは、マニフェストを合成する代わりに、アップストリームの Bitnami MariaDB Helm チャートに対して同じ core/datastore/mariadb Component
を実装します。Recipe はチャートを OCI 参照で取得し、
Component の値をチャートの値スキーマにマッピングします。
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 にフォールバックします。チャートバージョンの
固定はインフラストラクチャの関心事であるため、Release が固定値を設定している場合は常にオペレーターの固定値が優先されます。この Release は意図的に何も設定していないため、.values キーが
実際に解決されるバージョンになります。これがこのターゲットの要点です。開発者の値がソース解決に到達することは、運用上の固定値が存在しない場合にのみレンダリング出力で観察できるためです。release-helm-bitnami.yaml の db
コンポーネントに source_version を固定すると、レンダリングされる helm.sh/chart ラベルは
代わりにそのバージョンに従います。
optional は固定値をドット区切りのパスではなく名前で読み取ります。これにより、
固定値が存在しない場合に空のバージョンに解決されるのではなく、開発者の値にフォールスルーできます。
存在チェックのセマンティクスについては optional
を参照してください。
このターゲットのビルドは 2 段階のフローです。aggrega pull がチャートを解決し、
release-helm-bitnami.lock に固定して、コンテンツアドレス方式の
ビルドキャッシュに取得します(唯一のオンラインステップ)。続いて aggrega build がキャッシュからレンダリングするため、
ロック時とビルド時に同一のチャートが解決されます。注入された認証情報は
チャートの auth 値に流れ込み、チャートはデータベースが読み取る Kubernetes
Secret を生成します。Adminer は Target 2 と同じ合成された Recipe によってレンダリングされ、
チャートのプライマリ Service(db-mariadb)に接続します。上記の 2 つの
自己完結型ターゲットは、依存関係なしでスタックをエンドツーエンドで実行する方法です。
ターゲット 4 — Kubernetes(合成された Helm チャート)
第 4 のレイヤーは、同じコンポーネントを helm-chart
プロバイダーに対して実装します。このプロバイダーは、マニフェストをレンダリングする(ターゲット 2)のでも、アップストリームのチャートをレンダリングする(ターゲット 3)のでもなく、再配布可能な Helm アンブレラチャートを合成します。各
Recipe は小さなローカルチャートをソースとします。
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" }ビルドします。
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamldist/app/helm-chart/ 以下の出力:
Chart.yaml # umbrella; lists db and web as sub-chart dependenciesvalues.yaml # alias-keyed: db.* and web.* value blockscharts/├── 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]インストールします(サブチャートは charts/ 以下にベンダリングされているため、事前に
helm dependency build を実行する必要はありません)。
helm install mariadb-adminer dist/app/helm-chart/アンブレラの values.yaml には各コンポーネントの解決済みの値がすでに含まれているため、
データベースは認証情報を持って起動し、Adminer は MariaDB の
Service に接続されます。これは他のターゲットが表現するのと同じ接続であり、今回はインストールまたはベンダリングできるチャートとして提供されます。
2 つの異なるデリミタ方式が適用され、それらは重なりません。
- ソースとしたサブチャートは、自身の名前を除いてそのままコピーされます。
./charts/mariadbと./charts/adminer以下のファイルは、変更されずにアンブレラにバンドルされます。それらの Helm{{ }}ディレクティブはコンパイラによって変更されず、helm installの時点で解決されます。そこでのコンポーザーの役割は組み立てだけであり、テンプレート処理ではありません。コンポーザーが設定する唯一のフィールドは、配置された各Chart.yamlのnameです。 これはコンポーネントインスタンスの識別子(db、web)になるため、同じ名前を宣言するチャートをベンダリングする 2 つの コンポーネントも区別できます。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 はチャートの用語で表現されます。Adminer による MariaDB の databases での利用は、
データベースの Recipe の provides.host を、web エイリアスの下でアンブレラの values.yaml に解決します(adminerDefaultServer: db-mariadb)。Adminer
サブチャートはこれを {{ .Values.adminerDefaultServer }} として読み取ります。同じ値が
MariaDB サブチャートの Service の名前にもなるため、接続はインストール時に一貫して解決されます。
出力は helm install するかベンダリングするためのチャートであり、適用済みのマニフェストの集合ではありません。
ターゲットの選択方法
Recipe の選択はコンポーネントの型によって行われます。各ターゲットの Manifest は、その Release が読み込むカタログレイヤー内の Recipe にすべての型をマッピングするため、manifest-compose.yaml は core/datastore/mariadb を compose 用の Recipe にバインドし、manifest-helm-synth.yaml は Kubernetes 用の Recipe にバインドします。Manifest がマッピングしていない型があるとビルドは停止し、それを実装する Recipes を示します。読み込まれたレイヤーに 1 つしかない場合でも同様です。ノードをレンダリングするプロバイダーは、バインドされた Recipe の spec.capability です。ターゲットの切り替えは、Release を、その Manifest と .aggrega-config.yaml がそれに対して指定するカタログディレクトリとともに切り替えることです。Aggregate は一切変更されません。