Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Um certificado de webhook próprio: deixar de fora o Secret gerado de um chart

Este é um exemplo avançado. Ensina o campo omits: da Recipe, de que a maioria das Recipes nunca precisa: serve para uma fonte que se usa tal como está — aqui, um chart obtido de um registo — e que renderiza um documento que a Release não pode distribuir. Recorra-se a ele quando surgir esse caso.

O workspace compila o plano de controlo do Envoy AI Gateway, o controlador que o Envoy Gateway chama como o seu servidor de extensão, através da Recipe da biblioteca standard helm/envoy-ai-gateway-operator, nos dois modos que o seu certificado de webhook pode assumir. Num deles, o chart do projeto renderiza um Secret que contém uma chave e um certificado que gera de novo em cada renderização, e a entrada omits: da Recipe deixa esse Secret fora da compilação. Mais duas Releases mostram as duas interrupções que se podem encontrar em torno do campo: aquela que a entrada existe para evitar, e aquela que produz uma entrada que já não corresponde a nada.

O que 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:

Releaseo seu Manifest vinculamodo de certificadoresultado
release-cert-manager.yamlhelm/envoy-ai-gateway-operator, da biblioteca standardcert-managercompila
release-own-certificate.yamlhelm/envoy-ai-gateway-operator, da biblioteca standardo Secret ai-gateway-webhook-tlscompila, idêntico byte a byte de uma compilação para a seguinte
release-negative-without-omits.yamlhelm/envoy-ai-gateway-operator-without-omits, deste workspaceo Secret ai-gateway-webhook-tlsé interrompida com E0058 quando compilada com --verify-determinism
release-negative-stale-omits.yamlhelm/envoy-ai-gateway-operator-stale-omits, deste workspaceo Secret ai-gateway-webhook-tlsé interrompida com E0334

As duas Recipes no catalog/ deste workspace são variantes didáticas da Recipe da biblioteca standard. 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. Têm nomes próprios, pelo que ficam ao lado da Recipe da biblioteca standard em vez de a ocultarem, e o Manifest que uma Release nomeia decide com qual delas é compilada.

Duas formas de dar um certificado ao webhook

O controlador executa um webhook de mutação que o servidor de API do cluster chama através de TLS, pelo que o webhook serve um certificado. O Component oferece duas formas de o fornecer, escolhidas por uma única chave infra, webhook_tls_secret:

  • Não definida, a predefinição. O chart renderiza um Certificate do cert-manager para o nome do Service do controlador e o Issuer autoassinado que o assina, pelo que o cert-manager já tem de estar em execução no cluster.
  • Definida. O webhook serve o certificado do Secret que a chave nomeia, que quem faz a implementação cria previamente no namespace do controlador, com tls.crt, tls.key e ca.crt. Não é renderizado nenhum Certificate nem nenhum Issuer, e o cert-manager não é necessário: quando o controlador arranca, escreve o ca.crt do Secret na configuração do webhook como o bundle de CA com que o servidor de API verifica o webhook.

release-own-certificate.yaml define-a:

components:
ai-controller:
annotations:
aggrega.ai/namespace: envoy-ai-gateway-system
infra:
webhook_tls_secret: ai-gateway-webhook-tls

O 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 renderiza também um Secret seu com o mesmo nome, que contém um certificado de CA, um certificado e uma chave privada que gera durante a renderização. Duas compilações geram duas chaves diferentes, pelo que a saída deixa de ser idêntica byte a byte de uma compilação para a seguinte; e aplicá-la substituiria o Secret que o operador criou pelo que o chart gerou.

O chart é obtido do registo do projeto e usado tal como está; uma Recipe não edita um chart obtido. Em vez disso, a Recipe da biblioteca standard 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" "") "" }}'
  • kind e name nomeiam o documento tal como o chart o renderiza: um Secret cujo metadata.name é o nome que a Release definiu. O template de name lê a mesma chave infra que o chart recebe, pelo que a entrada nomeia o Secret gerado seja qual for o nome que a Release lhe dê.
  • when faz com que a entrada se aplique apenas neste modo. No modo cert-manager o chart não renderiza nenhum Secret desse tipo; aí a condição é falsa, e uma entrada cujo when: é falso é descartada antes de qualquer verificação. Uma única Recipe serve ambos os modos.

O resto do chart continua a ser renderizado por inteiro, e apenas o documento correspondente é descartado do que a compilação 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; não verifica se aquilo de que o resto da saída depende existe noutro lado.

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:

Terminal window
aggrega scaffold --example ai-gateway-own-webhook-certificate

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd ai-gateway-own-webhook-certificate

Compilação

