Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Un certificado de webhook propio: dejar fuera el Secret generado de un chart

Este es un ejemplo avanzado. Enseña el campo omits: de la Recipe, que la mayoría de las Recipes nunca necesitan: sirve para una fuente que tomas tal cual — aquí, un chart obtenido de un registro — y que renderiza un documento que tu Release no debe distribuir. Recurre a él cuando te encuentres con ese caso.

El workspace compila el plano de control de Envoy AI Gateway, el controlador al que Envoy Gateway llama como su servidor de extensión, mediante la Recipe de la biblioteca estándar helm/envoy-ai-gateway-operator, en los dos modos que puede adoptar su certificado de webhook. En uno de ellos, el chart del proyecto renderiza un Secret que contiene una clave y un certificado que genera de nuevo en cada renderizado, y la entrada omits: de la Recipe deja ese Secret fuera de la compilación. Dos Releases más muestran las dos detenciones con las que puedes encontrarte en torno al campo: la que la entrada existe para evitar, y la que produce una entrada que ya no coincide con nada.

Lo que construye

Un componente, ai-controller, de tipo core/gateway/envoy-ai-gateway-operator, compilado a manifiestos de Kubernetes. El Aggregate es el mismo para cada Release. Cada Release coloca el controlador en envoy-ai-gateway-system y elige el modo de certificado; cada Manifest elige la Recipe:

Releasesu Manifest vinculamodo de certificadoresultado
release-cert-manager.yamlhelm/envoy-ai-gateway-operator, de la biblioteca estándarcert-managercompila
release-own-certificate.yamlhelm/envoy-ai-gateway-operator, de la biblioteca estándarel Secret ai-gateway-webhook-tlscompila, idéntico byte a byte de una compilación a la siguiente
release-negative-without-omits.yamlhelm/envoy-ai-gateway-operator-without-omits, de este workspaceel Secret ai-gateway-webhook-tlsse detiene con E0058 al compilar con --verify-determinism
release-negative-stale-omits.yamlhelm/envoy-ai-gateway-operator-stale-omits, de este workspaceel Secret ai-gateway-webhook-tlsse detiene con E0334

Las dos Recipes del catalog/ de este workspace son variantes didácticas de la de la biblioteca estándar. Cada una toma el mismo chart en la misma versión y elige el modo de certificado mediante la misma correspondencia: una no tiene ninguna entrada omits:, y la otra tiene una entrada que nombra un Secret que el chart no renderiza. Llevan nombres propios, así que se sitúan junto a la Recipe de la biblioteca estándar en lugar de ocultarla, y el Manifest que nombra una Release decide con cuál se compila.

Dos formas de dar un certificado al webhook

El controlador ejecuta un webhook de mutación al que el servidor de API del clúster llama mediante TLS, así que el webhook sirve un certificado. El Component ofrece dos formas de proporcionarlo, elegidas por una sola clave infra, webhook_tls_secret:

  • Sin establecer, el valor predeterminado. El chart renderiza un Certificate de cert-manager para el nombre del Service del controlador y el Issuer autofirmado que lo firma, así que cert-manager ya debe estar en ejecución en el clúster.
  • Establecida. El webhook sirve el certificado del Secret que nombra la clave, que quien despliega crea de antemano en el namespace del controlador, con tls.crt, tls.key y ca.crt. No se renderiza ningún Certificate ni ningún Issuer, y cert-manager no es necesario: cuando el controlador arranca, escribe el ca.crt del Secret en la configuración del webhook como el bundle de CA con el que el servidor de API verifica el webhook.

release-own-certificate.yaml la establece:

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

Qué renderiza el chart en el modo de certificado propio

Con la clave establecida, el chart del proyecto monta el Secret de ese nombre en el pod del controlador en /certs — y también renderiza un Secret propio con el mismo nombre, que contiene un certificado de CA, un certificado y una clave privada que genera mientras renderiza. Dos compilaciones generan dos claves distintas, así que la salida deja de ser idéntica byte a byte de una compilación a la siguiente; y aplicarla sustituiría el Secret que creó el operador por el que generó el chart.

