Composición de entradas de la Recipe: tres tipos de entrada, Workload, artefactos
Una Recipe produce archivos de manifiesto para su proveedor de destino. Este capítulo trata de cómo las Recipes componen su salida a partir de tres tipos de entrada ortogonales —sourced, synthesized y artifacts—, de cómo se estructura cada tipo de entrada y de qué proveedor produce qué salida. El papel conceptual de la entidad Recipe (la plantilla de traducción escrita por Ops que mapea la intención del desarrollador a un único proveedor físico) se describe en 04-entity-taxonomy.md; la superficie de autoría de la Recipe a nivel de palabra clave se describe en ../language-reference/entities/recipe.md.
Justificación
La herramienta de renderizado nativa de cada proveedor —Helm, Docker Compose— ya sabe cómo renderizar manifiestos nativos del proveedor. La tarea de una Recipe es declarar QUÉ deben decir esos manifiestos: qué imágenes de contenedor, qué puertos, qué variables de entorno, qué volúmenes, qué servicios, qué límites de recursos.
Una Recipe tiene que expresar más de lo que puede contener un conjunto fijo de claves (p. ej., image, environment, ports, replicas) mapeado sobre un Deployment y un Service, entre otras cosas:
resources(solicitudes/límites de CPU/memoria)- Sondas de liveness, readiness o startup
volumeMounts/volumesnodeSelector/affinity/tolerationsserviceAccount/securityContext- Pods con varios contenedores, sidecars
- Recursos ConfigMap / Secret / PVC / CRD
- Services que no son ClusterIP (LoadBalancer, NodePort, Headless)
La capa de abstracción debe describir la forma completa de una carga de trabajo, no un conjunto fijo de claves. Los tres tipos de entrada que se describen a continuación son esa abstracción: una Recipe compone su salida de forma aditiva a partir de un chart o módulo cargado externamente (source:), una especificación abstracta de Workload que el proveedor sintetiza en manifiestos nativos del proveedor (workload:) y manifiestos nativos del proveedor basados en plantillas que la Recipe emite directamente (artifacts:).
Los tres tipos de entrada
Composición por adición
Hay tres formas de producir archivos de manifiesto nativos del proveedor a partir de una Recipe, y se componen por adición en lugar de excluirse mutuamente:
source:— un artefacto cargado externamente (chart de Helm, archivo compose) que el proveedor renderiza de forma nativa, convaluesMapping:aportando los valores de superposición.workload:— una especificación abstracta de Workload (tipo propiedad de la plataforma) que el proveedor sintetiza en manifiestos nativos del proveedor. El campo acepta un block scalar YAML en línea o un$import:a un único archivo local o entrada de biblioteca; el despacho depende de la forma del contenido.artifacts:— un mapa de manifiestos nativos del proveedor, en línea o cargados con$import:, procesados como plantillas Go contra el contexto completo de pilares. Cada entrada puede escribirse en línea (el valor de la entrada es un block scalar) o mediante$import:a un único archivo o contenido de biblioteca.
Los tres producen archivos que el compilador emite en el directorio de salida del boundary. Los tres pueden coexistir en una sola Recipe, con sujeción a las reglas de validación que siguen. La semántica de fusión es solo de nivel superior: cada tipo de entrada produce archivos completos; los archivos se emiten uno junto a otro; una colisión en el nombre de un archivo de salida es un error fatal.
Nombres descriptivos de los modos
Los tres «modos» son vocabulario descriptivo para la documentación y los diagnósticos. Los autores de Recipe no declaran un modo; escriben las palabras clave que necesitan. Una Recipe se caracteriza por su entrada dominante:
| Palabra(s) clave dominante(s) | Nombre descriptivo del modo |
|---|---|
source: + valuesMapping: (sin workload:, sin artefactos) | sourced |
workload: (sin source:, sin artefactos) | synthesized |
artifacts: (sin source:, sin workload:) | artifacts-only (informalmente: «inline») |
| Cualquier combinación de dos o más | se describe explícitamente (p. ej., «sourced con artifacts», «synthesized con artifacts») |
No existe ninguna palabra clave llamada mode: ni ningún enum. El modo es una propiedad emergente de qué entradas están presentes.
La forma de una Recipe de un vistazo
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: ... version: 1.0.0spec: capability: helm | compose | helm-chart | ... implements: core/...:1.0.0
locals: { ... } provides: { ... }
# ─── Sourced input (optional, paired) ─── source: ... valuesMapping: | # Go template → YAML/JSON overlay values # OR: valuesMapping: $import: ./mappings/api-server.tmpl # local file path # OR: valuesMapping: $import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ─── workload: | # Go template → YAML → parsed Workload # OR (single-source $import for whole-content load from a file or library): workload: $import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ─── artifacts: "filename.yaml": | # Inline Go template → manifest YAML "other.yaml": $import: ./artifacts/other.yaml # per-entry $import: for file or library contentEl esquema de la Recipe acepta todos los campos anteriores, y el compilador consume los tres tipos de entrada: el renderizado sourced, la síntesis de Workload y la emisión de artifacts. Lo que varía es la compatibilidad por proveedor —qué proveedor renderiza qué tipo de entrada—, recogida en la matriz de capacidades por Provider al final de este capítulo.
Reglas de validación en tiempo de carga
El esquema de la Recipe y la validación en la carga aplican estas reglas de composición:
valuesMapping:requieresource:. Sin unsource:sobre el que superponer, no hay nada que reciba los valores mapeados. Una Recipe convaluesMapping:y sinsource:es un error en tiempo de carga. (Se permite unsource:sinvaluesMapping:: el chart o módulo se renderiza con sus propios valores predeterminados).workload:acepta una sola fuente: en línea o$import:, no ambas. Una Recipe especifica el Workload como un block scalar en línea o como un$import:a un único archivo. La forma$import:es de fuente única según el vocabulario unificado de importación de archivos; la fusión de varias fuentes no se admite enworkload:. Un despacho mal formado es un error en tiempo de carga.workload:requiere un proveedor capaz de sintetizar. La capacidad de síntesis es una propiedad del propio proveedor, no de ningún campo declarado. Una Recipeworkload:vinculada a un proveedor que no puede sintetizar se rechaza cuando el nodo se renderiza —mediante la comprobación de capacidades del proveedor (consulta la matriz de capacidades por Provider)— con un diagnóstico claro. El catálogo de la biblioteca estándar declaraworkloadSchemaen los proveedores capaces de sintetizar por convención, como contrato de traducción documentado, pero la comprobación se basa en la capacidad que informa el propio proveedor y no en la presencia de ese campo.- Debe haber al menos un tipo de entrada. Una Recipe sin ninguno de
source:+valuesMapping:,workload:oartifacts:no produce salida y es un error en tiempo de carga. - Las entradas de artefactos en línea y con
$import:pueden coexistir. Una Recipe puede declarar algunas entradas deartifacts:en línea y otras mediante directivas$import:por entrada. La clave de cada entrada nombra su propia salida, de modo que las entradas de las dos formas nunca colisionan entre sí (consulta Qué da nombre a cada archivo de salida). - Las colisiones de nombres de archivo entre tipos de entrada son errores en tiempo de renderizado. Si dos de los tipos de entrada de una Recipe —salida renderizada desde la fuente, salida sintetizada desde la carga de trabajo o salida emitida desde los artefactos— producen un archivo con el mismo nombre, el compilador emite un error fatal que identifica a cada contribuyente. Esta comprobación se ejecuta después de la traducción del Workload, por lo que ocurre en tiempo de renderizado y no de carga.
El tipo Workload
Propiedad y ubicación
Workload es un tipo propiedad de la plataforma en apiVersion: aggrega.ai/v1beta1. Su declaración en JSON Schema 2020-12 se incrusta en el binario del compilador en tiempo de compilación; los autores de catálogos no editan el esquema del Workload ni escriben archivos YAML Workload independientes como entidades de catálogo. La gramática del Workload se consume dentro del campo workload: de una Recipe o de una FeatureRecipe (en línea, o mediante $import: a un único archivo o a una entrada de WorkloadLibrary) y en ningún otro lugar.
Workload es un tipo de la plataforma y un concepto del compilador, no una entidad aparte en la taxonomía de entidades. La Recipe es la entidad de autoría; el Workload es la forma que adopta la entrada sintetizada de la Recipe.
Un Workload por Recipe
Una Recipe declara como máximo un workload:. El Workload representa la única unidad de cómputo asociada al Component que implementa esta Recipe. Del mismo modo, una FeatureRecipe declara como máximo un workload: propio —una unidad de cómputo propiedad de la Feature, sintetizada mediante el mismo tipo Workload—; consulta FeatureRecipe. Los casos de uso que requieren cargas de trabajo secundarias adicionales se expresan mediante:
artifacts:— manifiestos adicionales junto a la carga de trabajo, en la misma Recipe (en línea o mediante$import:por entrada).- Features con generación de recursos — cargas de trabajo secundarias transversales (p. ej., un sidecar de copias de seguridad vinculado a bases de datos) declaradas como entidades de catálogo independientes, donde la FeatureRecipe sintetiza su propio
workload:(o renderiza mediantesource:/artifacts:). Consulta 14-extensibility.md para la generación de recursos de la FeatureRecipe.
Esto preserva el modelo de una unidad de cómputo por autor: una Recipe sintetiza la carga de trabajo del Component; una FeatureRecipe sintetiza la suya.
La superficie completa
El conjunto de campos del Workload es amplio y crece. En lugar de repetirlo aquí, donde una copia se quedaría por detrás del contrato sin que nada lo indicara, este capítulo remite a las dos superficies que lo recogen por completo:
- La referencia generada del esquema del Workload — cada campo, su tipo, su valor predeterminado y sus restricciones, generada a partir del JSON Schema publicado y comparada con él en cada build, de modo que no puede describir una forma que el compilador no acepte.
- La página de autoría del Workload — orientación de autoría a nivel de campo: qué significa cada campo, en qué lo renderiza cada proveedor y qué combinaciones rechaza el build.
La declaración en JSON Schema 2020-12 del Workload es la autorizada y se distribuye incrustada en el binario del compilador. Los providers de helm y compose sintetizan el workload: de una Recipe, en línea o cargado con $import:; consulta la matriz de capacidades por Provider para la compatibilidad por proveedor.
Integración de secretos con featuresSchema
El bloque containers.<name>.attachments del Workload hace referencia a slots declarados por el featuresSchema del Component; no declara slots nuevos. Consulta ../language-reference/entities/component.md para la superficie de autoría de featuresSchema.
El contrato de validación:
- Cada valor
attachments.<KEY>.fromdebe coincidir con un nombre de slot declarado en elfeaturesSchemadel Component o, para una entrada que nombra una conexión conconnection: <alias>, con un slot que el socket de esa conexión declara enusesSchema.<socket>.featuresSchema. Una entrada así se reescribe con el nombre que adopta la vinculación de la conexión en el componente (<alias>.<slot>) antes de que se aplique cualquiera de estas reglas, de modo que cada regla siguiente la lee como lee una entrada que nombra un slot propio del Component. - El mecanismo de entrega
as:(envofile) debe estar en la lista permitida del arrayinject:de ese slot. - Los slots marcados con
inject: [](caja negra) en elfeaturesSchemadel Component no pueden aparecer en los bloquesattachments:del Workload: esos slots se entregan mediante la fontanería interna de la Recipe (p. ej., medianteexistingSecretde Helm), no mediante su exposición en el Workload.
Ejemplo:
# In the Componentspec: featuresSchema: db_password: required: true inject: [env, file] # transparent: Workload may dictate delivery root_password: required: true inject: [] # blackbox: Recipe handles internally
# In the Recipeworkload: | containers: main: attachments: DB_PASSWORD: # OK — db_password slot allows env inject from: db_password as: env # ROOT_PASSWORD: ... # rejected — root_password is blackboxSondas de salud: intención, no mecanismo
Las sondas de Kubernetes y los healthchecks de Docker Compose tienen formas distintas. Una única forma abstracta de intención se traduce limpiamente a ambos:
health: ready: http: /healthz # intent: HTTP GET probe timeoutSeconds: 5 live: tcp: 8080 # intent: TCP socket check timeoutSeconds: 5 startup: exec: ["check-ready.sh"] # intent: command exec timeoutSeconds: 30 periodSeconds: 10Los Providers traducen cada intención a su forma nativa:
| Intención | Helm (K8s) | Compose |
|---|---|---|
http: /path | httpGet.path: /path, httpGet.port: <alphabetically-first port name> | CMD-SHELL "curl -f http://localhost:<port>/path" |
tcp: <port> | tcpSocket.port: <port> | CMD-SHELL "nc -z localhost <port>" |
exec: [cmd] | exec.command: [cmd] | CMD [cmd] |
La resolución del puerto para http: sin un puerto explícito toma el primer nombre de puerto, en orden alfabético, que el contenedor declara en containers.<name>.ports, en ambos destinos. Un contenedor que no declara ningún puerto con nombre no puede llevar una sonda HTTP, y el build se detiene nombrando la sonda.
Compose degrada las sondas HTTP/TCP a comandos de shell de healthcheck, y un servicio de compose lleva un único healthcheck: cuando se declara más de una sonda, se traduce una y una advertencia nombra las descartadas.
Tipos de volumen
Cinco tipos de volumen; ninguno compuesto:
| Tipo | Semántica | K8s (helm) | Compose |
|---|---|---|---|
ephemeral | Tmpfs / emptyDir; desaparece con el pod | emptyDir: { sizeLimit } | montaje tmpfs:, sin tamaño (una advertencia informa de un sizeLimit escrito por el autor) |
configmap | Archivos de configuración de solo lectura | Referencia a un volumen ConfigMap | referencia configs: a nivel de servicio a una config de nivel superior que declaran los artifacts: de la Recipe |
secret | Archivos de secretos de solo lectura | Referencia a un volumen Secret | archivo de secreto de solo lectura montado con bind |
persistent | PVC único; sobrevive a los reinicios del pod | Recurso PVC + volume.persistentVolumeClaim | volumen con nombre |
persistentTemplate | PVC por réplica; acompaña a form: stateful | StatefulSet.volumeClaimTemplates | volumen con nombre (degradado; se emite una advertencia) |
Compose no puede expresar plantillas por réplica. Cuando persistentTemplate se traduce a compose, se degrada a un único volumen con nombre compartido por todas las réplicas, y una advertencia informa de la degradación. Un volumen persistentTemplate requiere form: stateful; declararlo en cualquier otra forma detiene el build.
Exposiciones de varios servicios
Cada servicio es una exposición independiente. Un patrón habitual: un servicio HTTP en el puerto 8080 (ClusterIP interno) + un servicio de métricas en el puerto 9090 (ClusterIP) + un endpoint de administración en el puerto 9901 (LoadBalancer):
services: http: type: ClusterIP ports: web: 8080 metrics: type: ClusterIP ports: prom: 9090 admin: type: LoadBalancer ports: admin: 9901Cada uno se convierte en un objeto Service de Kubernetes independiente cuando se renderiza con el proveedor helm, que en cambio se detiene ante una entrada Loopback. En compose, los servicios NodePort y LoadBalancer publican sus puertos en todas las interfaces del host del servicio compose, los Loopback solo en la dirección de loopback del host, y los ClusterIP y Headless no publican nada.
En la salida de K8s, los nombres de servicio llevan como prefijo el instance_id del componente para garantizar su unicidad. Los nombres de puerto deben coincidir con los nombres de puerto del contenedor declarados en containers.<name>.ports.
Contrato de traducción del lado del Provider: workloadSchema
Un Plugin de renderizado de proveedor (pluginType: provider) declara un spec.provider.workloadSchema — una declaración en JSON Schema 2020-12 que documenta cómo se traducen los campos del Workload a la salida nativa de ese proveedor. Este es el contrato de traducción autodocumentado. Consulta ../language-reference/entities/plugin.md para la superficie de autoría del Plugin, incluido el bloque spec.provider.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: helm-renderer version: 1.0.0 pluginType: providerspec: abiVersion: v1beta1 provider: workloadSchema: | # how Workload translates to K8s manifests // Each Workload produces: 1 controller object chosen by workload.form // (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job) // + 1..N Services (one per workload.services entry) // + 1..N PVCs (one per workload.volumes.*.persistent entry) // + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source) // ...El campo workloadSchema comunica la intención de traducción a los autores de catálogos y a las herramientas de IDE. Es el contrato de traducción documentado, declarado por convención en los proveedores que sintetizan; pero la capacidad de síntesis la determina el propio proveedor, no la presencia de este campo. Una Recipe que apunta con workload: a un proveedor que no puede sintetizar se rechaza cuando el nodo se renderiza —mediante la comprobación de capacidades del proveedor— con un error claro, declare o no el proveedor workloadSchema.
El esquema del Plugin declara spec.provider.workloadSchema —su cuerpo se compila a JSON Schema 2020-12 cuando se carga el Plugin—, y el consumo de workload: del lado de la Recipe está disponible. La capacidad de síntesis se aplica en tiempo de renderizado mediante la comprobación de capacidades del proveedor, basada en la capacidad que informa el proveedor vinculado; workloadSchema es el contrato documentado que el catálogo de la biblioteca estándar mantiene sincronizado con esa capacidad, no la entrada de la comprobación en sí. aggrega validate, ejecutado sobre todo el catálogo, señala además de forma anticipada, antes de un build, una Recipe workload: vinculada a un proveedor que no sintetiza, cuando el catálogo contiene la entidad Plugin de ese proveedor.
Los recursos auxiliares viven fuera del Workload
La especificación del Workload no tiene ningún campo additionalResources, ni extras, ni declaraciones en línea de ConfigMap/Secret/CRD. El Workload modela solo la forma de la carga de trabajo: contenedores, volúmenes, servicios, réplicas, planificación, contexto de seguridad, cuenta de servicio; todo lo que describe cómo se ejecuta la única unidad de cómputo.
Los recursos auxiliares tienen dos ubicaciones legítimas fuera del Workload:
- Features + FeatureRecipes — el mecanismo para los aspectos transversales. Un ServiceMonitor vinculado a «cualquier servidor con métricas expuestas» es
core/prometheus-exportercomo Feature. El recurso de enrutamiento que publica un servidor en un nombre de host también es una Feature, y la forma de enrutamiento decide cuál:core/public-ingressdonde el destino reconcilia un Ingress,core/http-routedonde ejecuta la Gateway API; cada una realizada por una FeatureRecipe que el Manifest selecciona para cada Release. Una NetworkPolicy aplicada a todas las cargas de trabajo de producción es una Feature que la Release de producción vincula a todo el boundary. Las Features se componen de forma ortogonal y pueden reutilizarse entre Recipes. Consulta 14-extensibility.md para la generación de recursos de la FeatureRecipe. artifacts:a nivel de Recipe: para recursos que pertenecen a la implementación de esta Recipe concreta y por los que no merece la pena crear una Feature. Un registro puntual de un CRD que la Recipe necesita. Un PodDisruptionBudget específico de la Recipe que solo se aplica cuando se usa esta Recipe. Un ConfigMap al que hace referencia el Workload de la Recipe. Cada entrada está en línea o se carga con$import:; consulta la sección sobre el mecanismo de artefactos más abajo.
La línea entre Feature y artefacto es una convención social. Si un recurso auxiliar es transversal (se aplica a muchas Recipes o se vincula de forma condicional mediante selectores), es una Feature. Si es intrínseco a esta única Recipe (la Recipe no puede hacer su trabajo sin emitir ese recurso), es un artefacto. Los autores eligen en función de la reutilización y de la semántica de vinculación; el compilador no vigila esa elección.
Las Features y los artefactos de Recipe cubren juntos los recursos auxiliares que necesita una Recipe.
El mecanismo de artefactos
Artefactos en línea y cargados desde archivo
El tipo de entrada artifacts emite archivos de manifiesto nativos del proveedor basados en plantillas directamente en la salida del boundary, junto a cualquier salida renderizada desde la fuente o sintetizada desde la carga de trabajo. Los autores lo declaran mediante dos superficies:
spec: artifacts: "servicemonitor.yaml": | apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: name: {{ .context.instance_id }}-monitor spec: endpoints: - port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml": $import: ./artifacts/networkpolicy.yaml "crd-registration.yaml": $import: ./artifacts/crd-registration.yamlLas rutas de $import: son relativas al directorio de la Recipe y deben permanecer dentro de él, porque cada archivo que lleva una publicación de la Recipe se toma de ese directorio —cada archivo que nombra una importación viaja con ella— y un archivo de fuera no lo haría. Una convención habitual los sitúa en un subdirectorio ./artifacts/, aunque el compilador no lo impone. La clave del mapa da nombre a cada archivo emitido; la sección siguiente explica qué significa eso en cada una de las tres formas.
Cada entrada (en línea o cargada con $import:) se procesa como plantilla Go contra el contexto de plantilla completo antes de emitirse al directorio de salida.
Qué da nombre a cada archivo de salida
El mapa está indexado por nombre de entrada, y la clave nombra lo que la entrada emite en cada forma de autoría. Para una entrada en línea, la clave es el nombre del archivo de salida, usado tal como está escrito:
artifacts: "configmap-config.yaml": | ... "pdb.yaml": | ...Produce configmap-config.yaml y pdb.yaml. La clave fija el nombre del archivo; dónde acaba el archivo lo decide el destino, y la sección sobre la emisión por proveedor, más abajo, lo trata.
Para una entrada $import: de archivo, la clave también es el nombre del archivo de salida. El archivo importado aporta el contenido; no aporta el nombre, así que un autor que quiere un nombre de archivo de salida concreto escribe ese nombre como clave:
artifacts: "monitor.yaml": $import: ./artifacts/monitor.yaml "netpol.yaml": $import: ./artifacts/subdir/some-other-name.yamlProduce .../monitor.yaml y .../netpol.yaml. El archivo importado de la segunda entrada se llama some-other-name.yaml, y ese nombre no llega a la salida: llega la clave. Dos entradas que importan archivos distintos que casualmente comparten nombre, ./extras/shared.yaml y ./overrides/shared.yaml, son por tanto dos salidas distintas, cada una nombrada por su propia clave.
Para una entrada $import: de biblioteca, que incorpora un paquete de archivos como una sola unidad, la entrada se expande en una salida por cada archivo del paquete, cada una anidada bajo la clave como <key>/<filename>. Una clave nombra muchos archivos, así que la clave por sí sola no puede nombrarlos: es el directorio donde acaban los archivos del paquete y no el nombre de ninguno de ellos.
Como cada forma nombra su salida a partir de la clave, la clave está limitada en la superficie de autoría a lo que puede ser un único nombre de archivo: una letra o un dígito inicial y, después, letras, dígitos, puntos, guiones y guiones bajos. Los puntos llevan la extensión que espera un consumidor, que es lo que hace que una clave pueda usarse directamente como nombre de archivo; y el alfabeto no contiene / ni un . inicial, por lo que una clave nunca puede formar más de un segmento de ruta ni ser el segmento del directorio padre. Una clave fuera del alfabeto no supera la validación del envoltorio al cargar el espacio de trabajo, en aggrega validate y en los diagnósticos del editor.
Dos salidas de artifacts: con el mismo nombre de archivo detienen el build cuando el nodo se renderiza, sean cuales sean las formas que las produjeron. Dos entradas de un mismo mapa artifacts: nunca nombran una misma salida: una clave es única dentro de un documento y es un único nombre de archivo, así que el nombre de salida de una entrada de archivo único es su clave y las salidas de una entrada de paquete están todas bajo un directorio nombrado por su clave. El primer segmento de cada ruta emitida es, por tanto, la clave que la produjo, y claves distintas siguen siendo nombres de salida distintos. Lo que cubre la detención es el caso que cruza tipos de entrada —un nombre de archivo aportado por dos de ellos, una plantilla del chart y una entrada de artefacto que producen ambas servicemonitor.yaml—, con un diagnóstico que nombra cada origen contribuyente.
Contexto de plantilla para artefactos
Las plantillas de artefactos tienen acceso al contexto completo de pilares:
.values,.infra,.context.*,.locals,.provides,.features,.metadata— los pilares estándar de Aggrega descritos en 06-data-taxonomy-and-composition.md..workload— la especificación del Workload analizada para esta Recipe (si existe). Permite que los artefactos hagan referencia a valores del Workload sin duplicación, p. ej., un ServiceMonitor que hace referencia a.workload.services.metrics.ports.prom..source— el contenido resuelto del camposource:(si existe).
Los artefactos se evalúan después de analizar el Workload, por lo que .workload está disponible cuando existe. Para las Recipes sin workload:, .workload es nil; una plantilla que intente desreferenciarlo falla con un error claro. Para las Recipes sin source:, .source es nil, con el mismo modo de fallo.
El invariante de autocontención
Los artefactos deben ser autocontenidos. Solo pueden hacer referencia a las entradas declaradas de la Recipe: el contexto de pilares, el propio Workload de la Recipe (cuando existe) y el propio valor source: de la Recipe. No pueden hacer referencia a:
- Salidas de otras Recipes en el mismo boundary.
- Recursos de Kubernetes del entorno que la Recipe no declaró.
- Secrets, ConfigMaps u otros recursos que se supone que existen externamente (salvo que se haga referencia a ellos mediante un pilar declarado).
Un artefacto ConfigMap al que hace referencia volumes.*.configmap.source del Workload debe emitirlo ESTA Recipe (mediante artifacts: que produzcan ese ConfigMap) o una Feature vinculada a este nodo. No se admiten dependencias entre una Recipe y otra dentro de un boundary.
Este invariante preserva la reutilización de la Recipe: una Recipe puede incorporarse a cualquier combinación de Aggregate + Release que cumpla su contrato de pilares, sin dependencias ocultas.
Etiquetas de procedencia
Tras la traducción, cada archivo emitido lleva la procedencia aggrega.ai/* en sus metadatos, tanto si se renderizó desde la fuente como si se sintetizó desde la carga de trabajo o se emitió desde una plantilla de artefacto. Cada superficie de emisión la estampa a partir de un mismo conjunto compartido de builders, de modo que el mismo archivo lleva siempre la misma procedencia, sea cual sea el tipo de entrada que lo produjo. El conjunto se divide según si un valor cumple el juego de caracteres de los valores de etiqueta de Kubernetes: las claves aptas para etiquetas son etiquetas (consultables); las claves no aptas para el juego de caracteres —recipe-uri (contiene un :), boundary-path (una ruta anidada contiene /) y sync-wave (el - inicial de una oleada negativa)— son anotaciones, cuyos valores no tienen restricciones. Un valor de identidad que la compilación no somete a las reglas de las etiquetas —el nombre del agregado, el entorno, el nombre del proveedor, las versiones del compilador y del proveedor— es una etiqueta escrita en una forma que una etiqueta admite y, donde esa forma difiere del valor, el valor literal es además una anotación bajo la misma clave (un Aggregate llamado imported/flow recibe la etiqueta imported-flow y la anotación imported/flow). Todos los archivos que llevan la salida de una misma Recipe comparten la misma procedencia:
metadata: labels: aggrega.ai/component-id: api # ... plus the recommended app.kubernetes.io/name label annotations: aggrega.ai/recipe-uri: api-server-helm:1.0.0 aggrega.ai/boundary-path: productionEsta división es uniforme en los tres tipos de entrada. (El proveedor Compose no tiene concepto de anotación y sus valores de etiqueta no tienen restricciones, así que emite el conjunto completo como etiquetas de servicio). Consulta 11-governance-and-compliance.md para el estampado de procedencia en tiempo de compilación.
Como un proveedor estampa la procedencia donde la admite su propio formato de salida, un proveedor cuyo formato no ofrece ese lugar para un archivo determinado emite ese archivo sin cambios y lo indica. Compose es el caso que hay que conocer: su lugar de procedencia es el bloque labels: de un servicio, así que un fragmento de artefacto compose que solo aporta volumes:, configs: o models: de nivel superior no lleva procedencia, y el build emite una advertencia «skipped provenance label injection (inyección de etiquetas de procedencia omitida)» que nombra el artefacto. Esa advertencia es esperable para un fragmento de esa forma y no indica un problema: los servicios que emite el mismo componente llevan el conjunto completo, y nada cambia en los bytes emitidos. Lo que descarta es la tercera posibilidad: un archivo que sale del build sin estampar y sin que se nombre.
CloudFormation es el otro caso que hay que conocer, y se diferencia en dónde acaba la procedencia y no en si acaba. Una plantilla de CloudFormation no tiene un bloque de metadatos a nivel de documento que viaje con un recurso, así que la procedencia va en el atributo Metadata propio de cada recurso, bajo una única clave aggrega.ai/provenance que contiene el conjunto completo:
"StoreBucket": { "Type": "AWS::S3::Bucket", "Metadata": { "aggrega.ai/provenance": { "aggrega.ai/component-id": "store", "aggrega.ai/recipe-uri": "store-recipe:1.0.0", "aggrega.ai/boundary-path": "stack" } }}De ese lugar se derivan tres propiedades. El atributo Metadata está disponible en todos los recursos, sea cual sea su tipo, así que se estampa cada recurso que lleva una pila ensamblada, incluidos los muchos tipos de recurso que no aceptan ninguna etiqueta y en los que un estampado basado en etiquetas no habría tenido cabida. El estampado se añade a cualquier Metadata que haya escrito el autor en lugar de sustituirlo, de modo que las entradas propias del autor permanecen junto a él. Y como es por recurso y no por plantilla, una pila que ensamblan varios componentes lleva la identidad contribuyente propia de cada recurso —su componente, su Recipe y su boundary—, algo que una única entrada para toda la plantilla no podría expresar.
El conjunto completo viaja junto bajo esa clave. Un valor Metadata es JSON sin restricciones, así que no hay ninguna división por juego de caracteres que hacer; las dos claves que solo lee un runtime de Kubernetes —el nombre de la etiqueta recomendada estándar y la anotación de orden de despliegue que consume un controlador GitOps— se omiten, ya que ninguna nombra nada en una pila. La entrada de procedencia simple aggrega.ai/sync-wave se mantiene, porque registra la oleada que declaró el componente en lugar de dar instrucciones a un controlador.
La forma que aquí no tiene lugar es una plantilla o un fragmento que no declara ningún recurso: uno que solo aporta Parameters, Mappings, Conditions o Rules. No lleva procedencia, llega a la pila ensamblada con su propio contenido intacto, y el build emite una advertencia «skipped provenance injection (inyección de procedencia omitida)» que lo nombra. Como con compose, esa advertencia es esperable para una contribución de esa forma: los recursos que el mismo componente aporta en otros lugares llevan el conjunto completo, y los bytes emitidos son los mismos tanto si hay algo escuchando como si no.
Semántica de los artefactos por Provider
La semántica por provider que sigue describe cómo cada provider integra los artefactos en su salida nativa.
provider helm: los artefactos son documentos YAML de Kubernetes escritos en un directorio con el nombre del componente que los declaró, dentro del directorio de salida que contiene los manifiestos renderizados a partir del chart y sintetizados a partir del Workload. El motivo es el nombrado: el provider nombra un manifiesto renderizado o sintetizado a partir del componente al que pertenece, mientras que un artefacto se nombra por la clave que escribió su autor, que no dice nada de qué componente se trata — así, dos componentes vinculados a una misma Recipe escribirían una sola ruta sin que ninguno de los dos autores pudiera separarlas. El directorio lleva el nombre propio del componente, de modo que el archivo que el autor vuelve a leer en la salida tiene el nombre que escribió, un nivel más abajo.
Un operador que quiera una disposición diferente dispone de la plantilla subDirectory: de la boundary, que mueve todos los archivos que emite un contribuyente y no solo los artefactos. Consulta ../language-reference/path-template-variables.md.
provider compose: los artefactos son fragmentos de compose. Las claves de nivel superior (services:, volumes:, configs:, models:) se fusionan en el docker-compose.yaml combinado de cada boundary durante el paso de composición de la boundary.
provider helm-chart (caso especial): los artefactos no se escriben en el directorio de salida como archivos independientes — Helm es dueño del pipeline de renderizado. En su lugar, el provider helm-chart coloca cada entrada de artifacts: dentro del propio chart, y la forma en que está escrita la entrada decide dónde acaba. Cada entrada se procesa como plantilla Go con el contexto de pilares de Aggrega PRIMERO, antes de cualquier colocación; a partir de ahí las dos formas divergen. Una entrada cargada con $import: es un archivo de plantilla pre-Helm: se inyecta en el directorio templates/ del chart ANTES del renderizado de Helm, de modo que Helm la renderiza junto con las plantillas propias del chart de origen. Un escalar de bloque inline es un archivo suelto del chart: se coloca en la raíz del chart bajo su clave escrita, sin prefijo templates/ y sin etiquetas de procedencia fusionadas, de modo que las plantillas propias del chart pueden leerlo mediante .Files.Get / .Files.Glob de Helm — el patrón ConfigMap a partir de archivos. Esto da al provider helm-chart un mecanismo de extensión equivalente al que artifacts: ofrece al provider helm simple, respetando el modelo de chart de Helm.
El archivo inyectado acaba en boundaries/<bp>/charts/<nodeID>/templates/<authored-key> — los archivos de un bundle anidados bajo esa clave — de modo que queda junto a las plantillas del chart de origen y Helm lo recoge durante la pasada de renderizado posterior. Un escalar de bloque inline acaba en boundaries/<bp>/charts/<nodeID>/<authored-key> — la raíz del chart, un nivel por encima de templates/ — porque un archivo leído mediante .Files debe estar donde el chart lo busca, y un archivo colocado bajo templates/ se renderiza en cambio como manifiesto. Ambas formas se nombran por la clave bajo la que se escriben; lo que las diferencia es el directorio en el que el provider las coloca.
Convención de delimitadores de helm-chart. La pasada de pre-plantilla de Aggrega sobre las entradas de artefacto de helm-chart, tanto las cargadas con $import: como las inline, usa los delimitadores [[ ]] en lugar de los {{ }} predeterminados, para que la sintaxis {{ ... }} propia de Helm dentro del archivo llegue intacta a la pasada de renderizado de Helm. Los autores escriben las sustituciones del lado de Aggrega como [[ .context.instance_id ]], [[ .values.name ]], etc.; las sustituciones del lado de Helm se mantienen como {{ .Values.x }}, {{ .Release.Name }}, {{- include "common.labels" . }}, etc. Mezclar los dos pares de delimitadores en un mismo archivo es la forma de escritura admitida.
Procedencia y artefactos de helm-chart. La procedencia se fusiona en metadata.labels y metadata.annotations (según la división por conjunto de caracteres descrita arriba) para los archivos cargados con $import: que sobreviven a un ciclo de ida y vuelta por YAML con sus tokens de Helm preservados — archivos que usan solo el contexto de Aggrega [[ ]] o con {{ }} de Helm solo en posiciones de escalares entre comillas. Los archivos con acciones de plantilla de Helm estructurales ({{- include ... }}, {{- if ... }}, {{- range ... }}, {{- with ... }} en posiciones donde emiten estructura YAML en lugar de hojas escalares), o los archivos con {{ ... }} sin comillas en posiciones de valor, no sobreviven al ciclo de ida y vuelta por YAML de Aggrega; el build emite una advertencia «skipped provenance label injection (inyección de etiquetas de procedencia omitida)» que nombra el artefacto y deja pasar el archivo sin cambios. Esta advertencia es esperable para cualquier archivo de artefacto de helm-chart cargado con $import: que use acciones de plantilla de Helm estructurales o sustituciones de valores de Helm sin comillas — es el caso común en la escritura de Helm en producción, no el caso límite. Los autores que necesitan etiquetas de procedencia en esos archivos las inyectan mediante una plantilla con nombre que escriben en el propio _helpers.tpl del chart (por ejemplo, una llamada aggrega.commonLabels) o un mecanismo equivalente del lado de Helm, no mediante la inyección pre-plantilla de Aggrega.
Colisiones con nombres de archivo de la raíz del chart. Un artefacto cargado con $import: cuya clave escrita coincide con un nombre de archivo de la raíz del chart (Chart.yaml, values.yaml, .helmignore, etc.) no es detectado por la comprobación de colisiones de nombres de archivo de Aggrega — el artefacto acaba en templates/<authored-key> mientras que el archivo raíz acaba en la raíz del chart, y el prefijo de ruta los hace distintos desde el punto de vista de Aggrega. Los autores evitan estos nombres de clave; la consecuencia de usarlos es que Helm ve ambos archivos (uno en la raíz del chart, otro dentro de templates/) y puede renderizar inesperadamente la copia del lado de templates.
provider terraform: los artefactos son archivos de configuración de Terraform, emitidos tal cual en el directorio propio del componente bajo el árbol modules/ de la boundary. HCL (main.tf) es el valor predeterminado más ergonómico y Terraform JSON (.tf.json) se acepta de forma equivalente; ninguno de los dos se transpila ni se reformatea. La configuración raíz de la boundary declara ese componente como un bloque module cuyo source apunta a ese directorio, de modo que una boundary entera sigue siendo un único grafo de dependencias; es el mismo directorio que ocupan los archivos de un módulo vendorizado, así que una Recipe que declara tanto source: como artifacts: los escribe uno junto a otro. La procedencia viaja como un bloque de comentarios de Terraform inicial; cuando un componente aporta un cuerpo JSON, que no tiene sintaxis de comentarios, cada cuerpo se emite sin cambios y la procedencia viaja en un archivo .tf complementario que solo contiene comentarios, junto a ellos, de modo que el sello nunca se duplica entre los dos. Consulta la página del provider terraform.
provider cloudformation: los artefactos son fragmentos de stack — los recursos que aporta un componente en lugar de una plantilla completa. El provider normaliza cada fragmento a funciones intrínsecas en forma larga en JSON puro y lo fusiona en el único stack ensamblado para ese directorio de salida, donde los recursos se unen en un solo mapa Resources y los provides del componente aparecen como Outputs del stack bajo nombres acotados al componente que los publica. Qué otras secciones de nivel superior de un fragmento sobreviven al ensamblado se explica en Qué conserva un documento fusionado de artifacts:. Consulta la página del provider cloudformation.
El ámbito de la boundary: archivos para la salida compartida de una boundary
El mecanismo de artefactos tiene un segundo ámbito. Todo lo anterior se escribe en la posición propia del componente dentro de la salida de su boundary; el spec.boundary.artifacts de una Recipe es el mismo mapa — las mismas tres formas, la misma regla de clave a nombre de archivo, el mismo contexto de plantilla — escrito en cambio una sola vez para la boundary en su conjunto. Existe para un archivo que el destino lee una sola vez para todo lo que despliega una boundary, y que ninguna posición propia de un componente puede contener: la documentación de Terraform indica que un módulo pensado para ser llamado no debe contener bloques provider, y que un módulo que los contiene no puede llamarse con depends_on, count ni for_each, por lo que la configuración de un provider pertenece a la configuración raíz de la boundary y no al módulo de un componente.
Dónde acaba. En el directorio que contiene la salida ensamblada del grupo de despacho, junto a los archivos que escribe allí el ensamblado propio del provider — en terraform, junto a la configuración raíz. El compilador evalúa cada entrada una vez por cada componente que renderiza la Recipe, con el contexto de ese componente, y escribe el archivo él mismo: al provider no se le entrega ninguno de estos archivos, y en ninguno se estampa de qué componente procede, porque pertenece a cada contribuyente que lo declaró.
Cómo se encuentran los contribuyentes. Los archivos que declaró cada contribuyente de un mismo grupo de despacho se fusionan por nombre. Un nombre declarado con bytes idénticos es un solo archivo; un nombre declarado con bytes distintos, o un nombre que escribe el propio ensamblado del provider, detiene la build nombrando el archivo y a cada contribuyente — el mismo rechazo que encuentran dos contribuyentes que escriben una misma ruta de salida. Así, una configuración de provider que necesitan dos Recipes la escriben ambas bajo un mismo nombre, y la build comprueba que coinciden.
Quién lo acepta. Que un archivo colocado junto a la salida ensamblada de una boundary signifique algo es una propiedad del destino del provider, de modo que es una declaración del propio provider, leída de la propia declaración del provider igual que sus tipos de entrada. Una Recipe que declara el bloque para un provider que no lo declara se rechaza antes de que se renderice nada. La tabla de abajo recoge la declaración en su última columna; de los providers distribuidos con el compilador, la hace terraform.
Lo que no son los artefactos
Tres distinciones estructurales:
No son multi-provider dentro de una misma Recipe. Una Recipe declara exactamente una capability: al principio de su spec. Todo lo que produce la Recipe — salida renderizada desde el source, salida sintetizada desde el workload y emisiones de artefactos — está en el formato nativo de ese provider. Los artefactos de una Recipe de helm contienen YAML de Kubernetes. Los artefactos de una Recipe de compose contienen fragmentos de compose. Una Recipe apunta a un solo provider; toda salida está en el formato nativo de ese provider.
La composición multi-provider ocurre a nivel de la Release. Las boundaries contienen componentes con providers mixtos; los contribuyentes de cada provider en la ruta evaluada de una boundary se despachan y ensamblan de forma independiente por (ruta, provider). Una Release con componentes dirigidos respectivamente a helm, helm-chart y compose puede colocar los tres en una misma boundary; la agrupación de despacho los reparte por provider, los contribuyentes de cada provider acaban en su propia salida ensamblada bajo la ruta de la boundary, y el operador escribe la coordinación entre providers mediante la estructura de boundaries que elija. La coordinación entre providers es responsabilidad del autor de la Release.
No son Recipes dentro de Recipes. Los artefactos no cargan ni componen otras Recipes. Son manifiestos inline (o rutas de archivo a manifiestos inline), procesados como plantilla con los pilares de esta Recipe y emitidos a la salida de esta Recipe. La reutilización de una Recipe se produce mediante tres mecanismos: el extends: de un Component (una Recipe escrita para un Component base sirve a todo Component que lo extiende; lo que se hereda son metadatos y esquemas, no archivos de salida — una Recipe en sí no declara ningún extends:); el mapeo de URI planos del Manifest (el mismo Component puede resolverse a Recipes distintas según el catálogo — consulta ../language-reference/entities/manifest.md); y Features + FeatureRecipes (aspectos transversales acoplados de forma ortogonal).
No son una capa de unión entre Recipe. Los artefactos no pueden hacer referencia a nombres, recursos ni estado que la propia Recipe no haya declarado. Un artefacto ConfigMap al que hace referencia el Workload de la Recipe debe emitirlo esta Recipe. Un artefacto que espera un Secret aprovisionado externamente debe obtener el nombre de ese Secret a través del pilar .features — de los provides resueltos del acoplamiento que lo emite — en lugar de suponer que existe. Este es el invariante de autocontención (descrito arriba) expresado desde la perspectiva de la escritura de artefactos: cada Recipe emite archivos en un solo formato, aplicados por una sola herramienta, en el directorio de salida de una sola boundary.
Matriz de capacidades por Provider
Cada provider declara qué tipos de entrada renderiza; un control central de tipos de entrada acepta las combinaciones admitidas y rechaza el resto con un diagnóstico uniforme cuando se renderiza el nodo. La capacidad es una propiedad del provider, no de la Recipe — un provider renderiza un subconjunto de los tres tipos. La columna artifacts: distingue los artefactos que viajan junto a una entrada principal sourced/synthesized de una Recipe independiente compuesta solo de artefactos (sin source:, sin workload:). Las dos últimas columnas son las declaraciones del provider de que respeta omits: y de que acepta los archivos que una Recipe aporta a la salida compartida de su boundary bajo boundary.artifacts: (arriba); ninguna de las dos es un tipo de entrada.
Lee cada columna por separado. Una fila indica qué tipos renderiza un provider tomados de uno en uno. No indica que dos tipos marcados puedan declararse juntos. Como los tipos se componen por adición, cada tipo declarado se despacha y emite por separado, de modo que una pareja puede rechazarse por un motivo que ninguna de las dos columnas recoge — casi siempre porque ambos tipos producen un archivo con el mismo nombre de salida. Qué combinaciones acepta realmente cada provider se explica en prosa en Qué acepta cada provider, en detalle.
| Provider | source: + valuesMapping: | workload: | artifacts: (junto a) | solo artefactos (independiente) | omits: | boundary.artifacts: |
|---|---|---|---|---|---|---|
| helm | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| compose | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| helm-chart | ✅ | ❌ | ✅ procesado como plantilla con los delimitadores [[ ]] | ❌ | ❌ | ❌ |
| terraform | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ |
| cloudformation | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
Esta tabla cubre los providers distribuidos con el compilador. Un provider suministrado por separado declara del mismo modo los tipos de entrada que acepta, si respeta omits: y si acepta boundary.artifacts:, y el compilador lee esa declaración por la misma vía — no se enumera aquí, porque una página publicada no puede enumerar providers que nunca ha visto.
Las celdas marcadas con ✅ se renderizan; ❌ es un rechazo por capacidad del provider que señala el control. Los fragmentos de compose por nodo se fusionan por ruta de ensamblado, de modo que las boundaries que comparten un directory: comparten un único archivo.
Qué acepta cada provider, en detalle
helm — todas las combinaciones. source: + valuesMapping:, workload:, artifacts:, dos cualesquiera de ellos, o los tres. Es el único provider distribuido con el compilador que no rechaza ninguna combinación, y el motivo es cómo nombra su salida: cada archivo emitido lleva el nombre del recurso que contiene, de modo que los manifiestos renderizados de un chart y los manifiestos de un Workload sintetizado nunca acaban bajo un mismo nombre. Una Recipe que declara los tres emite los archivos del chart, los archivos del Workload y los archivos de artefactos uno junto a otro en el directorio de salida de la boundary.
compose — todas las combinaciones excepto las dos en las que source: y workload: aparecen juntos. Cada tipo por sí solo se construye, y artifacts: puede acompañar a cualquiera de los dos. source: con workload: no puede construirse, ni tampoco los tres juntos; Por qué compose no puede combinar un source con un workload explica el motivo, y no se trata de un rechazo por capacidad.
helm-chart — source: + valuesMapping:, solo o con artifacts: al lado. Nada más. No sintetiza un workload: y no tiene una forma compuesta solo de artefactos: una Recipe cuyo único tipo de entrada es artifacts: se detiene. El motivo es dónde coloca este provider un artefacto — dentro del chart propio del componente — de modo que una Recipe sin source: no le deja ningún chart donde colocarlo.
terraform — tres formas: source: + valuesMapping: por sí solo, artifacts: por sí solo, o los dos juntos. No sintetiza un workload:.
cloudformation — las mismas tres formas que terraform, con la misma única exclusión. source: + valuesMapping: por sí solo, artifacts: por sí solo, o los dos juntos; sin workload:.
Cómo se ve un tipo de entrada rechazado
Una Recipe que declara un tipo de entrada que su provider vinculado no renderiza detiene la build cuando se renderiza el nodo, y la detiene sea lo que sea lo que la Recipe declare junto a ese tipo — combinar un workload: con un source: que el provider sí puede renderizar no hace pasar el workload. La detención nombra el provider, el tipo que no puede renderizar y los tipos que sí renderiza:
[CATALOG_ERROR E0265] instance unit provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesizedEl rechazo de la forma compuesta solo de artefactos se lee de la misma manera y nombra esa forma: provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced). E0265 es el identificador que conviene registrar cuando esta detención deba nombrarse de forma duradera — en un control de integración continua, una incidencia o un runbook; la tabla de todas las condiciones lo resuelve.
Por qué compose no puede combinar un source con un workload
El provider compose produce un fragmento por componente y le da el nombre del componente. El renderizado desde un source y la síntesis del Workload producen cada uno el fragmento de ese componente bajo ese único nombre, de modo que una Recipe que declara ambos produce dos archivos con el mismo nombre, y la build se detiene por la colisión:
[CATALOG_ERROR E0211] instance unit rendering node "unit" caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")El nombre del fragmento procede del identificador propio del componente y no existe ninguna superficie de escritura para él, de modo que ningún cambio en el contenido de la Recipe evita la colisión. La detención es una propiedad de la pareja y no de ninguno de los dos tipos — compose renderiza un source, compose sintetiza un Workload, y la tabla hace bien en marcar ambos. Para usar ambas formas en un componente con compose, repártelas entre dos componentes, o incorpora el contenido del source al Workload.
Qué conserva un documento fusionado de artifacts:
Dos providers fusionan sus contribuyentes en un único documento por ruta de ensamblado: compose en un único docker-compose.yaml, cloudformation en una única plantilla de stack. Un documento fusionado solo puede contener las secciones que modela su ensamblador, de modo que una marca en artifacts: indica dónde se coloca el contenido de un fragmento, no que sobreviva cada clave del fragmento.
compose conserva services:, volumes:, configs: y models: de un fragmento de artefacto, junto con sus claves de extensión con el prefijo x-. Un fragmento que declara cualquier otra cosa en el nivel superior detiene el build, nombrando la clave — networks:, porque las redes se derivan por boundary en lugar de acumularse a partir de los contribuyentes, e igualmente un bloque secrets: o un name: de nivel superior. La página del provider compose da las reglas de fusión por clave y la alternativa para el enrutamiento entre redes.
cloudformation conserva Resources, Outputs, Parameters, Mappings, Conditions, Metadata y Rules, y construye Transform a partir de los de cada contribuyente. Las transformaciones se unen en el orden que documenta CloudFormation, con los Globals de SAM viajando junto a la transformación que los lee, y una transformación que cambiaría cómo se despliega el contenido de otro contribuyente detiene el build nombrándola. Description no se conserva, y el build lo indica: emite una advertencia de campo no admitido que nombra la sección y el componente, igual que con cualquier otra clave de nivel superior que el stack no conserve, de modo que nada se descarta en silencio. La advertencia es informativa — la plantilla emitida es idéntica byte a byte a la que sería sin ella, y --no-unsupported-field-warnings silencia esa clase. Outputs se conserva bajo un nombre que el provider acota al componente contribuyente, de modo que dos componentes que aportan a un mismo stack una salida con el mismo nombre las mantienen separadas. Secciones de nivel superior en el stack ensamblado da cuenta de cada sección una por una.
Los otros tres providers no fusionan, de modo que ninguna clave de artefacto corre el riesgo de ser descartada por un ensamblador. helm no ensambla nada: los manifiestos de cada componente llegan tal cual al directorio de salida de la boundary. terraform y helm-chart anidan — los archivos de cada componente acaban en un directorio propio, un directorio de módulo de Terraform o un subchart, y un documento raíz en la boundary hace referencia a ellos — de modo que una entrada de artefacto se coloca como archivo completo en lugar de leerse dentro de un documento compartido. Dónde acaba una entrada de artefacto de helm-chart, y por qué su par de delimitadores es distinto, se explica en Semántica de los artefactos por Provider.