Un certificat de webhook à vous : laisser de côté le Secret généré d’un chart
Ceci est un exemple avancé. Il enseigne le champ de Recipe omits:, dont la plupart des Recipes n’ont jamais besoin : il sert pour une source que vous prenez telle quelle — ici, un chart récupéré depuis un registre — et qui rend un document que votre Release ne doit pas livrer. Recourez-y lorsque vous rencontrez ce cas.
Le workspace construit le plan de contrôle d’Envoy AI Gateway, le contrôleur qu’Envoy Gateway appelle comme serveur d’extension, au moyen de la Recipe de la bibliothèque standard helm/envoy-ai-gateway-operator, dans les deux modes que peut prendre son certificat de webhook. Dans l’un d’eux, le chart du projet rend un Secret contenant une clé et un certificat qu’il génère à nouveau à chaque rendu, et l’entrée omits: de la Recipe laisse ce Secret hors du build. Deux autres Releases montrent les deux arrêts que vous pouvez rencontrer autour de ce champ : celui que l’entrée existe pour empêcher, et celui que produit une entrée qui ne correspond plus à rien.
Ce qu’il construit
Un seul composant, ai-controller, de type core/gateway/envoy-ai-gateway-operator, compilé en manifestes Kubernetes. L’Aggregate est le même pour chaque Release. Chaque Release place le contrôleur dans envoy-ai-gateway-system et choisit le mode de certificat ; chaque Manifest choisit la Recipe :
| Release | son Manifest lie | mode de certificat | résultat |
|---|---|---|---|
release-cert-manager.yaml | helm/envoy-ai-gateway-operator, de la bibliothèque standard | cert-manager | le build réussit |
release-own-certificate.yaml | helm/envoy-ai-gateway-operator, de la bibliothèque standard | le Secret ai-gateway-webhook-tls | le build réussit, identique octet pour octet d’un build à l’autre |
release-negative-without-omits.yaml | helm/envoy-ai-gateway-operator-without-omits, de ce workspace | le Secret ai-gateway-webhook-tls | s’arrête avec E0058 lors d’un build avec --verify-determinism |
release-negative-stale-omits.yaml | helm/envoy-ai-gateway-operator-stale-omits, de ce workspace | le Secret ai-gateway-webhook-tls | s’arrête avec E0334 |
Les deux Recipes du catalog/ de ce workspace sont des variantes pédagogiques de celle de la bibliothèque standard. Chacune tire le même chart dans la même version et choisit le mode de certificat par la même correspondance : l’une n’a pas d’entrée omits:, et l’autre a une entrée nommant un Secret que le chart ne rend pas. Elles portent des noms qui leur sont propres, de sorte qu’elles se placent à côté de la Recipe de la bibliothèque standard plutôt que de la masquer, et le Manifest que nomme une Release décide avec laquelle elle effectue son build.
Deux façons de donner un certificat au webhook
Le contrôleur exécute un webhook de mutation que le serveur d’API du cluster appelle via TLS, si bien que le webhook sert un certificat. Le Component offre deux façons de le fournir, choisies par une seule clé infra, webhook_tls_secret :
- Non définie, la valeur par défaut. Le chart rend un
Certificatecert-manager pour le nom du Service du contrôleur et l’Issuerautosigné qui le signe, si bien que cert-manager doit déjà s’exécuter dans le cluster. - Définie. Le webhook sert le certificat contenu dans le Secret que nomme la clé, que la personne qui déploie crée au préalable dans le namespace du contrôleur, avec
tls.crt,tls.keyetca.crt. AucunCertificateni aucunIssuern’est rendu, et cert-manager n’est pas nécessaire : au démarrage, le contrôleur écrit leca.crtdu Secret dans la configuration du webhook comme bundle d’AC par rapport auquel le serveur d’API vérifie le webhook.
release-own-certificate.yaml la définit :
components: ai-controller: annotations: aggrega.ai/namespace: envoy-ai-gateway-system infra: webhook_tls_secret: ai-gateway-webhook-tlsCe que rend le chart dans le mode à certificat propre
Avec la clé définie, le chart du projet monte le Secret de ce nom dans le pod du contrôleur sous /certs — et il rend aussi un Secret à lui sous le même nom, contenant un certificat d’AC, un certificat et une clé privée qu’il génère pendant le rendu. Deux builds génèrent deux clés différentes, si bien que la sortie cesse d’être identique octet pour octet d’un build à l’autre ; et l’appliquer remplacerait le Secret créé par l’opérateur par celui que le chart a généré.
Le chart est récupéré depuis le registre du projet et utilisé tel quel ; une Recipe ne modifie pas un chart récupéré. La Recipe de la bibliothèque standard laisse plutôt le Secret de côté :
# 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" "") "" }}'kindetnamenomment le document tel que le chart le rend : unSecretdont lemetadata.nameest le nom que la Release a défini. Le template denamelit la même cléinfraque celle donnée au chart, si bien que l’entrée nomme le Secret généré quel que soit le nom que lui donne la Release.whenfait que l’entrée ne s’applique que dans ce mode. Dans le mode cert-manager, le chart ne rend aucun Secret de ce genre ; la condition y est fausse, et une entrée dont lewhen:est faux est écartée avant toute vérification. Une seule Recipe sert les deux modes.
Le reste du chart est toujours rendu en entier, et seul le document correspondant est retiré de ce que le build écrit. Le laisser de côté est juste ici parce que le Secret que monte le pod du contrôleur est celui de l’opérateur, créé séparément. Le champ laisse un document de côté ; il ne vérifie pas que ce dont dépend le reste de la sortie existe ailleurs.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example ai-gateway-own-webhook-certificateElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
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 liste le catalog/ propre au workspace, qui contient les deux Recipes pédagogiques ; le Component et la Recipe de la bibliothèque standard sont résolus depuis hub.aggrega.ai, le registre par défaut qu’il nomme. Avec un checkout du catalogue de la bibliothèque standard (où en obtenir un), nommez son répertoire aggrega-catalog avec --catalog et chaque entité est résolue depuis ces deux répertoires.
--auto-pull remplit le lockfile de chaque Release pendant le build ; les lockfiles et la sortie rendue sont générés, non livrés. Résoudre un lockfile récupère le chart du contrôleur depuis Docker Hub, si bien que le premier build de chaque Release a besoin du réseau.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `ai-gateway-own-webhook-certificate`, appelez une seule fois l’outil `scaffold` avec `example` défini sur `ai-gateway-own-webhook-certificate` et sans `dir` : il écrit l’exemple dans un nouveau dossier `ai-gateway-own-webhook-certificate`. Appelez ensuite l’outil `build` une fois pour chaque Release, dans cet ordre — `release-cert-manager.yaml`, `release-own-certificate.yaml` —, chaque fois avec `workspace_root` défini sur `ai-gateway-own-webhook-certificate`, `release` défini sur ce fichier, `auto_pull` défini sur true et `write` défini sur true. Appelez ensuite l’outil `cli-build`, qui exécute `aggrega build` et accepte son option `--verify-determinism`, avec `workspace_root` défini sur `ai-gateway-own-webhook-certificate`, `release` défini sur `release-negative-without-omits.yaml`, `auto_pull` défini sur true et `verify_determinism` défini sur true : ce build doit être refusé, alors lisez-moi le refus. Appelez ensuite l’outil `build` de la même manière que pour les deux premiers builds avec `release` défini sur `release-negative-stale-omits.yaml` : ce build doit lui aussi être refusé, alors lisez-moi également ce refus. Indiquez-moi quels fichiers chaque build a écrits ; ils se trouvent sous `ai-gateway-own-webhook-certificate/dist/`.Les deux modes de certificat, tels que rendus
release-cert-manager.yaml, construit avec --auto-pull, affiche, <workspace> désignant le dossier de cet exemple :
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>/distet ls dist/helm liste ensuite :
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.yamlLe répertoire ai-controller contient les six définitions de ressources d’AI Gateway que la Recipe émet à côté du chart. release-own-certificate.yaml, construit de la même façon, affiche :
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>/distet ls dist/helm liste :
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’arborescence du mode cert-manager contient un Certificate et un Issuer et aucun Secret. Celle du mode à certificat propre ne contient aucun des trois : aucun Certificate et aucun Issuer, parce que le chart ne rend ni l’un ni l’autre dans ce mode, et aucun Secret, parce que l’entrée de la Recipe a laissé de côté celui que le chart a bel et bien rendu. Ce que le contrôleur monte à la place, c’est le Secret que la Release a nommé :
[… 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-tlsLe contrôleur lit son certificat depuis /certs, le volume certs, qui est le Secret ai-gateway-webhook-tls — un nom que le build transmet tel qu’il est écrit et que le cluster résout au démarrage du pod.
Les mêmes octets d’un build à l’autre
Construit une seconde fois avec --verify-determinism, release-own-certificate.yaml affiche :
[… omitted: the total build time, which differs per run]Build completed: 14 files written to <workspace>/dist--verify-determinism rend chaque composant deux fois à partir de la même entrée et s’arrête si les deux rendus diffèrent. Il réussit ici, et l’arborescence qu’il écrit est octet pour octet celle que le premier build a écrite. Les deux tiennent parce que le seul document que le chart génère à neuf n’atteint jamais la sortie.
Sans l’entrée : le build qui vérifie le déterminisme s’arrête
release-negative-without-omits.yaml est la Release à certificat propre déployée via manifest-without-omits.yaml, qui lie la Recipe pédagogique sans entrée omits:. Construite avec --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 deterministicLe build se termine avec 1. Les deux rendus du contrôleur diffèrent, parce que le chart a généré à chaque fois une clé et un certificat différents. Le pull rend aussi la Release, pour trouver les entrées externes dont elle a besoin épinglées, et y rencontre le même arrêt ; c’est pourquoi les lignes de pull omises portent la phrase une seconde fois. Le lockfile est tout de même écrit.
Construite sans l’option, la même Release va jusqu’au bout. Son arborescence contient les documents du chart que contient celle de la Release à certificat propre — moins les définitions de ressources, que la Recipe pédagogique n’émet pas — et un de plus, le Secret que le chart a généré :
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]Construisez-la deux fois et les deux arborescences diffèrent exactement par ces trois valeurs. Un build ordinaire rend chaque composant une fois, il écrit donc la clé générée, quelle qu’elle soit, sans s’en apercevoir ; c’est la vérification qui rend la différence visible. Appliqué, ce fichier remplacerait le Secret créé par l’opérateur.
L’arrêt est décrit sous A provider rendered the same input twice and produced different output (Un fournisseur a effectué deux fois le rendu de la même entrée et a produit des sorties différentes), dont le correctif nomme les deux solutions lorsque la différence est une valeur que génère un chart que vous utilisez comme source : fournir la valeur via un paramètre que le chart propose ou, lorsque le document généré est un document que la Release ne doit pas livrer, le laisser de côté avec une entrée omits: — la réponse que retient la Recipe de la bibliothèque standard.
Une entrée qui ne correspond à rien
release-negative-stale-omits.yaml est la Release à certificat propre déployée via manifest-stale-omits.yaml, qui lie la Recipe pédagogique dont l’entrée nomme le Secret d’après le nom rendu du contrôleur plutôt que d’après la clé :
# 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" "") "" }}'Construite :
[… 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 causeLe fournisseur est nommé avec la version du binaire qui a exécuté le build, si bien que votre propre exécution y affiche la version de votre binaire.
Le build se termine avec 1, et les lignes du pull portent la même phrase pour la même raison que ci-dessus. Le message se lit de gauche à droite comme l’endroit où regarder : le composant, le fournisseur qui l’a rendu, la Recipe qui déclare l’entrée et la position de l’entrée dans sa liste omits:, en comptant à partir de 0, puis le kind et le nom auxquels l’entrée s’est résolue. La condition when: est vraie dans ce mode, donc l’entrée s’applique ; son nom est rendu en ai-controller-webhook-tls, le chart a nommé son Secret ai-gateway-webhook-tls, et l’entrée n’a rien laissé de côté.
Toute entrée qui s’applique doit laisser quelque chose de côté, et le build s’arrête sur une entrée qui ne le fait pas, parce qu’une entrée qui ne correspond à rien est une affirmation sur la source qui n’est plus vraie. La cause habituelle est une mise à niveau de la source qui a renommé le document. Le document renommé est alors dans la sortie sous son nouveau nom — celui-là même que l’entrée a été écrite pour tenir à l’écart — et l’arrêt est ce qui l’empêche d’être livré sans que personne le remarque. Dans ce build, le Secret que le chart a généré est un tel document : l’entrée a été écrite pour le tenir à l’écart, et nomme autre chose. Pour corriger une entrée, comparez-la avec ce que la source rend maintenant : lancez le build avec l’entrée retirée, comme le fait release-negative-without-omits.yaml sans la vérification, et relevez le nom dans le fichier que le chart a écrit.
E0334 est listé dans la référence des diagnostics sous omit-matched-nothing, et décrit sous An omits entry left out nothing the source rendered (Une entrée omits n’a rien laissé de côté de ce que la source a rendu). Le champ lui-même — chaque champ d’une entrée, le contexte de template, ce qu’une Release peut décider à propos d’une entrée et quels fournisseurs le respectent — est présenté dans Recipe → Le champ omits:.
Vérifier chaque build
Cette auto-vérification s’exécute dans un checkout du dépôt de la documentation, qui contient l’utilitaire de build partagé qu’elle utilise ; une copie écrite par aggrega scaffold --example ne contient pas cet utilitaire.
./check.shcheck.sh construit les quatre Releases via ./build-release.sh et vérifie chaque résultat par rapport à celui que décrit cette page. Il construit deux fois chaque Release qui réussit, la seconde fois avec --verify-determinism : les deux builds doivent se terminer avec 0 et écrire les mêmes fichiers, octet pour octet, et l’arborescence doit contenir, en comptant par kind chaque document rendu, un Certificate et un Issuer et aucun Secret dans le mode cert-manager, et aucun des trois dans le mode à certificat propre, le volume certs du Deployment du contrôleur nommant ai-gateway-webhook-tls. Une Release garde-fou doit se terminer avec un code non nul, avec exactement un arrêt portant le code court et la phrase que cette page montre pour elle, et l’arrêt de l’entrée périmée doit nommer l’entrée. Il affiche une ligne par Release et se termine avec 1 si un résultat diffère, en affichant la sortie de ce 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.Il a besoin de ce dont a besoin un build unique : le catalogue de la bibliothèque standard, et le réseau pour le chart. Il utilise le binaire que résout ./build-release.sh, si bien que AGGREGA_BIN le choisit ; les arguments après -- atteignent chaque build. Il refuse de démarrer tant qu’un dist/ se trouve dans ce répertoire, parce qu’il compare les arborescences qu’écrivent les builds, et il n’en laisse aucune derrière lui. Son code de sortie est tout le verdict, si bien qu’un pipeline peut l’exécuter au lieu de construire chaque Release séparément.
Là où le compilateur n’interprète pas
Le compilateur ne sait pas ce qu’est un Secret, ce que le contrôleur en fait, ni pourquoi un chart en générerait un. Il évalue les templates de l’entrée comme il évalue tout template de Recipe, transmet le kind et le nom auxquels ils se résolvent au fournisseur helm avec les données d’entrée du composant, et le fournisseur écarte les documents rendus qui correspondent et indique combien chaque entrée en a écarté. Il ne cherche jamais ai-gateway-webhook-tls dans un cluster, ne le crée jamais et ne vérifie jamais qu’il contient les trois entrées que lit le contrôleur : le nom est une chaîne que fournit la Release, acheminée dans les valeurs du chart et dans l’entrée. Que le Secret existe avant le démarrage du contrôleur relève du côté qui déploie.
Fichiers
aggregate.yaml— le contrôleur de la passerelle d’IA, l’unique composant ; le même pour chaque Release.manifest.yaml— lie le contrôleur à la Recipe de la bibliothèque standard ; partagé par les deux Releases qui réussissent.manifest-without-omits.yaml,manifest-stale-omits.yaml— le lient à l’une des deux Recipes pédagogiques.release-cert-manager.yaml,release-own-certificate.yaml— les deux modes de certificat.release-negative-without-omits.yaml,release-negative-stale-omits.yaml— le mode à certificat propre à travers chaque Recipe pédagogique ; les deux s’arrêtent.catalog/recipe/helm/envoy-ai-gateway-operator-without-omits/1.0.0/— la Recipe pédagogique sans entréeomits:, et l’entity.lockqui épingle son chart.catalog/recipe/helm/envoy-ai-gateway-operator-stale-omits/1.0.0/— la Recipe pédagogique dont l’entrée ne correspond à rien, et sonentity.lock..aggrega-config.yaml— la pile de recherche du catalogue et le registre.build-release.sh— construit une Release, en affichant la commandeaggrega buildéquivalente.check.sh— construit les quatre et vérifie chaque résultat.