Terminal window
aggrega build --release release-cert-manager.yaml --auto-pull
aggrega build --release release-own-certificate.yaml --auto-pull
aggrega build --release release-negative-without-omits.yaml --auto-pull --verify-determinism # halts; exits 1
aggrega 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 standard são resolvidos a partir de hub.aggrega.ai, o registo predefinido que ele nomeia. Com um checkout do catálogo da biblioteca standard (onde obter um), indique o seu diretório aggrega-catalog com --catalog e todas as entidades são resolvidas a partir desses dois diretórios.

--auto-pull preenche o lockfile de cada Release durante a compilação; os lockfiles e a saída renderizada são gerados, não distribuídos. Resolver um lockfile obtém o chart do controlador a partir do Docker Hub, pelo que a primeira compilação 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-lhe este prompt.

Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta do espaço de trabalho 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`: esta escreve o exemplo numa nova pasta `ai-gateway-own-webhook-certificate`. Em seguida, chame a ferramenta `build` uma vez para cada Release, por esta ordem — `release-cert-manager.yaml`, `release-own-certificate.yaml` —, de cada vez com `workspace_root` definido como `ai-gateway-own-webhook-certificate`, `release` definido como esse ficheiro, `auto_pull` definido como true e `write` definido como true. Depois, chame a ferramenta `cli-build`, que executa `aggrega build` e aceita a sua opção `--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: destina-se a ser recusada, por isso leia-me a recusa. Depois, chame a ferramenta `build` da mesma forma que nas duas primeiras compilações com `release` definido como `release-negative-stale-omits.yaml`: também se destina a ser recusada, por isso leia-me também essa recusa. Diga-me que ficheiros cada compilação escreveu; encontram-se em `ai-gateway-own-webhook-certificate/dist/`.

Os dois modos de certificado, tal como renderizados

release-cert-manager.yaml, compilado com --auto-pull, imprime, com <workspace> a representar 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>/dist

e ls dist/helm lista depois:

ai-controller
ai-controller-certificate-envoy-ai-gateway-system-self-signed-cert-for-mutating-webhook.yaml
ai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yaml
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
ai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yaml

O 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, compilado 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>/dist

e ls dist/helm lista:

ai-controller
ai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yaml
ai-controller-deployment-envoy-ai-gateway-system-ai-controller.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
ai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yaml

A á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 efetivamente renderizou. O que o controlador monta em vez disso é o Secret que a Release nomeou:

dist/helm/ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml
[… omitted: the chart's licence header, four comment lines]
apiVersion: apps/v1
kind: Deployment
metadata:
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-tls

O controlador lê o seu certificado a partir de /certs, o volume certs, que é o Secret ai-gateway-webhook-tls — um nome que a compilação passa tal como está escrito e que o cluster resolve quando o pod arranca.

Os mesmos bytes de uma compilação para a seguinte

Compilado uma segunda vez 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 a compilação se as duas renderizações diferirem. Aqui passa, e a árvore que escreve é, byte a byte, a árvore que a primeira compilação escreveu. Ambas as coisas se verificam porque o único documento que o chart gera de novo nunca chega à saída.

Sem a entrada: a compilação que verifica o determinismo é interrompida

release-negative-without-omits.yaml é a Release de certificado próprio implementada através de manifest-without-omits.yaml, que vincula a Recipe didática sem entrada omits:. Compilada 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 deterministic

A compilação termina com 1. As duas renderizações do controlador diferem, porque o chart gerou uma chave e um certificado diferentes de cada vez. O pull também renderiza a Release, para encontrar as entradas externas de que precisa fixadas, e encontra aí a mesma interrupção; é por isso que as linhas do pull omitidas trazem a frase uma segunda vez. O lockfile é escrito mesmo assim.

Compilada 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:

dist/helm/ai-controller-secret-envoy-ai-gateway-system-ai-gateway-webhook-tls.yaml
apiVersion: v1
kind: Secret
metadata:
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]

Ao compilá-la duas vezes, as duas árvores diferem exatamente nesses três valores. Uma compilação comum renderiza cada componente uma vez, pelo que escreve qualquer chave que tenha sido gerada e não dá por isso; é a verificação que torna a diferença visível. Aplicado, este ficheiro substituiria o Secret que o operador criou.

