Envoy Gateway davanti a OpenAI, con un budget mensile di token
Un team mette gpt-4o-mini di OpenAI dietro un gateway interno al cluster, vuole un tetto ai token che il gateway spende per esso ogni mese di calendario, e indirizza il suo agente al gateway anziché a OpenAI. Questo workspace compila tutto ciò in manifest Kubernetes: Envoy Gateway che serve il modello tramite Envoy AI Gateway, con core/period-budget associato, un Redis che tiene il conteggio, e un agente CrewAI che invia le sue richieste al modello tramite il gateway.
La pagina mostra anche che cosa questo gateway si rifiuta di contare: un budget in dollari statunitensi fa arrestare il build, e lo stesso fa un budget per chiamante.
Questo workspace non scrive alcuna entità di catalogo propria. I tre file di entità qui presenti — un Aggregate, un Manifest e una Release — sono tutto ciò che chiunque scrive.
Che cosa costruisce
| istanza | Component del catalogo | che cosa è qui |
|---|---|---|
edge | core/gateway/envoy-gateway | il gateway, che serve un alias, assistant, dal modello chat |
ai-controller | core/gateway/envoy-ai-gateway-operator | il controller di Envoy AI Gateway, che il gateway chiama come suo server di estensione, installato con le sei definizioni di risorse di AI Gateway |
chat | core/ai-model/openai | gpt-4o-mini di OpenAI, raggiunto come riferimento: nel cluster non gira nulla per esso |
counters | core/datastore/redis | lo store in cui il servizio di rate limiting del gateway tiene il conteggio del budget |
assistant | core/ai-agent/crewai | un agente le cui richieste al modello vanno al gateway |
certs | core/security/cert-manager | cert-manager, che emette il certificato servito dal webhook del controller |
Gli archi uses del gateway partono dal suo socket extension, verso il controller; da models, verso il modello, portando come sua credential la chiave che il gateway presenta a OpenAI; e da cache, verso lo store, portando la password che il servizio di rate limiting gli presenta. L’arco model dell’agente punta al gateway, non al modello. Un’unica associazione di Feature sul gateway, budget: l’Aggregate scrive che cosa viene contato, total_tokens, e il traffico di chi è coperto da un unico limite, gateway — tutto ciò che il gateway serve — e la Release scrive quanto e su quale durata: venti milioni di token per mese di calendario.
Il Manifest vincola ogni credenziale a k8s-existing-secret, che indirizza un carico di lavoro a un Secret già presente nel suo namespace e non ne renderizza alcuno, così nessuna chiave o password si trova nell’Aggregate, nella Release o nell’output renderizzato. I nomi dei Secret sono due parametri che la Release soddisfa, e lo slot password dello store legge lo stesso parametro della connessione cache del gateway, così lo store e il servizio che gli presenta la password nominano un unico Secret.
La Release dichiara dove gira ciascun carico di lavoro: cert-manager in cert-manager, il controller in envoy-ai-gateway-system, l’agente in assistant e il gateway in envoy-gateway-system — il controller cerca lì il piano di controllo del gateway, e il build si arresta se il gateway è collocato altrove — con lo store accanto a esso. Il modello non esegue nulla: il suo unico file, un Service che mappa un nome interno al cluster sull’host di OpenAI, non nomina alcun namespace, e il gateway raggiunge OpenAI all’endpoint che il modello pubblica anziché attraverso quel Service.
cert-manager è dichiarato, non presunto
Il webhook del controller serve un certificato emesso da cert-manager: la sua Recipe renderizza un Certificate di cert-manager e l’Issuer autofirmato che lo firma, che solo un cert-manager in esecuzione riconcilia. Il compilatore non può esaminare un cluster per vedere se lì ne gira uno, quindi il workspace dichiara cert-manager anziché presumerlo: certs si trova nell’Aggregate accanto al controller, e il build renderizza cert-manager insieme a tutto il resto.
Un cluster esegue un solo cert-manager. Se il tuo ne esegue già uno, rimuovi certs dall’Aggregate e dalla Release prima del build; il build renderizza allora gli stessi file, meno quelli di cert-manager.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example envoy-ai-gateway-token-budgetPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd envoy-ai-gateway-token-budgetBuild
aggrega build --release release.yaml --auto-pullUna release ha bisogno di un lockfile prima di eseguire il build, e i lockfile sono generati anziché distribuiti, quindi un clone appena creato non ne ha nessuno. Risolvine prima uno, oppure lascia che sia il build a crearlo:
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 risoluzione fissa i tre chart che le Recipes renderizzano — quello di Envoy Gateway e quello di Envoy AI Gateway da Docker Hub, quello di cert-manager da quay.io — quindi richiede la rete. Questo workspace risolve le entità del catalogo dal registry predefinito nominato da .aggrega-config.yaml.
Il build con --auto-pull stampa, con <workspace> al posto della cartella di questo esempio:
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>/distCon un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella dell’area di lavoro non contiene ancora una cartella `envoy-ai-gateway-token-budget`, chiama una volta lo strumento `scaffold` con `example` impostato a `envoy-ai-gateway-token-budget` e senza `dir`: scrive l’esempio in una nuova cartella `envoy-ai-gateway-token-budget`. Poi chiama lo strumento `build` con `workspace_root` impostato a `envoy-ai-gateway-token-budget`, `release` impostato a `release.yaml`, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto la build; si trovano in `envoy-ai-gateway-token-budget/dist/`.L’albero renderizzato
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.yamlIl budget non porta alcun file proprio. Ciò che fa è scritto in due dei file del gateway: dist/helm/edge/models.yaml, che contiene la route AI e le risorse che raggiungono il modello, e la configurazione del piano di controllo, dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml.
Il budget, come lo legge il gateway
Da models.yaml, la route 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"e, dallo stesso file, la policy di traffico che la limita, chiamata come la route a cui si applica:
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_tokenEcco la chiave envoy-gateway.yaml della configurazione del piano di controllo:
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: trueChe cosa leggervi:
Il costo sta sulla route AI, il limite sulla route in cui essa si trasforma. Envoy AI Gateway legge i total_tokens che ogni risposta del modello riporta e li scrive nei metadati della richiesta sotto llm_total_token: è ciò che dichiara llmRequestCosts. Il controller trasforma la route AI in una route HTTP con lo stesso nome, edge-models, e la policy di traffico si applica a quella route, così il budget copre il traffico verso il modello e nessun’altra route collegata al gateway.
Una risposta viene addebitata quando si completa. cost.request non addebita nulla all’arrivo di una richiesta; cost.response addebita i token della risposta una volta che la risposta è completa. Una richiesta viene rifiutata quando il conteggio addebitato fino a quel momento supera limit.
Un unico conteggio per l’intero gateway. shared: true mantiene un unico conteggio su tutte le regole della route — l’ambito gateway richiesto dall’associazione. Con scope: model la Recipe scrive una regola per connessione sul socket models, ciascuna corrispondente al nome del modello che una richiesta porta in x-ai-eg-model, così ogni modello viene contato a parte.
Il periodo è un’unità sull’orologio. 1mo viene scritto come unit: Month, e la configurazione indica al servizio di rate limiting di Envoy Gateway, tramite USE_CALENDAR_MONTH_RATE_LIMIT, di contare un Month dal primo giorno di un mese di calendario all’ultimo. Quell’impostazione appartiene al servizio, quindi si applica a ogni rate limit Month che questa installazione di Envoy Gateway mantiene, quello del budget e qualsiasi altro. Ogni finestra inizia in un punto fisso dell’orologio UTC anziché con una prima richiesta: un giorno alle 00:00 UTC, una settimana di giovedì.
Il conteggio risiede nello store sul socket cache. Il blocco rateLimit attiva il servizio di rate limiting proprio di Envoy Gateway, che il piano di controllo crea nel suo namespace e attiva per ogni gateway che serve, e lo indirizza al Redis che il socket cache del gateway raggiunge. Lo store pubblica il proprio host senza namespace, quindi il gateway lo qualifica con quello in cui la Release colloca lo store.
Un controllo che non riceve risposta rifiuta la richiesta. failClosed: true fa sì che Envoy rifiuti una richiesta al modello con HTTP 500 mentre lo store o il servizio di rate limiting non sono raggiungibili, o un controllo impiega più del timeout di rate limiting di Envoy, 20 ms per impostazione predefinita, anziché servirla senza contarla. Quell’impostazione appartiene al piano di controllo, quindi vale per ogni rate limit che questa installazione di Envoy Gateway mantiene, e anche un rate limit applicato a mano all’installazione fallisce in modo chiuso. La configurazione la porta solo mentre il budget è associato.
Non contiene alcuna password. Il servizio legge la password dello store come REDIS_AUTH, dal Secret che nomina la credenziale della connessione cache, counter-store-password, che risolve nel proprio namespace, quello del gateway. Lo store, counters-deployment.yaml, si avvia con --requirepass letto dallo stesso Secret.
Il percorso dall’agente al modello
Da assistant-deployment.yaml, l’env del container dell’agente:
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’agente legge le due chiavi che il gateway pubblica, che sono le due che pubblica un modello, quindi la sua Recipe le legge come leggerebbe quelle di un modello. Le variabili CREWAI_ portano i valori propri dell’agente, con i nomi che il Component CrewAI assegna loro per impostazione predefinita. L’indirizzo è il Service che Envoy Gateway crea per il piano dati del gateway, con un nome ricavato dal namespace del gateway, dal suo nome e da un hash dei due, e qualificato con envoy-gateway-system, così si risolve dal namespace dell’agente. Il nome del modello è l’alias assistant; la route invia una richiesta che lo nomina al backend del modello, chiedendo invece gpt-4o-mini.
Il backend raggiunge OpenAI all’endpoint che il modello pubblica: models.yaml contiene un Backend di Envoy Gateway per api.openai.com sulla porta 443, una policy TLS che verifica il suo certificato rispetto alle trust anchor del sistema, un AIServiceBackend per l’API di OpenAI sotto /v1, e la policy di sicurezza che presenta la chiave, edge-assistant, il cui spec è:
spec: targetRefs: - group: aigateway.envoyproxy.io kind: AIServiceBackend name: edge-assistant type: APIKey apiKey: secretRef: name: "openai-api-key"Il controller legge la chiave da quel Secret, nel namespace del gateway, sotto la chiave dati apiKey, e la invia a OpenAI come bearer token, così nessun file renderizzato la contiene e l’agente non la detiene mai. Il gateway chiama il controller all’indirizzo che il controller pubblica, qualificato con il namespace in cui la Release lo colloca — il blocco extensionManager sopra. Mentre è cablato un modello, il gateway riceve anche la policy del traffico client di Envoy AI Gateway, edge-client-buffer-limit in models.yaml, che porta a 50Mi il buffer consentito a ogni connessione in ingresso; si applica al gateway, quindi vale per ogni route collegata a esso.
Che cosa fa il gateway in fase di esecuzione
A ogni richiesta al modello il gateway chiede al servizio di rate limiting se i token addebitati finora in questo mese superano limit. Una volta che li superano, risponde alle richieste al modello con HTTP 429 fino alla fine del mese. I token di una richiesta vengono aggiunti una volta che la sua risposta è completa, quindi la richiesta che supera il limite viene servita, e così qualsiasi richiesta a cui si risponde accanto a essa. Mentre lo store o il servizio di rate limiting non sono raggiungibili, o un controllo impiega più del timeout di rate limiting di Envoy, rifiuta le richieste al modello con HTTP 500, in base all’impostazione failClosed sopra, così nessuna richiesta al modello viene ammessa mentre il suo conteggio non può essere controllato.
Ciò che ne consegue è comportamento del prodotto anziché configurazione:
- Una richiesta ammessa appena prima di un’interruzione viene comunque servita e non contata. I suoi token vengono addebitati dopo la risposta, quindi una risposta che si completa mentre lo store o il servizio non sono raggiungibili non aggiunge nulla al conteggio.
- Uno store che tiene il conteggio in memoria fa ripartire ogni finestra quando si riavvia.
core/datastore/redistiene le sue voci in memoria per impostazione predefinita, quindi uno store riavviato perde il conteggio tenuto fino a quel momento, e il resto del mese viene contato da zero. - Una risposta che non riporta alcun utilizzo non aggiunge nulla. Il conteggio è ciò che riporta ciascuna risposta; Envoy AI Gateway chiede al modello di riportare il proprio utilizzo anche alla fine di una risposta in streaming.
Che cosa arresta il build
Ognuno di questi casi è una frase che il build stampa, e che nomina che cosa cambiare:
-
Un costo in dollari statunitensi. Imposta
unit: usdnell’associazione e il build si arresta prima che venga renderizzato qualsiasi cosa:[… 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 per chiamante,
scope: caller. Il gateway distingue i chiamanti solo in base a un header che il chiamante scrive da sé, e nulla su questo percorso verifica chi sia il chiamante, quindi un chiamante che invia un nuovo valore avvierebbe un budget nuovo e uno che non ne invia alcuno non verrebbe contato. -
Qualsiasi periodo per cui il gateway non ha una finestra. Il gateway tiene un’unità intera del suo rate limit:
1s,1m,1h,1d,7d,30d,365doppure1mo, o la stessa durata scritta in altro modo, come24h. Con2h,14do2moil build si arresta. -
Un limite che non è un numero intero di token, o uno superiore a 4294967295.
-
Una seconda associazione di
core/period-budgetsul gateway, che scrive un unico budget sulla route che serve i suoi modelli. -
Nulla cablato al socket
models, il che non lascia alcuna route di modello da contare, o al socketcache, il che non lascia al conteggio alcun luogo in cui risiedere. Rimuovi solo la connessione del modello e ad arrestarsi per primo è il Component stesso del gateway, perchévalues.modelnomina un alias che nulla serve. -
Uno store sul socket
cacheche non parla il protocollo Redis — uno che pubblica un protocollo diverso daredisovalkey. -
Il gateway collocato fuori da
envoy-gateway-systemmentre il controller è cablato al suo socketextension.
Prima di applicarlo
L’albero non contiene alcun Namespace né alcun Secret, quindi un cluster che riceve dist/helm/ ha bisogno di:
- I namespace
cert-manager,envoy-ai-gateway-system,envoy-gateway-systemeassistant. - I Secret, in
envoy-gateway-system:openai-api-key, che contiene la chiave di OpenAI sotto la chiave datiapiKey, ecounter-store-password, che contiene la password dello store sottopassword. Un carico di lavoro che fa riferimento a un Secret inesistente non si avvia. - Un apply lato server per due delle definizioni di AI Gateway,
aigateway.envoyproxy.io_backendsecuritypolicies.yamleaigateway.envoyproxy.io_mcproutes.yaml, che sono più grandi della copia dell’oggetto applicato che un apply lato client registra, quindi un apply lato client le rifiuta. - Un’immagine per l’agente. La Release nomina
registry.example/crew-assistant:1.0.0; il catalogo confeziona il runtime dell’agente, e la crew che esegue è codice tuo.
Dove il compilatore non interpreta
Il compilatore convoglia nelle risorse del gateway il limite, l’unità e il costo in token come stringhe, e l’endpoint del modello, l’indirizzo dello store e l’indirizzo del controller a partire da ciò che ciascuno pubblica. Non raggiunge OpenAI, non sa se una risposta riporta i propri token e non conta nulla da sé; non verifica che i Secret esistano né che cert-manager sia in esecuzione. Ciascun arresto descritto sopra è dichiarato dalle entità proprie del catalogo, come un’asserzione nella realizzazione del budget o nel Component o nella Recipe del gateway, e nessuno di essi si basa su una qualche comprensione del traffico.
Adattarlo
- Un limite per modello. Cabla altri modelli al socket
modelse impostascope: model: ciascuno riceve una propria regola, e un proprio conteggio. - Contare un solo lato. Imposta
unit: prompt_tokensper contare ciò che il modello legge, oppurecompletion_tokensper ciò che scrive. - Inviare di nuovo una richiesta non riuscita. Associa
core/retry-policyal gateway conmax_attemptse mappala nel Manifest suhelm/retry-policy-envoy-gateway: la stessa policy di traffico,edge-models, acquisisce unretryaccanto al rate limit, perché Envoy Gateway associa una sola policy di traffico a una route. - Una finestra più breve o di lunghezza fissa. Imposta
periodnella Release su una delle durate indicate sopra:1dè un giorno a partire dalle 00:00 UTC, e30dsono 30 giorni contati dal 1º gennaio 1970 anziché un mese di calendario. Con qualsiasi periodo diverso da1mola configurazione lascia non impostata l’impostazione del mese di calendario. - Route MCP. Il controller cifra gli identificatori di sessione MCP con una chiave derivata dal seed contenuto nel Secret che
infra.mcp_session_seed_secretnomina suai-controller; se non ne è nominato alcuno, come qui, il seed è il valore predefinito pubblicato dal suo chart, quindi nominane uno prima di servire una route MCP attraverso di esso.