ゲートウェイからのみ呼び出せるモデルサーバー
クラスタ内で動作するモデルサーバーは、そのアドレスに到達したものすべてに応答します。 ネットワークポリシーのない Pod ネットワーク(Kubernetes のデフォルト)では、それはクラスタ内の すべてのワークロードを意味します。モデルの前に置かれたゲートウェイは、トラフィックが 到着することを想定された経路であって、到達できる唯一の経路ではありません。
どのコンポーネントがどのコンポーネントを呼び出すかは、Aggregate がすでに示しています。ゲートウェイの
upstream 接続がモデルサーバーを指定しています。オペレーターが Release でモデルサーバーに
アタッチする core/caller-allowlist は、その宣言された接続をクラスタネットワークのルールに変換します。
このワークスペースは、この構成を Kubernetes マニフェストにコンパイルします。名前空間 edge の
NGINX ゲートウェイ、名前空間 models の Ollama モデルサーバー、そしてアタッチメントが
モデルサーバーの隣に書き出すネットワークポリシーです。
このワークスペースは独自のカタログエンティティを一切作成しません。 ここにある 3 つのエンティティファイル — Aggregate、Manifest、Release — が、 誰かが書くもののすべてです。
誰が何を書くか
| ファイル | 作成者 | ここで記述する内容 |
|---|---|---|
aggregate.yaml | 開発者 | ゲートウェイ、モデルサーバー、およびゲートウェイからモデルサーバーへの upstream 接続 |
release.yaml | オペレーター | 2 つの名前空間、およびモデルサーバーのエントリ上の allowlist アタッチメントとその infra |
manifest.yaml | オペレーター | Kubernetes 上で各コンポーネントと Feature をどの Recipe が実現するか |
Aggregate はネットワークポリシーについて何も記述しません。開発者はゲートウェイが行う接続を宣言します。
それ以外のすべての接続をクラスターが拒否するかどうかは、この環境に対するオペレーターの判断であり、
Release の components.model.features で行われます。この Feature が受け取る入力はすべて infra、
つまりオペレーターの柱です。開発者が知っておくべきなのはその結果です。Release がこの Feature を
コンポーネントにアタッチする場所ではどこでも、Aggregate がそのコンポーネントへの uses エッジとして宣言していない呼び出しは、
ネットワークプラグインがネットワークポリシーを適用するクラスターによって拒否されます。
構築されるもの
| インスタンス | カタログの Component | namespace | ここでの役割 |
|---|---|---|---|
gateway | core/gateway/nginx | edge | クライアントが呼び出すゲートウェイ。モデルサーバーへ転送します |
model | core/ai-model/ollama | models | llama3.1 を提供するモデルサーバー |
uses エッジは 1 つです。ゲートウェイの upstream ソケットからモデルサーバーへのエッジです。Feature のアタッチメントは Release 内に 1 つあります。モデルサーバー上の allowlist、core/caller-allowlist です。Release は、クラスターがネットワークポリシーを強制することを表明し、Aggregate の外部にあるソースとして監視エージェントを 1 つ指定します。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example model-server-caller-allowlistその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd model-server-caller-allowlistビルド
aggrega build --release release.yaml --auto-pullrelease はビルドの前に lockfile を必要とします。lockfile は同梱されるのではなく生成されるため、クローンした直後には存在しません。先に解決するか、ビルドに作成させてください:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildこのワークスペースは、.aggrega-config.yaml が指定するデフォルトレジストリからカタログのエンティティを解決します。チャートリポジトリからは何も取得しません。
ビルドは次のように出力します。<workspace> はこの例のフォルダを表します。
warning: node "model" (provider "helm"): target "helm" does not support annotation aggrega.ai/namespace on artifacts-only input and ignored it[… omitted: the resolution's summary and a total build time, which differ per run]Build completed: 6 files written to <workspace>/distこの警告はポリシーに関するものです。ターゲットは Feature 自身のマニフェストを namespace に配置しないため、アタッチメントのテンプレートは、モデルサーバーの StatefulSet が出力される namespace をポリシーに書き込みます。以下の namespace: "models" がそれです。
AI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `model-server-caller-allowlist` フォルダーがない場合は、`example` を `model-server-caller-allowlist` に設定し、`dir` を指定せずに `scaffold` ツールを一度呼び出してください。これにより、例が新しい `model-server-caller-allowlist` フォルダーに書き込まれます。次に、`workspace_root` を `model-server-caller-allowlist`、`release` を `release.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。ファイルは `model-server-caller-allowlist/dist/` の下にあります。レンダリングされたツリー
dist/├── edge/helm/│ ├── gateway-default-service.yaml│ └── gateway-deployment.yaml└── models/helm/ ├── model--allowlist--networkpolicy.yaml ├── model-default-service.yaml ├── model-headless-service.yaml └── model-statefulset.yamlアタッチメントが追加するファイルはポリシーの 1 つだけです。それ以外のファイルはすべて、アタッチメントなしで同じ Release がレンダリングするものとバイト単位で同一です。
モデルサーバーに到達できるもの
dist/models/helm/model--allowlist--networkpolicy.yaml の spec 以降:
spec: podSelector: matchLabels: "app": "model" policyTypes: - Ingress ingress: - from: - namespaceSelector: matchLabels: "kubernetes.io/metadata.name": "models" podSelector: matchLabels: "app": "model" - namespaceSelector: matchLabels: "kubernetes.io/metadata.name": "edge" podSelector: matchLabels: "app": "gateway" - namespaceSelector: matchLabels: "kubernetes.io/metadata.name": "monitoring" podSelector: matchLabels: "app.kubernetes.io/name": "prometheus" ports: - port: 11434 protocol: "TCP"このポリシーは、モデルサーバーの StatefulSet が出力される namespace である models に置かれ、
モデルサーバーの pod を選択し、モデルサーバーのコンテナが宣言する唯一のポートで、
3 つの送信元からの接続を許可します:
models内の、モデルサーバー自身の pod。これにより、1 つのサーバーのレプリカ同士が 互いに到達できます。- namespace
edge内の、ゲートウェイの pod。 namespace セレクターと pod セレクターは 1 つのエントリーに置かれているため、pod は両方に一致する必要があります。 同じラベルを持つ別の namespace のワークロード(たとえば、同じ Aggregate を 別の場所で再度リリースしたもの)はゲートウェイではなく、許可されません。 - Release が指定する監視エージェント:namespace
monitoring内の、app.kubernetes.io/name: prometheusというラベルが付いた pod。
各コンポーネントの pod は、それぞれのコントローラーが書き出すセレクター
(モデルサーバーの StatefulSet では app: model、ゲートウェイの Deployment では app: gateway)で選択され、
各 namespace はそのワークロードが出力される namespace です。どちらも手作業で書き直すのではなく、
レンダリングが出力したものから読み取られます。
どちらのセレクターにもバージョンは含まれないため、新しいビルドがロールアウトされる際、
以前のビルドの pod は置き換えられるまで引き続き選択され、許可されます。
到達できないもの
- その他のすべてのワークロード。
models、edge、その他どの名前空間にあるものも含みます。monitoring内の別のエージェントも含まれます。 - イングレスコントローラー、およびクラスター外のあらゆるクライアント。 Aggregate の外にあるものは、 Release が名前を挙げない限り許可されません。この Release が挙げているのは 監視エージェントのみです。クライアントはゲートウェイを経由してモデルサーバーに到達します。 これが Aggregate の宣言する接続です。
- 11434 以外のすべてのポート。
このポリシーが制限するのは誰が接続できるかであり、接続が何を運ぶかではありません。 ゲートウェイが転送したリクエストは、ゲートウェイが送信したとおりにモデルに届きます。
ビルドが知り得ないこと
ルールが強制されるかどうか。 ネットワークポリシーはクラスタのネットワークプラグインによって強制され、強制されるのはそのプラグインがネットワークポリシーを実装している場合に限られます。プラグインが実装していないクラスタは、ポリシーを受け入れても何も強制しません。ビルドはポリシーを書き出しますが、クラスタを見ることはできません。そのため Release はアタッチメントに control_plane_present: true を記述します。これは対象クラスタがポリシーを強制するというオペレーターの表明であり、この表明がなされるまでビルドは停止します。
さらに 3 つの制限は、この Feature ではなく、ネットワークポリシーの仕組みに由来します。
- ポリシーは加算されます。 クラスタ内の別のポリシーが同じ Pod を選択している場合、いずれかのポリシーが許可する接続は許可されます。
- ゲートウェイはこのアタッチメントでは制限されません。 このアタッチメントが保護するのはモデル サーバーです。ゲートウェイに到達できる相手を制限するには、Release 内のゲートウェイのエントリにも Feature をアタッチし、そこでゲートウェイが応答するクライアントを指定します。
- 送信トラフィックには影響しません。 モデルサーバーは引き続き、 重みを取得するレジストリに到達でき、名前解決もこれまでどおり行います。
ビルドを停止させるもの
以下はいずれもビルドが出力する文で、変更すべき箇所を示します。
-
前提条件が確認されていない。 Release から
control_plane_present: trueを削除した場合です。[… omitted: what resolving the lockfile prints, the same halt among it, and the halt's heading, the template position and the assertion's own source]error calling fail: assertion failed: core/caller-allowlist attachment "allowlist" on "model" writes a network policy, which restricts connections only where the cluster's network plugin enforces network policy; once the target cluster's plugin does, affirm it by setting infra.control_plane_present to true on this attachment in the Release -
ワークロードがどの名前空間にも出力されない呼び出し元。
edge境界からaggrega.ai/namespaceアノテーションを削除すると、ゲートウェイの Deployment は名前空間なしで出力されます。[… omitted: what resolving the lockfile prints, the same halt among it, and the halt's heading, the artifact being rendered, the template position and the template's own source]error calling fail: core/caller-allowlist attachment "allowlist" on "model": "gateway" connects to "model" through its "upstream" socket, but the Deployment "gateway" it renders is emitted into no namespace, so the policy cannot name where its pods run; set aggrega.ai/namespace on the boundary holding "gateway", or on its own entry, in the Release, or have the manifest that carries it write one -
モデルサーバーのワークロードがどの名前空間にも出力されない場合も、同じ 理由によります。ポリシーは自身の名前空間内の Pod のみを選択します。
-
いずれかのワークロードで、コントローラーのセレクターを記述せず、ビルドが Pod に付与する 識別ラベルをひとつも持たないもの。たとえば、クラスターが生成するセレクターに依存する チャートの Job です。持っているすべてのラベルで選択すると、バージョンラベルが最初に変わった 時点で Pod に一致しなくなるため、ビルドは代わりに停止します。
-
レンダリングが Pod を出力しない呼び出し元またはモデルサーバー。コントローラーが後から Pod を作成するカスタムリソースで実現されるもの、またはクラスター外のアドレスで到達される ものです。このようなコンポーネントはポリシーで指定できないため、ビルドはそれを拒否する、 あるいは何も選択しないポリシーを書く代わりに停止します。
-
admitted_sources内のソースが、アドレス範囲と Pod の両方を指定している、 またはどちらも指定していない場合。
コンパイラが解釈しない箇所
コンパイラは、各レンダリングが報告したセレクター、ラベル、名前空間を文字列としてポリシーに渡します。クラスターには接続せず、そこでどのネットワークプラグインが動作しているかも、ある名前空間ですでにどのワークロードが動作しているかも把握しません。上記の各停止は、カタログ自身のエンティティによって Feature の実現の中で宣言されたものであり、いずれもクラスターに関する知識には依存していません。
応用する
- イングレスコントローラーを許可する。
admitted_sourcesに、その namespace とその Pod のラベルを含むエントリを追加します。両方を 1 つのエントリに含めることで、 その namespace 内のそれらの Pod だけが許可されます。 - アドレス範囲を許可する。
10.20.0.0/16のようなcidrを持つエントリを追加します。 - 2 つ目の呼び出し元。 Aggregate 内でその呼び出し元からモデルサーバーへの
usesエッジを追加し、 Release が宣言する namespace に配置します。次のビルドでは、アタッチメントを変更せずにそれが許可されます。 - Compose。 この Feature は Compose では実現されていません。Compose スタックはグループのすべてのサービスを 1 つのネットワークに置き、 あるサービスの設定で別のサービスをそのネットワークから外すことはできないため、Compose 上でこの Feature をバインドする Release は 実現がないために停止します。