A interrupção é descrita em A provider rendered the same input twice and produced different output (Um fornecedor 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 usado como fonte: fornecer o valor através de uma definiçã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 standard adota.

Uma entrada que não corresponde a nada

release-negative-stale-omits.yaml é a Release de certificado próprio implementada através de manifest-stale-omits.yaml, que vincula a Recipe didática cuja entrada nomeia o Secret segundo o nome renderizado do controlador e não segundo a 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" "") "" }}'

Compilada:

[… 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 cause

O fornecedor é nomeado com a versão do binário que executou a compilação, pelo que cada execução mostra aí a versão do binário usado.

A compilação termina com 1, e as linhas do pull trazem a mesma frase pelo mesmo motivo indicado acima. A mensagem lê-se da esquerda para a direita como onde procurar: o componente, o fornecedor que o renderizou, a Recipe que declara a entrada e a posição da entrada na sua lista omits:, a contar de 0, e depois o kind e o nome em que a entrada se resolveu. A condição when: é verdadeira neste modo, pelo que a entrada se aplica; o seu nome é renderizado como ai-controller-webhook-tls, o chart chamou ao seu Secret ai-gateway-webhook-tls, e a entrada não deixou nada de fora.

Cada entrada que se aplica tem de deixar algo de fora, e a compilação para numa que não o faz, porque uma entrada que não corresponde a nada é uma afirmação sobre a fonte que deixou de ser verdadeira. A causa habitual é uma atualização da fonte que mudou o nome do documento. O documento com o novo nome está então na saída — precisamente o documento que a entrada foi escrita para manter de fora — e a interrupção é o que impede que seja distribuído sem que ninguém dê por isso. Nesta compilação, o Secret que o chart gerou é um desses documentos: a entrada foi escrita para o manter de fora, e nomeia outra coisa. Para corrigir uma entrada, compare-a com o que a fonte renderiza agora: compile com a entrada removida, como release-negative-without-omits.yaml faz sem a verificação, e leia o nome no ficheiro 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 que fornecedores o respeitam — está em Recipe → O campo omits:.

Verificar cada compilação

Esta autoverificação é executada num checkout do repositório da documentação, que contém o script auxiliar de compilação partilhado que usa; uma cópia escrita por aggrega scaffold --example não inclui esse script auxiliar.

Terminal window
./check.sh

check.sh compila as quatro Releases através de ./build-release.sh e verifica cada resultado face ao que esta página descreve. Compila duas vezes cada Release que passa, a segunda com --verify-determinism: ambas as compilações têm de terminar com 0 e escrever os mesmos ficheiros, byte a byte, e a árvore tem de 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 a nomear ai-gateway-webhook-tls. Uma Release de guardrail tem de terminar com um 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 tem de nomear a entrada. Imprime uma linha por Release e termina com 1 se algum resultado diferir, imprimindo a saída dessa compilação:

RELEASE EXIT EXPECTED VERDICT
------------------------------------------------------------------------------------------------
release-cert-manager.yaml 0/0 pass OK: byte-identical twice; Certificate=1 Issuer=1 Secret=0
release-own-certificate.yaml 0/0 pass OK: byte-identical twice; Certificate=0 Issuer=0 Secret=0; certs volume: ai-gateway-webhook-tls
release-negative-without-omits.yaml 1 halt OK: E0058, the expected sentence
release-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 uma única compilação precisa: o catálogo da biblioteca standard e a rede para o chart. Usa o binário que ./build-release.sh resolve, pelo que AGGREGA_BIN o escolhe; os argumentos após -- chegam a cada compilação. Recusa-se a arrancar enquanto existir um dist/ neste diretório, porque compara as árvores que as compilações escrevem, e não deixa nenhuma para trás. O seu estado de saída é todo o veredicto, pelo que um pipeline pode executá-lo em vez de compilar cada Release separadamente.

Onde o compilador não interpreta

O compilador não sabe o que é um Secret, o que o controlador faz com ele, nem porque é que um chart geraria um. Avalia os templates da entrada como avalia qualquer template de Recipe, entrega o kind e o nome em que se resolvem ao fornecedor helm juntamente com os dados de entrada do componente, e o fornecedor descarta os documentos renderizados que correspondem e indica quantos cada entrada descartou. Nunca procura ai-gateway-webhook-tls num cluster, nunca o cria e nunca verifica se contém as três entradas que o controlador lê: o nome é uma string que a Release fornece, encaminhada para os valores do chart e para a entrada. Que o Secret exista antes de o controlador arrancar cabe ao lado que faz a implementação.

Ficheiros

  • aggregate.yaml — o controlador do gateway de IA, o único componente; o mesmo para cada Release.
  • manifest.yaml — vincula o controlador à Recipe da biblioteca standard; partilhado pelas duas Releases que passam.
  • manifest-without-omits.yaml, manifest-stale-omits.yaml — vinculam-no 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 através 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 entrada omits:, e o entity.lock que 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 seu entity.lock.
  • .aggrega-config.yaml — a pilha de pesquisa do catálogo e o registo.
  • build-release.sh — compila uma Release, mostrando o comando aggrega build equivalente.
  • check.sh — compila as quatro e verifica cada resultado.