El chart se obtiene del registro del proyecto y se usa tal cual; una Recipe no edita un chart obtenido. En su lugar, la Recipe de la biblioteca estándar deja fuera el 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" "") "" }}'
  • kind y name nombran el documento tal como lo renderiza el chart: un Secret cuyo metadata.name es el nombre que estableció la Release. La plantilla de name lee la misma clave infra que recibe el chart, así que la entrada nombra el Secret generado sea cual sea el nombre que le dé la Release.
  • when hace que la entrada se aplique solo en este modo. En el modo cert-manager el chart no renderiza ningún Secret así; ahí la condición es falsa, y una entrada cuyo when: es falso se descarta antes de comprobar nada. Una sola Recipe sirve a ambos modos.

El resto del chart se sigue renderizando completo, y solo el documento que coincide se descarta de lo que escribe la compilación. Dejarlo fuera es correcto aquí porque el Secret que monta el pod del controlador es el del propio operador, creado por separado. El campo deja fuera un documento; no comprueba que aquello de lo que depende el resto de la salida exista en otra parte.

Generar el ejemplo

Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

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

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

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

Compilación

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 enumera el catalog/ propio del workspace, que contiene las dos Recipes didácticas; el Component y la Recipe de la biblioteca estándar se resuelven desde hub.aggrega.ai, el registro predeterminado que nombra. Con un checkout del catálogo de la biblioteca estándar (dónde conseguir uno), nombra su directorio aggrega-catalog con --catalog y cada entidad se resuelve desde esos dos directorios.

--auto-pull rellena el lockfile de cada Release durante la compilación; los lockfiles y la salida renderizada se generan, no se distribuyen. Resolver un lockfile obtiene el chart del controlador de Docker Hub, así que la primera compilación de cada Release necesita la red.

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.

Usa solo las herramientas de Aggrega y no crees ninguna carpeta tú mismo. Si la carpeta del espacio de trabajo aún no contiene una carpeta `ai-gateway-own-webhook-certificate`, llama una sola vez a la herramienta `scaffold` con `example` establecido en `ai-gateway-own-webhook-certificate` y sin `dir`: escribe el ejemplo en una nueva carpeta `ai-gateway-own-webhook-certificate`. Después llama a la herramienta `build` una vez por cada Release, en este orden — `release-cert-manager.yaml`, `release-own-certificate.yaml` —, cada vez con `workspace_root` establecido en `ai-gateway-own-webhook-certificate`, `release` establecido en ese archivo, `auto_pull` establecido en true y `write` establecido en true. Después llama a la herramienta `cli-build`, que ejecuta `aggrega build` y acepta su opción `--verify-determinism`, con `workspace_root` establecido en `ai-gateway-own-webhook-certificate`, `release` establecido en `release-negative-without-omits.yaml`, `auto_pull` establecido en true y `verify_determinism` establecido en true: está pensada para ser rechazada, así que léeme el rechazo. Después llama a la herramienta `build` igual que en las dos primeras compilaciones con `release` establecido en `release-negative-stale-omits.yaml`: también está pensada para ser rechazada, así que léeme también ese rechazo. Dime qué archivos escribió cada compilación; están en `ai-gateway-own-webhook-certificate/dist/`.

Los dos modos de certificado, tal como se renderizan

release-cert-manager.yaml, compilado con --auto-pull, imprime, donde <workspace> representa la carpeta de este ejemplo:

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

y ls dist/helm enumera después:

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

El directorio ai-controller contiene las seis definiciones de recursos de AI Gateway que la Recipe emite junto al chart. release-own-certificate.yaml, compilado del mismo modo, 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

y ls dist/helm enumera:

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

El árbol del modo cert-manager contiene un Certificate y un Issuer y ningún Secret. El del modo de certificado propio no contiene ninguno de los tres: ningún Certificate ni ningún Issuer, porque el chart no renderiza ninguno de los dos en ese modo, y ningún Secret, porque la entrada de la Recipe dejó fuera el que el chart sí renderizó. Lo que el controlador monta en su lugar es el Secret que nombró la Release:

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

