OpenAI の前段に置く Envoy Gateway と月間トークン予算
あるチームが OpenAI の gpt-4o-mini をクラスタ内のゲートウェイの背後に置き、
ゲートウェイがそのモデルに費やすトークンに暦月ごとの上限を設け、エージェントの接続先を
OpenAI ではなくゲートウェイにしたいとします。このワークスペースはそれを Kubernetes
マニフェストにコンパイルします。Envoy AI Gateway を通じてモデルを提供する Envoy Gateway に
core/period-budget をアタッチし、Redis がカウントを保持し、CrewAI エージェントが
モデルへのリクエストをゲートウェイ経由で送信します。
このページでは、このゲートウェイがカウントを拒否するものも示します。米ドル建ての予算は ビルドを停止させ、呼び出し元ごとの予算も同様にビルドを停止させます。
このワークスペースは独自のカタログエンティティを一切作成しません。 ここにある 3 つのエンティティファイル — Aggregate、Manifest、Release — が、 誰かが書くもののすべてです。
構築されるもの
| インスタンス | カタログの Component | ここでの役割 |
|---|---|---|
edge | core/gateway/envoy-gateway | ゲートウェイ。モデル chat から 1 つのエイリアス assistant を提供します |
ai-controller | core/gateway/envoy-ai-gateway-operator | Envoy AI Gateway のコントローラ。ゲートウェイが拡張サーバーとして呼び出すもので、6 つの AI Gateway リソース定義とともにインストールされます |
chat | core/ai-model/openai | OpenAI の gpt-4o-mini。参照として到達されるもので、クラスタ内ではこのために何も実行されません |
counters | core/datastore/redis | ゲートウェイのレート制限サービスが予算のカウントを保持するストア |
assistant | core/ai-agent/crewai | モデルへのリクエストがゲートウェイに送られるエージェント |
certs | core/security/cert-manager | cert-manager。コントローラの Webhook が提供する証明書を発行します |
ゲートウェイの uses エッジは、extension ソケットからコントローラへ、models からモデルへ(ゲートウェイが OpenAI に提示するキーを credential として運びます)、そして cache からストアへ(レート制限サービスがストアに提示するパスワードを運びます)と出ています。エージェントの model エッジは、モデルではなくゲートウェイを指します。ゲートウェイには Feature のアタッチメントが 1 つ、budget があります。Aggregate は何をカウントするか(total_tokens)と、1 つの制限がどのトラフィックを対象とするか(gateway、つまりゲートウェイが提供するすべて)を記述し、
Release はどれだけの量をどの期間にわたって許すか、すなわち暦月あたり 2,000 万トークンを記述します。
Manifest はすべての認証情報を k8s-existing-secret にバインドします。これはワークロードを、その名前空間にすでに存在する Secret に向けるもので、Secret を一切レンダリングしません。そのため、キーやパスワードは Aggregate にも Release にもレンダリング出力にも含まれません。Secret の名前は Release が満たす 2 つのパラメータであり、ストア自身の password スロットはゲートウェイの cache 接続と同じパラメータを読み取ります。そのため、ストアと、ストアにパスワードを提示するサービスは、同じ 1 つの Secret を指します。
Release は各ワークロードの実行場所を宣言します。cert-manager は cert-manager に、コントローラは envoy-ai-gateway-system に、エージェントは assistant に、ゲートウェイは envoy-gateway-system に配置され(コントローラはゲートウェイのコントロールプレーンをそこで探すため、ゲートウェイを他の場所に配置するとビルドは停止します)、ストアはゲートウェイと同じ場所に置かれます。モデルは何も実行しません。その唯一のファイルは、クラスタ内の名前を OpenAI のホストにマッピングする Service であり、名前空間を指定しません。また、ゲートウェイはその Service を経由するのではなく、モデルが公開するエンドポイントで OpenAI に到達します。
cert-manager は前提とせず宣言する
コントローラーの webhook は cert-manager が発行する証明書を提供します。その Recipe は cert-manager の Certificate と、それに署名する自己署名の Issuer をレンダリングしますが、これらを調整するのは稼働中の cert-manager だけです。コンパイラはクラスタを調べて cert-manager が稼働しているかどうかを確認できないため、ワークスペースは cert-manager を前提とせずに宣言します。certs は Aggregate 内でコントローラーの隣に置かれ、ビルドは他のすべてと一緒に cert-manager もレンダリングします。
1 つのクラスタで稼働する cert-manager は 1 つです。クラスタですでに cert-manager が稼働している場合は、ビルドの前に Aggregate と Release から certs を削除してください。そうすると、ビルドは cert-manager 自体のファイルを除いた同じファイルをレンダリングします。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example envoy-ai-gateway-token-budgetその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd envoy-ai-gateway-token-budgetビルド
aggrega build --release release.yaml --auto-pullrelease はビルドの前に lockfile を必要とします。lockfile は同梱されるのではなく生成されるため、クローンした直後には存在しません。先に解決するか、ビルドに作成させてください:
aggrega pull --release release.yaml --pin-sources # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the build解決では、Recipes がレンダリングする 3 つのチャート(Docker Hub から取得する Envoy Gateway と Envoy AI Gateway のチャート、quay.io から取得する cert-manager のチャート)を固定するため、ネットワークが必要です。このワークスペースは、.aggrega-config.yaml が指定するデフォルトレジストリからカタログのエンティティを解決します。
--auto-pull を付けてビルドすると、次のように出力されます(<workspace> はこの例のフォルダを表します):
Pull complete: release.lock (entities=26, source_artifacts=3, external_inputs=0)[… omitted: a notice that core/referenced-secret declares origin in both of its pillars, and the total build time, which differs per run]Build completed: 113 files written to <workspace>/distAI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `envoy-ai-gateway-token-budget` フォルダーがない場合は、`example` を `envoy-ai-gateway-token-budget` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、例が新しい `envoy-ai-gateway-token-budget` フォルダーに書き込まれます。次に、`workspace_root` を `envoy-ai-gateway-token-budget`、`release` を `release.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。ファイルは `envoy-ai-gateway-token-budget/dist/` の下にあります。レンダリングされたツリー
dist/helm/├── ai-controller-certificate-envoy-ai-gateway-system-self-signed-cert-for-mutating-webhook.yaml[… omitted: the controller's two cluster roles and their bindings]├── ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml├── ai-controller-issuer-envoy-ai-gateway-system-self-signed-issuer-for-mutating-webhook.yaml├── ai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yaml├── ai-controller-service-envoy-ai-gateway-system-ai-controller.yaml[… omitted: the controller's service account]├── ai-controller/│ ├── aigateway.envoyproxy.io_aigatewayroutes.yaml[… omitted: the other five AI Gateway resource definitions]├── assistant-deployment.yaml[… omitted: the files cert-manager's chart renders, each named certs-…]├── chat-service.yaml├── counters-default-service.yaml├── counters-deployment.yaml[… omitted: Envoy Gateway's cluster roles and their bindings]├── edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml[… omitted: the resource definitions Envoy Gateway's chart installs]├── edge-deployment-envoy-gateway-system-envoy-gateway.yaml[… omitted: the rest of Envoy Gateway's chart — its certificate job, admission configurations, roles, bindings, Service and service accounts]└── edge/ ├── gateway.yaml ├── gatewayclass.yaml └── models.yaml予算は独自のファイルを持ちません。予算の働きは、ゲートウェイの 2 つのファイルに書き込まれます。AI ルートとモデルに到達するリソースを保持する dist/helm/edge/models.yaml と、コントロールプレーンの設定である dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml です。
ゲートウェイが読み取る予算
models.yaml から、AI ルートです。
apiVersion: aigateway.envoyproxy.io/v1beta1kind: AIGatewayRoutemetadata: [… omitted: the labels and annotations every rendered resource carries] name: edge-models namespace: "envoy-gateway-system"spec: parentRefs: - name: edge kind: Gateway group: gateway.networking.k8s.io llmRequestCosts: - metadataKey: llm_total_token type: TotalToken rules: - matches: - headers: - type: Exact name: x-ai-eg-model value: "assistant" backendRefs: - name: edge-assistant modelNameOverride: "gpt-4o-mini"そして同じファイルから、それを制限するトラフィックポリシーです。名前は対象とするルートと同じです。
apiVersion: gateway.envoyproxy.io/v1alpha1kind: BackendTrafficPolicymetadata: [… omitted: the labels and annotations every rendered resource carries] name: edge-models namespace: "envoy-gateway-system"spec: targetRefs: - group: gateway.networking.k8s.io kind: HTTPRoute name: edge-models rateLimit: global: rules: - limit: requests: 20000000 unit: Month shared: true cost: request: from: Number number: 0 response: from: Metadata metadata: namespace: io.envoy.ai_gateway key: llm_total_tokenコントロールプレーンの設定の envoy-gateway.yaml キーは次のとおりです。
apiVersion: gateway.envoyproxy.io/v1alpha1kind: EnvoyGatewayextensionApis: enableBackend: true enableEnvoyPatchPolicy: trueextensionManager: hooks: xdsTranslator: post: - Translation - Cluster - Route translation: cluster: includeAll: true listener: includeAll: true route: includeAll: true secret: includeAll: true service: fqdn: hostname: ai-controller.envoy-ai-gateway-system.svc.cluster.local port: 1063gateway: controllerName: gateway.envoyproxy.io/gatewayclass-controllerlogging: level: default: infoprovider: kubernetes: rateLimitDeployment: container: env: - name: REDIS_AUTH valueFrom: secretKeyRef: key: password name: counter-store-password - name: USE_CALENDAR_MONTH_RATE_LIMIT value: "true" image: docker.io/envoyproxy/ratelimit:8fe6ea42 patch: type: StrategicMerge value: spec: template: spec: containers: - imagePullPolicy: IfNotPresent name: envoy-ratelimit shutdownManager: image: docker.io/envoyproxy/gateway:v1.9.1 type: KubernetesrateLimit: backend: redis: url: counters-default.envoy-gateway-system.svc.cluster.local:6379 type: Redis failClosed: trueここから読み取れることは次のとおりです。
コストは AI ルートに、制限はそれが変換されたルートに置かれます。 Envoy AI
Gateway は、モデルの各応答が報告する total_tokens を読み取り、リクエストのメタデータの llm_total_token に書き込みます。これが
llmRequestCosts の宣言する内容です。コントローラは AI ルートを同じ名前 edge-models の HTTP ルートに変換し、トラフィックポリシーはそのルートを対象とします。そのため、予算はモデルのトラフィックに適用され、ゲートウェイに接続された他のルートには適用されません。
応答は完了した時点で課金されます。 cost.request はリクエストの到着時には何も課金せず、cost.response は応答が完了した時点でその応答のトークンを課金します。それまでに課金されたカウントが limit を超えると、リクエストは拒否されます。
ゲートウェイ全体で 1 つのカウントです。 shared: true は、ルートのすべてのルールにわたって 1 つのカウントを保持します。これはアタッチメントが求めた gateway スコープです。
scope: model の場合、Recipe は models ソケット上の接続ごとに 1 つのルールを書き出し、各ルールはリクエストが x-ai-eg-model で指定するモデル名に一致するため、モデルごとに別々にカウントされます。
期間は時計上の単位です。 1mo は unit: Month として書き出され、設定は
USE_CALENDAR_MONTH_RATE_LIMIT を通じて、Envoy Gateway のレート制限サービスに、Month を暦月の初日から末日までとしてカウントするよう指示します。この設定はサービスに属するため、この Envoy Gateway インストールが保持するすべての Month のレート制限に適用されます。予算のものにも、それ以外のものにも適用されます。どのウィンドウも、最初のリクエストからではなく UTC の時計上の固定点から始まります。日は 00:00 UTC、週は木曜日から始まります。
カウントは cache ソケット上のストアに保持されます。 rateLimit ブロックは Envoy Gateway 自身のレート制限サービスを有効にし、ゲートウェイの cache ソケットが到達する Redis をそのサービスに指定します。このサービスはコントロールプレーンが自身の名前空間に作成し、管理するすべてのゲートウェイで有効にします。ストアは名前空間なしでホストを公開するため、ゲートウェイは Release がストアを配置する名前空間でそれを修飾します。
応答のないチェックはリクエストを拒否します。 failClosed: true により、ストアまたはレート制限サービスに到達できない間、あるいはチェックが Envoy のレート制限タイムアウト(デフォルトは 20 ms)より長くかかった場合、Envoy はモデルへのリクエストを、カウントせずに処理するのではなく、HTTP 500 で拒否します。この設定はコントロールプレーンに属するため、この Envoy
Gateway インストールが保持するすべてのレート制限に適用され、インストールに手動で適用したレート制限もフェイルクローズになります。設定にこれが含まれるのは、予算がアタッチされている間だけです。
パスワードは含まれません。 サービスは、cache 接続の認証情報が指定する Secret
counter-store-password から、ストアのパスワードを REDIS_AUTH として読み取ります。この Secret は、サービス自身の名前空間、つまりゲートウェイの名前空間で解決されます。
ストア counters-deployment.yaml は、同じ Secret から読み取った --requirepass で起動します。
エージェントからモデルへの経路
assistant-deployment.yaml から、エージェントのコンテナの env です。
env: - name: OPENAI_BASE_URL value: http://envoy-envoy-gateway-system-edge-06431a46.envoy-gateway-system.svc.cluster.local:80/v1 - name: MODEL value: assistant - name: CREWAI_ALLOW_DELEGATION value: "false" - name: CREWAI_BACKSTORY value: a help-desk agent answering customers - name: CREWAI_GOAL value: answer questions about the product - name: CREWAI_LOG_LEVEL value: DEBUG - name: CREWAI_ROLE value: support assistantエージェントはゲートウェイが公開する 2 つのキーを読み取ります。これはモデルが公開する 2 つのキーと同じであるため、エージェントの Recipe はモデルのキーを読むのと同じようにそれらを読み取ります。CREWAI_ 変数は、CrewAI Component が既定で付ける名前のもとで、エージェント自身の値を運びます。アドレスは、Envoy Gateway がゲートウェイのデータプレーン用に作成する Service であり、ゲートウェイの名前空間、その名前、およびその 2 つのハッシュから命名され、envoy-gateway-system で修飾されるため、エージェントの名前空間から解決できます。モデル名はエイリアス assistant です。ルートは、この名前を指定したリクエストをモデルのバックエンドに送り、代わりに gpt-4o-mini を要求します。
バックエンドは、モデルが公開するエンドポイントで OpenAI に到達します。
models.yaml には、ポート 443 の api.openai.com に対する Envoy Gateway の Backend、その証明書をシステムのトラストアンカーに照らして検証する TLS ポリシー、/v1 配下の OpenAI API に対する AIServiceBackend、そしてキーを提示するセキュリティポリシー edge-assistant が含まれています。そのセキュリティポリシーの spec は次のとおりです。
spec: targetRefs: - group: aigateway.envoyproxy.io kind: AIServiceBackend name: edge-assistant type: APIKey apiKey: secretRef: name: "openai-api-key"コントローラーは、ゲートウェイの名前空間にあるその Secret から、データキー apiKey の下にあるキーを読み取り、ベアラートークンとして OpenAI に送信します。そのため、レンダリングされたどのファイルにもキーは含まれず、エージェントがキーを保持することもありません。ゲートウェイは、コントローラーが公開するアドレスでコントローラーを呼び出します。このアドレスは、Release がコントローラーを配置する名前空間で修飾されます。これが上記の extensionManager ブロックです。モデルが接続されている間、ゲートウェイは Envoy AI Gateway のクライアントトラフィックポリシー(models.yaml 内の edge-client-buffer-limit)も受け取り、各受信接続に許可されるバッファを 50Mi に引き上げます。このポリシーはゲートウェイを対象とするため、ゲートウェイに接続されたすべてのルートに適用されます。
実行時にゲートウェイが行うこと
モデルへのリクエストごとに、ゲートウェイはレート制限サービスに、今月これまでに課金されたトークンが limit を超えているかどうかを問い合わせます。超えた時点から、月が終わるまでモデルへのリクエストには HTTP 429 で応答します。リクエストのトークンは応答が完了した時点で加算されるため、上限を超えるリクエストは処理され、それと並行して応答されたリクエストも同様に処理されます。ストアまたはレート制限サービスに到達できない間、あるいはチェックが Envoy のレート制限タイムアウトより長くかかった場合は、上記の failClosed 設定に従ってモデルへのリクエストを HTTP 500 で拒否します。そのため、カウントを確認できない間はモデルへのリクエストが受け付けられることはありません。
そこから生じる以下の点は、設定ではなく製品の挙動です。
- 障害の直前に受け付けられたリクエストは引き続き処理され、カウントされません。 トークンは応答の後に課金されるため、ストアまたはサービスに到達できない間に完了した応答はカウントに何も加算しません。
- カウントをメモリに保持するストアは、再起動するとすべてのウィンドウを最初からやり直します。
core/datastore/redisはデフォルトでエントリをメモリに保持するため、再起動したストアはそれまでのカウントを失い、その月の残りはゼロから数え直されます。 - 使用量を報告しない応答は何も加算しません。 カウントは各応答が報告する値です。Envoy AI Gateway は、ストリーミング応答の最後にも使用量を報告するようモデルに求めます。
ビルドを停止させるもの
以下はいずれもビルドが出力する文で、変更すべき箇所を示します。
-
米ドル建てのコスト。 アタッチメントで
unit: usdを設定すると、何もレンダリングされる前にビルドが 停止します。[… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][CATALOG_ERROR E0033]Recipe/FeatureRecipe assertionscaused by: FeatureRecipe "period-budget-envoy-gateway" instance "edge" assertion "unit_is_a_token_count": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/period-budget attachment "budget" on "edge" asks for unit usd, but core/gateway/envoy-gateway, which declares dataplane.aggrega.ai/period-budget: tokens, counts the tokens each model's reply reports and prices nothing, so it keeps no budget in US dollars; set unit to total_tokens, prompt_tokens or completion_tokens, or attach the Feature to a gateway that counts cost -
呼び出し元ごとの予算(
scope: caller)。ゲートウェイは呼び出し元自身が書き込むヘッダーによってのみ 呼び出し元を区別し、この経路上には呼び出し元が誰かを検証するものがありません。そのため、新しい値を送る呼び出し元は新たな予算を開始し、 値を送らない呼び出し元はカウントされなくなります。 -
ゲートウェイにウィンドウがない期間。 ゲートウェイはレート制限の 1 単位全体を 保持します。
1s、1m、1h、1d、7d、30d、365d、1mo、またはそれと同じ 長さを別の表記で書いたもの(24hなど)です。2h、14d、2moは停止します。 -
トークン数が整数でない上限、または 4294967295 を超える上限。
-
ゲートウェイ上の 2 つ目の
core/period-budgetアタッチメント。このアタッチメントは、モデルを提供するルートに 1 つの予算を書き込みます。 -
modelsソケットに何も接続されていない場合はカウントするモデルルートがなくなり、cacheソケットに何も接続されていない場合はカウントを保持する場所がなくなります。モデルの接続だけを外すと、ゲートウェイ自身の Component が先に停止します。values.modelが、どこからも提供されていないエイリアスを指すためです。 -
Redis プロトコルを話さない、
cacheソケット上のストア —redisまたはvalkey以外のプロトコルを公開するストア。 -
envoy-gateway-systemの外に配置されたゲートウェイ(コントローラーが そのextensionソケットに接続されている場合)。
適用する前に
ツリーには Namespace も Secret も含まれないため、
dist/helm/ を受け取るクラスタには以下が必要です。
- 名前空間
cert-manager、envoy-ai-gateway-system、envoy-gateway-system、assistant。 envoy-gateway-system内の Secret: OpenAI のキーをデータキーapiKeyに保持するopenai-api-keyと、 ストアのパスワードをpasswordに保持するcounter-store-password。存在しない Secret を参照する workload は起動しません。- 2 つの AI Gateway 定義に対するサーバーサイド apply。
aigateway.envoyproxy.io_backendsecuritypolicies.yamlとaigateway.envoyproxy.io_mcproutes.yamlは、クライアントサイド apply が記録する適用済みオブジェクトのコピーよりも大きいため、クライアントサイド apply では拒否されます。 - エージェントのイメージ。 Release は
registry.example/crew-assistant:1.0.0を指定しています。カタログはエージェントのランタイムをパッケージ化しており、それが実行する crew は独自のコードです。
コンパイラが解釈しない箇所
コンパイラは、上限、単位、トークンコストを文字列としてゲートウェイのリソースに渡し、モデルのエンドポイント、ストアのアドレス、コントローラのアドレスをそれぞれが公開するものから渡します。コンパイラは OpenAI に接続せず、応答がトークン数を報告するかどうかを知らず、自身では何も数えません。Secrets が存在することや cert-manager が稼働していることも確認しません。上記の各停止は、カタログ自身のエンティティによって、予算の実現内、またはゲートウェイの Component もしくは Recipe 内のアサーションとして宣言されたものであり、いずれもトラフィックについての理解には基づいていません。
応用する
- モデルごとの上限。
modelsソケットにさらにモデルを接続し、scope: modelを設定します。各モデルがそれぞれ独自のルールとカウントを持ちます。 - 片側だけをカウントする。 モデルが読み込む分をカウントするには
unit: prompt_tokensを、モデルが書き出す分をカウントするにはcompletion_tokensを設定します。 - 失敗したリクエストを再送する。
core/retry-policyをmax_attemptsとともにゲートウェイにアタッチし、Manifest でそれをhelm/retry-policy-envoy-gatewayにマッピングします。Envoy Gateway は 1 つのルートに 1 つのトラフィックポリシーをアタッチするため、同じトラフィックポリシーであるedge-modelsに、レート制限と並んでretryが追加されます。 - より短い、または固定長のウィンドウ。 Release の
periodを上記の長さのいずれかに設定します。1dは 00:00 UTC から始まる 1 日であり、30dは暦月ではなく 1970 年 1 月 1 日から数えた 30 日です。1mo以外の期間では、設定は暦月の設定を未設定のままにします。 - MCP ルート。 コントローラは、
ai-controller上でinfra.mcp_session_seed_secretが指定する Secret 内のシードから導出した鍵で MCP セッション識別子を暗号化します。ここでのように何も指定されていない場合、シードはそのチャートが公開しているデフォルト値になるため、このコントローラを通じて MCP ルートを提供する前に Secret を指定してください。