Envoy Gateway na frente da OpenAI, com um orçamento mensal de tokens
Uma equipe coloca o gpt-4o-mini da OpenAI atrás de um gateway interno ao cluster, quer um teto para os tokens que o gateway gasta com ele a cada mês de calendário, e aponta o seu agente para o gateway em vez de para a OpenAI. Este espaço de trabalho compila isso para manifestos do Kubernetes: o Envoy Gateway servindo o modelo por meio do Envoy AI Gateway, com core/period-budget vinculado, um Redis mantendo a contagem, e um agente CrewAI enviando as suas requisições ao modelo por meio do gateway.
A página também mostra o que este gateway se recusa a contar: um orçamento em dólares americanos interrompe o build, assim como um orçamento por chamador.
Este workspace não cria nenhuma entidade de catálogo própria. Os três arquivos de entidade daqui — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.
O que ele constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
edge | core/gateway/envoy-gateway | o gateway, servindo um alias, assistant, a partir do modelo chat |
ai-controller | core/gateway/envoy-ai-gateway-operator | o controlador do Envoy AI Gateway, que o gateway chama como seu servidor de extensão, instalado com as seis definições de recursos do AI Gateway |
chat | core/ai-model/openai | o gpt-4o-mini da OpenAI, alcançado como referência: nada é executado para ele no cluster |
counters | core/datastore/redis | o repositório no qual o serviço de limitação de taxa do gateway mantém a contagem do orçamento |
assistant | core/ai-agent/crewai | um agente cujas requisições ao modelo vão para o gateway |
certs | core/security/cert-manager | cert-manager, que emite o certificado que o webhook do controlador serve |
As arestas uses do gateway partem do seu socket extension, para o controlador; de models, para o modelo, trazendo como seu credential a chave que o gateway apresenta à OpenAI; e de cache, para o repositório, trazendo a senha que o serviço de limitação de taxa apresenta a ele. A aresta model do agente aponta para o gateway, não para o modelo. Uma única vinculação de Feature no gateway, budget: o Aggregate escreve o que é contado, total_tokens, e de quem é o tráfego que um limite cobre, gateway — tudo o que o gateway serve —, e a Release escreve quanto e ao longo de quanto tempo: vinte milhões de tokens por mês de calendário.
O Manifest vincula toda credencial a k8s-existing-secret, que aponta uma carga de trabalho para um Secret já presente no seu namespace e não renderiza nenhum, de modo que nenhuma chave ou senha está no Aggregate, na Release ou na saída renderizada. Os nomes dos Secrets são dois parâmetros que a Release preenche, e o próprio slot password do repositório lê o mesmo parâmetro que a conexão cache do gateway, de modo que o repositório e o serviço que apresenta a senha a ele nomeiam um único Secret.
A Release declara onde cada carga de trabalho é executada: o cert-manager em cert-manager, o controlador em envoy-ai-gateway-system, o agente em assistant e o gateway em envoy-gateway-system — o controlador procura ali o plano de controle do gateway, e o build é interrompido se o gateway for colocado em qualquer outro lugar —, com o repositório ao lado dele. O modelo não executa nada: o seu único arquivo, um Service que mapeia um nome interno ao cluster para o host da OpenAI, não nomeia nenhum namespace, e o gateway alcança a OpenAI no endpoint que o modelo publica em vez de por meio desse Service.
cert-manager é declarado, não presumido
O webhook do controlador serve um certificado que o cert-manager emite: a sua Recipe renderiza um Certificate do cert-manager e o Issuer autoassinado que o assina, que só um cert-manager em execução reconcilia. O compilador não pode olhar um cluster para ver se há um em execução ali, então o espaço de trabalho declara o cert-manager em vez de presumi-lo: certs fica no Aggregate ao lado do controlador, e o build renderiza o cert-manager com todo o resto.
Um cluster executa um único cert-manager. Se o seu já executa um, remova certs do Aggregate e da Release antes do build; o build então renderiza os mesmos arquivos, menos os do próprio cert-manager.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example envoy-ai-gateway-token-budgetEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd envoy-ai-gateway-token-budgetBuild
aggrega build --release release.yaml --auto-pullUma release precisa de um lockfile antes de fazer o build, e os lockfiles são gerados em vez de distribuídos, então um clone recém-feito não tem nenhum. Resolva um primeiro, ou deixe o build preenchê-lo:
aggrega pull --release release.yaml --pin-sources # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildA resolução fixa os três charts que as Recipes renderizam — o do Envoy Gateway e o do Envoy AI Gateway do Docker Hub, o do cert-manager do quay.io —, então precisa da rede. Este espaço de trabalho resolve as entidades do catálogo a partir do registro padrão que .aggrega-config.yaml nomeia.
O build com --auto-pull imprime, com <workspace> representando a pasta deste exemplo:
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>/distCom um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use somente as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do espaço de trabalho ainda não contém uma pasta `envoy-ai-gateway-token-budget`, chame uma vez a ferramenta `scaffold` com `example` definido como `envoy-ai-gateway-token-budget` e sem `dir`: ela grava o exemplo em uma nova pasta `envoy-ai-gateway-token-budget`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `envoy-ai-gateway-token-budget`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `envoy-ai-gateway-token-budget/dist/`.A árvore renderizada
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.yamlO orçamento não traz nenhum arquivo próprio. O que ele faz é escrito em dois dos arquivos do gateway: dist/helm/edge/models.yaml, que contém a rota de IA e os recursos que alcançam o modelo, e a configuração do plano de controle, dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml.
O orçamento, como o gateway o lê
De models.yaml, a rota de 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"e, do mesmo arquivo, a política de tráfego que a limita, nomeada como a rota que ela tem como alvo:
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_tokenAqui está a chave envoy-gateway.yaml da configuração do plano de controle:
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: trueO que tirar deles:
O custo fica na rota de IA, o limite na rota em que ela se transforma. O Envoy AI Gateway lê os total_tokens que cada resposta do modelo informa e os escreve nos metadados da requisição sob llm_total_token: é isso que llmRequestCosts declara. O controlador transforma a rota de IA em uma rota HTTP com o mesmo nome, edge-models, e a política de tráfego tem essa rota como alvo, de modo que o orçamento cobre o tráfego do modelo e nenhuma outra rota anexada ao gateway.
Uma resposta é cobrada quando é concluída. cost.request não cobra nada quando uma requisição chega; cost.response cobra os tokens da resposta assim que a resposta está completa. Uma requisição é recusada assim que a contagem cobrada até então excede limit.
Uma única contagem para o gateway inteiro. shared: true mantém uma única contagem em todas as regras da rota — o escopo gateway que a vinculação pediu. Com scope: model, a Recipe escreve uma regra por conexão no socket models, cada uma correspondendo ao nome do modelo que uma requisição traz em x-ai-eg-model, de modo que cada modelo é contado separadamente.
O período é uma unidade no relógio. 1mo é escrito como unit: Month, e a configuração instrui o serviço de limitação de taxa do Envoy Gateway, por meio de USE_CALENDAR_MONTH_RATE_LIMIT, a contar um Month do primeiro ao último dia de um mês de calendário. Essa configuração pertence ao serviço, então se aplica a todo limite de taxa Month que esta instalação do Envoy Gateway mantém, o do orçamento e qualquer outro. Toda janela começa em um ponto fixo do relógio UTC em vez de com uma primeira requisição: um dia às 00:00 UTC, uma semana em uma quinta-feira.
A contagem vive no repositório do socket cache. O bloco rateLimit ativa o próprio serviço de limitação de taxa do Envoy Gateway, que o plano de controle cria no seu namespace e ativa para todo gateway que serve, e o aponta para o Redis que o socket cache do gateway alcança. O repositório publica o seu host sem namespace, então o gateway o qualifica com o namespace em que a Release coloca o repositório.
Uma verificação que não recebe resposta recusa a requisição. failClosed: true faz o Envoy recusar uma requisição ao modelo com HTTP 500 enquanto o repositório ou o serviço de limitação de taxa não podem ser alcançados, ou uma verificação demora mais que o timeout de limitação de taxa do Envoy, 20 ms por padrão, em vez de servi-la e não contá-la. Essa configuração pertence ao plano de controle, então vale para todo limite de taxa que esta instalação do Envoy Gateway mantém, e um limite de taxa aplicado manualmente à instalação também falha fechado. A configuração a traz apenas enquanto o orçamento está vinculado.
Nenhuma senha está nela. O serviço lê a senha do repositório como REDIS_AUTH, do Secret que a credencial da conexão cache nomeia, counter-store-password, que ele resolve no seu próprio namespace, o do gateway. O repositório, counters-deployment.yaml, inicia com --requirepass lido do mesmo Secret.
O caminho do agente até o modelo
De assistant-deployment.yaml, o env do contêiner do 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 assistantO agente lê as duas chaves que o gateway publica, que são as duas que um modelo publica, então a sua Recipe as lê como leria as de um modelo. As variáveis CREWAI_ levam os valores próprios do agente, com os nomes que o Component do CrewAI dá a elas por padrão. O endereço é o Service que o Envoy Gateway cria para o plano de dados do gateway, nomeado a partir do namespace do gateway, do seu nome e de um hash dos dois, e qualificado com envoy-gateway-system, de modo que é resolvido a partir do namespace do agente. O nome do modelo é o alias assistant; a rota envia uma requisição que o nomeia para o backend do modelo, pedindo gpt-4o-mini em vez disso.
O backend alcança a OpenAI no endpoint que o modelo publica: models.yaml traz um Backend do Envoy Gateway para api.openai.com na porta 443, uma política TLS que verifica o seu certificado em relação às âncoras de confiança do sistema, um AIServiceBackend para a API da OpenAI sob /v1, e a política de segurança que apresenta a chave, edge-assistant, cujo spec é:
spec: targetRefs: - group: aigateway.envoyproxy.io kind: AIServiceBackend name: edge-assistant type: APIKey apiKey: secretRef: name: "openai-api-key"O controlador lê a chave desse Secret, no namespace do gateway, sob a chave de dados apiKey, e a envia à OpenAI como bearer token, de modo que nenhum arquivo renderizado a contém e o agente nunca a detém. O gateway chama o controlador no endereço que o controlador publica, qualificado com o namespace em que a Release o coloca — o bloco extensionManager acima. Enquanto um modelo está ligado, o gateway recebe também a política de tráfego de cliente do Envoy AI Gateway, edge-client-buffer-limit em models.yaml, que eleva para 50Mi o buffer permitido a cada conexão de entrada; ela tem o gateway como alvo, então se aplica a toda rota anexada a ele.
O que o gateway faz em tempo de execução
A cada requisição ao modelo, o gateway pergunta ao serviço de limitação de taxa se os tokens cobrados até agora neste mês excedem limit. Assim que excedem, ele responde às requisições ao modelo com HTTP 429 até o mês terminar. Os tokens de uma requisição são somados assim que a sua resposta está completa, então a requisição que ultrapassa o limite é servida, assim como qualquer requisição respondida ao lado dela. Enquanto o repositório ou o serviço de limitação de taxa não podem ser alcançados, ou uma verificação demora mais que o timeout de limitação de taxa do Envoy, ele recusa as requisições ao modelo com HTTP 500, conforme a configuração failClosed acima, de modo que nenhuma requisição ao modelo é admitida enquanto a sua contagem não pode ser verificada.
O que decorre disso é comportamento do produto, e não configuração:
- Uma requisição admitida pouco antes de uma interrupção ainda é servida e não é contada. Os seus tokens são cobrados depois da resposta, então uma resposta concluída enquanto o repositório ou o serviço não podem ser alcançados não acrescenta nada à contagem.
- Um repositório que mantém a contagem em memória recomeça toda janela quando é reiniciado.
core/datastore/redismantém as suas entradas em memória por padrão, então um repositório reiniciado perde a contagem mantida até então, e o resto do mês é contado a partir do zero. - Uma resposta que não informa uso não acrescenta nada. A contagem é o que cada resposta informa; o Envoy AI Gateway pede ao modelo que informe o seu uso também no final de uma resposta em streaming.
O que interrompe o build
Cada um destes casos é uma frase que o build imprime, nomeando o que mudar:
-
Um custo em dólares americanos. Defina
unit: usdna vinculação e o build é interrompido antes que qualquer coisa seja renderizada:[… 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 -
Um orçamento por chamador,
scope: caller. O gateway distingue os chamadores apenas por um cabeçalho que o próprio chamador escreve, e nada neste caminho verifica quem é o chamador, então um chamador que envie um novo valor iniciaria um orçamento novo e um que não envie nenhum não seria contado. -
Qualquer período para o qual o gateway não tem janela. Ele mantém uma unidade inteira do seu limite de taxa:
1s,1m,1h,1d,7d,30d,365dou1mo, ou a mesma duração escrita de outra forma, como24h. Com2h,14dou2mo, o build é interrompido. -
Um limite que não é um número inteiro de tokens, ou um acima de 4294967295.
-
Uma segunda vinculação de
core/period-budgetno gateway, que escreve um único orçamento na rota que serve os seus modelos. -
Nada ligado ao socket
models, o que não deixa nenhuma rota de modelo para contar, ou ao socketcache, o que não deixa à contagem nenhum lugar onde viver. Remova apenas a conexão do modelo e o próprio Component do gateway é interrompido primeiro, porquevalues.modelnomeia um alias que nada serve. -
Um repositório no socket
cacheque não fala o protocolo do Redis — um que publica um protocolo diferente deredisouvalkey. -
O gateway colocado fora de
envoy-gateway-systemenquanto o controlador está ligado ao seu socketextension.
Antes de aplicá-lo
A árvore não contém nenhum Namespace nem nenhum Secret, então um cluster que recebe dist/helm/ precisa de:
- Os namespaces
cert-manager,envoy-ai-gateway-system,envoy-gateway-systemeassistant. - Os Secrets, em
envoy-gateway-system:openai-api-key, que guarda a chave da OpenAI sob a chave de dadosapiKey, ecounter-store-password, que guarda a senha do repositório sobpassword. Uma carga de trabalho que referencia um Secret inexistente não inicia. - Um apply do lado do servidor para duas das definições do AI Gateway,
aigateway.envoyproxy.io_backendsecuritypolicies.yamleaigateway.envoyproxy.io_mcproutes.yaml, que são maiores do que a cópia do objeto aplicado que um apply do lado do cliente registra, então um apply do lado do cliente as recusa. - Uma imagem para o agente. A Release nomeia
registry.example/crew-assistant:1.0.0; o catálogo empacota o runtime do agente, e a crew que ele executa é o seu próprio código.
Onde o compilador não interpreta
O compilador canaliza o limite, a unidade e o custo em tokens para os recursos do gateway como strings, e o endpoint do modelo, o endereço do repositório e o endereço do controlador a partir do que cada um publica. Ele não acessa a OpenAI, não sabe se uma resposta informa os seus tokens e não conta nada por si mesmo; não verifica se os Secrets existem nem se o cert-manager está em execução. Cada interrupção acima é declarada pelas próprias entidades do catálogo, como uma asserção na realização do orçamento ou no Component ou na Recipe do gateway, e nenhuma delas se apoia em qualquer compreensão do tráfego.
Adaptando-o
- Um limite por modelo. Ligue mais modelos ao socket
modelse definascope: model: cada um recebe uma regra, e uma contagem, próprias. - Contar um único lado. Defina
unit: prompt_tokenspara contar o que o modelo lê, oucompletion_tokenspara o que ele escreve. - Reenviar uma requisição que falhou. Vincule
core/retry-policyao gateway commax_attemptse mapeie-a no Manifest parahelm/retry-policy-envoy-gateway: a mesma política de tráfego,edge-models, ganha umretryao lado do limite de taxa, porque o Envoy Gateway associa uma única política de tráfego a uma rota. - Uma janela mais curta ou de duração fixa. Defina
periodna Release como uma das durações acima:1dé um dia a partir das 00:00 UTC, e30dsão 30 dias contados a partir de 1º de janeiro de 1970, e não um mês de calendário. Com qualquer período que não seja1mo, a configuração deixa a definição de mês de calendário sem valor. - Rotas MCP. O controlador criptografa os identificadores de sessão MCP com uma chave derivada da semente no Secret que
infra.mcp_session_seed_secretnomeia emai-controller; sem nenhum nomeado, como aqui, a semente é o valor padrão publicado do seu chart, então nomeie um antes de servir uma rota MCP por meio dele.