Kong スタック — モジュールとして構成された、データベースを利用する API ゲートウェイ
この例では、小規模ながら実際のスタック、つまりデータベースを利用する API ゲートウェイを、
Developer が記述した 1 つの Aggregate から合成された Kubernetes マニフェストへコンパイルします。
このゲートウェイは単一のコンポーネントではありません。モジュール、つまり 2 つの単一ワークロードのコンポーネントを構成する 再利用可能なサブアグリゲートです。
- プロキシポートでクライアントのトラフィックを終端し、ローカルな状態を 持たないゲートウェイと、
- ゲートウェイの設定を保持し、それをボリュームに 永続化するバックエンドである PostgreSQL です。
モジュールはゲートウェイからバックエンドへの独自の内部エッジを接続し、
ゲートウェイを公開エンドポイント proxy としてエクスポートします。トップレベルの Aggregate
はモジュールを名前でインポートし、構成されたスタックをレンダリングします。オペレーターは
Release でモジュールの内部コンポーネントのサイズを指定します。
ファイル
| ファイル | 役割 |
|---|---|
aggregate.yaml | Developer の意図:API ゲートウェイモジュール(core/kong)をインポートします。 |
manifest-helm-synth.yaml | ゲートウェイとバックエンドの型を、それぞれの synth helm Recipes にマッピングします。 |
release-helm-synth.yaml | Kubernetes ターゲット向けのオペレーターのレコードです。モジュールの内部コンポーネントをモジュールスコープの ID でサイズ指定します。スキーマのデフォルトに任せた部分は自己完結した形でレンダリングされます。 |
示す内容
- モジュールとしての構成。 複数ワークロードからなる機能、つまり実際には プロキシと設定データベースの組み合わせである API ゲートウェイは、1 つのモノリシックな コンポーネントとしてではなく、2 つの単一ワークロードのコンポーネントを構成する サブアグリゲートとしてパッケージ化されます。モジュールは名前でインポートされ、 ゲートウェイが必要な場所で再利用されます。
- モジュール内部のエッジ。 ゲートウェイはバックエンドの利用を宣言します。
バックエンドの Recipe の
providesのホスト、ポート、ユーザー、データベースは ゲートウェイに渡され、その PostgreSQL 接続へと組み立てられます。 コンパイラは文字列を解釈せずにルーティングします。 - 公開エンドポイント。 モジュールはゲートウェイを
proxyとしてエクスポートします。 これはコンシューマーが接続する安定した公開名であり、モジュールの内部 コンポーネント名から切り離されています。 - 内部コンポーネントのオペレーターによるサイズ指定。 Release はモジュールの
内部コンポーネントをモジュールスコープの ID(
gateway.backend、gateway.gateway)で指定してコンピュートを設定するため、開発者の Aggregate で 物理的なサイズを改めて記述する必要はありません。 - サービス開始前に実行されるマイグレーションステップ。 ゲートウェイは、メインの ゲートウェイコンテナの起動前に完了まで実行される init コンテナを通じて データベーススキーマをプロビジョニングするため、準備済みのスキーマに対してサービスを提供します。 このブートストラップは冪等であるため、プロビジョニング済みのデータベースに対して 再実行しても何も行われません。
- 共有の認証情報。 ゲートウェイは PostgreSQL バックエンドに対して認証を行うため、 両者は 1 つのパスワードを共有します。この例では共有のインライン開発用 デフォルトを使用するため、スタックは外部シークレットなしで自己完結して動作します。
- 再現可能なイメージ。 ゲートウェイとバックエンドの両方が明示的なイメージ タグを固定しているため、レンダリングされたマニフェストは安定したイメージを参照します。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example kong-stackその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd kong-stackビルド
このワークスペースには .aggrega-config.yaml がないため、標準ライブラリのエンティティはハブレジストリ hub.aggrega.ai から解決され、カタログフラグは不要です。--auto-pull は、新しいクローンに欠けているロックファイルをビルド中に書き込みます。
aggrega build --release release-helm-synth.yaml --auto-pullレンダリングされた成果物は dist/ 以下に出力されます。Kubernetes ターゲットはオフラインで
プレーンなマニフェストをレンダリングするため、チャートのプルは不要です。
AI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `kong-stack` フォルダーがない場合は、`example` を `kong-stack` に設定し、`dir` を指定せずに `scaffold` ツールを一度呼び出してください。これにより、例が新しい `kong-stack` フォルダーに書き込まれます。次に、`workspace_root` を `kong-stack`、`release` を `release-helm-synth.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。ファイルは `kong-stack/dist/` の下にあります。構成されたスタックの姿
ゲートウェイは、ステートレスな Deployment に加え、プロキシポート上の ClusterIP Service と、 Status API のリクエスト許可リストを保持する ConfigMap としてレンダリングされます。その Pod は メインコンテナより前に実行されるマイグレーション用 init コンテナを持ちます。どちらのコンテナも バックエンドエッジから組み立てられた接続、つまりバックエンドのクラスタ内 Service 名、ユーザー、データベースを持ちます:
env: - name: KONG_DATABASE value: postgres - name: KONG_PG_HOST value: gateway-zdbackend-default - name: KONG_PG_PORT value: "5432" - name: KONG_PG_USER value: kong - name: KONG_PG_DATABASE value: kong [… omitted: the gateway's own proxy, admin and status listen addresses, and the allowlist file its Status API includes] - name: KONG_PG_PASSWORD value: apppassゲートウェイの readiness プローブと liveness プローブは、コンテナポート status 上で Kong の Status API
(GET /status/ready と GET /status)に問い合わせるため、そのリスナーは Pod のアドレスにバインドされます。
Kong は ConfigMap の許可リストを Status API 自身の server ブロックに取り込みます。Pod の
ループバックアドレス以外のどのアドレスからも、/status、/status/ready、/metrics への GET には応答し、
それ以外のすべてのリクエストは 403 で拒否します。拒否されるものには POST /status/ready も含まれます。
これが許可されると、ゲートウェイがドレイン中としてマークされ、再起動するまで Service から
外されてしまいます。
バックエンドは、/var/lib/postgresql/data にマウントされた永続ボリュームを持つ StatefulSet と、
ClusterIP Service および headless Service としてレンダリングされます。