El controlador lee su certificado de /certs, el volumen certs, que es el Secret ai-gateway-webhook-tls — un nombre que la compilación transmite tal como está escrito y que el clúster resuelve cuando arranca el pod.

Los mismos bytes de una compilación a la siguiente

Compilado una segunda vez con --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 dos veces a partir de la misma entrada y se detiene si los dos renderizados difieren. Aquí pasa, y el árbol que escribe es, byte a byte, el árbol que escribió la primera compilación. Ambas cosas se cumplen porque el único documento que el chart genera de nuevo nunca llega a la salida.

Sin la entrada: la compilación que comprueba el determinismo se detiene

release-negative-without-omits.yaml es la Release de certificado propio desplegada mediante manifest-without-omits.yaml, que vincula la Recipe didáctica sin entrada omits:. Compilada 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 deterministic

La compilación sale con 1. Los dos renderizados del controlador difieren, porque el chart generó una clave y un certificado distintos cada vez. El pull también renderiza la Release, para encontrar las entradas externas que necesita fijadas, y se encuentra ahí con la misma detención; por eso las líneas del pull omitidas llevan la frase una segunda vez. El lockfile se escribe de todos modos.

Compilada sin el flag, la misma Release se completa. Su árbol contiene los documentos del chart que contiene el de la Release de certificado propio — menos las definiciones de recursos, que la Recipe didáctica no emite — y uno más, el Secret que generó el chart:

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]

Compílala dos veces y los dos árboles difieren exactamente en esos tres valores. Una compilación ordinaria renderiza cada componente una vez, así que escribe la clave que se haya generado y no lo nota; la comprobación es lo que hace visible la diferencia. Aplicado, este archivo sustituiría el Secret que creó el operador.

La detención se describe en A provider rendered the same input twice and produced different output (Un proveedor renderizó dos veces la misma entrada y produjo salidas distintas), cuya corrección nombra las dos soluciones cuando la diferencia es un valor que genera un chart que usas como fuente: proporcionar el valor mediante un ajuste que ofrece el chart o, cuando el documento generado es uno que la Release no debe distribuir, dejarlo fuera con una entrada omits: — la respuesta que adopta la Recipe de la biblioteca estándar.

Una entrada que no coincide con nada

release-negative-stale-omits.yaml es la Release de certificado propio desplegada mediante manifest-stale-omits.yaml, que vincula la Recipe didáctica cuya entrada nombra el Secret según el nombre renderizado del controlador en lugar de según la clave:

# 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

El proveedor se nombra con la versión del binario que ejecutó la compilación, así que tu propia ejecución muestra ahí la versión de tu binario.

La compilación sale con 1, y las líneas del pull llevan la misma frase por la misma razón que antes. El mensaje se lee de izquierda a derecha como dónde mirar: el componente, el proveedor que lo renderizó, la Recipe que declara la entrada y la posición de la entrada en su lista omits:, contando desde 0, y luego el kind y el nombre a los que se resolvió la entrada. La condición when: es verdadera en este modo, así que la entrada se aplica; su nombre se renderiza como ai-controller-webhook-tls, el chart llamó a su Secret ai-gateway-webhook-tls, y la entrada no dejó nada fuera.

Toda entrada que se aplica debe dejar algo fuera, y la compilación se detiene en una que no lo hace, porque una entrada que no coincide con nada es una afirmación sobre la fuente que ya no es cierta. La causa habitual es una actualización de la fuente que renombró el documento. El documento renombrado está entonces en la salida con su nuevo nombre — justo el documento que la entrada se escribió para mantener fuera — y la detención es lo que impide que se distribuya sin que nadie lo note. En esta compilación, el Secret que generó el chart es uno de esos documentos: la entrada se escribió para mantenerlo fuera, y nombra otra cosa. Para corregir una entrada, compárala con lo que la fuente renderiza ahora: compila con la entrada eliminada, como hace release-negative-without-omits.yaml sin la comprobación, y lee el nombre en el archivo que escribió el chart.

