Un certificato webhook tutto tuo: lasciare fuori il Secret generato da un chart
Questo è un esempio avanzato. Insegna il campo omits: della Recipe, di cui la maggior parte delle Recipes non ha mai bisogno: serve per una sorgente che prendi così com’è — qui, un chart recuperato da un registry — che renderizza un documento che la tua Release non deve distribuire. Ricorrici quando incontri quel caso.
Il workspace esegue il build del control plane di Envoy AI Gateway, il controller che Envoy Gateway chiama come proprio extension server, tramite la Recipe della libreria standard helm/envoy-ai-gateway-operator, in entrambe le modalità che il suo certificato webhook può assumere. In una di esse il chart del progetto renderizza un Secret che contiene una chiave e un certificato che genera di nuovo a ogni rendering, e la voce omits: della Recipe lascia quel Secret fuori dal build. Altre due Releases mostrano i due arresti che puoi incontrare attorno al campo: quello che la voce esiste per prevenire, e quello che produce una voce che non corrisponde più a nulla.
Che cosa costruisce
Un solo componente, ai-controller, di tipo core/gateway/envoy-ai-gateway-operator, compilato in manifest Kubernetes. L’Aggregate è lo stesso per ogni Release. Ogni Release colloca il controller in envoy-ai-gateway-system e sceglie la modalità del certificato; ogni Manifest sceglie la Recipe:
| Release | il suo Manifest vincola | modalità del certificato | esito |
|---|---|---|---|
release-cert-manager.yaml | helm/envoy-ai-gateway-operator, dalla libreria standard | cert-manager | il build riesce |
release-own-certificate.yaml | helm/envoy-ai-gateway-operator, dalla libreria standard | il Secret ai-gateway-webhook-tls | il build riesce, identico byte per byte da un build al successivo |
release-negative-without-omits.yaml | helm/envoy-ai-gateway-operator-without-omits, da questo workspace | il Secret ai-gateway-webhook-tls | si arresta con E0058 quando il build viene eseguito con --verify-determinism |
release-negative-stale-omits.yaml | helm/envoy-ai-gateway-operator-stale-omits, da questo workspace | il Secret ai-gateway-webhook-tls | si arresta con E0334 |
Le due Recipes nel catalog/ di questo workspace sono varianti didattiche di quella della libreria standard. Ciascuna attinge allo stesso chart nella stessa versione e sceglie la modalità del certificato con la stessa mappatura: una non ha alcuna voce omits:, e l’altra ha una voce che nomina un Secret che il chart non renderizza. Portano nomi propri, quindi si collocano accanto alla Recipe della libreria standard anziché oscurarla, e il Manifest che una Release nomina decide con quale delle due esegue il build.
Due modi per dare un certificato al webhook
Il controller esegue un webhook mutante che l’API server del cluster chiama tramite TLS, quindi il webhook serve un certificato. Il Component offre due modi per fornirlo, scelti da un’unica chiave infra, webhook_tls_secret:
- Non impostata, il valore predefinito. Il chart renderizza un
Certificatedi cert-manager per il nome del Service del controller e l’Issuerautofirmato che lo firma, quindi cert-manager deve essere già in esecuzione nel cluster. - Impostata. Il webhook serve il certificato contenuto nel Secret nominato dalla chiave, che chi esegue la distribuzione crea in anticipo nel namespace del controller, con
tls.crt,tls.keyeca.crt. Non viene renderizzato alcunCertificatené alcunIssuer, e cert-manager non serve: all’avvio, il controller scrive ilca.crtdel Secret nella configurazione del webhook come bundle CA rispetto al quale l’API server verifica il webhook.
release-own-certificate.yaml la imposta:
components: ai-controller: annotations: aggrega.ai/namespace: envoy-ai-gateway-system infra: webhook_tls_secret: ai-gateway-webhook-tlsChe cosa renderizza il chart nella modalità con certificato proprio
Con la chiave impostata, il chart del progetto monta il Secret con quel nome nel pod del controller in /certs — e renderizza anche un proprio Secret con lo stesso nome, contenente un certificato CA, un certificato e una chiave privata che genera durante il rendering. Due build generano due chiavi diverse, quindi l’output smette di essere identico byte per byte da un build all’altro; e applicarlo sostituirebbe il Secret creato dall’operatore con quello generato dal chart.
Il chart viene scaricato dal registry del progetto e usato così com’è; una Recipe non modifica un chart scaricato. La Recipe della libreria standard lascia invece fuori il Secret:
# 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" "") "" }}'kindenamenominano il documento come lo renderizza il chart: unSecretil cuimetadata.nameè il nome impostato dalla Release. Il template dinamelegge la stessa chiaveinfrache riceve il chart, quindi la voce nomina il Secret generato comunque lo chiami la Release.whenfa sì che la voce si applichi solo in questa modalità. Nella modalità cert-manager il chart non renderizza alcun Secret del genere; lì la condizione è falsa, e una voce il cuiwhen:è falso viene scartata prima che si controlli qualsiasi cosa. Una sola Recipe serve entrambe le modalità.
Il resto del chart viene comunque renderizzato per intero, e solo il documento corrispondente viene scartato da ciò che il build scrive. Lasciarlo fuori è corretto qui perché il Secret montato dal pod del controller è quello proprio dell’operatore, creato separatamente. Il campo lascia fuori un documento; non controlla che ciò su cui si basa il resto dell’output esista da qualche altra parte.
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 ai-gateway-own-webhook-certificatePoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
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 elenca il catalog/ proprio del workspace, che contiene le due Recipes didattiche; il Component e la Recipe della libreria standard vengono risolti da hub.aggrega.ai, il registry predefinito che nomina. Con un checkout del catalogo della libreria standard (dove procurarselo), indica la sua directory aggrega-catalog con --catalog e ogni entità viene risolta da quelle due directory.
--auto-pull riempie il lockfile di ogni Release durante il build; i lockfile e l’output renderizzato sono generati, non forniti con l’esempio. Risolvere un lockfile scarica il chart del controller da Docker Hub, quindi il primo build di ogni Release richiede la rete.
Con 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 stesso alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `ai-gateway-own-webhook-certificate`, chiama una sola volta lo strumento `scaffold` con `example` impostato su `ai-gateway-own-webhook-certificate` e senza `dir`: scrive l’esempio in una nuova cartella `ai-gateway-own-webhook-certificate`. Poi chiama lo strumento `build` una volta per ogni Release, in questo ordine — `release-cert-manager.yaml`, `release-own-certificate.yaml` — ogni volta con `workspace_root` impostato su `ai-gateway-own-webhook-certificate`, `release` impostato su quel file, `auto_pull` impostato su true e `write` impostato su true. Poi chiama lo strumento `cli-build`, che esegue `aggrega build` e accetta il suo flag `--verify-determinism`, con `workspace_root` impostato su `ai-gateway-own-webhook-certificate`, `release` impostato su `release-negative-without-omits.yaml`, `auto_pull` impostato su true e `verify_determinism` impostato su true: è previsto che venga rifiutata, quindi leggimi il rifiuto. Poi chiama lo strumento `build` come per le prime due build con `release` impostato su `release-negative-stale-omits.yaml`: è previsto che venga rifiutata anche questa, quindi leggimi anche quel rifiuto. Dimmi quali file ha scritto ciascuna build; si trovano in `ai-gateway-own-webhook-certificate/dist/`.Le due modalità del certificato, come vengono renderizzate
release-cert-manager.yaml, con il build eseguito con --auto-pull, stampa, dove <workspace> sta per la cartella di questo esempio:
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 elenca poi:
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.yamlLa directory ai-controller contiene le sei definizioni di risorse di AI Gateway che la Recipe emette accanto al chart. release-own-certificate.yaml, con il build eseguito allo stesso modo, stampa:
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 elenca:
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.yamlL’albero della modalità cert-manager contiene un Certificate e un Issuer e nessun Secret. Quello della modalità con certificato proprio non contiene nessuno dei tre: nessun Certificate e nessun Issuer, perché in quella modalità il chart non renderizza né l’uno né l’altro, e nessun Secret, perché la voce della Recipe ha lasciato fuori quello che il chart ha effettivamente renderizzato. Ciò che il controller monta al suo posto è il Secret nominato dalla Release:
[… 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-tlsIl controller legge il suo certificato da /certs, il volume certs, che è il Secret ai-gateway-webhook-tls — un nome che il build lascia passare così come è scritto e che il cluster risolve all’avvio del pod.
Gli stessi byte da un build all’altro
Con un secondo build eseguito con --verify-determinism, release-own-certificate.yaml stampa:
[… omitted: the total build time, which differs per run]Build completed: 14 files written to <workspace>/dist--verify-determinism renderizza ogni componente due volte dallo stesso input e si arresta se i due rendering differiscono. Qui passa, e l’albero che scrive è byte per byte l’albero scritto dal primo build. Entrambe le cose valgono perché l’unico documento che il chart genera ex novo non raggiunge mai l’output.
Senza la voce: il build che controlla il determinismo si arresta
release-negative-without-omits.yaml è la Release con certificato proprio distribuita tramite manifest-without-omits.yaml, che vincola la Recipe didattica senza voce omits:. Con il build eseguito con --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 deterministicIl build esce con codice 1. I due rendering del controller differiscono, perché il chart ha generato ogni volta una chiave e un certificato diversi. Anche il pull renderizza la Release, per trovare eventuali input esterni di cui ha bisogno fissati, e incontra lì lo stesso arresto; è per questo che le righe del pull omesse riportano la frase una seconda volta. Il lockfile viene comunque scritto.
Con il build eseguito senza il flag, la stessa Release viene completata. Il suo albero contiene i documenti del chart che contiene quello della Release con certificato proprio — meno le definizioni di risorse, che la Recipe didattica non emette — e uno in più, il Secret generato dal chart:
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]Esegui il build due volte e i due alberi differiscono esattamente in quei tre valori. Un build ordinario renderizza ogni componente una volta, quindi scrive qualunque chiave sia stata generata e non se ne accorge; è il controllo a rendere visibile la differenza. Applicato, questo file sostituirebbe il Secret creato dall’operatore.
L’arresto è descritto in A provider rendered the same input twice and produced different output (Un provider ha renderizzato due volte lo stesso input e ha prodotto output diversi), la cui correzione nomina le due soluzioni quando la differenza è un valore generato da un chart che usi come sorgente: fornire il valore tramite un’impostazione offerta dal chart oppure, quando il documento generato è uno che la Release non deve includere, lasciarlo fuori con una voce omits: — la risposta adottata dalla Recipe della libreria standard.
Una voce che non corrisponde a nulla
release-negative-stale-omits.yaml è la Release con certificato proprio distribuita tramite manifest-stale-omits.yaml, che vincola la Recipe didattica la cui voce nomina il Secret in base al nome renderizzato del controller anziché in base alla chiave:
# 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" "") "" }}'Con il build:
[… 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 causeIl provider è nominato con la versione del binario che ha eseguito il build, quindi la tua esecuzione mostra lì la versione del tuo binario.
Il build esce con codice 1, e le righe del pull riportano la stessa frase per lo stesso motivo visto sopra. Il messaggio si legge da sinistra a destra come un’indicazione di dove guardare: il componente, il provider che lo ha renderizzato, la Recipe che dichiara la voce e la posizione della voce nel suo elenco omits:, contando da 0, e poi il kind e il nome in cui la voce si è risolta. In questa modalità la condizione when: è vera, quindi la voce si applica; il suo nome viene renderizzato come ai-controller-webhook-tls, il chart ha chiamato il suo Secret ai-gateway-webhook-tls, e la voce non ha lasciato fuori nulla.
Ogni voce che si applica deve lasciare fuori qualcosa, e il build si ferma su una che non lo fa, perché una voce che non corrisponde a nulla è un’affermazione sulla sorgente che non è più vera. La causa abituale è un aggiornamento della sorgente che ha rinominato il documento. Il documento rinominato si trova allora nell’output con il suo nuovo nome — proprio il documento che la voce era stata scritta per tenere fuori — e l’arresto è ciò che impedisce che venga distribuito senza che nessuno se ne accorga. In questo build, il Secret generato dal chart è un documento del genere: la voce era stata scritta per tenerlo fuori, e nomina qualcos’altro. Per correggere una voce, confrontala con ciò che la sorgente renderizza ora: esegui il build con la voce rimossa, come fa release-negative-without-omits.yaml senza il controllo, e leggi il nome dal file scritto dal chart.
E0334 è elencato nel riferimento della diagnostica come omit-matched-nothing, e descritto in An omits entry left out nothing the source rendered (Una voce omits non ha lasciato fuori nulla di ciò che la sorgente ha renderizzato). Il campo stesso — ogni campo della voce, il contesto del template, ciò che una Release può decidere su una voce e quali provider lo rispettano — è descritto in Recipe → Il campo omits:.
Verificare ogni build
Questo controllo automatico viene eseguito in un checkout del repository della documentazione, che contiene lo script di build condiviso che usa; una copia scritta da aggrega scaffold --example non porta con sé quello script.
./check.shcheck.sh esegue il build delle quattro Releases tramite ./build-release.sh e confronta ogni esito con quello descritto in questa pagina. Esegue due volte il build di ogni Release che passa, la seconda volta con --verify-determinism: entrambi i build devono uscire con 0 e scrivere gli stessi file, byte per byte, e l’albero deve contenere, contando per kind ogni documento renderizzato, un Certificate e un Issuer e nessun Secret nella modalità cert-manager, e nessuno dei tre nella modalità con certificato proprio, con il volume certs del Deployment del controller che nomina ai-gateway-webhook-tls. Una Release di guardrail deve uscire con un codice diverso da zero con esattamente un arresto che porta il codice breve e la frase che questa pagina mostra per essa, e l’arresto della voce obsoleta deve nominare la voce. Stampa una riga per Release ed esce con 1 se un esito differisce, stampando l’output di quel 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.Richiede ciò che richiede un singolo build: il catalogo della libreria standard e la rete per il chart. Usa il binario che risolve ./build-release.sh, quindi è AGGREGA_BIN a sceglierlo; gli argomenti dopo -- raggiungono ogni build. Si rifiuta di partire finché in questa directory si trova una dist/, perché confronta gli alberi scritti dai build, e non ne lascia nessuno dietro di sé. Il suo stato di uscita è l’intero verdetto, quindi una pipeline può eseguirlo al posto di eseguire il build di ogni Release separatamente.
Dove il compilatore non interpreta
Il compilatore non sa che cos’è un Secret, che cosa ne fa il controller, né perché un chart ne genererebbe uno. Valuta i template della voce come valuta qualsiasi template di una Recipe, passa il kind e il nome in cui si risolvono al provider helm insieme all’input del componente, e il provider scarta i documenti renderizzati che corrispondono e riporta quanti ne ha scartati ciascuna voce. Non cerca mai ai-gateway-webhook-tls in un cluster, non lo crea mai e non controlla mai che contenga le tre voci che il controller legge: il nome è una stringa fornita dalla Release, convogliata nei valori del chart e nella voce. Che il Secret esista prima dell’avvio del controller spetta a chi esegue la distribuzione.
File
aggregate.yaml— il controller dell’AI gateway, l’unico componente; lo stesso per ogni Release.manifest.yaml— vincola il controller alla Recipe della libreria standard; condiviso dalle due Releases che passano.manifest-without-omits.yaml,manifest-stale-omits.yaml— lo vincolano a una delle due Recipes didattiche.release-cert-manager.yaml,release-own-certificate.yaml— le due modalità del certificato.release-negative-without-omits.yaml,release-negative-stale-omits.yaml— la modalità con certificato proprio attraverso ciascuna Recipe didattica; entrambe si arrestano.catalog/recipe/helm/envoy-ai-gateway-operator-without-omits/1.0.0/— la Recipe didattica senza voceomits:, e l’entity.lockche fissa il suo chart.catalog/recipe/helm/envoy-ai-gateway-operator-stale-omits/1.0.0/— la Recipe didattica la cui voce non corrisponde a nulla, e il suoentity.lock..aggrega-config.yaml— lo stack di ricerca del catalogo e il registry.build-release.sh— esegue il build di una Release, mostrando il comandoaggrega buildequivalente.check.sh— esegue il build di tutte e quattro e controlla ogni esito.