AI Gateway ルート
aigatewayroute カスタムリソース定義 (CRD) は、複数の AI サービスバックエンドを結合し、NetScaler® Kubernetes Gateway Controller によって管理される Gateway リソースにアタッチします。これにより、Gateway のための 統合された AI API を定義する方法が提供され、ダウンストリームクライアントは単一のスキーマを使用して、プロバイダーをまたがる複数の AI バックエンドと対話できます。
NetScaler Kubernetes Gateway Controller は、
aigatewayroute に対して以下の機能を提供します。
-
Gateway API の
HTTPRouteを介した、ヘッダーベースおよびポリシーベースの AI バックエンドへのルーティング。生成されたHTTPRouteはaigatewayrouteと同じ名前を持ちます。 -
プライマリ AI バックエンドが利用できないか過負荷状態の場合に自動フェイルオーバーを可能にする、優先度ベースのモデルスピルオーバーをバックアップバックエンドに適用します。
-
マルチプロバイダー展開のためのフロントエンドとバックエンドの AI Gateway プロファイルを分離し、クライアント向けおよびアップストリームの AI サービスポリシーを個別に構成できるようにします。
-
きめ細かなトラフィック制御とリクエストまたはレスポンスの変換のための
ratelimitおよびrewritepolicyCRD のサポート。 -
AI バックエンド接続のプロトコルレベルチューニングのための
sslprofile、tcpprofile、およびhttpprofileCRD のサポート。 -
AI トラフィックパターン、トークン使用量、およびバックエンドパフォーマンスの可観測性のための、組み込みの TCP、HTTP、およびストリーミング分析。
これらのリソースはすべて、
aigatewayroute と同じ名前空間に作成されます。ExtensionRef フィルターを介して生成された HTTPRoute に NetScaler ポリシー CRD をアタッチすることで、デフォルトの動作をカスタマイズできます。
注:
マッチング条件では、モデル名に基づいたルーティング決定のために
x-ai-eg-model ヘッダーが利用可能です。モデル名はルーティング前にリクエストコンテンツから抽出されます。
aigatewayroute CRD を展開する
aigatewayroute CRD をダウンロードし、以下のコマンドを使用して展開します。
kubectl create -f https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/crd/aigateway/aigatewayroute-crd.yaml
注:
CRDデプロイメントYAMLファイルを変更しないでください。
aigatewayroute カスタムリソース定義の属性
次の表は、
aigatewayroute CRDのspecで利用可能なトップレベルの属性を一覧表示しています。
| 属性 | 説明 | サポートされている値 |
|---|---|---|
rules |
このルートがトラフィックを照合するルーティングルールのリスト。このフィールドは必須です。 | ルールの配列（最大128） |
aigatewayprofiles |
生成されたロードバランシング仮想サーバーおよびサービスグループに適用するデフォルトのAI Gatewayプロファイル。 | オブジェクト |
hostnames |
このルートを選択するためにHTTP Host ヘッダーと照合されるホスト名のセット。ワイルドカードプレフィックス (*.) はサフィックスマッチとして解釈されます。IPアドレスは許可されていません。 |
RFC 1123ホスト名の配列（最大16） |
parentRefs |
このルートがアタッチされているリソース（通常は Gateway オブジェクト）への参照。 |
配列（最大32） |
エーアイゲートウェイプロファイル属性
以下の各プロファイル参照は、
name (必須) と、aigatewayroute 名前空間にデフォルト設定されるオプションの namespace を指定します。
| 属性 | 説明 |
|---|---|
frontend |
プライマリロードバランシング仮想サーバーに適用されるAI Gatewayプロファイル。 |
spillover-frontend |
スピルオーバーロードバランシング仮想サーバーに適用されるAI Gatewayプロファイル。 |
default-backend |
バックエンド参照ごとの backend-aigatewayprofile によって上書きされない限り、すべてのバックエンドサービスグループに適用されるAI Gatewayプロファイル。 |
parentRefs 属性
次の表に
parentRefs 属性を示します。
| 属性 | 説明 | サポートされている値 |
|---|---|---|
name |
参照先の名前。このフィールドは必須です。 | 文字列 |
group |
参照先のグループ。指定されていない場合、gateway.networking.k8s.io が推測されます。 |
文字列 |
kind |
参照先の種類。 | デフォルト: Gateway |
namespace |
参照先の名前空間。デフォルトはルートのローカル名前空間です。 | 文字列 |
port |
このルートがターゲットとするネットワークポート。 | 整数 (1–65535) |
sectionName |
ターゲットリソース内のセクション名 (Gateway のリスナー名)。 |
文字列 |
ルール属性
rules の各エントリは、以下の属性をサポートします。
| 属性 | 説明 | サポートされる値 |
|---|---|---|
backendRefs |
このルールがトラフィックをルーティングするAIサービスバックエンドのリスト。 | 配列 (最大128) |
matches |
このルールがいつ適用されるかを決定する条件のリスト。パスベース、ヘッダーベース、およびポリシー式の一致をサポートします。 | 配列 (最大128) |
filters |
このルールに ExtensionRef を介してアタッチするNetScalerポリシーCRD。 |
配列 (最大16) |
timeouts |
HTTPリクエストに対して設定できるタイムアウト。 | オブジェクト |
backendRefs属性
次の表に
backendRefs 属性を示します。
| 属性 | 説明 | サポートされている値 |
|---|---|---|
name |
バックエンド Service リソースの名前。このフィールドは必須です。 |
文字列 |
group |
参照先のAPIグループ。空の場合、コアAPIグループが推論されます。 | 文字列 |
kind |
参照先のKubernetesリソースの種類。 | デフォルト: Service |
namespace |
バックエンドリソースの名前空間。デフォルトはルートのローカル名前空間です。 | 文字列 |
port |
このバックエンドに使用する宛先ポート番号。 | 整数 (1–65535) |
weight |
同じルール内の他のバックエンドと比較して、このバックエンドに送信するトラフィックの割合。 | 整数 (デフォルト 1) |
is_spillover |
このバックエンドが、プライマリバックエンドが利用できないか過負荷の場合にのみトラフィックを受信するスピルオーバーバックエンドであるかどうかを示します。1つのbackendRefのみがこれをtrueに設定できます。 |
ブール値 (デフォルト false) |
backend-aigatewayprofile |
このバックエンドのサービスグループに適用するバックエンドAI Gatewayプロファイル。スペックレベルのdefault-backendプロファイルを上書きします。 |
オブジェクト (name, namespace) |
filters |
ExtensionRefを介してアタッチする、バックエンドごとのNetScalerポリシーCRD。 |
配列 (最大 16) |
一致属性
次の表に一致属性を示します。
| 属性 | 説明 | サポートされる値 |
|---|---|---|
path |
HTTPリクエストパスのマッチャー。デフォルトは/に対するPathPrefixマッチです。 |
type: Exact, PathPrefix, RegularExpression; value: 文字列 |
headers |
HTTPリクエストヘッダーマッチャー。複数の値にはANDを使用します。 | name、value、type: Exact、RegularExpression |
policyExpression |
高度なマッチングのためのNetScalerポリシー式。ヘッダーマッチに加えて評価されます。 | 文字列 |
フィルター属性
次の表にフィルター属性を示します。
| 属性 | 説明 | サポートされている値 |
|---|---|---|
type |
フィルターの種類。現在、ExtensionRef のみがサポートされています。 |
ExtensionRef |
extensionRef |
NetScalerポリシーCRDへの参照 (group、kind、name — すべて必須)。サポートされている種類には、ratelimit、rewritepolicy、aigatewayprofile、sslprofile、tcpprofile、および httpprofile が含まれます。 |
オブジェクト |
タイムアウト属性
次の表に、タイムアウト属性を示します。
| 属性 | 説明 | サポートされている値 |
|---|---|---|
request |
ゲートウェイがHTTPリクエストに応答する最大期間。 | 期間。例: 30s |
backendRequest |
ゲートウェイからバックエンドへの個々のリクエストのタイムアウト。request より長くすることはできません。 |
期間、例えば 20s |
注:
ストリーミング応答（
stream=true を使用したチャット補完など）の場合、応答の完了に時間がかかる可能性があるため、タイムアウトを長く設定してください。
ルート設定の記述方法
aigatewayroute YAML定義で、kind を aigatewayroute に設定します。spec セクションで、ルートを Gateway にアタッチする parentRefs、フロントエンドとバックエンドのプロファイルを選択する aigatewayprofiles、およびトラフィックを照合してルーティングする1つ以上の rules を追加します。
以下のガイドラインに留意してください。
-
rulesフィールドは必須です。 -
優先度の低い値を持つバックエンドが優先されます。ルール内の最大1つのバックエンドに
is_spillover: trueを設定して、フェイルオーバーバックエンドを指定します。 -
モデル名でルーティングするには、
x-ai-eg-modelヘッダーまたはmatches内のpolicyExpressionを使用します。 -
ポリシーCRD（
ratelimit、rewritepolicyなど）をルールレベルまたはバックエンドごとにExtensionRefフィルターを介してアタッチします。
ルート設定の例
複数のバックエンドへのモデルルーティング
次の構成は、
x-ai-eg-model ヘッダーに含まれるモデル名に基づいて、リクエストを異なるバックエンドにルーティングします。
apiVersion: citrix.com/v1
kind: aigatewayroute
metadata:
name: ai-model-route
namespace: default
spec:
parentRefs:
- name: ai-gateway
sectionName: https
aigatewayprofiles:
frontend:
name: frontend-profile
default-backend:
name: backend-profile
rules:
- matches:
- headers:
- name: x-ai-eg-model
value: gpt-5
backendRefs:
- name: gpt-5-backend
port: 80
- matches:
- headers:
- name: x-ai-eg-model
value: gpt-5-codex
backendRefs:
- name: gpt-5-codex-backend
port: 80
優先度ベースのモデルスピルオーバー
次の構成は、プライマリバックエンドにトラフィックを送信し、プライマリが利用できないか過負荷の場合にバックアップバックエンドにスピルオーバーします。
apiVersion: citrix.com/v1
kind: aigatewayroute
metadata:
name: ai-spillover-route
namespace: default
spec:
parentRefs:
- name: ai-gateway
sectionName: https
aigatewayprofiles:
frontend:
name: frontend-profile
spillover-frontend:
name: spillover-frontend-profile
default-backend:
name: backend-profile
rules:
- matches:
- path:
type: PathPrefix
value: /v1/chat/completions
backendRefs:
- name: primary-backend
port: 80
weight: 1
- name: backup-backend
port: 80
is_spillover: true
backend-aigatewayprofile:
name: backup-backend-profile
timeouts:
request: 120s
backendRequest: 110s
ルールにレート制限ポリシーをアタッチする
次の構成は、
ExtensionRef フィルターを介して、ratelimit CRD をルーティングルールにアタッチします。
apiVersion: citrix.com/v1
kind: aigatewayroute
metadata:
name: ai-ratelimited-route
namespace: default
spec:
parentRefs:
- name: ai-gateway
sectionName: https
rules:
- matches:
- path:
type: PathPrefix
value: /v1/chat/completions
filters:
- type: ExtensionRef
extensionRef:
group: citrix.com
kind: ratelimit
name: token-ratelimit
backendRefs:
- name: llama-backend
port: 80
関連資料
-
AI Gateway の概要
-
モデルルーティングの構成
-
代替モデルへのスピルオーバーの構成