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

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.yaml
manifest-compose.yaml
aggrega build
docker-compose.yaml

Kubernetes クラスター上で

release-helm-synth.yaml
manifest-helm-synth.yaml
aggrega build

Kubernetes マニフェスト

各プラットフォームは、それぞれの 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 を、それを管理する Headless Service およびコンシューマーが接続する ClusterIP Service とともに合成します。
  • 認証情報サブシステム。 データベースのパスワードは、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-chart provider はアンブレラチャートを構成します。各 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 アシスタントにビルドを任せることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

Terminal window
aggrega scaffold --example mariadb-adminer

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd mariadb-adminer

ビルド

各ターゲットは 1 つの Release で、1 回の実行につき 1 つずつビルドします。pull はビルドが読み込むロックファイルを書き出します。まず Docker Compose から始めます。以下の各ターゲットのセクションに、それぞれのコマンドがあります。

Terminal window
aggrega pull --release release-compose.yaml
aggrega build --release release-compose.yaml

AI アシスタントを使う

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: host

web は 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 を書き出し、ビルドはそれを読み込みます:

Terminal window
aggrega pull --release release-compose.yaml
aggrega 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 のサービス名)を持ちます。

実行します:

Terminal window
docker compose -f dist/app/compose/docker-compose.yaml up -d

http://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 のプロパティであり、別のコンポーネントではありません。

Terminal window
aggrega pull --release release-helm-synth.yaml
aggrega build --release release-helm-synth.yaml

dist/app/helm/ 配下の出力:

db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysql
db-default-service.yaml # ClusterIP Service "db-default" on 3306
db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceName
web-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-default
web-default-service.yaml # NodePort Service "web-default" on 8080

ADMINER_DEFAULT_SERVER: db-default に注目してください。Kubernetes では、データベースの Recipe がクラスタ内の Service DNS 名を出力するため、同じ Aggregate のエッジがこのターゲット上ではルーティング可能なアドレスに解決されます。

適用して開きます:

Terminal window
kubectl apply -f dist/app/helm/
kubectl rollout status statefulset/db
kubectl port-forward svc/web-default 8080:8080

http://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" }

ビルドします。

Terminal window
aggrega pull --release release-helm-chart.yaml
aggrega build --release release-helm-chart.yaml

dist/app/helm-chart/ 以下の出力:

Chart.yaml # umbrella; lists db and web as sub-chart dependencies
values.yaml # alias-keyed: db.* and web.* value blocks
charts/
├── 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 を実行する必要はありません)。

Terminal window
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 は一切変更されません。