Envoy Gateway devant OpenAI, avec un budget mensuel de tokens
Une équipe place le gpt-4o-mini d’OpenAI derrière une passerelle interne au cluster, veut un plafond sur les tokens que la passerelle dépense pour lui chaque mois calendaire, et oriente son agent vers la passerelle plutôt que vers OpenAI. Cet espace de travail compile cela en manifestes Kubernetes : Envoy Gateway servant le modèle via Envoy AI Gateway, avec core/period-budget rattaché, un Redis tenant le compteur, et un agent CrewAI envoyant ses requêtes de modèle via la passerelle.
La page montre aussi ce que cette passerelle refuse de compter : un budget en dollars américains arrête le build, tout comme un budget par appelant.
Ce workspace ne rédige aucune entité de catalogue qui lui soit propre. Les trois fichiers d’entité présents ici — un Aggregate, un Manifest et une Release — sont tout ce que quiconque écrit.
Ce qu’il construit
| instance | Component du catalogue | ce qu’il est ici |
|---|---|---|
edge | core/gateway/envoy-gateway | la passerelle, qui sert un alias, assistant, issu du modèle chat |
ai-controller | core/gateway/envoy-ai-gateway-operator | le contrôleur d’Envoy AI Gateway, que la passerelle appelle comme son serveur d’extension, installé avec les six définitions de ressources d’AI Gateway |
chat | core/ai-model/openai | le gpt-4o-mini d’OpenAI, atteint comme référence : rien ne s’exécute pour lui dans le cluster |
counters | core/datastore/redis | le magasin dans lequel le service de limitation de débit de la passerelle tient le compteur du budget |
assistant | core/ai-agent/crewai | un agent dont les requêtes de modèle vont à la passerelle |
certs | core/security/cert-manager | cert-manager, qui émet le certificat que sert le webhook du contrôleur |
Les arêtes uses de la passerelle partent de son socket extension, vers le contrôleur ; de models, vers le modèle, en portant comme credential la clé que la passerelle présente à OpenAI ; et de cache, vers le magasin, en portant le mot de passe que le service de limitation de débit lui présente. L’arête model de l’agent pointe vers la passerelle, et non vers le modèle. Un seul rattachement de Feature sur la passerelle, budget : l’Aggregate écrit ce qui est compté, total_tokens, et le trafic de qui une limite couvre, gateway — tout ce que sert la passerelle — et la Release écrit combien et sur quelle durée : vingt millions de tokens par mois calendaire.
Le Manifest lie chaque information d’identification à k8s-existing-secret, qui oriente une charge de travail vers un Secret déjà présent dans son namespace et n’en rend aucun, si bien qu’aucune clé ni aucun mot de passe ne figure dans l’Aggregate, dans la Release ou dans la sortie rendue. Les noms des Secrets sont deux paramètres que la Release remplit, et le slot password propre au magasin lit le même paramètre que la connexion cache de la passerelle, si bien que le magasin et le service qui lui présente le mot de passe nomment un seul et même Secret.
La Release déclare où s’exécute chaque charge de travail : cert-manager dans cert-manager, le contrôleur dans envoy-ai-gateway-system, l’agent dans assistant et la passerelle dans envoy-gateway-system — le contrôleur y cherche le plan de contrôle de la passerelle, et le build s’arrête si la passerelle est placée ailleurs — avec le magasin à côté d’elle. Le modèle n’exécute rien : son unique fichier, un Service qui associe un nom interne au cluster à l’hôte d’OpenAI, ne nomme aucun namespace, et la passerelle atteint OpenAI au point de terminaison que publie le modèle plutôt que par ce Service.
cert-manager est déclaré, pas supposé
Le webhook du contrôleur sert un certificat qu’émet cert-manager : sa Recipe rend un Certificate cert-manager et l’Issuer autosigné qui le signe, que seul un cert-manager en cours d’exécution réconcilie. Le compilateur ne peut pas examiner un cluster pour voir si un cert-manager y tourne, si bien que l’espace de travail déclare cert-manager plutôt que de le supposer : certs se trouve dans l’Aggregate à côté du contrôleur, et le build rend cert-manager avec tout le reste.
Un cluster exécute un seul cert-manager. Si le vôtre en exécute déjà un, retirez certs de l’Aggregate et de la Release avant le build ; le build rend alors les mêmes fichiers, moins ceux de cert-manager.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example envoy-ai-gateway-token-budgetElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd envoy-ai-gateway-token-budgetBuild
aggrega build --release release.yaml --auto-pullUne release a besoin d’un lockfile avant son build, et les lockfiles sont générés plutôt que livrés, de sorte qu’un clone neuf n’en contient aucun. Résolvez-en un d’abord, ou laissez le build le remplir :
aggrega pull --release release.yaml --pin-sources # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildLa résolution épingle les trois charts que rendent les Recipes — ceux d’Envoy Gateway et d’Envoy AI Gateway depuis Docker Hub, celui de cert-manager depuis quay.io — si bien qu’elle a besoin du réseau. Cet espace de travail résout les entités du catalogue depuis le registre par défaut que nomme .aggrega-config.yaml.
Le build avec --auto-pull affiche, <workspace> désignant le dossier de cet exemple :
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>/distAvec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `envoy-ai-gateway-token-budget`, appelez une fois l’outil `scaffold` avec `example` défini sur `envoy-ai-gateway-token-budget` et sans `dir` : il écrit l’exemple dans un nouveau dossier `envoy-ai-gateway-token-budget`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `envoy-ai-gateway-token-budget`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi les fichiers écrits par le build ; ils se trouvent sous `envoy-ai-gateway-token-budget/dist/`.L’arborescence rendue
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.yamlLe budget n’apporte aucun fichier à lui. Ce qu’il fait est écrit dans deux des fichiers de la passerelle : dist/helm/edge/models.yaml, qui contient la route d’IA et les ressources atteignant le modèle, et la configuration du plan de contrôle, dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml.
Le budget, tel que la passerelle le lit
Depuis models.yaml, la route d’IA :
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"et, depuis le même fichier, la politique de trafic qui la limite, nommée comme la route qu’elle cible :
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_tokenVoici la clé envoy-gateway.yaml de la configuration du plan de contrôle :
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: trueCe qu’il faut en retenir :
Le coût se trouve sur la route d’IA, la limite sur la route qu’elle devient. Envoy AI Gateway lit les total_tokens que déclare chaque réponse du modèle et les écrit dans les métadonnées de la requête sous llm_total_token : c’est ce que déclare llmRequestCosts. Le contrôleur transforme la route d’IA en une route HTTP du même nom, edge-models, et la politique de trafic cible cette route, si bien que le budget couvre le trafic de modèle et aucune autre route attachée à la passerelle.
Une réponse est imputée lorsqu’elle se termine. cost.request n’impute rien à l’arrivée d’une requête ; cost.response impute les tokens de la réponse une fois la réponse terminée. Une requête est refusée dès que le compteur imputé jusque-là dépasse limit.
Un seul compteur pour toute la passerelle. shared: true tient un seul compteur pour toutes les règles de la route — la portée gateway que le rattachement a demandée. Avec scope: model, la Recipe écrit une règle par connexion sur le socket models, chacune correspondant au nom de modèle qu’une requête porte dans x-ai-eg-model, si bien que chaque modèle est compté à part.
La période est une unité de l’horloge. 1mo s’écrit unit: Month, et la configuration indique au service de limitation de débit d’Envoy Gateway, via USE_CALENDAR_MONTH_RATE_LIMIT, de compter un Month du premier au dernier jour d’un mois calendaire. Ce paramètre appartient au service, si bien qu’il s’applique à toute limite de débit Month que tient cette installation d’Envoy Gateway, celle du budget comme toute autre. Chaque fenêtre commence à un point fixe de l’horloge UTC plutôt qu’avec une première requête : un jour à 00:00 UTC, une semaine un jeudi.
Le compteur vit dans le magasin du socket cache. Le bloc rateLimit active le service de limitation de débit propre à Envoy Gateway, que le plan de contrôle crée dans son namespace et active pour chaque passerelle qu’il sert, et l’oriente vers le Redis qu’atteint le socket cache de la passerelle. Le magasin publie son hôte sans namespace, si bien que la passerelle le qualifie avec celui dans lequel la Release place le magasin.
Une vérification qui ne reçoit aucune réponse refuse la requête. failClosed: true fait refuser par Envoy une requête de modèle avec HTTP 500 tant que le magasin ou le service de limitation de débit est injoignable, ou qu’une vérification dure plus longtemps que le délai de limitation de débit d’Envoy, 20 ms par défaut, plutôt que de la servir sans la compter. Ce paramètre appartient au plan de contrôle, si bien qu’il vaut pour toute limite de débit que tient cette installation d’Envoy Gateway, et qu’une limite de débit appliquée à la main à l’installation échoue aussi en mode fermé. La configuration ne le porte que tant que le budget est rattaché.
Aucun mot de passe n’y figure. Le service lit le mot de passe du magasin comme REDIS_AUTH, depuis le Secret que nomme l’information d’identification de la connexion cache, counter-store-password, qu’il résout dans son propre namespace, celui de la passerelle. Le magasin, counters-deployment.yaml, démarre avec --requirepass lu depuis le même Secret.
Le chemin de l’agent au modèle
Depuis assistant-deployment.yaml, l’env du conteneur de l’agent :
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 assistantL’agent lit les deux clés que publie la passerelle, qui sont les deux que publie un modèle, si bien que sa Recipe les lit comme elle lirait celles d’un modèle. Les variables CREWAI_ portent les valeurs propres de l’agent, sous les noms que leur donne par défaut le Component CrewAI. L’adresse est le Service qu’Envoy Gateway crée pour le plan de données de la passerelle, nommé à partir du namespace de la passerelle, de son nom et d’un hachage des deux, et qualifié avec envoy-gateway-system, si bien qu’elle se résout depuis le namespace de l’agent. Le nom du modèle est l’alias assistant ; la route envoie une requête qui le nomme au backend du modèle, en demandant gpt-4o-mini à la place.
Le backend atteint OpenAI au point de terminaison que publie le modèle : models.yaml contient un Backend Envoy Gateway pour api.openai.com sur le port 443, une politique TLS vérifiant son certificat par rapport aux ancres de confiance du système, un AIServiceBackend pour l’API OpenAI sous /v1, et la politique de sécurité présentant la clé, edge-assistant, dont la spec est :
spec: targetRefs: - group: aigateway.envoyproxy.io kind: AIServiceBackend name: edge-assistant type: APIKey apiKey: secretRef: name: "openai-api-key"Le contrôleur lit la clé depuis ce Secret, dans le namespace de la passerelle, sous la clé de données apiKey, et l’envoie à OpenAI comme bearer token, si bien qu’aucun fichier rendu ne la contient et que l’agent ne la détient jamais. La passerelle appelle le contrôleur à l’adresse que publie le contrôleur, qualifiée avec le namespace dans lequel la Release le place — le bloc extensionManager ci-dessus. Tant qu’un modèle est câblé, la passerelle reçoit aussi la politique de trafic client d’Envoy AI Gateway, edge-client-buffer-limit dans models.yaml, qui porte à 50Mi le tampon autorisé pour chaque connexion entrante ; elle cible la passerelle, si bien qu’elle s’applique à toute route attachée à celle-ci.
Ce que fait la passerelle à l’exécution
À chaque requête de modèle, la passerelle demande au service de limitation de débit si les tokens imputés jusque-là ce mois-ci dépassent limit. Dès que c’est le cas, elle répond aux requêtes de modèle avec HTTP 429 jusqu’à la fin du mois. Les tokens d’une requête sont ajoutés une fois sa réponse terminée, si bien que la requête qui franchit la limite est servie, tout comme toute requête traitée à côté d’elle. Tant que le magasin ou le service de limitation de débit est injoignable, ou qu’une vérification dure plus longtemps que le délai de limitation de débit d’Envoy, elle refuse les requêtes de modèle avec HTTP 500, en vertu du paramètre failClosed ci-dessus, si bien qu’aucune requête de modèle n’est admise tant que son compteur ne peut pas être vérifié.
Ce qui en découle relève du comportement du produit plutôt que de la configuration :
- Une requête admise juste avant une panne est quand même servie et non comptée. Ses tokens sont imputés après la réponse, si bien qu’une réponse qui se termine alors que le magasin ou le service est injoignable n’ajoute rien au compteur.
- Un magasin qui tient le compteur en mémoire recommence chaque fenêtre lorsqu’il redémarre.
core/datastore/redisgarde ses entrées en mémoire par défaut, si bien qu’un magasin redémarré perd le compteur tenu jusque-là, et le reste du mois est compté à partir de zéro. - Une réponse qui ne déclare aucune utilisation n’ajoute rien. Le compteur correspond à ce que déclare chaque réponse ; Envoy AI Gateway demande au modèle de déclarer son utilisation à la fin d’une réponse en streaming aussi.
Ce qui arrête le build
Chacun de ces cas est une phrase qu’affiche le build, nommant ce qu’il faut changer :
-
Un coût en dollars américains. Définissez
unit: usddans le rattachement et le build s’arrête avant que quoi que ce soit ne soit rendu :[… 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 -
Un budget par appelant,
scope: caller. La passerelle ne distingue les appelants que par un en-tête que l’appelant écrit lui-même, et rien sur ce chemin ne vérifie qui est l’appelant, si bien qu’un appelant envoyant une nouvelle valeur démarrerait un nouveau budget et qu’un appelant n’en envoyant aucune ne serait pas compté. -
Toute période pour laquelle la passerelle n’a pas de fenêtre. Elle tient une unité entière de sa limite de débit :
1s,1m,1h,1d,7d,30d,365dou1mo, ou la même durée écrite autrement, comme24h. Avec2h,14dou2mo, le build s’arrête. -
Une limite qui n’est pas un nombre entier de tokens, ou une limite supérieure à 4294967295.
-
Un second rattachement de
core/period-budgetsur la passerelle, qui écrit un seul budget sur la route servant ses modèles. -
Rien de câblé au socket
models, ce qui ne laisse aucune route de modèle à compter, ni au socketcache, ce qui ne laisse au compteur aucun endroit où vivre. Retirez seulement la connexion du modèle, et c’est le Component propre à la passerelle qui s’arrête en premier, parce quevalues.modelnomme un alias que rien ne sert. -
Un magasin sur le socket
cachequi ne parle pas le protocole Redis — un magasin publiant un protocole autre queredisouvalkey. -
La passerelle placée en dehors de
envoy-gateway-systemalors que le contrôleur est câblé à son socketextension.
Avant de l’appliquer
L’arborescence ne contient aucun Namespace ni aucun Secret, si bien qu’un cluster recevant dist/helm/ a besoin de :
- Les namespaces
cert-manager,envoy-ai-gateway-system,envoy-gateway-systemetassistant. - Les Secrets, dans
envoy-gateway-system:openai-api-key, contenant la clé d’OpenAI sous la clé de donnéesapiKey, etcounter-store-password, contenant le mot de passe du magasin souspassword. Une charge de travail référençant un Secret qui n’existe pas ne démarre pas. - Un apply côté serveur pour deux des définitions d’AI Gateway,
aigateway.envoyproxy.io_backendsecuritypolicies.yamletaigateway.envoyproxy.io_mcproutes.yaml, qui sont plus grandes que la copie de l’objet appliqué qu’enregistre un apply côté client, si bien qu’un apply côté client les refuse. - Une image pour l’agent. La Release nomme
registry.example/crew-assistant:1.0.0; le catalogue empaquette le runtime de l’agent, et la crew qu’il exécute est votre propre code.
Là où le compilateur n’interprète pas
Le compilateur achemine la limite, l’unité et le coût en tokens dans les ressources de la passerelle sous forme de chaînes, ainsi que le point de terminaison du modèle, l’adresse du magasin et l’adresse du contrôleur à partir de ce que chacun publie. Il n’atteint pas OpenAI, ne sait pas si une réponse déclare ses tokens et ne compte rien lui-même ; il ne vérifie pas que les Secrets existent ni que cert-manager s’exécute. Chaque arrêt ci-dessus est déclaré par les entités propres au catalogue, sous forme d’assertion dans la réalisation du budget ou dans le Component ou la Recipe de la passerelle, et aucun ne repose sur une quelconque compréhension du trafic.
L’adapter
- Une limite par modèle. Câblez d’autres modèles au socket
modelset définissezscope: model: chacun reçoit une règle, et un compteur, qui lui sont propres. - Compter un seul côté. Définissez
unit: prompt_tokenspour compter ce que lit le modèle, oucompletion_tokenspour ce qu’il écrit. - Renvoyer une requête en échec. Rattachez
core/retry-policyà la passerelle avecmax_attemptset associez-la dans le Manifest àhelm/retry-policy-envoy-gateway: la même politique de trafic,edge-models, gagne unretryà côté de la limite de débit, parce qu’Envoy Gateway attache une seule politique de trafic à une route. - Une fenêtre plus courte ou de longueur fixe. Définissez
perioddans la Release à l’une des durées ci-dessus :1dest un jour à partir de 00:00 UTC, et30dcorrespond à 30 jours comptés depuis le 1er janvier 1970 plutôt qu’à un mois calendaire. Avec toute période autre que1mo, la configuration laisse le paramètre de mois calendaire non défini. - Routes MCP. Le contrôleur chiffre les identifiants de session MCP sous une clé dérivée de la graine contenue dans le Secret que nomme
infra.mcp_session_seed_secretsurai-controller; si aucun n’est nommé, comme ici, la graine est la valeur par défaut publiée de son chart, donc nommez-en un avant de servir une route MCP par son intermédiaire.