Envoy Gateway à frente da OpenAI, com um orçamento mensal de tokens
Uma equipa 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 em 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 em manifestos do Kubernetes: o Envoy Gateway a servir o modelo através do Envoy AI Gateway, com core/period-budget anexado, um Redis que mantém a contagem, e um agente CrewAI que envia os seus pedidos ao modelo através do gateway.
A página mostra também aquilo que este gateway se recusa a contar: um orçamento em dólares americanos interrompe a compilação, tal como um orçamento por chamador.
Este workspace não cria nenhuma entidade de catálogo própria. Os três ficheiros de entidade aqui presentes — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.
O que constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
edge | core/gateway/envoy-gateway | o gateway, que serve 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 onde o serviço de limitação de taxa do gateway mantém a contagem do orçamento |
assistant | core/ai-agent/crewai | um agente cujos pedidos ao modelo vão para o gateway |
certs | core/security/cert-manager | o 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, com a chave que o gateway apresenta à OpenAI como o seu credential; e de cache, para o repositório, com a palavra-passe que o serviço de limitação de taxa lhe apresenta. A aresta model do agente aponta para o gateway, não para o modelo. Um único anexo 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 cada credencial a k8s-existing-secret, que aponta uma carga de trabalho para um Secret já presente no seu namespace e não renderiza nenhum, pelo que nenhuma chave ou palavra-passe está no Aggregate, na Release ou na saída renderizada. Os nomes dos Secrets são dois parâmetros que a Release satisfaz, e o próprio slot password do repositório lê o mesmo parâmetro que a ligação cache do gateway, pelo que o repositório e o serviço que lhe apresenta a palavra-passe nomeiam um único Secret.
A Release declara onde é executada cada carga de trabalho: 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 aí o plano de controlo do gateway, e a compilação é interrompida se o gateway for colocado noutro lugar —, com o repositório ao lado dele. O modelo não executa nada: o seu único ficheiro, 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 através desse Service.
cert-manager é declarado, não pressuposto
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 consegue olhar para um cluster para ver se aí é executado um, pelo que o espaço de trabalho declara o cert-manager em vez de o pressupor: certs fica no Aggregate ao lado do controlador, e a compilação renderiza o cert-manager com tudo o resto.
Um cluster executa um único cert-manager. Se o cluster em uso já executar um, remova certs do Aggregate e da Release antes da compilação; a compilação renderiza então os mesmos ficheiros, menos os do próprio cert-manager.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example envoy-ai-gateway-token-budgetDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd envoy-ai-gateway-token-budgetCompilação
aggrega build --release release.yaml --auto-pullUma release precisa de um lockfile antes de ser compilada, e os lockfiles são gerados em vez de distribuídos, pelo que um clone novo não tem nenhum. Resolva-se um primeiro, ou deixe-se que a compilação o preencha:
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 a partir do Docker Hub, o do cert-manager a partir do quay.io —, pelo que precisa da rede. Este espaço de trabalho resolve as entidades do catálogo a partir do registo predefinido que .aggrega-config.yaml nomeia.
A compilação com --auto-pull imprime, com <workspace> em vez da 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-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta da área de trabalho ainda não contiver 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`: esta escreve o exemplo numa 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. Indique-me que ficheiros o build escreveu; encontram-se 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 ficheiro próprio. O que faz é escrito em dois dos ficheiros 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 controlo, dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml.
O orçamento, tal 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 ficheiro, a política de tráfego que a limita, com o nome da rota a que se destina:
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_tokenEis a chave envoy-gateway.yaml da configuração do plano de controlo:
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 retirar 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 indica e escreve-os nos metadados do pedido sob llm_total_token: é isso que llmRequestCosts declara. O controlador transforma a rota de IA numa rota HTTP com o mesmo nome, edge-models, e a política de tráfego destina-se a essa rota, pelo que o orçamento cobre o tráfego do modelo e nenhuma outra rota associada ao gateway.
Uma resposta é cobrada quando termina. cost.request não cobra nada quando chega um pedido; cost.response cobra os tokens da resposta assim que a resposta está completa. Um pedido é recusado assim que a contagem cobrada até então excede limit.
Uma única contagem para todo o gateway. shared: true mantém uma única contagem em todas as regras da rota — o âmbito gateway que o anexo pediu. Com scope: model, a Recipe escreve uma regra por ligação no socket models, cada uma correspondente ao nome do modelo que um pedido traz em x-ai-eg-model, pelo que cada modelo é contado à parte.
O período é uma unidade no relógio. 1mo é escrito como unit: Month, e a configuração indica ao serviço de limitação de taxa do Envoy Gateway, através de USE_CALENDAR_MONTH_RATE_LIMIT, que conte um Month do primeiro ao último dia de um mês de calendário. Essa definição pertence ao serviço, pelo que se aplica a todos os limites de taxa Month que esta instalação do Envoy Gateway mantém, o do orçamento e qualquer outro. Cada janela começa num ponto fixo do relógio UTC em vez de com um primeiro pedido: um dia às 00:00 UTC, uma semana numa 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 controlo cria no seu namespace e ativa para cada gateway que serve, e aponta-o para o Redis que o socket cache do gateway alcança. O repositório publica o seu host sem namespace, pelo que o gateway o qualifica com o namespace em que a Release coloca o repositório.
Uma verificação que não obtém resposta recusa o pedido. failClosed: true faz o Envoy recusar um pedido ao modelo com HTTP 500 enquanto o repositório ou o serviço de limitação de taxa não puderem ser alcançados, ou uma verificação demorar mais do que o tempo limite de limitação de taxa do Envoy, 20 ms por predefinição, em vez de o servir e não o contar. Essa definição pertence ao plano de controlo, pelo que vale para todos os limites 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 só a traz enquanto o orçamento estiver anexado.
Não contém nenhuma palavra-passe. O serviço lê a palavra-passe do repositório como REDIS_AUTH, a partir do Secret que a credencial da ligação cache nomeia, counter-store-password, que resolve no seu próprio namespace, o do gateway. O repositório, counters-deployment.yaml, arranca com --requirepass lido do mesmo Secret.
O caminho do agente até ao modelo
De assistant-deployment.yaml, o env do contentor 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, pelo que a sua Recipe as lê como leria as de um modelo. As variáveis CREWAI_ transportam os valores próprios do agente, com os nomes que o Component do CrewAI lhes atribui por predefinição. O endereço é o Service que o Envoy Gateway cria para o plano de dados do gateway, com um nome formado a partir do namespace do gateway, do seu nome e de um hash dos dois, e qualificado com envoy-gateway-system, pelo que se resolve a partir do namespace do agente. O nome do modelo é o alias assistant; a rota envia um pedido que o nomeia para o backend do modelo, pedindo em vez disso gpt-4o-mini.
O backend alcança a OpenAI no endpoint que o modelo publica: models.yaml contém um Backend do Envoy Gateway para api.openai.com na porta 443, uma política TLS que verifica o seu certificado face à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 envia-a à OpenAI como bearer token, pelo que nenhum ficheiro 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 estiver 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 aumenta para 50Mi o buffer permitido a cada ligação de entrada; destina-se ao gateway, pelo que se aplica a todas as rotas a ele associadas.
O que o gateway faz em tempo de execução
Em cada pedido 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, responde aos pedidos ao modelo com HTTP 429 até ao fim do mês. Os tokens de um pedido são somados assim que a sua resposta está completa, pelo que o pedido que ultrapassa o limite é servido, tal como qualquer pedido respondido ao lado dele. Enquanto o repositório ou o serviço de limitação de taxa não puderem ser alcançados, ou uma verificação demorar mais do que o tempo limite de limitação de taxa do Envoy, recusa os pedidos ao modelo com HTTP 500, de acordo com a definição failClosed acima, pelo que nenhum pedido ao modelo é admitido enquanto a sua contagem não puder ser verificada.
O que daí decorre é comportamento do produto, e não configuração:
- Um pedido admitido pouco antes de uma interrupção continua a ser servido e não é contado. Os seus tokens são cobrados depois da resposta, pelo que uma resposta que termine enquanto o repositório ou o serviço não puderem ser alcançados não acrescenta nada à contagem.
- Um repositório que mantém a contagem em memória recomeça cada janela quando é reiniciado.
core/datastore/redismantém as suas entradas em memória por predefinição, pelo que 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 indique utilização não acrescenta nada. A contagem é aquilo que cada resposta indica; o Envoy AI Gateway pede ao modelo que indique a sua utilização também no fim de uma resposta em streaming.
O que interrompe a compilação
Cada um destes casos é uma frase que a compilação imprime, a nomear o que alterar:
-
Um custo em dólares americanos. Ao definir
unit: usdno anexo, a compilação é interrompida antes de qualquer coisa ser 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, pelo que 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 tenha janela. 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, a compilação é interrompida. -
Um limite que não é um número inteiro de tokens, ou um superior a 4294967295.
-
Um segundo anexo 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 sítio onde viver. Ao remover apenas a ligação do modelo, é o próprio Component do gateway que é 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 o aplicar
A árvore não contém nenhum Namespace nem nenhum Secret, pelo que 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 palavra-passe do repositório sobpassword. Uma carga de trabalho que referencie um Secret inexistente não arranca. - 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 regista, pelo que 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 executa é código próprio.
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. Não contacta a OpenAI, não sabe se uma resposta indica os seus tokens e não conta nada por si; 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 assenta em qualquer compreensão do tráfego.
Adaptá-lo
- Um limite por modelo. Ao ligar mais modelos ao socket
modelse definirscope: model, cada um recebe uma regra, e uma contagem, próprias. - Contar um único lado. Define-se
unit: prompt_tokenspara contar o que o modelo lê, oucompletion_tokenspara o que escreve. - Reenviar um pedido que falhou. Ao anexar
core/retry-policyao gateway commax_attemptse mapeá-la 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. Define-se
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 por definir. - Rotas MCP. O controlador cifra 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 predefinido publicado do seu chart, pelo que convém nomear um antes de servir uma rota MCP através dele.