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

APISIX スタック — モジュールとして構成された動的 API ゲートウェイ

この例では、小規模ながら実用的なスタックである動的 API ゲートウェイを、Developer が作成した 1 つの Aggregate から、 合成された Kubernetes マニフェストへとコンパイルします。

このゲートウェイは単一のコンポーネントではありません。モジュール、つまり 2 つの単一ワークロードのコンポーネントを構成する 再利用可能なサブアグリゲートです。

  • プロキシポートでクライアントのトラフィックを終端し、ローカルな状態を 持たないゲートウェイと、
  • ゲートウェイの設定を保持し、それをボリュームに永続化する ストアである etcd です。

モジュールは、ゲートウェイからストアへの内部エッジを自ら配線し、ゲートウェイを 公開エンドポイント proxy としてエクスポートします。トップレベルの Aggregate はモジュールを名前でインポートし、 構成されたスタックをレンダリングします。オペレーターは Release でモジュールの 内部コンポーネントのサイズを指定します。

ファイル

ファイル役割
aggregate.yamlDeveloper の意図:API ゲートウェイモジュール(core/apisix)をインポートし、自身のパラメーターからゲートウェイの Admin API キーをモジュールに渡します。
manifest-helm-synth.yamlゲートウェイとストアの型を synth helm の Recipes にマッピングし、モジュールがアタッチする資格情報 Feature を、名前空間に既に存在する Secret を読み取る実現にマッピングします。
release-helm-synth.yamlKubernetes ターゲット用のオペレーターレコードです。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 アシスタントにビルドを任せることもできます。

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

Terminal window
aggrega scaffold --example apisix-stack

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

Terminal window
cd apisix-stack

ビルド

このワークスペースには .aggrega-config.yaml がないため、標準ライブラリのエンティティはハブレジストリ hub.aggrega.ai から解決され、カタログフラグは不要です。--auto-pull は、新しいクローンに欠けているロックファイルをビルド中に書き込みます。

Terminal window
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: 9080
deployment:
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: 30

Deployment はその変数を Secret から提供するため、キーはレンダリングされた どのファイルにも現れません:

env:
- name: APISIX_ADMIN_KEY
valueFrom:
secretKeyRef:
name: apisix-admin-key
key: admin-key

ストアは、/etcd-data に永続ボリュームをマウントした StatefulSet と、 ClusterIP Service およびヘッドレス Service としてレンダリングされます。