Composición de la salida
Una sola compilación de Aggrega produce archivos de salida en directorios por límite bajo dist/ mediante seis mecanismos distintos — renderizado desde fuente, síntesis de carga de trabajo, generación de recursos de la FeatureRecipe, parches del pipeline de plugins de la FeatureRecipe, composición a nivel de Release y emisión directa de artefactos. Los mecanismos se ejecutan en un orden definido; las salidas colisionan de forma determinista cuando dos mecanismos producen un archivo con el mismo nombre en el mismo directorio de límite; la compilación se detiene antes de la emisión, nombrando a cada contribuyente, cuando se detecta una colisión, bajo la categoría que nombra la regla de colisión.
Esta página documenta los seis mecanismos en un solo lugar y nombra el orden de renderizado entre ellos. Las referencias por capítulo y por entidad cubren sus propias superficies; las reglas de detección de colisiones entre los seis están aquí.
Los seis mecanismos que producen salida
Cada mecanismo reside en una superficie de autoría específica de Recipe / FeatureRecipe y produce archivos según convenciones de nomenclatura específicas. Los mecanismos se acumulan por nodo — una sola instancia de componente puede activar varios mecanismos a la vez (una Recipe base con fuente + un archivo complementario sintetizado por el Workload + un CRD ExternalSecret emitido por una FeatureRecipe + un parche del pipeline de plugins aplicado al Deployment sintetizado).
1 — Renderizado desde fuente de la Recipe (source: + valuesMapping:)
Superficie de autoría. La Recipe declara source: <path> más valuesMapping: (el campo acepta una plantilla Go en línea, un $import: de archivo o un $import: de biblioteca hacia una entrada de una MappingLibrary — consulta entities/recipe.md «The valuesMapping field — three authoring modes (El campo valuesMapping — tres modos de autoría)»). La fuente apunta a un chart de Helm en disco, a un archivo YAML de docker-compose o a otro artefacto nativo del proveedor.
Ubicación en el pipeline. Renderizado base, después de que se resuelven los locals y los provides de la Recipe.
Forma de la salida. Específica del Provider:
- proveedor helm — archivos YAML de Kubernetes planos, nombrados según la identidad del componente y luego según el propio recurso:
<component-id>-<kind>[-<namespace>]-<name>.yaml, y un documento que no lleva ningún kind o ningún nombre se nombra en cambio según la ruta de su plantilla. El nombre procede del recurso y no de la plantilla, por lo que dos plantillas en subdirectorios distintos que comparten un nombre de archivo siguen siendo dos archivos. El SDK de Helm renderiza el chart con los valores combinados; Aggrega inyecta etiquetas y anotaciones de procedencia después del renderizado. - proveedor helm-chart — archivos de subchart copiados en
charts/<instance_id>/, sin cambios salvo elnamepropio del chart, que el umbrella establece en la identidad codificada de la instancia para que dos componentes que incorporan charts que declaran un mismo nombre sigan siendo distinguibles (consultaproviders/helm-chart.md); unChart.yaml+values.yamlumbrella por límite emitidos junto a ellos. - proveedor compose — archivos intermedios
<nodeID>.compose-fragment.yamlque fluyen hacia la composición a nivel de Release (mecanismo 5).
2 — Síntesis de Workload de la Recipe (workload:)
Superficie de autoría. La Recipe declara workload: con un documento Workload. El campo acepta contenido en línea (block scalar) o $import: (ruta de archivo).
Ubicación en el pipeline. Renderizado base, después de que se resuelve el valuesMapping de la Recipe (el cuerpo del Workload es a su vez una cadena con plantilla Go evaluada con el contexto de plantilla completo).
Forma de la salida. Específica del Provider:
- proveedor helm — un objeto controlador elegido por el
formdel Workload (Deployment para stateless, StatefulSet para stateful, DaemonSet para daemon, Job para task, CronJob para scheduled) + un Service por servicio + un PVC por cada volumenpersistent. Dos formas de nombrado, y no son la misma: el objeto controlador se nombra según el nombre de la release del nodo y su kind —<release name>-deployment.yaml,<release name>-statefulset.yaml,<release name>-daemonset.yaml,<release name>-job.yaml,<release name>-cronjob.yaml— mientras que un archivo por recurso se nombra según el recurso que lleva, con el kind al final:<release name>-<svcName>-service.yamly<release name>-<volName>-pvc.yaml, porque cada uno se nombra a partir del propiometadata.namede ese recurso. El nombre de la release es la identidad del nodo escrita en el alfabeto que admite un nombre de Kubernetes, por lo que coincide con el ID del nodo dondequiera que este no contenga guiones bajos ni mayúsculas: el nodomy_apiescribemy-zuapi-deployment.yaml(consultaentities/workload.md«Synthesized-name convention (Convención de nombres sintetizados)»). Un Workload cuya única exposición es un nombre externo emite en cambio<release name>-service.yaml, al no haber ninguna clave de servicio que llevar. - proveedor compose — archivos intermedios
<nodeID>.compose-fragment.yamlque fluyen hacia la composición a nivel de Release. - proveedor helm-chart — no admitido; el papel de helm-chart es únicamente la composición de charts en modo con fuente. Una Recipe que tiene como destino helm-chart con
workload:se rechaza en el momento del renderizado (el proveedor helm-chart no declara ninguna capacidad de síntesis).
3 — Generación de recursos de la FeatureRecipe (modo con fuente para las FeatureRecipes)
Superficie de autoría. La FeatureRecipe declara source: más valuesMapping: (o equivalente), el mismo patrón que el renderizado desde fuente de la Recipe, pero para las vinculaciones de Feature en lugar de para los Components principales.
Ubicación en el pipeline. Renderizado base, junto al renderizado de la Recipe base para el Component padre. Cada vinculación de Feature ejecuta su propia pasada de renderizado de la FeatureRecipe.
Forma de la salida. La decide el proveedor del Component padre, porque la salida de la vinculación se une al grupo de ensamblado de ese Component en lugar de a uno propio — y se deriva de cómo ese proveedor combina el grupo, ya que eso es lo que dice si existe siquiera un lugar donde poner una vinculación. Tres formas, una por cada manera de combinar:
- Un proveedor que da a cada contribuyente una posición propia — un chart que contiene un chart por contribuyente, una configuración raíz que contiene un módulo por contribuyente — da también a una vinculación una posición propia, junto al componente al que se vinculó en lugar de dentro de él. Las dos coordenadas componen el único segmento de directorio de esa posición,
<component-id>--<feature-instance-id>, de modo que un componenteapique lleva una vinculaciónauxse sitúa enapi--auxjunto aapi, bajo el directorio que ese proveedor designe para sus contribuyentes. Junto y no dentro, porque el destino de un proveedor así descubre a sus contribuyentes en las posiciones que les dio: un directorio un nivel por debajo de una de esas posiciones es contenido que pertenece a ese contribuyente y no un contribuyente por sí mismo, por lo que nada lo direcciona y nada lo lee. Una vinculación declarada en el límite no tiene ningún componente anfitrión que nombrar, por lo que su segmento es solo su nombre de instancia. Cada coordenada se codifica antes de unir las dos, de modo que una coordenada que contenga ella misma la secuencia de unión no pueda confundirse con la unión. - Un proveedor que escribe cada documento directamente en el directorio de límite no tiene tal lugar, porque eso es exactamente lo que declara sobre su destino: solo se leen los archivos que están directamente en un directorio. Así, las mismas dos coordenadas salen de los segmentos de directorio y pasan al nombre de archivo, y los archivos de la vinculación quedan junto a los del componente como
<component-id>--<feature-instance-id>--<file>. Las dos coordenadas se codifican, porque un nombre de archivo no tiene ningún separador al que recurrir, y se unen al nombre propio del archivo en una frontera de dos caracteres que ninguna coordenada codificada puede contener — que es lo que mantiene a dos vinculaciones que emiten un mismo nombre de archivo en dos archivos distintos. - Un proveedor que integra a los contribuyentes de su grupo en un único documento integra también en ese documento la salida de la vinculación, donde cada recurso lleva la identidad propia de la vinculación para que lo que vino de dónde siga siendo legible. Cuando un proveedor así lleva una vinculación que se renderizó para un destino diferente, ese contenido no puede integrarse en un documento al que no pertenece, por lo que se escribe junto al documento ensamblado — en la forma con prefijo en el nombre de archivo descrita arriba, por la misma razón.
Formas comunes:
- Un CRD
ExternalSecret/VaultSecretgenerado por el Fetcher de una FeatureRecipe de credenciales. - Un CRD
ServiceMonitor/PrometheusRulegenerado por una Feature de observabilidad. - Un CRD
HTTPRoute/Gatewaygenerado por una Feature de enrutamiento.
4 — Pipeline de plugins de la FeatureRecipe (parches RFC 6902 + emisión de recursos)
Superficie de autoría. La FeatureRecipe declara pipeline: — un array de pasos de plugins Wasm (principio del Plugin en dos partes: Fetcher + Injector para las Features de credenciales; pipelines de plugins arbitrarios para las Features que no son de credenciales).
Ubicación en el pipeline. El pipeline de plugins, después de que se completan el renderizado base y el renderizado desde fuente de la FeatureRecipe.
Forma de la salida. Específica del Plugin. Un paso devuelve dos clases de salida:
- Parches RFC 6902 que el motor de aplicación aplica a los documentos direccionados en el conjunto renderizado (p. ej., añadir un contenedor sidecar, montar un volumen de secret, reescribir una variable de entorno en el Deployment sintetizado).
- Efectos secundarios — recursos nuevos completos emitidos junto al parche mediante el
side_effectsde un paso (normalmente el CRD vault-fetch del Fetcher al que luego hace referencia el Injector).
Estado actual: disponible según Estado del lenguaje → Fases del pipeline de compilación. Cada paso declarado se ejecuta durante aggrega build: el host invoca el plugin Wasm del paso sobre el conjunto renderizado, aplica los parches devueltos y emite los efectos secundarios del paso. Consulta plugins/plugin-contract.md para la superficie del contrato de plugins.
5 — Composición a nivel de Release (ensamblado del límite por proveedor)
Superficie de autoría. Determinada por la forma de la Release — sin autoría por Recipe. Una capacidad que ensambla un límite lo hace una sola vez, después de que cada nodo de ese límite se ha renderizado: la capacidad compose reúne todos los fragmentos por nodo en un único docker-compose.yaml por límite, y la capacidad helm-chart reúne las copias de subcharts por nodo en un único chart umbrella por límite.
Ubicación en el pipeline. Después del renderizado base, una vez que la salida por Recipe de cada nodo se ha acumulado para el límite.
Forma de la salida. Por proveedor:
- proveedor compose — un único
docker-compose.yamlen la raíz del límite, que agrega los servicios, volúmenes y redes de cada nodo contribuyente. Los archivos intermedios<nodeID>.compose-fragment.yaml(mecanismos 1 + 2) se combinan en la salida única; los fragmentos no aparecen en el directorio final del límite. - proveedor helm-chart — un
Chart.yaml+values.yamlumbrella en la raíz del límite, más directorios de subchart por nodo encharts/<instance_id>/.
6 — Emisión directa de artefactos de la Recipe (artifacts:)
Superficie de autoría. La Recipe declara artifacts: como un mapa de entradas con nombre; cada entrada es o bien contenido en línea (una cadena con plantilla que lleva el cuerpo del archivo) o bien una referencia $import: a una ruta de archivo de plantilla — emisión directa de archivos sin pasar por un proveedor.
Ubicación en el pipeline. Evaluación de artefactos, dentro del renderizado base.
Forma de la salida. Un archivo por cada entrada de artefacto, nombrado según la clave de la entrada en el mapa artifacts:. El autor de la Recipe dicta directamente el nombre de archivo y el contenido.
Estado actual: disponible según Estado del lenguaje → Tipos de entrada de la Recipe. Cada entrada se evalúa con el contexto de plantilla completo después de la síntesis de carga de trabajo y la resolución de la fuente, y el archivo resultante se emite bajo la clave de la entrada. Lo que un destino hace con un artefacto emitido depende de la capacidad: un proveedor que acepta un artefacto independiente lo emite como su propio archivo, mientras que uno que solo acepta artefactos junto con otro tipo de entrada integra la entrada en lo que ensambla — de modo que un cuerpo que no tiene la forma que espera ese ensamblador provoca una detención bajo la categoría TRANSLATION_ERROR en lugar de emitirse tal cual. Consulta la cuadrícula por capacidad en architecture/16-recipe-input-composition.md antes de escribir un artefacto para una capacidad.
Orden de renderizado
Los seis mecanismos se ejecutan en un orden definido para que los mecanismos posteriores puedan leer las salidas de los anteriores. El orden:
- Evaluación de los provides — por nodo, el bloque
locals:de la Recipe se resuelve primero, en el orden del autor, y cada entrada lee las entradas que tiene encima; a continuación se evalúan las plantillasprovides:del nodo, en cualquier orden entre sí (autocontenidas:.context.instance_id,.context.rendered_namedonde el proveedor del nodo informa uno,.values,.infra, los.localsresueltos, texto estático). El orden locals-antes-que-provides es lo que permite a una entradaprovides:leer un local y recibir un valor resuelto. - Publicación de los locals y resolución de la fuente — esos locals se publican en
.locals, y la plantilla de URIsource:de la Recipe se evalúa con respecto a ellos (resolviendo el puntero de la fuente si tiene plantilla). La superficie de la fuente comparte el contexto de los locals, por lo que lee.localsy no.provides. - Mapeo de inyección — se evalúan los bloques
injectMapping:de la FeatureRecipe (el pipe de inyección se intercepta antes del renderizado de la Recipe). - Mapeo de valores — se evalúa el
valuesMapping:de la Recipe (el modo con fuente + el modo sin fuente producen diccionarios de valores). - Síntesis de Workload — síntesis de Workload de la Recipe (el mecanismo 2 emite manifiestos para el modo sintetizado).
- Evaluación de artefactos — evaluación de
artifacts:de la Recipe (mecanismo 6). - Renderizado del Provider — el proveedor renderiza (mecanismo 1 — el modo con fuente produce manifiestos planos; el modo sin fuente produce manifiestos generativos).
- Renderizado de Feature — renderizado de la FeatureRecipe para cada vinculación de Feature en el nodo (mecanismos 3 + 4 — la generación de recursos se ejecuta aquí; el pipeline de plugins se ejecuta más tarde, en el paso 9).
- El pipeline de plugins — mutación posterior al renderizado: los pasos de plugin
pipeline:de la FeatureRecipe aplican parches RFC 6902 y emiten recursos adicionales (mecanismo 4). - Composición a nivel de Release — el ensamblado del límite de la capacidad reúne los fragmentos por nodo en salidas por límite (mecanismo 5).
El orden importa porque los mecanismos posteriores pueden leer las salidas de los anteriores — por ejemplo, un paso del pipeline de plugins puede aplicar un parche a un Deployment renderizado por el proveedor, y un compositor a nivel de Release puede combinar fragmentos emitidos por el renderizado del proveedor, por el renderizado de funcionalidades y por el pipeline de plugins.
Conjunto de reglas de detección de colisiones
Cuando dos mecanismos producen un archivo con el mismo nombre en el mismo directorio de límite, la compilación se detiene, nombrando a cada contribuyente, bajo la categoría que nombra cada regla a continuación. El conjunto de reglas:
Regla de forma de la Recipe: colisión de claves de entrada de artifacts:
Una Recipe declara dos entradas bajo artifacts: con la misma clave (la clave dicta el nombre del archivo emitido, tanto si el cuerpo de la entrada se escribe en línea como si se carga mediante $import:). Se detecta en el momento de carga de la Recipe según errors/fatal-halts.md «artifacts: entry keys must be unique (Las claves de las entradas de artefactos deben ser únicas)».
Regla de forma de la Recipe: colisión en tiempo de emisión entre tipos de entrada
Los tres tipos de entrada de una Recipe — con fuente, sintetizado y artefactos — emiten cada uno archivos en el mismo directorio de límite. Si la salida renderizada desde la fuente, sintetizada a partir de la carga de trabajo o emitida como artefacto produce un archivo cuyo nombre también produjo otro tipo de entrada, la compilación se detiene en la emisión. Se detecta en tiempo de emisión según errors/fatal-halts.md «Emission-time filename collision across input kinds (Colisión de nombres de archivo en tiempo de emisión entre tipos de entrada)».
Colisión de nombres de servicio de Compose (nivel de Release)
Cuando dos nodos diferentes (en cualquier combinación de límites) aportan servicios con el mismo nombre a la salida compose combinada, el proveedor compose se detiene mientras compone el límite, bajo la categoría TRANSLATION_ERROR, nombrando cada tupla (boundary, node, serviceName) contribuyente. Se detecta en la composición a nivel de Release según la sección de salida a nivel de Release de providers/compose.md.
Un servicio se rechaza solo por el nombre, sin comparar lo que declararon los dos nodos. Un servicio compose es un único contenedor en ejecución, así que dos nodos que querían uno cada uno obtienen uno entre los dos, y la intención de un contribuyente se pierde por idénticas que sean las dos definiciones.
Conflicto de nombres de volumen y de config de Compose (nivel de Release)
Cuando dos nodos diferentes aportan una entrada volumes: o configs: de nivel superior con el mismo nombre a la salida compose combinada, y las dos declaraciones difieren, el proveedor compose se detiene bajo la categoría TRANSLATION_ERROR, nombrando la entrada y cada tupla (boundary, node) contribuyente. Se detecta en la composición a nivel de Release según la sección de salida a nivel de Release de providers/compose.md.
A diferencia de la regla de servicios anterior, esta compara las declaraciones, y un nombre compartido es legítimo cuando los contribuyentes coinciden. Un volumen o una config con nombre es un único objeto, así que dos nodos que lo declaran de forma idéntica han pedido ambos exactamente la entrada con la que acaba el documento combinado, y no se pierde nada. Dos nodos que lo declaran de forma distinta discrepan sobre ese único objeto, y conservar cualquiera de las dos declaraciones descartaría la otra de una compilación que, de otro modo, tendría éxito. Dos declaraciones cuentan como coincidentes cuando describen la misma entrada en el archivo ensamblado, de modo que un cuerpo escrito como un mapeo vacío y uno omitido por completo coinciden.
Alias y directorio de los subcharts de helm-chart
Un subchart de helm-chart se sitúa en charts/<instance_id>/ y sus valores se acotan bajo su alias, que es el ID de instancia codificado para la posición del alias. Dos instancias no pueden llegar a un mismo alias a menos que sus ID de instancia sean la misma cadena, porque la codificación escribe explícitamente los caracteres que un alias no acepta en lugar de sustituirlos — así que un alias identifica exactamente un subchart, y los valores escritos bajo él llegan solo a ese subchart. Los ID de instancia son a su vez únicos por límite según las reglas de aplanamiento del Aggregate, por lo que tampoco el directorio puede colisionar. Ambas mitades son estructurales: ninguna depende de una comprobación.
Colisión de nombres de recursos renderizados por Helm
Dentro de un límite, dos nodos que se renderizan con el mismo nombre de recurso de Kubernetes producen dos archivos YAML con campos metadata.name superpuestos. Los nombres de archivo difieren, porque cada uno lleva como prefijo su propia base de nombrado, mientras que el metadata.name de su interior puede aun así coincidir — así que la compilación comprueba los nombres que llevan los recursos renderizados, y dos contribuyentes que derivan un mismo nombre para un mismo kind en un mismo namespace la detienen bajo la categoría TRANSLATION_ERROR antes de que se escriba nada, nombrando el nombre y cada componente, y cada vinculación, que lo derivó (consulta errors/fatal-halts.md).
El caso más amplio queda cerrado por construcción en lugar de comprobarse. Un chart con fuente que nombra sus recursos según el nombre de la release ya no puede producir esto entre dos componentes, porque dos bases de nombrado que difieran en lo más mínimo llegan a dos nombres de release — consulta providers/helm.md «How the release name is derived (Cómo se deriva el nombre de la release)». Quedan dos casos, y la comprobación anterior es lo que los informa. Uno es un chart que escribe literalmente un nombre de recurso en sus plantillas, y ninguna derivación puede distinguir ese nombre de cualquier otro literal. El otro son dos vinculaciones de Feature en un componente que entregan cada una un chart escrito por su autor: ambas se renderizan con el nombre de la release de ese componente, por diseño, así que dos charts que nombran un recurso según .Release.Name coinciden allí — da nombres distintos a los recursos de los dos charts, o vincúlalos a componentes diferentes.
Todo nombre sintetizado comienza con la identidad propia del nodo — el del objeto controlador, y cada nombre por recurso mediante la convención sintetizada de nombres de Service <release name>-<svcName> (según entities/workload.md «Synthesized-name convention (Convención de nombres sintetizados)») — lo que hace que las colisiones entre nodos sean estructuralmente imposibles por construcción. Los autores cuya compilación se detiene en un nombre de Deployment / Service deberían comprobar primero si dos Recipes diferentes están emitiendo recursos con el mismo nombre a través de distintas rutas de renderizado (p. ej., el templates/deployment.yaml de un chart con fuente que colisiona con el metadata.name de un Deployment sintetizado a partir de la carga de trabajo).
Patrones de interacción entre mecanismos
Workload sintetizado + parche del pipeline de plugins
El patrón canónico: el mecanismo 2 (síntesis de carga de trabajo) emite un Deployment base; el mecanismo 4 (el plugin Injector) aplica un parche RFC 6902 que monta un volumen de secret en el Deployment. Los dos mecanismos se componen — el Deployment es el mismo recurso K8s, con el parche superponiendo referencias a ConfigMap / Secret sobre la base sintetizada.
Este es el patrón dominante para la inyección de credenciales en cargas de trabajo sintetizadas. El Fetcher (mecanismo 3, generación de recursos) emite un CRD ExternalSecret que el clúster obtiene en tiempo de ejecución; el Injector (mecanismo 4, un parche del pipeline de plugins) modifica el Deployment para montar el Secret K8s resultante.
Con fuente + síntesis de Workload en límites diferentes
Un solo Aggregate puede tener un componente vinculado a una Recipe helm con fuente (mecanismo 1) en el límite A y un componente hermano vinculado a una Recipe helm que sintetiza un Workload (mecanismo 2) en el límite B. El directorio de cada límite lleva la forma de salida adecuada; el nombrado de archivos entre límites no colisiona porque los directorios dist/ por límite están aislados entre sí.
Combinación de Compose a nivel de Release por directorio de salida
El ensamblado de la capacidad compose reúne los fragmentos por nodo de cada límite cuyo directorio se evalúa a una misma ruta en un único docker-compose.yaml en esa ruta; dos límites dirigidos a compose en una misma Release escriben dos archivos cuando sus directorios difieren, y un único archivo combinado cuando comparten un directorio.
Las colisiones de nombres de servicio se detectan, por tanto, por archivo, en su combinación a nivel de Release, según la regla anterior. Dos límites dirigidos a compose en directorios diferentes que declaran cada uno un servicio llamado api no colisionan: el archivo de cada límite lleva el suyo. Dos que comparten un directorio escriben un único archivo, y la compilación se detiene nombrando a ambos contribuyentes.
Referencias cruzadas
entities/recipe.md— superficie de autoría de la Recipe (los mecanismos 1 + 2 + 6 emiten a partir del contenido de la Recipe).entities/featurerecipe.md— superficie de autoría de la FeatureRecipe (los mecanismos 3 + 4 emiten a partir del contenido de la FeatureRecipe).providers/helm.md— formas de salida por mecanismo y convenciones de nombrado del proveedor helm.providers/helm-chart.md— composición umbrella + subcharts del proveedor helm-chart (mecanismo 5).providers/compose.md— fragmentación por nodo + composición a nivel de Release del proveedor compose (mecanismo 5).errors/fatal-halts.md— las reglas de forma de la Recipe sobre claves de entrada únicas enartifacts:y sobre la colisión de nombres de archivo entre tipos de entrada.templates/expansion-matrix.md— momento de evaluación por sitio de plantilla a lo largo del orden de renderizado.plugins/plugin-contract.md— la superficie del contrato del pipeline de plugins (mecanismo 4).10-status.md— estado de disponibilidad actual del mecanismo 6 (artifacts:) y del tiempo de ejecución del pipeline de plugins del mecanismo 4.architecture/10-compilation-pipeline.md— el pipeline de compilación completo, incluido el orden de las etapas de renderizado.architecture/16-recipe-input-composition.md— los tres tipos de entrada de la Recipe (el encuadre previo de los mecanismos 1 + 2 + 6).