Um certificado de webhook próprio: deixando de fora o Secret gerado de um chart
Este é um exemplo avançado. Ele ensina o campo omits: da Recipe, de que a maioria das Recipes nunca precisa: ele serve para uma fonte que você usa como ela é — aqui, um chart buscado de um registro — e que renderiza um documento que a sua Release não pode distribuir. Recorra a ele quando encontrar esse caso.
O workspace faz o build do plano de controle do Envoy AI Gateway, o controlador que o Envoy Gateway chama como seu servidor de extensão, por meio da Recipe da biblioteca padrão helm/envoy-ai-gateway-operator, nos dois modos que o seu certificado de webhook pode assumir. Em um deles, o chart do projeto renderiza um Secret que contém uma chave e um certificado que ele gera de novo a cada renderização, e a entrada omits: da Recipe deixa esse Secret fora do build. Mais duas Releases mostram as duas interrupções que você pode encontrar em torno do campo: a que a entrada existe para evitar, e a que uma entrada que não corresponde mais a nada produz.
O que ele constrói
Um componente, ai-controller, do tipo core/gateway/envoy-ai-gateway-operator, compilado para manifestos Kubernetes. O Aggregate é o mesmo para cada Release. Cada Release coloca o controlador em envoy-ai-gateway-system e escolhe o modo de certificado; cada Manifest escolhe a Recipe:
| Release | o seu Manifest vincula | modo de certificado | resultado |
|---|---|---|---|
release-cert-manager.yaml | helm/envoy-ai-gateway-operator, da biblioteca padrão | cert-manager | o build tem sucesso |
release-own-certificate.yaml | helm/envoy-ai-gateway-operator, da biblioteca padrão | o Secret ai-gateway-webhook-tls | o build tem sucesso, idêntico byte a byte de um build para o seguinte |
release-negative-without-omits.yaml | helm/envoy-ai-gateway-operator-without-omits, deste workspace | o Secret ai-gateway-webhook-tls | é interrompida com E0058 quando o build é feito com --verify-determinism |
release-negative-stale-omits.yaml | helm/envoy-ai-gateway-operator-stale-omits, deste workspace | o Secret ai-gateway-webhook-tls | é interrompida com E0334 |
As duas Recipes no catalog/ deste workspace são variantes didáticas da Recipe da biblioteca padrão. Cada uma obtém o mesmo chart na mesma versão e escolhe o modo de certificado pelo mesmo mapeamento: uma não tem nenhuma entrada omits:, e a outra tem uma entrada que nomeia um Secret que o chart não renderiza. Elas têm nomes próprios, então ficam ao lado da Recipe da biblioteca padrão em vez de sombreá-la, e o Manifest que uma Release nomeia decide com qual delas é feito o build.
Duas formas de dar um certificado ao webhook
O controlador executa um webhook de mutação que o servidor de API do cluster chama via TLS, então o webhook serve um certificado. O Component oferece duas formas de fornecê-lo, escolhidas por uma única chave infra, webhook_tls_secret:
- Não definida, o padrão. O chart renderiza um
Certificatedo cert-manager para o nome do Service do controlador e oIssuerautoassinado que o assina, então o cert-manager já deve estar em execução no cluster. - Definida. O webhook serve o certificado do Secret que a chave nomeia, que quem faz a implantação cria de antemão no namespace do controlador, contendo
tls.crt,tls.keyeca.crt. NenhumCertificatee nenhumIssuersão renderizados, e o cert-manager não é necessário: quando o controlador inicia, ele escreve oca.crtdo Secret na configuração do webhook como o bundle de CA com o qual o servidor de API verifica o webhook.
release-own-certificate.yaml a define:
components: ai-controller: annotations: aggrega.ai/namespace: envoy-ai-gateway-system infra: webhook_tls_secret: ai-gateway-webhook-tlsO que o chart renderiza no modo de certificado próprio
Com a chave definida, o chart do projeto monta o Secret com esse nome no pod do controlador em /certs — e também renderiza um Secret próprio com o mesmo nome, contendo um certificado de CA, um certificado e uma chave privada que ele gera enquanto renderiza. Dois builds geram duas chaves diferentes, então a saída deixa de ser idêntica byte a byte de um build para o seguinte; e aplicá-la substituiria o Secret que o operador criou pelo que o chart gerou.
O chart é obtido do registro do projeto e usado como está; uma Recipe não edita um chart obtido. Em vez disso, a Recipe da biblioteca padrão deixa o Secret de fora:
# helm/envoy-ai-gateway-operator:1.0.0, its omits: field omits: - kind: Secret name: "{{ .infra.webhook_tls_secret }}" when: '{{ ne (optional .infra "webhook_tls_secret" "") "" }}'kindenamenomeiam o documento como o chart o renderiza: umSecretcujometadata.nameé o nome que a Release definiu. O template denamelê a mesma chaveinfraque o chart recebe, então a entrada nomeia o Secret gerado seja qual for o nome que a Release lhe dê.whenfaz a entrada se aplicar apenas neste modo. No modo cert-manager o chart não renderiza nenhum Secret desse tipo; ali a condição é falsa, e uma entrada cujowhen:é falso é descartada antes que qualquer coisa seja verificada. Uma única Recipe serve os dois modos.
O resto do chart continua sendo renderizado por inteiro, e apenas o documento correspondente é descartado do que o build escreve. Deixá-lo de fora é correto aqui porque o Secret que o pod do controlador monta é o do próprio operador, criado separadamente. O campo deixa um documento de fora; ele não verifica se aquilo de que o resto da saída depende existe em outro lugar.
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 ai-gateway-own-webhook-certificateEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd ai-gateway-own-webhook-certificateBuild
aggrega build --release release-cert-manager.yaml --auto-pullaggrega build --release release-own-certificate.yaml --auto-pullaggrega build --release release-negative-without-omits.yaml --auto-pull --verify-determinism # halts; exits 1aggrega build --release release-negative-stale-omits.yaml --auto-pull # halts; exits 1.aggrega-config.yaml lista o catalog/ próprio do workspace, que contém as duas Recipes didáticas; o Component e a Recipe da biblioteca padrão são resolvidos a partir de hub.aggrega.ai, o registro padrão que ele nomeia. Com um checkout do catálogo da biblioteca padrão (onde obter um), nomeie o seu diretório aggrega-catalog com --catalog e toda entidade é resolvida a partir desses dois diretórios.
--auto-pull preenche o lockfile de cada Release durante o build; os lockfiles e a saída renderizada são gerados, não distribuídos. Resolver um lockfile obtém o chart do controlador do Docker Hub, então o primeiro build de cada Release precisa da rede.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `ai-gateway-own-webhook-certificate`, chame a ferramenta `scaffold` uma única vez com `example` definido como `ai-gateway-own-webhook-certificate` e sem `dir`: ela escreve o exemplo em uma nova pasta `ai-gateway-own-webhook-certificate`. Em seguida, chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-cert-manager.yaml`, `release-own-certificate.yaml` —, cada vez com `workspace_root` definido como `ai-gateway-own-webhook-certificate`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Depois, chame a ferramenta `cli-build`, que executa `aggrega build` e aceita sua flag `--verify-determinism`, com `workspace_root` definido como `ai-gateway-own-webhook-certificate`, `release` definido como `release-negative-without-omits.yaml`, `auto_pull` definido como true e `verify_determinism` definido como true: ele deve ser recusado, então leia para mim a recusa. Depois, chame a ferramenta `build` da mesma forma que nos dois primeiros builds com `release` definido como `release-negative-stale-omits.yaml`: ele também deve ser recusado, então leia para mim essa recusa também. Diga-me quais arquivos cada build escreveu; eles ficam em `ai-gateway-own-webhook-certificate/dist/`.Os dois modos de certificado, como renderizados
release-cert-manager.yaml, com o build feito com --auto-pull, imprime, com <workspace> representando a pasta deste exemplo:
Pull complete: release-cert-manager.lock (entities=5, source_artifacts=1, external_inputs=0)[… omitted: the total build time, which differs per run]Build completed: 16 files written to <workspace>/diste ls dist/helm então lista:
ai-controllerai-controller-certificate-envoy-ai-gateway-system-self-signed-cert-for-mutating-webhook.yamlai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yamlai-controller-deployment-envoy-ai-gateway-system-ai-controller.yamlai-controller-issuer-envoy-ai-gateway-system-self-signed-issuer-for-mutating-webhook.yamlai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yamlai-controller-service-envoy-ai-gateway-system-ai-controller.yamlai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yamlO diretório ai-controller contém as seis definições de recursos do AI Gateway que a Recipe emite ao lado do chart. release-own-certificate.yaml, com o build feito da mesma forma, imprime:
Pull complete: release-own-certificate.lock (entities=5, source_artifacts=1, external_inputs=0)[… omitted: the total build time, which differs per run]Build completed: 14 files written to <workspace>/diste ls dist/helm lista:
ai-controllerai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yamlai-controller-deployment-envoy-ai-gateway-system-ai-controller.yamlai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yamlai-controller-service-envoy-ai-gateway-system-ai-controller.yamlai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yamlA árvore do modo cert-manager contém um Certificate e um Issuer e nenhum Secret. A do modo de certificado próprio não contém nenhum dos três: nenhum Certificate e nenhum Issuer, porque o chart não renderiza nenhum dos dois nesse modo, e nenhum Secret, porque a entrada da Recipe deixou de fora aquele que o chart de fato renderizou. O que o controlador monta em vez disso é o Secret que a Release nomeou:
[… omitted: the chart's licence header, four comment lines]apiVersion: apps/v1kind: Deploymentmetadata: name: ai-controller namespace: envoy-ai-gateway-system [… omitted: the labels and annotations every rendered document carries]spec: [… omitted: the replica count, the selector, and the pod template's labels, service account, host-network setting and security settings] containers: - name: ai-gateway-helm [… omitted: the container's security settings, its image and pull policy, and its ports] args: [… omitted: the controller's logging, external-processor, gateway-namespace and endpoint arguments] - --tlsCertDir=/certs - --tlsCertName=tls.crt - --tlsKeyName=tls.key [… omitted: the controller's webhook-port, leader-election, prefix, cache, namespace, quota and session-encryption arguments] [… omitted: the probes, the environment and the resources] volumeMounts: - mountPath: /certs name: certs readOnly: true volumes: - name: certs secret: secretName: ai-gateway-webhook-tlsO controlador lê o seu certificado de /certs, o volume certs, que é o Secret ai-gateway-webhook-tls — um nome que o build repassa como está escrito e que o cluster resolve quando o pod inicia.
Os mesmos bytes de um build para o seguinte
Com um segundo build feito com --verify-determinism, release-own-certificate.yaml imprime:
[… omitted: the total build time, which differs per run]Build completed: 14 files written to <workspace>/dist--verify-determinism renderiza cada componente duas vezes a partir da mesma entrada e interrompe o build se as duas renderizações diferirem. Aqui ele passa, e a árvore que escreve é, byte a byte, a árvore que o primeiro build escreveu. As duas coisas valem porque o único documento que o chart gera do zero nunca chega à saída.
Sem a entrada: o build que verifica o determinismo é interrompido
release-negative-without-omits.yaml é a Release de certificado próprio implantada por meio de manifest-without-omits.yaml, que vincula a Recipe didática sem entrada omits:. Com o build feito com --verify-determinism:
[… omitted: the pull's lines][TRANSLATION_ERROR E0058] instance ai-controller rendering node "ai-controller" caused by: wasmengine: node "ai-controller" (provider "helm"): two renders of identical input produced different output: provider render is not deterministicO build sai com 1. As duas renderizações do controlador diferem, porque o chart gerou uma chave e um certificado diferentes a cada vez. O pull também renderiza a Release, para encontrar as entradas externas de que ela precisa fixadas, e encontra ali a mesma interrupção; é por isso que as linhas do pull omitidas trazem a frase uma segunda vez. O lockfile é escrito mesmo assim.
Com o build feito sem a flag, a mesma Release é concluída. A sua árvore contém os documentos do chart que a da Release de certificado próprio contém — menos as definições de recursos, que a Recipe didática não emite — e mais um, o Secret que o chart gerou:
apiVersion: v1kind: Secretmetadata: name: ai-gateway-webhook-tls namespace: envoy-ai-gateway-system [… omitted: the labels and annotations every rendered document carries]data: [… omitted: the three base64-encoded entries ca.crt, tls.crt and tls.key]Faça o build duas vezes e as duas árvores diferem exatamente nesses três valores. Um build comum renderiza cada componente uma vez, então escreve qualquer chave que tenha sido gerada e não percebe; é a verificação que torna a diferença visível. Aplicado, este arquivo substituiria o Secret que o operador criou.
A interrupção é descrita em A provider rendered the same input twice and produced different output (Um provedor renderizou a mesma entrada duas vezes e produziu saídas diferentes), cuja correção nomeia as duas soluções quando a diferença é um valor gerado por um chart que você usa como fonte: fornecer o valor por meio de uma configuração que o chart oferece ou, quando o documento gerado é um que a Release não deve distribuir, deixá-lo de fora com uma entrada omits: — a resposta que a Recipe da biblioteca padrão adota.
Uma entrada que não corresponde a nada
release-negative-stale-omits.yaml é a Release de certificado próprio implantada por meio de manifest-stale-omits.yaml, que vincula a Recipe didática cuja entrada nomeia o Secret pelo nome renderizado do controlador e não pela chave:
# catalog/recipe/helm/envoy-ai-gateway-operator-stale-omits/1.0.0/recipe.yaml, its omits: field omits: - kind: Secret name: "{{ .context.rendered_name }}-webhook-tls" when: '{{ ne (optional .infra "webhook_tls_secret" "") "" }}'Com o build feito:
[… omitted: the pull's lines][TRANSLATION_ERROR E0334] instance ai-controller rendering node "ai-controller" caused by: [CATALOG_ERROR] instance ai-controller an omits entry left out nothing the source rendered (node "ai-controller", provider "provider/helm:0.8.8-75-g9e6ef4e0", "envoy-ai-gateway-operator-stale-omits" omits[0], kind "Secret", name "ai-controller-webhook-tls"). correct the entry so it names something the source renders, or remove it; a source upgrade that renamed or removed it is the usual causeO provedor é nomeado com a versão do binário que executou o build, então a sua própria execução mostra ali a versão do seu binário.
O build sai com 1, e as linhas do pull trazem a mesma frase pelo mesmo motivo de antes. A mensagem se lê da esquerda para a direita como onde procurar: o componente, o provedor que o renderizou, a Recipe que declara a entrada e a posição da entrada na sua lista omits:, contando a partir de 0, e depois o kind e o nome para os quais a entrada foi resolvida. A condição when: é verdadeira neste modo, então a entrada se aplica; o seu nome é renderizado como ai-controller-webhook-tls, o chart nomeou o seu Secret ai-gateway-webhook-tls, e a entrada não deixou nada de fora.
Toda entrada que se aplica deve deixar algo de fora, e o build para em uma que não o faz, porque uma entrada que não corresponde a nada é uma afirmação sobre a fonte que não é mais verdadeira. A causa habitual é uma atualização da fonte que renomeou o documento. O documento renomeado fica então na saída com o seu novo nome — justamente o documento que a entrada foi escrita para manter de fora — e a interrupção é o que o impede de ser distribuído sem que ninguém perceba. Neste build, o Secret que o chart gerou é um desses documentos: a entrada foi escrita para mantê-lo de fora, e nomeia outra coisa. Para corrigir uma entrada, compare-a com o que a fonte renderiza agora: faça o build com a entrada removida, como release-negative-without-omits.yaml faz sem a verificação, e leia o nome no arquivo que o chart escreveu.
E0334 está listado na referência de diagnósticos como omit-matched-nothing, e descrito em An omits entry left out nothing the source rendered (Uma entrada omits não deixou de fora nada do que a fonte renderizou). O próprio campo — cada campo da entrada, o contexto do template, o que uma Release pode decidir sobre uma entrada e quais provedores o respeitam — está em Recipe → O campo omits:.
Verificando cada build
Esta autoverificação é executada em um checkout do repositório da documentação, que contém o script auxiliar de build compartilhado que ela usa; uma cópia escrita por aggrega scaffold --example não traz esse script auxiliar.
./check.shcheck.sh faz o build das quatro Releases por meio de ./build-release.sh e verifica cada resultado em relação ao que esta página descreve. Faz o build de cada Release que passa duas vezes, a segunda com --verify-determinism: os dois builds devem sair com 0 e escrever os mesmos arquivos, byte a byte, e a árvore deve conter, contando pelo kind de cada documento renderizado, um Certificate e um Issuer e nenhum Secret no modo cert-manager, e nenhum dos três no modo de certificado próprio, com o volume certs do Deployment do controlador nomeando ai-gateway-webhook-tls. Uma Release de guardrail deve sair com código diferente de zero, com exatamente uma interrupção que traga o código curto e a frase que esta página mostra para ela, e a interrupção da entrada obsoleta deve nomear a entrada. Imprime uma linha por Release e sai com 1 se algum resultado diferir, imprimindo a saída desse build:
RELEASE EXIT EXPECTED VERDICT------------------------------------------------------------------------------------------------release-cert-manager.yaml 0/0 pass OK: byte-identical twice; Certificate=1 Issuer=1 Secret=0release-own-certificate.yaml 0/0 pass OK: byte-identical twice; Certificate=0 Issuer=0 Secret=0; certs volume: ai-gateway-webhook-tlsrelease-negative-without-omits.yaml 1 halt OK: E0058, the expected sentencerelease-negative-stale-omits.yaml 1 halt OK: E0334, the expected sentence, naming "envoy-ai-gateway-operator-stale-omits" omits[0]
check: every build ended as expected.Precisa do que um único build precisa: o catálogo da biblioteca padrão e a rede para o chart. Usa o binário que ./build-release.sh resolve, então AGGREGA_BIN o escolhe; os argumentos após -- chegam a cada build. Recusa-se a iniciar enquanto houver um dist/ neste diretório, porque compara as árvores que os builds escrevem, e não deixa nenhuma para trás. O seu status de saída é o veredito inteiro, então um pipeline pode executá-lo no lugar de fazer o build de cada Release separadamente.
Onde o compilador não interpreta
O compilador não sabe o que é um Secret, o que o controlador faz com um, nem por que um chart geraria um. Ele avalia os templates da entrada como avalia qualquer template de Recipe, entrega o kind e o nome para os quais eles se resolvem ao provedor helm com os dados de entrada do componente, e o provedor descarta os documentos renderizados que correspondem e informa quantos cada entrada descartou. Ele nunca procura ai-gateway-webhook-tls em um cluster, nunca o cria e nunca verifica se ele contém as três entradas que o controlador lê: o nome é uma string que a Release fornece, canalizada para os valores do chart e para a entrada. Que o Secret exista antes de o controlador iniciar cabe ao lado que faz a implantação.
Arquivos
aggregate.yaml— o controlador do gateway de IA, o único componente; o mesmo para toda Release.manifest.yaml— vincula o controlador à Recipe da biblioteca padrão; compartilhado pelas duas Releases que passam.manifest-without-omits.yaml,manifest-stale-omits.yaml— o vinculam a uma das duas Recipes didáticas.release-cert-manager.yaml,release-own-certificate.yaml— os dois modos de certificado.release-negative-without-omits.yaml,release-negative-stale-omits.yaml— o modo de certificado próprio por meio de cada Recipe didática; ambas são interrompidas.catalog/recipe/helm/envoy-ai-gateway-operator-without-omits/1.0.0/— a Recipe didática sem entradaomits:, e oentity.lockque fixa o seu chart.catalog/recipe/helm/envoy-ai-gateway-operator-stale-omits/1.0.0/— a Recipe didática cuja entrada não corresponde a nada, e o seuentity.lock..aggrega-config.yaml— a pilha de busca do catálogo e o registro.build-release.sh— faz o build de uma Release, exibindo o comandoaggrega buildequivalente.check.sh— faz o build das quatro e verifica cada resultado.