APISIX スタック — モジュールとして構成された動的 API ゲートウェイ
この例では、小規模ながら実用的なスタックである動的 API ゲートウェイを、Developer が作成した 1 つの Aggregate から、
合成された Kubernetes マニフェストへとコンパイルします。
このゲートウェイは単一のコンポーネントではありません。モジュール、つまり 2 つの単一ワークロードのコンポーネントを構成する 再利用可能なサブアグリゲートです。
- プロキシポートでクライアントのトラフィックを終端し、ローカルな状態を 持たないゲートウェイと、
- ゲートウェイの設定を保持し、それをボリュームに永続化する ストアである etcd です。
モジュールは、ゲートウェイからストアへの内部エッジを自ら配線し、ゲートウェイを
公開エンドポイント proxy としてエクスポートします。トップレベルの Aggregate はモジュールを名前でインポートし、
構成されたスタックをレンダリングします。オペレーターは Release でモジュールの
内部コンポーネントのサイズを指定します。
ファイル
| ファイル | 役割 |
|---|---|
aggregate.yaml | Developer の意図:API ゲートウェイモジュール(core/apisix)をインポートし、自身のパラメーターからゲートウェイの Admin API キーをモジュールに渡します。 |
manifest-helm-synth.yaml | ゲートウェイとストアの型を synth helm の Recipes にマッピングし、モジュールがアタッチする資格情報 Feature を、名前空間に既に存在する Secret を読み取る実現にマッピングします。 |
release-helm-synth.yaml | Kubernetes ターゲット用のオペレーターレコードです。Admin API キーを保持する Secret を指定し、モジュールの内部コンポーネントをモジュールスコープの ID でサイズ指定します。それ以外はスキーマのデフォルトに任せます。 |
示す内容
- モジュールとしての構成。 複数ワークロードからなる機能(実体はプロキシと設定ストアである API ゲートウェイ)を、1 つのモノリシックなコンポーネントではなく、2 つの単一ワークロードの コンポーネントを構成するサブアグリゲートとしてパッケージ化します。 モジュールは名前でインポートされ、ゲートウェイが必要な場所で再利用されます。
- モジュール内部のエッジ。 ゲートウェイはストアの使用を宣言します。
ストア Recipe の
providesのホストとポートがゲートウェイに渡され、 その etcd 接続に組み込まれます。コンパイラはこれらの文字列を 解釈せずにルーティングします。 - 公開エンドポイント。 モジュールはゲートウェイを
proxyとしてエクスポートします。 これはコンシューマーが接続する安定した公開名であり、モジュールの内部 コンポーネント名から切り離されています。 - オペレーターによる内部コンポーネントのサイズ指定。 Release はモジュールの
内部コンポーネントをモジュールスコープの ID(
gateway.store、gateway.gateway)で指定してコンピュートを設定するため、開発者の Aggregate で 物理的なサイズを改めて記述する必要はありません。 - 実行時に書き込まれるファイルと並べてマウントされる設定ファイル。 ゲートウェイは 起動時に自らも書き込むディレクトリ内のファイルから設定を読み取ります。 Recipe はその設定を ConfigMap として出力し、単一ファイルとしてマウントするため、 ゲートウェイがそこに書き込むファイルを覆い隠すことなくゲートウェイを設定できます。
- Secret から読み取られる Admin API キー。 ゲートウェイは Admin API を通じてルートを
管理し、そのキーはゲートウェイの資格情報スロットを通じて届きます。この例のように
models ソケットに何も配線されていない間はゲートウェイがこのスロットを必須とするため、
デフォルトのキーは存在しません。モジュールはキーをパラメーター
admin_keyとして受け取り、 それを用いてcore/referenced-secret資格情報 Feature をスロットにアタッチします。 この Aggregate は自身のパラメーターを宣言してそれを下へ渡し、Release がそれを満たします。 Manifest はこの Feature をk8s-existing-secretにマッピングするため、値は 名前空間に既に存在する Secret の名前になります。ビルドはキーを読み取らず、レンダリングもせず、 ゲートウェイは起動時にその Secret からキーを読み取ります。値を指定しない Release は、 そのパラメーターを示してビルドを停止させます。 - 再現可能なイメージ。 ゲートウェイとストアはどちらも明示的なイメージタグを 固定しているため、レンダリングされたマニフェストは安定したイメージを参照します。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example apisix-stackその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd apisix-stackビルド
このワークスペースには .aggrega-config.yaml がないため、標準ライブラリのエンティティはハブレジストリ hub.aggrega.ai から解決され、カタログフラグは不要です。--auto-pull は、新しいクローンに欠けているロックファイルをビルド中に書き込みます。
aggrega build --release release-helm-synth.yaml --auto-pullレンダリングされた成果物は dist/ 以下に出力されます。Kubernetes ターゲットはオフラインで
プレーンなマニフェストをレンダリングするため、チャートのプルは不要です。
適用する前に、Release が指定する Secret apisix-admin-key を
ターゲットの名前空間に作成し、データキー admin-key に独自のキーを保持させてください。
キーは空であってはなりません(空の場合、ゲートウェイは起動時に停止します)。また、
すべて数字のキーなど、APISIX が数値や true/false として読み取る値であってもなりません。
その場合、APISIX はリクエストが提示するキーと照合しなくなるためです。
AI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーを自分で作成しないでください。ワークスペースフォルダーにまだ `apisix-stack` フォルダーがない場合は、`example` を `apisix-stack` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、サンプルが新しい `apisix-stack` フォルダーに書き出されます。次に、`workspace_root` を `apisix-stack`、`release` を `release-helm-synth.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き出したファイルを教えてください。ファイルは `apisix-stack/dist/` の下にあります。構成されたスタックの姿
ゲートウェイは、ステートレスな Deployment と、プロキシポート上の ClusterIP Service として レンダリングされます。その設定は、コンテナの conf ディレクトリに単一ファイルとしてマウントされる ConfigMap として提供されます。設定にはストアのクラスター内 Service 名が含まれ、 Admin API キーの位置には、APISIX がファイルを読み込む際にキーを読み取る 環境変数の名前が入ります:
apisix: node_listen: 9080deployment: role: traditional role_traditional: config_provider: etcd admin: [… omitted: the client range the Admin API accepts] admin_key: - name: admin key: ${{APISIX_ADMIN_KEY}} role: admin admin_listen: ip: 0.0.0.0 port: 9180 etcd: host: - "http://gateway-zdstore-default:2379" prefix: "/apisix" timeout: 30Deployment はその変数を Secret から提供するため、キーはレンダリングされた どのファイルにも現れません:
env: - name: APISIX_ADMIN_KEY valueFrom: secretKeyRef: name: apisix-admin-key key: admin-keyストアは、/etcd-data に永続ボリュームをマウントした StatefulSet と、
ClusterIP Service およびヘッドレス Service としてレンダリングされます。