Cuándo recurrir a un paso de pipeline
Una FeatureRecipe te ofrece dos formas de dar forma a la salida que aporta una Feature: una FeatureRecipe basada en plantillas que genera sus propios documentos, y un paso de pipeline (pipeline:) que ejecuta un plugin Wasm sobre la salida renderizada. Resuelven problemas distintos. Esta página es la guía de decisión: recurre a un paso de pipeline ante exactamente dos desencadenantes, y usa una FeatureRecipe basada en plantillas para todo lo demás.
Las dos herramientas
Una FeatureRecipe basada en plantillas es local y generativa. Produce sus propios documentos a partir de sus propios valores mediante una plantilla de Go — el ConfigMap de un sidecar, un CRD de política, un objeto de autoescalado. Todo lo que emite es función de los values: y los infra: de la Feature y del contexto de renderizado que se entrega a sus plantillas. Nunca entra en la salida de otra entidad; añade documentos propios. Si lo que necesitas producir puede escribirse a partir de lo que la Feature ya sabe, una FeatureRecipe basada en plantillas es la herramienta correcta y más sencilla — sin plugin, sin pipeline.
Un paso de pipeline es global y transformador. Se ejecuta después del renderizado, sobre el conjunto real de documentos que la compilación ya ha emitido. El host entrega al paso ese conjunto de documentos indexado por clave, completo; el paso lee el contenido real, selecciona los documentos a los que apunta y devuelve parches RFC 6902 precisos sobre su estructura — o emite documentos nuevos como efectos secundarios. Un paso razona sobre lo que se renderizó, no solo sobre lo que la Feature declaró. Ese alcance es toda su razón de existir, y es también por qué lo usas con moderación.
Los dos desencadenantes de un paso de pipeline
Recurre a un paso de pipeline solo cuando se cumple uno de estos casos. Si no se cumple ninguno, genera en su lugar el documento con una FeatureRecipe basada en plantillas.
-
Parche en el ámbito del host — necesitas entrar en la estructura de otra entidad ya renderizada. El caso clásico es inyectar una variable de entorno, un montaje de volumen o un contenedor sidecar en la carga de trabajo del componente consumidor — un documento que la propia Feature no escribió. Una FeatureRecipe basada en plantillas no puede hacerlo: produce sus propios documentos, no edita los de otro. Un paso de pipeline sí puede, porque opera sobre el conjunto renderizado y puede direccionar por clave los documentos del componente host.
-
Emisión o parche dependiente del contenido — la salida depende de lo que contiene el conjunto renderizado. Cuando el recurso que emites, o el parche que aplicas, es función del contenido que produjo la compilación — los puertos reales que declaró un Deployment, los nombres de contenedor que acabaron en el manifiesto, los recursos en los que se expandió un chart — la decisión necesita tener en la mano el contenido renderizado. Una FeatureRecipe basada en plantillas renderiza a partir de los valores propios de la Feature y nunca ve el conjunto terminado, así que no puede tomar una decisión dependiente del contenido; un paso de pipeline primero lee el contenido y luego actúa.
Ambos desencadenantes comparten una forma: necesitan información que solo existe después del renderizado — la estructura de otra entidad, o el propio contenido emitido. La generación local nunca la necesita, así que la generación local nunca necesita un paso de pipeline.
Un paso transforma; una política valida
Un paso de pipeline es un transformador: cambia el conjunto renderizado. No es el lugar para comprobar si un resultado es aceptable. Para validar una compilación — para afirmar que una carga de trabajo parcheada tiene el sidecar, que ningún secreto en texto plano llegó a la salida, que una etiqueta requerida está presente — vincula una política de la etapa de renderizado: un plugin de gobernanza en el rol render-verdict, que se ejecuta después del renderizado sobre los artefactos emitidos y devuelve un veredicto. Un veredicto halt detiene la compilación; un veredicto warn o info avisa sin bloquear.
Mantén separadas las dos cosas. No incorpores lógica de validación en un paso de pipeline, y no recurras a una política para modificar la salida — un plugin de gobernanza vinculado a un rol de veredicto devuelve veredictos y nunca aplica parches, y el host lee la salida de un rol de veredicto solo como una decisión. Un paso da forma a la salida; una política render-verdict la juzga. La página del socket de gobernanza trata los cuatro roles de gobernanza y las severidades de los veredictos.
Los pasos se componen
Un paso de pipeline puede declarar un contrato tipado de entrada y salida, de modo que su entrada with: y las salidas que devuelve sean formas validadas en lugar de blobs libres. Un paso también devuelve outputs con nombre, y un paso declarado más adelante en el mismo pipeline lee las salidas de un paso anterior desde su propia plantilla with: como .steps.<id>.outputs.<key>. Así es como un patrón de dos partes se compone sin acoplamiento: un paso Fetcher emite un recurso de credenciales y publica el nombre del Secret resultante como salida; un paso Injector lee ese nombre y parchea la carga de trabajo consumidora para montarlo. Cada paso lleva una sola responsabilidad, y el pipeline encadena sus salidas en el orden declarado.
Referencias cruzadas
entities/featurerecipe.md— la superficie de creación de la FeatureRecipe, incluidopipeline:.plugins/plugin-contract.md— la forma de transmisión del paso de pipeline: de entrada, el conjunto de documentos indexado por clave; de salida, parches RFC 6902, efectos secundarios, diagnósticos y salidas del paso.plugins/policy-socket.md— el socket de gobernanza, incluido el rol de veredicto de la etapa de renderizado que valida la salida de una compilación.templates/template-context-contract.md— el campo.steps.<id>.outputsque lee un paso posterior.examples/04-secrets.md— la forma de pipeline Fetcher + Injector.