E0334 figura en la referencia de diagnósticos como omit-matched-nothing, y se describe en An omits entry left out nothing the source rendered (Una entrada omits no dejó fuera nada de lo que renderizó la fuente). El campo en sí — cada campo de la entrada, el contexto de plantilla, lo que una Release puede decidir sobre una entrada y qué proveedores lo respetan — está en Recipe → El campo omits:.

Comprobar cada compilación

Esta autocomprobación se ejecuta en un checkout del repositorio de la documentación, que contiene el script auxiliar de compilación compartido que usa; una copia escrita por aggrega scaffold --example no incluye ese script auxiliar.

Terminal window
./check.sh

check.sh compila las cuatro Releases mediante ./build-release.sh y comprueba cada resultado frente al que describe esta página. Compila dos veces cada Release que pasa, la segunda con --verify-determinism: ambas compilaciones deben salir con 0 y escribir los mismos archivos, byte a byte, y el árbol debe contener, contando por el kind de cada documento renderizado, un Certificate y un Issuer y ningún Secret en el modo cert-manager, y ninguno de los tres en el modo de certificado propio, con el volumen certs del Deployment del controlador nombrando ai-gateway-webhook-tls. Una Release de salvaguarda debe salir con un código distinto de cero, con exactamente una detención que lleve el código corto y la frase que esta página muestra para ella, y la detención de la entrada obsoleta debe nombrar la entrada. Imprime una línea por Release y sale con 1 si algún resultado difiere, imprimiendo la salida de esa compilación:

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.

Necesita lo que necesita una sola compilación: el catálogo de la biblioteca estándar y la red para el chart. Usa el binario que resuelve ./build-release.sh, así que AGGREGA_BIN lo elige; los argumentos después de -- llegan a cada compilación. Se niega a arrancar mientras haya un dist/ en este directorio, porque compara los árboles que escriben las compilaciones, y no deja ninguno atrás. Su estado de salida es todo el veredicto, así que un pipeline puede ejecutarlo en lugar de compilar cada Release por separado.

Dónde el compilador no interpreta

El compilador no sabe qué es un Secret, qué hace el controlador con uno ni por qué un chart generaría uno. Evalúa las plantillas de la entrada como evalúa cualquier plantilla de Recipe, entrega el kind y el nombre a los que se resuelven al proveedor helm junto con los datos de entrada del componente, y el proveedor descarta los documentos renderizados que coinciden e informa de cuántos descartó cada entrada. Nunca busca ai-gateway-webhook-tls en un clúster, nunca lo crea y nunca comprueba que contenga las tres entradas que lee el controlador: el nombre es una cadena que proporciona la Release, canalizada a los valores del chart y a la entrada. Que el Secret exista antes de que arranque el controlador corresponde al lado que despliega.

Archivos

  • aggregate.yaml — el controlador del gateway de IA, el único componente; el mismo para cada Release.
  • manifest.yaml — vincula el controlador a la Recipe de la biblioteca estándar; compartido por las dos Releases que pasan.
  • manifest-without-omits.yaml, manifest-stale-omits.yaml — lo vinculan a una de las dos Recipes didácticas.
  • release-cert-manager.yaml, release-own-certificate.yaml — los dos modos de certificado.
  • release-negative-without-omits.yaml, release-negative-stale-omits.yaml — el modo de certificado propio a través de cada Recipe didáctica; ambas se detienen.
  • catalog/recipe/helm/envoy-ai-gateway-operator-without-omits/1.0.0/ — la Recipe didáctica sin entrada omits:, y el entity.lock que fija su chart.
  • catalog/recipe/helm/envoy-ai-gateway-operator-stale-omits/1.0.0/ — la Recipe didáctica cuya entrada no coincide con nada, y su entity.lock.
  • .aggrega-config.yaml — la pila de búsqueda del catálogo y el registro.
  • build-release.sh — compila una Release, mostrando el comando aggrega build equivalente.
  • check.sh — compila las cuatro y comprueba cada resultado.