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

Recipe

El papel conceptual de la entidad Recipe (la plantilla de traducción escrita por Ops que asigna el Developer Intent al formato físico) se describe en architecture/04-entity-taxonomy.md. Esta página trata la superficie de autoría de la Recipe — el puntero (source), el mapper (valuesMapping:), el soporte nativo de IaC y ejemplos desarrollados.

La arquitectura de la Recipe: punteros y mappers

Una Recipe cumple exactamente dos funciones:

  1. El puntero (source): indica al compilador exactamente dónde está el código de infraestructura.
  2. El mapper (valuesMapping): inyecta el contexto abstracto de Aggrega en las variables específicas que espera el código subyacente. El campo es una única superficie de plantilla Go con tres modos de autoría — block scalar inline, $import: de archivo o $import: de biblioteca — que se seleccionan según la forma del contenido. Consulta El campo valuesMapping — tres modos de autoría más abajo.

Como una Recipe corresponde estrictamente 1:1 a una capacidad de renderizado, esa capacidad (spec.capability) se declara explícitamente en el nivel raíz, lo que garantiza que el compilador Go sepa exactamente qué plugin de renderizado Wasm posterior debe invocar.

spec.implements declara qué tipo de componente del catálogo puede implementar la Recipe. El compilador lo usa para verificar las asignaciones del Manifest (el implements de una Recipe asignada debe coincidir con el tipo asignado) y para sugerir candidatas — las recipes que se listan en un diagnóstico de falta de asignación y que aparecen primero en el autocompletado del editor. Nunca resuelve un build: la asignación del Manifest es la elección explícita de despliegue del usuario, fijada en el lockfile. Una Recipe cuyo implements no tiene versión, es exacto o es un rango compatible con la versión mayor solo se ofrece para un tipo; el usuario fija la elección. FeatureRecipe.spec.implements cumple el mismo papel para los tipos de feature.

A. Esquemas de origen dirigidos por Wasm

Para mantener los sesgos de implementación fuera del compilador, el bloque source no es un conjunto fijo de campos de infraestructura. El campo source admite dos formatos:

  • La cadena universal (rápida y limpia): ideal para rutas locales, artefactos OCI y repositorios Git. El compilador deduce el método de obtención a partir del prefijo y el sufijo de la cadena (./src, https://github.com/example/module.git, oci://...): una URL que termina en .git, o escrita con git:// o ssh://, es un repositorio Git que se obtiene en su rama predeterminada, y una URL https:// que no nombra ni un repositorio ni un chart .tgz o un fragmento .yaml se rechaza por ambigua.
  • El objeto estructurado abierto: un diccionario abierto (additionalProperties: true) cuyas claves define el provider y que se exponen a las plantillas de la Recipe como .source.* (por ejemplo .source.chart). La intención del diseño es que el socket WebAssembly de cada provider defina y valide su propia forma de origen (p. ej., registry/chart/appVersion para Helm).

Qué resuelve el núcleo. Ningún provider valida claves de origen propias. Un origen obtenido se resuelve mediante una identidad integrada cuyo kind selecciona un resolvedor — helm-oci-chart, helm-https-chart, compose-https-fragment y git-repository. Un origen destinado a obtenerse debe incluir kind y url; qué coordenada adicional selecciona el contenido depende del kind. Los kinds de chart y de fragmento admiten version, y la fijan tal como está escrita. git-repository admite ref — una etiqueta, una rama o un commit — y, opcionalmente, module_subdir, que nombra el directorio dentro del repositorio que constituye el artefacto; como solo un commit nombra contenido que no puede reapuntarse, la referencia se resuelve en el momento del bloqueo y el lockfile registra tanto la referencia escrita como el commit al que se resolvió. Un module_subdir que, tal como está escrito, sube por encima del repositorio — una barra invertida cuenta como separador — se rechaza antes de obtener nada. El repositorio se archiva desde su propio checkout: un enlace simbólico que incluye en un commit se archiva como el archivo o directorio al que apunta cuando este se encuentra dentro del repositorio, y uno que sale de él detiene el pull, nombrando el enlace por su ubicación en el repositorio. Un origen estructurado cuyo url: nombra una ruta del sistema de archivos no se obtiene: se lee del disco en las mismas condiciones que una cadena de ruta simple, con un url: relativo anclado al directorio que contiene el archivo de entidad que lo declara. Un origen estructurado que omite kind/url tampoco se obtiene y, si se pretendía una obtención, el build se detiene de forma explícita en el descenso de orígenes en el momento del bloqueo en lugar de resolverse silenciosamente en nada. El contenido siempre se fija por adelantado; el compilador nunca obtiene estado de runtime en vivo.

Qué se fija junto a la Recipe. Para un origen obtenido cuyos kind, url, chart, module_subdir, version y ref están todos escritos explícitamente en lugar de generados por plantilla, aggrega pin registra el digest de lo que obtuvo en entity.lock, un archivo en el propio directorio de la Recipe que incluyes en un commit junto a ella. Fijar es un paso del autor de la Recipe y no necesita ninguna Release; un pull sobre una Recipe cuyo lock no registra la fijación se detiene y la nombra, a menos que se pida al pull que ejecute ese mismo paso. Un build compara ese digest con el que registra el lockfile de la Release para el mismo origen, y se detiene donde ambos difieren — salvo en un origen escrito con un ref: de git, cuya fila se registra en el commit al que se resolvió la ref y no se compara. Un origen obtenido cuyas coordenadas se rellenan a partir de una plantilla se fija por Release en su lugar, en el lockfile de cada Release. Un origen que nombra un directorio o un archivo junto a la Recipe no se obtiene: aggrega pin registra un digest por cada archivo que aporta a lo que contiene una publicación de la Recipe — cada archivo del directorio de la Recipe, para un origen escrito como plantilla — y, una vez que el lock los registra, un build compara el origen con ellos antes de que el provider lo lea, y se detiene ante un archivo añadido, modificado o eliminado desde la fijación — con E0305, o primero con E0130 cuando el lockfile de la Release, escrito antes del cambio, registra la Recipe por lo que contiene. Un lock que no registra ninguna fijación para un origen así no deja nada que comparar a un build, y un pull o una publicación que no fija lo rechaza. El propio archivo de la Recipe nunca se modifica. aggrega pull describe el archivo y cómo responder a cada detención.

spec.capability puede incluir una fijación de versión en las formas que admite implements — exacta (helm:<version>) o un rango con acento circunflejo (helm:^<version>) — que selecciona qué versión del plugin del provider renderiza la Recipe; una fijación que ninguna versión disponible satisface detiene el build. Sin fijación (spec.capability: "helm"), la renderiza la versión disponible más alta. Las versiones disponibles son las que muestra aggrega plugin list: los providers integrados en aggrega llevan la versión del propio compilador. La fijación no forma parte del nombre de la Recipe: un Manifest asigna una Recipe que declara capability: "compose:1.2.3" como compose/<name>:<version>, exactamente igual que una sin fijar, y cambiar la fijación nunca le cambia el nombre; un valor de asignación que escribe la fijación en el nombre (compose:1.2.3/<name>:<version>) se rechaza como referencia de recipe mal formada (E0095) antes de buscar nada.

Modelo mental: spec.capability nombra el formato de salida que quieres (p. ej., helm, terraform, compose); el compilador lo resuelve al plugin Wasm que renderiza ese formato (p. ej., provider/helm). Tú declaras el formato; Aggrega vincula la herramienta.

B. Inyección de contexto: la capa de mapeo semántico

Para evitar que el compilador realice deep-merges peligrosos y no deterministas entre varios entornos, una Recipe solo permite una única fuente de verdad para su capa de mapeo.

Los ingenieros de Ops escriben el contenido de mapeo para traducir el contexto abstracto antes de que se ejecute el plugin de renderizado Wasm. El lenguaje de mapeo es la plantilla Go (text/template + Sprig); la biblioteca Sprig está prerregistrada; las acciones estándar define y template son compatibles, e include no está registrada.

Nombre del campoÁmbito y fase de ejecuciónMejor caso de uso
injectMapping (solo FeatureRecipe)Intercepción previa al renderizado. Se evalúa en la memoria de Go antes de la Recipe base. Fusiona en profundidad de forma nativa su diccionario de salida estrictamente sobre el pipe .context.inject del llamador. Ausente a propósito del esquema Recipe base — consulta entities/featurerecipe para la justificación arquitectónica.Reescribir de forma precisa las variables env inyectadas o dar formato a FQDN para un llamador sin necesidad de un JSONPatch de Wasm.
valuesMappingRenderizado base (plantilla Go). Se evalúa para asignar variables al chart/módulo de infraestructura source subyacente. Un solo campo, tres modos de autoría (inline, $import: de archivo, $import: de biblioteca). Consulta la subsección de abajo para el mecanismo de selección.Asignar variables estándar (como réplicas o etiquetas de imagen) a un chart de Helm directamente en el YAML de la Recipe, o hacer referencia a una plantilla compartida mediante $import: para reutilizarla entre una Recipe y otra.

Nota: injectMapping es exclusivo de las FeatureRecipes y aísla la intercepción de variables de valuesMapping. El valuesMapping de la Recipe base consume sin saberlo las cadenas .context.inject reescritas que generan los bloques injectMapping de la FeatureRecipe, de modo que ambos permanecen desacoplados.

Una clave que valuesMapping escribe como null llega al provider como null, y lo que hace allí lo decide el provider, así que cada página de provider lo indica: helm elimina el valor predeterminado del chart para esa clave, helm-chart la escribe en los values del umbrella, compose la escribe en el archivo compose, terraform la escribe como argumento de módulo null, y cloudformation la rechaza.

El campo valuesMapping — tres modos de autoría

El valuesMapping: de una Recipe es una única superficie de plantilla Go que acepta tres modos de selección. El compilador selecciona según la forma del contenido del campo; no se necesita ninguna anotación $mode:.

Modo 1: plantilla Go inline (block scalar de YAML). El valor del campo es una cadena escrita en la forma block scalar de YAML |:

spec:
valuesMapping: |
{{- with .values -}}
image:
tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }}
pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }}
architecture: {{ optional . `architecture` "standalone" }}
primary:
replicaCount: {{ optional .primary `replicaCount` 1 }}
{{- end }}

El modo inline es la forma de autoría típica para las Recipes cuyo contenido de mapeo es de tamaño pequeño a mediano (menos de ~50 líneas). El cuerpo de la plantilla está inline con el resto del envoltorio de la Recipe; el contenido de la Recipe es autónomo.

Modo 2: $import: de archivo. El valor del campo es un mapa que contiene solo $import: con una ruta de archivo local:

spec:
valuesMapping:
$import: ./mappings/api-server.tmpl

El compilador carga el contenido del archivo (una plantilla Go), lo renderiza con el contexto de plantilla estándar de la Recipe y trata el resultado como la salida del mapeo. La resolución de la ruta es relativa al directorio de la Recipe — una ruta relativa se ancla al directorio que contiene el recipe.yaml que la declara, no al directorio desde el que se invoca el build — y la ruta debe permanecer dentro de ese directorio, como explica Las rutas de contenido permanecen dentro del propio directorio de la Recipe. El modo de archivo es adecuado para contenido de mapeo mediano a grande (~50+ líneas) y para flujos de revisión en los que los cambios de mapeo aparecen como diffs de archivos independientes.

Modo 3: $import: de biblioteca. El valor del campo es un mapa que contiene solo $import: con una referencia de identidad por nombre simple a una entrada de una MappingLibrary:

spec:
valuesMapping:
$import: DatastoreHelpers#/mappings/MariaDBCore

El compilador resuelve la referencia frente al conjunto resuelto de MappingLibrary (el catálogo local más cualquier biblioteca fijada en el lockfile), carga el contenido de la entrada y lo trata como la salida del mapeo; una entrada cuyo cuerpo es a su vez un $import: en la raíz del campo se resuelve de forma recursiva. La referencia no incluye ningún host de registry — el nombre de la biblioteca se resuelve por identidad y la versión procede del lockfile por Release, con un mínimo de versión opcional :<version> (<Library>:<version>#/mappings/<entry>). El contenido de la biblioteca comparte el contexto de plantilla estándar de la Recipe. El modo de biblioteca es adecuado para reutilizar entre una Recipe y otra — patrones de mapeo que se repiten en muchas Recipes (varias Recipes de almacenes de datos que comparten lógica auxiliar de almacén de datos; varias Recipes del provider Helm que comparten patrones de pod template). La entidad MappingLibrary proporciona versionado, fijación en el lockfile y visibilidad en la interfaz del hub.

Reglas de selección. El compilador recorre el nodo YAML y selecciona según la forma del contenido:

  1. Si el nodo es un escalar de cadena, se selecciona el modo inline (Modo 1).
  2. En caso contrario, el nodo es un mapa; se comprueba la clave $import:.
  3. Si el valor de $import: es una referencia de biblioteca por nombre simple (<Library>#/mappings/<Entry>, opcionalmente con un mínimo :<version>), se selecciona el modo de biblioteca (Modo 3).
  4. En caso contrario (una ruta de archivo local), se selecciona el modo de archivo (Modo 2).
  5. Cualquier otra forma (un mapa sin $import:, un mapa con claves adicionales además de $import:, etc.) produce un error en tiempo de build.

Solo $import: de un único origen. $import: acepta un único origen. La fusión de varios orígenes no se admite en valuesMapping:. Una Recipe que necesite componer varios fragmentos de mapeo usa una entrada de MappingLibrary con composición interna define / template de plantillas Go, un archivo local con directivas template de plantillas Go que invocan archivos vecinos, o composición inline para contenido breve. Consulta entities/mappinglibrary para la entidad de biblioteca y vocabulary/cross-document-ref para la distinción más amplia $ref: / $import:.

Procedencia. Los mensajes de error de fallos de renderizado de plantillas citan la procedencia apropiada según el modo: las plantillas inline citan el archivo:línea de la Recipe donde empieza el block scalar; las importaciones de archivo citan el contenido del archivo importado; las importaciones de biblioteca citan la posición de origen de la entrada de la MappingLibrary, con la identidad de biblioteca sin host (<Library>#/mappings/<entry>) como puntero canónico para referencias estables — un host de registry en una referencia se rechaza, así que la ubicación física nunca entra en el puntero.

C. Soporte nativo de IaC

Un equipo de Ops que trae su propio infrastructure-as-code lo mantiene en el propio directorio de la Recipe — un directorio de módulo o de plantilla como ./src, nombrado por source: — o lo obtiene con un source: estructurado (un módulo de Terraform desde su repositorio git, con kind: git-repository), o lo escribe como cuerpos con plantilla bajo artifacts:. La capa de mapeo (valuesMapping: — inline, importación de archivo o importación de biblioteca) proporciona el contexto abstracto a ese código, y el provider emite el resultado en el formato propio del destino; ningún lenguaje de configuración se convierte en otro:

  1. Terraform: un módulo se copia archivo por archivo, y un cuerpo escrito por el autor se emite exactamente como está escrito, tanto HCL nativo (main.tf) como Terraform JSON (.tf.json) — la CLI terraform lee ambos. La configuración raíz del boundary, aggrega.modules.tf, llama al directorio de cada componente como un bloque module, y la salida de valuesMapping: de un módulo con origen se convierte en los argumentos de ese bloque. Consulta el provider terraform.
  2. CloudFormation: una plantilla con origen, YAML o JSON, y los fragmentos de recursos que escribe una Recipe se normalizan a JSON en forma larga y se fusionan en una sola plantilla de stack por boundary, con la salida de valuesMapping: rellenando los parámetros que declara una plantilla con origen. Consulta el provider cloudformation.

Un valor que solo existe una vez aplicada la infraestructura sigue siendo un puntero que el destino resuelve — una interpolación de Terraform ${ ... }, un Ref o un Fn::GetAtt de CloudFormation — y nunca se evalúa en tiempo de build.

Ejemplo A: el chart de Helm remoto (mapping inline y contrato de locals)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-chart
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
# The shipped fetch form: { kind, url, version }. 'kind' selects a built-in
# resolver (helm-oci-chart, helm-https-chart, compose-https-fragment).
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
# Default chart version. Override via infra.source_version.
version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals:
primary_compute: mariadb
listen_port: "3306"
volumes_path: "/spec/template/spec/volumes"
root_path: "/-"
# The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm
# pipeline: the suffix it follows the rendered name with. A local cannot read
# .context.rendered_name, so each template writing the full name joins the two.
secret_target_db_password: "mariadb-auth"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
# Every key the Component's provides contract declares is published
user: "{{ .values.user }}"
database: "{{ .values.database }}"
protocol: "mariadb"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"
auth:
# Reads the suffix from the local rather than restating it, so the secret
# name is authored once and every reader follows that one definition
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"
primary:
persistence:
size: "{{ .infra.storage.size }}"

Ejemplo B: el módulo de Terraform local (mapping desde archivo)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: aws-s3-tf
version: 1.0.0
spec:
capability: terraform
implements: aws/s3-bucket:1.0.0
source: "./src"
locals:
primary_compute: bucket_instance
resource_path: "/resource/aws_s3_bucket/main"
root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments
valuesMapping: |
bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data"
region: "{{ .infra.aws_region }}"

Ejemplo C: Recipe de Component concreta (vincula la infraestructura) Ops asigna la interfaz genérica a la realidad física. (Aquí es donde se vinculan los detalles de red L4 — ya sea codificados de forma fija o, como con el puerto del proxy de abajo, tomados del bloque infra que completa la Release.)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: kong-gateway
version: 1.0.0
spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
# A chart repository root paired with the chart's name.
kind: helm-https-chart
url: https://charts.konghq.com
chart: kong
version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides:
# The chart's proxy Service: it suffixes the name pinned below with "-proxy"
host: "{{ .context.rendered_name }}-proxy"
port: "{{ .infra.proxy_port }}"
protocol: "http"
# The contract's other keys: empty while nothing is wired to the models
# socket, and while metrics are off
endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}'
model: '{{ optional .values "model" "" }}'
metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

Disciplina de nomenclatura de recursos cloud.

Las Recipes que emiten nombres de recursos cloud — nombres de buckets de S3, identificadores de bases de datos de RDS, nombres de roles de IAM, nombres de stacks de CloudFormation y cualquier otro campo cuyo valor ocupe un espacio de nombres global en el proveedor cloud — deben concatenar {{ .metadata.release_name }} y/o {{ .context.instance_id }} en el nombre renderizado para evitar colisiones cuando la misma Recipe se ejecuta en varias Releases o instancias de componente. El bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" del ejemplo B es el patrón canónico.

La disciplina se aplica dondequiera que un único espacio de nombres global restrinja el nombre. Los nombres de buckets de AWS S3 comparten un espacio de nombres global entre todas las cuentas de una región; dos Releases del mismo Aggregate (prod-billing y staging-billing) no pueden desplegar ambas buckets llamados customer-data — el segundo despliegue falla en tiempo de ejecución con un rechazo del lado de AWS. Concatenar release_name diferencia la Release; concatenar context.instance_id diferencia por instancia de componente; concatenar ambos diferencia por componente y por Release.

Qué comprueba y qué no comprueba el compilador. El compilador no inspecciona las salidas de valuesMapping: en busca de campos de nombres de recursos cloud sin estas interpolaciones. La disciplina la sostienen los autores de Recipe (que saben qué campos nombran recursos globalmente únicos para el provider de destino) y los revisores (que detectan patrones de recursos sin nombre en la revisión de PR). Un plugin linter podría señalar las Recipes cuyas salidas de valuesMapping: hagan referencia a campos de nombres de recursos cloud sin interpolación de release_name / instance_id; el socket de linter se distribuye y se ejecuta mediante aggrega lint (consulta plugins/plugin-contract.md «Criterio de ubicación: el socket de linter frente a los roles de veredicto de gobernanza»), y ninguna de las reglas del linter de publicación comprueba esto.

Esta disciplina es uno de varios contratos sociales sostenidos por convención — disciplina de autoría que los autores aprenden de la documentación y no de la aplicación por parte del compilador. Consulta vocabulary/social-contracts.md para ver la lista completa de convenciones y la justificación arquitectónica de la clasificación de cada contrato.

Plantillas en el campo source. El campo source de una Recipe es en sí mismo una superficie de plantillas. Ambas formas de source aceptan plantillas Go: la forma de cadena universal

source: "{{ optional .infra `module_path` \"./src\" }}"

y la forma de objeto estructurado (cada subcampo con valor de cadena se evalúa como plantilla; los subcampos que no son cadenas pasan sin cambios). Lo que una plantilla de source puede leer depende de si el source nombra un artefacto remoto. La coordenada de un source remoto — version, chart, ref y module_subdir de un bloque estructurado que nombra un registry, un repositorio de charts o un repositorio git — se evalúa cuando aggrega pull resuelve el artefacto para fijarlo, solo frente a .values, .infra y .locals, con los helpers propios de Aggrega (optional, capitalizedWords e index) y ninguna de las funciones de Sprig. .context no está en esa superficie, por lo que qué artefacto se fija para un componente lo deciden los values y el infra que recibe, y nunca su nombre de instancia. Las entradas de locals: evaluadas allí son las que leen esos campos, y las que a su vez lee una de esas entradas: una entrada que ningún campo de source lee no se evalúa mientras se resuelve el source, así que un local que solo necesita el render — uno que llama a una función de Sprig, o que lee .context.instance_id — no afecta al pinning y se evalúa cuando se renderiza el nodo. Un campo que lee .locals de una forma que no nombra ninguna entrada concreta, como {{ index .locals "version" }}, hace que se evalúen todas las entradas. Un source que nombra una ruta en el workspace, como el de arriba, no se resuelve para el pinning: su plantilla se evalúa al renderizarse el nodo, frente al mismo contexto autocontenido que los locals de una Recipe — .context.instance_id, .values, .infra y .locals, todo el bloque resuelto del nodo — de modo que admite y rechaza las mismas raíces de referencia que una entrada de locals:, con una diferencia a su favor: puede leer cualquier entrada que declare el bloque, no solo las que están por encima de él. Una coordenada remota puede igualmente leer cualquier entrada que declare el bloque. .provides no está en ninguno de los dos contextos, y una plantilla de source que intenta alcanzar los provides de su propio nodo detiene el build y nombra la referencia infractora. Es una propiedad fija de la superficie y no una carencia a la espera de trabajo futuro — los locals de un nodo se resuelven antes que sus provides para que provides: pueda leer .locals, y una plantilla de source lee esos mismos locals resueltos en lugar de adelantarse a los provides. Las referencias a .context.inject y .context.uses están prohibidas por las mismas razones de autocontención; la URI del source debe resolverse antes de que se hidrate el pipe de topología y antes de que cualquier elemento posterior cargue el chart, el módulo o el cuerpo del artefacto al que apunta la URI. Las reglas completas de disponibilidad y la justificación de las referencias prohibidas están en la fila #5 de la matriz de expansión de plantillas. El uso canónico es una sobrescritura infra.source_version expuesta por el Component y trasladada al campo de versión del source — consulta entities/component «El pilar infra» — para que un catálogo no tenga que volver a publicar una Recipe con cada incremento compatible de versión upstream.

Inventario de esquemas del campo source. El campo source: acepta varias variantes de forma en el esquema. El soporte en tiempo de ejecución de cada variante depende del provider; la tabla siguiente documenta lo que hace cada forma.

FormaEjemploEstado
Ruta relativa simple del sistema de archivossource: "./charts/postgres"available — todos los providers distribuidos (helm, helm-chart, compose, terraform, cloudformation) aceptan una cadena con una ruta simple del sistema de archivos.
Ruta absoluta simple del sistema de archivossource: "/abs/path/to/chart"accepted but blocked — el esquema la acepta y todos los comandos que leen la Recipe la rechazan: una ruta absoluta nombra un lugar en la máquina en la que se escribió en lugar de contenido dentro del propio directorio de la Recipe, por lo que no viajaría con la Recipe. Mueve el chart al directorio de la Recipe y nómbralo de forma relativa a él; consulta Las rutas de contenido permanecen dentro del propio directorio de la Recipe.
Cadena vacíasource: ""accepted but blocked — el esquema acepta la cadena vacía y todo comando que carga la Recipe la rechaza al leer la Recipe, porque una cadena vacía no nombra ninguno de los dos modos. El rechazo nombra la ambigüedad junto con las dos maneras de salir de ella: omitir el campo para el modo sin source, o darle una ruta o URI real para el modo con source. aggrega validate <recipe-file> lo informa para la Recipe, y aggrega pull, aggrega build y aggrega validate --release lo informan para una Release que llega a la Recipe. Consulta errors/fatal-halts.md «Recipe source: is an empty string (El campo source de la Recipe es una cadena vacía)».
Objeto estructurado cuyo url: lleva un esquema de transportesource: { url: "oci://…/mariadb", version: "25.0.8" }available — el source-resolver integrado lee la forma {kind, url, version, chart, ref, module_subdir} (el esquema de url: selecciona el tipo — oci:// → chart OCI, https://….tgz → archivo comprimido de chart, raíz de repositorio https:// emparejada con chart: → chart de repositorio — o lo nombras con kind:), obtiene y fija el artefacto en aggrega pull, y el build lo extrae de la caché. Incluir un chart localmente (vendoring) se admite como alternativa, y no es obligatorio. El esquema acepta un objeto estructurado abierto. Consulta providers/helm.md «Conjunto de claves de source:».
Objeto estructurado cuyo url: nombra una ruta del sistema de archivossource: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" }available — un url: que no lleva esquema de transporte nombra una ruta, así que no se obtiene ni se fija nada; el build lee el contenido del disco. Un url: relativo se ancla al directorio que contiene el recipe.yaml que lo declara, y uno que sale de ese directorio — incluido uno absoluto — se rechaza: la misma lectura que reciben las dos filas de ruta simple de arriba, y la forma en que lo escribiste no la cambia. Solo url: decide desde dónde se lee el contenido; los demás campos seleccionan lo que se obtendría, y siguen llegando a las plantillas de la Recipe como .source.*.
URI OCI (oci://...)source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0"planned — objetivo de diseño para la distribución de catálogos. El resolver actual de tres niveles (los archivos que una Release nombra por ruta, los catálogos del workspace, el registry OCI remoto) está documentado en architecture/13-catalog-and-registry.md; el resolver a nivel de entidad consume URI OCI a través de esa cascada, pero la forma OCI del campo source: de cada Recipe no está conectada hoy en los providers.
Otros esquemas de URL (https://, git+https://, etc.)(ilustrativo)planned — documentado como intención de diseño en la hoja de ruta de la arquitectura para sources conectables; ningún provider lo admite hoy.

Cómo se ancla una ruta de source:. El anclaje se aplica a las rutas del sistema de archivos y a nada más, y se aplica sea cual sea la de las dos formas que lleve la ruta. Una ruta relativa se ancla al directorio que contiene el recipe.yaml que la declara, y una ruta que sale de ese directorio — incluida una ruta absoluta — se rechaza, como explica Las rutas de contenido permanecen dentro del propio directorio de la Recipe. Una referencia que lleva un esquema de transporte — oci://, https://, http://, git://, ssh://, git+ssh://, o cualquier referencia que termine en .git — nombra algo que se debe obtener y no una ruta, así que se transmite exactamente como la escribiste y nunca se une a un directorio.

En la forma estructurada la ruta es el campo url:, y se lee del mismo modo: un url: relativo se ancla al directorio que contiene el recipe.yaml, uno que sale de ese directorio se rechaza, y uno que lleva un esquema de transporte se obtiene. Todos los demás campos de un source: estructurado se transmiten sin cambios, incluidos los definidos por el provider.

Un source: escrito como plantilla se ancla con respecto al valor que produce la plantilla, no al texto de la propia plantilla. Una plantilla no nombra nada hasta que se ha evaluado, así que la lectura anterior se aplica a su resultado: un resultado que es una ruta relativa se ancla al directorio que contiene el recipe.yaml, uno que sale de ese directorio — incluida una ruta absoluta — detiene el build, y uno que lleva un esquema de transporte se transmite y se obtiene. Por tanto, una plantilla puede producir cualquiera de las formas del inventario anterior, y cada una se trata exactamente como se trataría el mismo valor escrito literalmente; la diferencia está solo en cuándo puede juzgarse la ruta, que para una plantilla es cuando el build la evalúa y no cuando se lee la Recipe.

Una plantilla que no produce nada — un resultado vacío — deja la Recipe sin source, que es el modo sin source. Eso es distinto de escribir tú mismo source: "", que no nombra ninguno de los dos modos y se rechaza; consulta la fila del inventario de arriba.

El inventario es la referencia canónica de lo que los autores pueden poner en source:; sus etiquetas son las que define 10-status.md.

Las rutas de contenido permanecen dentro del propio directorio de la Recipe

El contenido de una Recipe vive en el propio directorio de la Recipe, porque todo archivo que lleva una publicación de ella se toma de allí. Toda ruta que una Recipe escribe para contenido que lleva — su source:, ya sea una ruta simple o el url: de la forma estructurada, y cada archivo que sus entradas valuesMapping:, workload: y artifacts: importan con $import: — se lee con respecto al directorio que contiene el recipe.yaml y debe permanecer dentro de él. Esas rutas son también lo que lleva una publicación: los archivos que nombran viajan con la Recipe, y nada más de su directorio lo hace (consulta aggrega push). Una ruta que sale del directorio apunta a un archivo que no viajaría con la Recipe, de modo que el archivo no está ahí para quien la consume, y un pin registrado sobre él respaldaría bytes que esa persona no puede obtener.

Dos formas salen del directorio, y ambas se rechazan:

  • una ruta que sube por encima de él, como ../shared/charts/app;
  • una ruta absoluta, como /opt/charts/app, que nombra un lugar en la máquina en la que se escribió.

Una ruta que sube y vuelve a entrar es una ruta ordinaria dentro del directorio: ./charts/../values.tmpl nombra el values.tmpl que está junto a la Recipe. Lo que se juzga es dónde termina la ruta, medido desde el directorio de la Recipe sin salir de él — así que una subida hacia fuera que vuelve a nombrar el directorio al regresar, como ../1.0.0/values.tmpl escrito en un directorio llamado 1.0.0, también se rechaza. El propio nombre del directorio no viaja: una Recipe publicada se lee desde un directorio que nombra la caché del consumidor, donde ese nombre no encuentra nada.

Dónde se rechaza. Todo comando que lee la Recipe rechaza una ruta así al leerla, antes de que se obtenga, renderice o publique nada: aggrega validate, sobre el catálogo o sobre el propio archivo de la Recipe, aggrega pull, aggrega build, aggrega pin y aggrega push. Un source: escrito como plantilla no nombra nada hasta que el build lo evalúa, así que una plantilla que produce una ruta fuera del directorio la rechaza el build, en el momento en que el valor existe. La detención es A path names content outside the entity’s own directory (Una ruta nombra contenido fuera del directorio propio de la entidad), y nombra la ruta que escribiste.

Qué hacer en su lugar. Pon el archivo en el directorio de la Recipe, o en un directorio por debajo de él, y nómbralo de forma relativa a la Recipe: ./charts/app, ./extras/netpol.yaml. Un chart que usan varias Recipes se copia en el directorio de cada Recipe, ya que cada Recipe se publica por separado; un cuerpo de mapping, workload o artefacto que comparten varias Recipes pertenece a una MappingLibrary, WorkloadLibrary o ArtifactLibrary, a la que cada Recipe hace referencia por identidad.

Por qué una Release es diferente. Una Release apunta a otras entidades — su Aggregate, su Manifest, la Release que extiende — y nunca se publica, así que nada de lo que lee viaja a ninguna parte. Esas referencias, y el archivo que importa su parameters:, se leen tal como están escritas, y eso es lo que permite que un Aggregate sea compartido por variantes de Release en subdirectorios. Consulta entities/release.md.

El mismo límite se aplica a una FeatureRecipe, y a todo esquema que importe un Component o una Feature.

El campo workload: — tipo de entrada sintetizado

Recipe.spec.workload: declara el cuerpo de Workload que el compilador sintetiza en recursos nativos del provider. Es uno de los tres tipos de entrada que una Recipe puede declarar junto a source: (renderizado desde source) y artifacts: (manifiestos auxiliares). Al menos uno de los tres debe estar presente en todo provider; un servicio que el build no aprovisiona declara un workload: con form: reference.

El campo acepta tres modos de autoría — block scalar inline, $import: de archivo o $import: de biblioteca. El compilador despacha según la forma del contenido del campo; no hace falta ninguna anotación $mode:.

Modo 1: inline (escalar de cadena de plantilla Go). El valor es un block scalar de YAML cuya salida se interpreta como aggrega.ai/v1beta1 Workload:

spec:
capability: helm
implements: core/web-server:1.0.0
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra "replicas" 1 }}
containers:
app:
image: "{{ .values.image }}"
ports:
http: 8080

Los campos de un Workload están en la raíz del documento — no hay ningún envoltorio spec: — y containers: y los ports: de cada contenedor son mapas indexados por nombre en lugar de secuencias, con el orden del autor preservado. El provider traduce esa forma a su propia forma nativa, de modo que una entrada del mapa de contenedores aparece en la salida renderizada de helm como un elemento containers[] con el nombre de su clave; la forma escrita es el mapa, no la lista renderizada.

Modo 2: $import: de archivo. El valor es un mapa con una única clave $import: que apunta a un archivo local de plantilla Go:

spec:
workload:
$import: ./workload/web-server.yaml.tmpl

La resolución de rutas coincide con la de valuesMapping:: una ruta relativa se ancla al directorio que contiene el recipe.yaml que la declara, no al directorio desde el que se invoca el build, y debe permanecer dentro de ese directorio. El cuerpo importado es una plantilla Go evaluada en el contexto de render de la Recipe, exactamente como un cuerpo inline.

Modo 3: $import: de biblioteca. El valor es un mapa con una única clave $import: que lleva una referencia de identidad por nombre simple a una entrada de una WorkloadLibrary:

spec:
workload:
$import: BaseWorkloads#/workloads/StatelessService

El fragmento #/workloads/ es lo que selecciona una entrada de Workload, y es el fragmento que distingue esta referencia de la forma #/mappings/ que usa valuesMapping: — esa direcciona una entrada de una MappingLibrary y no nombra un cuerpo de Workload. La referencia no lleva ningún host de registry, la versión resuelta proviene del lockfile por Release, se puede afirmar un mínimo de versión :<version> opcional como <Library>:<version>#/workloads/<Entry>, y una entrada cuyo cuerpo es a su vez un $import: en la raíz del campo se resuelve de forma recursiva. El cuerpo importado es una plantilla Go evaluada en el contexto de render de la Recipe que lo consume, así que .values, .infra y .features fluyen hacia él exactamente como hacia un cuerpo inline. Consulta entities/workloadlibrary para la entidad de biblioteca y la gramática completa de la referencia.

El provider de destino debe admitir la síntesis (el catálogo de la biblioteca estándar declara workloadSchema en esos providers por convención); apuntar a un provider que no puede sintetizar se rechaza cuando se renderiza el nodo, con el diagnóstico de capacidad del provider — basado en la capacidad del provider, no en la presencia de workloadSchema. Para la gramática completa de Workload, los campos de paso directo con forma de K8s y el comportamiento de traducción por provider, consulta entities/workload.md. Para el modelo más amplio de los tres tipos de entrada y el ensamblador que fusiona la síntesis con la salida renderizada desde source y los artefactos, consulta architecture/16-recipe-input-composition.md.

Entregar los valores propios de un componente a la imagen propia del desarrollador. Por la convención del catálogo de la biblioteca estándar, se espera que una Recipe que ejecuta una imagen construida por el desarrollador entregue todo lo que resolvieron los bloques inject: del desarrollador, desde .context.inject, y además puede entregar los valores propios del componente con nombres elegidos por ella. Donde el Component declara spec.inject, es el propio bloque del desarrollador el que elige los nombres, y .context.self_inject indica a la Recipe el único valor propio que lee la plantilla de cada entrada — values.<key> para una entrada que lee exactamente un valor propio y nada más. La convención del catálogo de la biblioteca estándar es tratar los nombres que una Recipe da a esos valores como valores predeterminados y no como un contrato que el código del desarrollador deba leer, entregando un valor con su nombre predeterminado solo cuando ninguna entrada lo mapea; un catálogo empresarial puede elegir otra cosa. El contrato del contexto de plantillas da las reglas exactas del mapa y una plantilla de ejemplo completa.

El campo artifacts: — manifiestos auxiliares

Recipe.spec.artifacts: es un mapa de nombre de entrada → definición del cuerpo de un artefacto cuyas entradas emiten archivos de manifiesto adicionales junto a la salida principal de la Recipe, obtenida de una fuente o sintetizada. Es uno de los tres tipos de entrada (desde fuente / sintetizada / artefactos) — una Recipe puede declarar artifacts: solo, o junto con workload: y/o source:.

El valor de cada entrada adopta uno de tres modos, elegidos según la forma del contenido y paralelos a los de workload: — contenido inline, un $import: de archivo o un $import: de biblioteca. El compilador elige el modo según la forma del contenido del valor; no hace falta ninguna anotación $mode:. En los tres modos, la clave del mapa nombra lo que la entrada emite: en los dos modos de archivo único es el nombre del archivo de salida, y en el modo bundle es el directorio bajo el que se anidan los archivos del bundle. Como la clave nombra la salida, se limita 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 conservan la extensión que una clave lleva por convención — main.tf, template.yaml, serviceaccount.yaml —, mientras que el alfabeto no admite /, que haría que una clave nombrara una ruta en lugar de un archivo, ni un . inicial, de modo que una clave nunca puede ser el segmento del directorio padre. Una clave fuera de ese alfabeto no supera la validación de la envoltura al cargar el espacio de trabajo, en aggrega validate y en los diagnósticos del editor.

spec:
capability: helm
implements: core/web-server:1.0.0
artifacts:
extra-configmap.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: "{{ .context.instance_id }}-extras"
data:
threshold: "{{ .values.threshold }}"
network-policy.yaml:
$import: ./artifacts/network-policy.tmpl
operator-support:
$import: PlatformArtifacts#/artifacts/OperatorSupport

Modo 1: inline (escalar de cadena con plantilla Go). El valor es un escalar de bloque, y la clave del mapa es el nombre del archivo de salida, usado tal como está escrito — la primera entrada de arriba emite extra-configmap.yaml.

Modo 2: $import: de archivo. El valor es un mapa con una única clave $import: que apunta a un archivo local de plantilla Go, y la clave del mapa es el nombre del archivo de salida, exactamente como en el modo 1. El archivo importado aporta el contenido; no aporta el nombre. La segunda entrada de arriba tiene la clave network-policy.yaml y emite network-policy.yaml, aunque el archivo que importa se llame network-policy.tmpl. Así, un autor que quiere un nombre de archivo de salida concreto lo escribe como clave, y dos entradas que importan archivos distintos que casualmente comparten nombre — ./extras/shared.yaml y ./overrides/shared.yaml — son dos salidas distintas. La resolución de rutas es la misma que en valuesMapping: y workload:: una ruta relativa se ancla al directorio que contiene el recipe.yaml que la declara, no al directorio desde el que se invoca la compilación, y debe permanecer dentro de ese directorio.

Modo 3: $import: de biblioteca. El valor es un mapa con una única clave $import: que lleva una referencia de identidad por nombre simple a un bundle de una ArtifactLibrary, <Library>#/artifacts/<name>. Un bundle es un conjunto de archivos importados como una sola unidad, así que una entrada se expande en una salida por cada archivo del bundle, cada una anidada bajo la clave del mapa como <key>/<filename> — la clave nombra el punto de uso y es el directorio en el que acaban esos archivos, no el nombre de ninguno de ellos. La tercera entrada de arriba tiene la clave operator-support; si PlatformArtifacts#/artifacts/OperatorSupport declara crd.yaml y rbac.yaml, esa única entrada emite operator-support/crd.yaml y operator-support/rbac.yaml. La referencia no lleva ningún host de registry — se rechaza una forma oci://… con host —, la versión resuelta procede del lockfile por Release, y puede indicarse un mínimo de versión :<version> opcional como <Library>:<version>#/artifacts/<name>. Consulta entities/artifactlibrary para la entidad de biblioteca y la gramática completa de la referencia.

Un $import: de archivo se fija junto a la Recipe. aggrega pin registra el digest de los bytes de cada archivo importado en el archivo entity.lock del directorio de la Recipe, con la clave del mapa de la entrada como clave, y aggrega build vuelve a calcular el digest del archivo y se detiene con [CATALOG_ERROR E0026] cuando ya no coincide — o antes con E0130 cuando el lockfile de la Release, escrito antes de la edición, registra la Recipe por lo que contiene —, de modo que un archivo editado después de fijarse nunca se renderiza sin verificar. Si el cambio era intencionado, ejecuta aggrega pin sobre la Recipe para registrar el nuevo digest; si no, restaura el archivo. Una entrada inline forma parte del archivo de la Recipe, y una entrada de biblioteca queda fijada por la versión de la biblioteca que registra el lockfile, así que ninguna de las dos lleva un pin propio. aggrega pull describe el archivo.

La plantilla de cada entrada de artefacto se evalúa con el mismo contexto de plantilla que valuesMapping:, sea cual sea el modo que aportó su cuerpo. Dos salidas con el mismo nombre de archivo detienen la compilación cuando se renderiza el nodo. Dos entradas de un mismo mapa artifacts: no pueden nombrar una misma salida: una clave de mapa es única dentro de un documento y escribe un solo nombre de archivo, así que la salida de una entrada de archivo único es su clave y los archivos de una entrada bundle quedan bajo un directorio con el nombre de su clave — el primer segmento de cada ruta que emite una entrada es la clave que la produjo, de modo que claves distintas siguen siendo nombres de salida distintos, se llamen como se llamen los archivos importados. Lo que cubre la detención es un mismo nombre de archivo aportado por dos tipos de entrada distintos — una plantilla de chart y una entrada de artefacto que producen ambas servicemonitor.yaml —, notificado para esa Recipe con un diagnóstico que nombra cada origen que contribuye.

Casos de uso. artifacts: es el lugar de los recursos auxiliares que el chart o el módulo principal no produce: una NetworkPolicy que acompaña a una carga de trabajo, un HPA emparejado con un Deployment, un ConfigMap sidecar con instance_id como clave. Los recursos auxiliares transversales que se aplican a muchos componentes (un sidecar de copia de seguridad conectado a cada almacén de datos, por ejemplo) corresponden a la Resource Generation de la FeatureRecipe y no a los artifacts: de cada Recipe — consulta entities/featurerecipe.md para la superficie de extensión de la FeatureRecipe.

El bloque boundary: — archivos para la salida compartida de la boundary

La mayoría de las Recipes nunca lo necesitan. Todo lo demás que escribe una Recipe pertenece a su propio componente: el proveedor lo coloca en la posición propia de ese componente en la salida de la boundary. Algunos archivos pertenecen, en cambio, a la boundary en su conjunto — un archivo que el destino lee una sola vez para todo lo que la boundary despliega. La configuración de proveedores de Terraform es el caso habitual: la documentación de Terraform deja los bloques provider fuera de un módulo al que llama otra configuración, y un módulo que lleva uno propio no puede llamarse con depends_on, count o for_each. spec.boundary.artifacts es donde una Recipe escribe un archivo así.

spec:
capability: terraform
implements: core/api-gateway/azure-api-management:1.0.0
artifacts:
main.tf:
$import: ./module/main.tf
boundary:
artifacts:
# Terraform reads this beside the root configuration; one copy serves every
# component of the boundary that declares it.
provider-azurerm.tf: |
provider "azurerm" {
features {}
}

El bloque es artifacts: en un segundo ámbito. artifacts es su único miembro, y adopta exactamente la forma del propio artifacts: de la Recipe: los mismos tres modos — contenido inline, un $import: de archivo, un $import: de biblioteca cuyos archivos se anidan bajo la clave de la entrada como <key>/<filename> —, la misma regla de clave a nombre de archivo y el mismo alfabeto para una clave, y el mismo contexto de plantilla, de modo que una entrada lee .values, .infra, .locals y el resto exactamente como lo hace una entrada de artifacts:. Necesita al menos una entrada, y cualquier otro miembro bajo boundary: se rechaza cuando se lee la Recipe. Una FeatureRecipe no tiene un bloque así.

Dónde se escribe un archivo. Una sola vez, en el directorio que contiene la salida ensamblada de la boundary, junto a los archivos que escribe allí el propio ensamblado del proveedor — en terraform, junto a la configuración raíz aggrega.modules.tf y no dentro del módulo del componente. Al proveedor no se le entrega ninguno de estos archivos: el compilador los evalúa y los escribe él mismo, y no marca en ninguno de qué componente procede, porque pertenece a todos los componentes que lo declararon. Una entrada cuya plantilla no produce nada al renderizarse no escribe ningún archivo.

Cómo se encuentran varios contribuyentes. Cada entrada se evalúa para cada componente que la Recipe renderiza en la boundary, y los archivos que declararon todos los contribuyentes de la boundary se combinan por nombre. Un nombre evaluado a los mismos bytes — por dos componentes vinculados a una misma Recipe, o por dos Recipes que configuran un mismo proveedor de forma idéntica — es un solo archivo. Un nombre evaluado a bytes distintos detiene la compilación, nombrando el archivo y a cada contribuyente, porque ningún archivo único es lo que todos escribieron; lo mismo ocurre con un nombre que escribe el propio ensamblado del proveedor, como aggrega.modules.tf. Ambos casos son la colisión de la salida ensamblada. Dos Recipes que configuran un mismo proveedor con dos nombres de archivo distintos no se combinan — se escribe cada archivo — y es entonces el destino el que notifica la configuración duplicada, así que las Recipes destinadas a compartir una configuración de proveedor comparten su nombre de archivo, por convención uno con el nombre del proveedor que configura.

Qué proveedores lo aceptan. Que un archivo colocado junto a la salida ensamblada de una boundary signifique algo es una propiedad del destino del proveedor, de modo que forma parte de la declaración del propio proveedor. Una Recipe que declara el bloque y cuyo proveedor no lo acepta se rechaza antes de que se renderice nada, sea cual sea el resultado del renderizado de sus entradas; consulta The provider does not support boundary artifacts (El proveedor no admite artefactos de límite). La tabla de capacidades recoge lo que declara cada proveedor.

Providerboundary.artifacts:
terraformAceptado. Cada archivo se escribe junto a la configuración raíz de la boundary, que Terraform lee junto con todos los demás archivos de configuración de ese directorio.
helm, compose, helm-chart, cloudformationRechazado antes de que se renderice nada.

Un $import: de archivo se fija aquí como uno que importa una entrada de artifacts:. El lock de la entidad registra su digest en la misma lista artifactDigests, bajo boundary/<key> en lugar de solo bajo la clave, de modo que una entrada de cada bloque escrita bajo una misma clave se fija por separado. El paso de fijación lo registra, un pull que no fija se detiene donde su pin falta o ya no coincide, y una compilación rechaza un archivo editado después de fijarse exactamente como rechaza un archivo de artifacts:.

El campo outputLabels: — etiquetas declaradas por el autor en la salida renderizada

Recipe.spec.outputLabels: es un mapa de clave de etiqueta → valor que el proveedor estampa en cada objeto que produce la salida renderizada de la Recipe. Es el lugar honesto para un rasgo de realización — una propiedad de cómo una Recipe concreta realiza un componente, en contraposición a lo que el componente es. Toma el almacenamiento con el que una realización persiste sus datos, escrito más abajo con la clave ilustrativa example.io/storage-backing: una Recipe de Helm que monta un PersistentVolumeClaim y una Recipe de Compose que monta un volumen con nombre realizan el mismo componente con mecanismos distintos, así que llevan outputLabels distintas, y las herramientas posteriores (asignación de costos, políticas, inventario) pueden distinguirlas en los recursos emitidos. La clave es ilustrativa — example.io/ es un namespace de ejemplo, y un catálogo elige las claves que leen sus propias herramientas.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/storage-backing: persistent-volume
example.io/team: platform

Las etiquetas de salida viajan por el mismo carril que las etiquetas fijas de procedencia de la compilación: se combinan en el conjunto de etiquetas que estampa cada superficie de emisión, así que llegan a todas partes adonde llega la procedencia. Lo que cambia es la titularidad — las claves de procedencia pertenecen al compilador, las outputLabels al autor de la Recipe.

La etiqueta de identidad propia de un componente no se escribe aquí — una convención del catálogo, no una regla que el compilador imponga. Las claves que indican qué es el componente y no cómo lo realiza una Recipe — su categoría cognitiva, su tipo operativo, sus etiquetas de capacidad por rol, quién opera el recurso subyacente, la clase de licencia de lo que envuelve — se declaran en los metadata.labels del Component; consulta entities/component «La taxonomía semántica de etiquetas» para los ejes. Una Recipe lleva una de ellas a su salida renderizada nombrando la clave en outputComponentLabels: más abajo, no escribiendo aquí la clave y un valor. El motivo es que una entrada literal es una segunda copia de un valor que el componente ya lleva, y una segunda copia puede discrepar de la primera: el autor de una Recipe puede escribir una postura en un nodo cuyo Component declara otra, y decirle así a un lector posterior algo que el grafo no dice. Una entrada promovida copia por referencia y, por tanto, no tiene segunda copia que pueda divergir. El núcleo acepta lo que escribas, salvo por la regla de los namespaces reservados de más abajo; la convención la mantienen los autores de catálogos.

Namespaces reservados. Los namespaces aggrega.ai/ y app.kubernetes.io/ están reservados para la procedencia nativa de la plataforma. Una Recipe que declara una clave de outputLabels bajo cualquiera de los dos prefijos se rechaza al cargarse con un error de catálogo claro que nombra la clave en cuestión. Cualquier otra clave se acepta. Por lo demás, el núcleo no vigila la clave ni el valor — una clave o un valor que no sea válido para la superficie de etiquetas del motor de destino es responsabilidad del autor, y el runtime posterior lo rechaza; el compilador no interviene más allá de la regla de los namespaces reservados.

Exposición por proveedor. Cada proveedor traslada las etiquetas a su propia superficie de salida:

  • helm, síntesis de workload — tanto en los metadata.labels del objeto como en los metadata.labels de la plantilla de pod, en correspondencia con el lugar donde la síntesis coloca la procedencia.
  • helm, renderizado desde la fuente y artefactos — en los metadata.labels del objeto.
  • compose — en el mapa labels: de cada servicio.
  • terraform — como tags por recurso en los cuerpos de artefacto .tf.json direccionables estructuralmente, en la medida de lo posible: un bloque de recurso que ya declara un mapa tags (AWS/azurerm) o labels (Google) recibe allí las etiquetas de salida, una clave declarada por el autor nunca se sobrescribe, y un recurso sin ese atributo se deja intacto (nunca se inventa un atributo). Los cuerpos en HCL nativo (main.tf, *.tf) y los módulos vendorizados se emiten literalmente y no llevan tags inyectadas. La procedencia de Terraform sigue viajando en su archivo de comentarios asociado, separado del carril de tags.

Las etiquetas de salida son solo etiquetas; no existe una superficie separada de anotaciones de salida. outputLabels lo declara el autor de la Recipe (la capa de realización escrita por Ops), no el Aggregate — describe la realización, nunca la identidad del grafo abstracto del desarrollador.

El campo outputComponentLabels: — promover las etiquetas propias de un componente

Recipe.spec.outputComponentLabels: es una lista de claves de etiqueta, no de pares clave-valor. Para cada clave que nombra, el proveedor estampa esa clave en la salida renderizada con el valor que la clave tiene en la instancia del componente que se está renderizando. Donde outputLabels indica un valor, outputComponentLabels indica de dónde debe leerse el valor.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/team: platform
outputComponentLabels:
- component.aggrega.ai/hosting

Dado un Component cuyos metadata.labels declaran component.aggrega.ai/hosting: managed, cada objeto que esta Recipe renderiza para ese componente lleva component.aggrega.ai/hosting: managed. Vincula la misma Recipe a un componente que declare self-hosted y los objetos de ese componente llevarán self-hosted en su lugar — una Recipe, una clave nombrada, un valor por componente.

La promoción es por referencia, y de eso se trata. El valor se lee del componente cada vez que se renderiza la salida, así que no puede divergir de la identidad de la que procede: no hay una segunda copia que mantener sincronizada cuando cambia la etiqueta del componente. Una entrada literal de outputLabels que repite la etiqueta de un componente es esa segunda copia, y las dos discrepan en cuanto cualquiera de ellas cambia. Así que recurre a outputLabels cuando el valor es una propiedad de cómo esta Recipe realiza el componente, y a outputComponentLabels cuando el valor ya existe en el componente y la salida renderizada también debe llevarlo.

Una clave promovida llega exactamente a la misma superficie que una literal — la exposición por proveedor descrita arriba se aplica sin cambios, y ningún proveedor distingue una clave promovida de una escrita en el propio lugar.

Namespaces reservados. Los namespaces aggrega.ai/ y app.kubernetes.io/ están reservados para la procedencia nativa de la plataforma, y una clave promovida bajo cualquiera de los dos prefijos se rechaza al cargarse con un error de catálogo que nombra la clave y el campo en el que aparece. El criterio es el prefijo desnudo: una clave como component.aggrega.ai/hosting está en un namespace propio y no bajo la raíz reservada, y se puede promover.

Una clave pertenece a un bloque o al otro. Declarar la misma clave tanto en outputLabels como en outputComponentLabels se rechaza al cargar, de modo que cada clave estampada tiene una única fuente — o el valor literal escrito en la Recipe o la etiqueta propia del componente, nunca ambos.

Una clave promovida que el componente no declara no estampa nada. La compilación continúa y emite una advertencia que nombra el nodo, la Recipe y la clave que falta. Es deliberado: una Recipe vinculada a componentes cuyos conjuntos de etiquetas difieren se sigue renderizando, y la discrepancia se notifica en lugar de detener la compilación.

Componentes de postura única — una convención, no una regla. La promoción lleva el valor que declare el componente, sea cual sea, y el compilador no interpreta ese valor. Un componente cuya etiqueta de identidad contiene un marcador de posición que representa «varía» promueve, por tanto, ese marcador a cada objeto renderizado para él. Cuando un componente tiene realmente más de una postura, la convención del catálogo de la biblioteca estándar es que cada Recipe indique la postura de su propia realización mediante una clave de outputLabels de la que la Recipe es titular, en lugar de mediante la clave de identidad del componente, que esa misma convención encauza por outputComponentLabels: — o que no estampe nada. Las dos claves responden a preguntas distintas y ninguna sustituye a la otra: la clave de identidad dice qué es el componente en todas sus realizaciones, la clave de la Recipe dice qué hace esta realización concreta. Es una convención del catálogo que mantienen sus autores, no una restricción que el compilador imponga.

El bloque locals:

Recipe.spec.locals: es el estado privado de Ops — un mapa de cadenas de plantilla Go con nombre cuya salida renderizada expone un mapa .locals.* a las plantillas posteriores de la Recipe. Es el espacio de trabajo para calcular una sola vez realidades físicas (contenedores de destino, rutas JSON, nombres de host derivados) y reutilizarlas en los payloads de provides:, source:, valuesMapping:, workload:, artifacts:, assertions: y pipeline[].with sin volver a calcularlas. La salida renderizada de cada entrada se almacena sin sus espacios en blanco iniciales y finales.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
locals:
primary_compute: postgresql
listen_port: "5432"
secret_target_db_password: "postgres-auth"
volumes_path: "/spec/template/spec/volumes"
valuesMapping: |
primary:
auth:
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"

locals: nunca se expone a quienes llaman — los componentes posteriores que consumen esta Recipe mediante uses: solo ven provides:. Las plantillas provides:, source:, valuesMapping:, workload:, artifacts:, assertions: y pipeline[].with de la propia Recipe ven todas el mapa .locals.* resuelto. Los valores por clave pueden ser cadenas simples o plantillas Go; el compilador resuelve el bloque entero en el preámbulo de locals, antes del provides: de ese nodo, de modo que cada plantilla posterior observa valores resueltos estables.

Cada entrada se evalúa frente a un contexto autónomo y local al nodo: .context.instance_id, .values, .infra y las entradas de este mismo bloque ya resueltas. Un local no puede leer .provides — ese pilar no está en esta superficie, y una entrada que intenta alcanzarlo detiene la compilación. Tampoco puede leer .context.rendered_name, el nombre que un proveedor como helm da a los recursos que renderiza para el nodo, así que un local que nombra uno de esos recursos lleva solo la parte posterior a ese nombre, como hace secret_target_db_password arriba, y la plantilla que escribe el nombre completo une las dos partes.

El orden de escritura es determinante

Las entradas se resuelven en el orden en que están escritas, y una entrada puede leer una entrada hermana definida encima de ella, recibiendo el valor resuelto de esa entrada hermana:

spec:
locals:
db_identifier: "{{ .context.instance_id }}-postgres" # defined first
secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry above

El encadenamiento va solo hacia abajo. Cuando una entrada lee otra, el orden de las entradas decide si la compilación tiene éxito: mueve db_identifier debajo de secret_target y la compilación se detiene. El compilador nunca ordena ni reordena el bloque para que una referencia se resuelva, así que el orden escrito es el contrato — reordenar un bloque locals: es un cambio de comportamiento, no estético.

Dos detenciones separan los dos errores que puede cometer un autor, porque se corrigen de forma distinta:

  • Una referencia a una entrada que el bloque define más abajo detiene la compilación nombrando el error de orden; la corrección es mover la definición por encima de quien la lee.
  • Una referencia a una clave que el bloque no declara en absoluto detiene la compilación nombrando la clave; la corrección es corregir la ortografía.

La comprobación sigue a un alias del bloque. Una clave a la que se llega mediante el punto que reasigna un cuerpo with .locals, o mediante una variable vinculada a .locals, se comprueba exactamente en los mismos términos que la escritura directa: {{ with .locals }}{{ .nope }}{{ end }} y {{ $l := .locals }}{{ $l.nope }} detienen ambas la compilación nombrando .locals.nope, igual que {{ .locals.nope }}, y lo mismo hacen {{ (.locals).nope }} y {{ ($.locals).nope }}, porque los paréntesis producen el propio bloque y nada más. Una sola escritura escapa a la comprobación: una clave a la que se llega mediante una llamada cuyo resultado el texto de la plantilla no puede nombrar — {{ index .locals "nope" }}, o {{ (default dict .locals).nope }} —, porque lo que produce una llamada así se decide cuando la plantilla se ejecuta y no por lo que está escrito. Una clave ausente leída como campo del resultado de una llamada así no detiene la compilación, y se renderiza como el texto literal <no value> en lugar de como nada. Una clave ausente a la que se llega mediante index detiene la compilación, nombrando la clave, porque index se detiene en todas las superficies de plantilla cuando el mapa que lee no contiene la clave que se le pide — un aviso distinto del de esta comprobación, documentado en errors/fatal-halts.md bajo «A template indexes a map with a key the map does not hold (Una plantilla indexa un mapa con una clave que el mapa no contiene)». Por tanto, index sigue siendo la forma de llegar a una clave cuyo nombre se calcula, como {{ index .locals (printf "secret_target_%s" .values.slot) }}, y un nombre calculado que el bloque no declara se sigue notificando por su clave.

provides: lee .locals y recibe valores resueltos, porque los locals de un nodo se resuelven antes que sus provides. Una plantilla provides: que nombra una clave que el bloque locals no declara detiene la compilación. Esto significa que un valor que necesitan tanto una entrada de provides: como un artefacto se escribe una vez, en locals:, y se lee desde ambos sitios.

Para la contraparte de API pública, consulta El bloque provides: más abajo. La superficie de la FeatureRecipe sigue las mismas reglas — consulta entities/featurerecipe.md «El bloque locals:».

El bloque provides:

Recipe.spec.provides: es la API pública para desarrolladores — un mapa de nombre → cadena de plantilla Go que declara los valores que esta Recipe aporta a los pipes .context.inject y .context.uses de los llamadores aguas abajo. El compilador evalúa las plantillas provides: durante la evaluación de provides (autocontenida, en cualquier orden); las claves inject de los llamadores se resuelven contra estos valores durante la hidratación de inject.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
provides:
# The Service this chart names after its release name, suffixed "-postgresql"
host: "{{ .context.rendered_name }}-postgresql"
port: "5432"
database: "{{ .values.db_name }}"

La plantilla de cada entrada se evalúa sobre la superficie autocontenida de evaluación de provides — .context.instance_id, .context.rendered_name cuando el proveedor del nodo informa uno, .values, .infra, los .locals resueltos del nodo y texto estático. El namespace en el que se coloca el nodo no forma parte de ella, por lo que un host publicado no lleva ninguno: un consumidor en otro namespace lo cualifica por su propio lado. .locals forma parte de ella porque los locals del nodo se resuelven en el preámbulo de la misma etapa, antes de sus provides; una plantilla provides que nombra una clave que el bloque locals no declara detiene la compilación. Separar la evaluación de provides de la hidratación de inject es fundamental: el provides: de una Recipe no puede hacer referencia al estado de ningún llamador porque los llamadores aún no se han resuelto cuando se ejecuta la evaluación de provides — provides: es autocontenido según el invariante arquitectónico. Después, los llamadores leen estos valores mediante .context.uses.<alias>.provides.<provided-name> en sus propias plantillas — los nombres provistos se anidan bajo provides en la arista, junto a los demás campos de la arista. Un llamador que declara una lista de permitidos inject: en la arista llega en cambio a los mismos valores a través de su pipe .context.inject.

Las claves provides: forman parte de la superficie contractual de la Recipe. Renombrar o eliminar una clave es un cambio incompatible para todo llamador que dependa del nombre anterior; la versión de interfaz implements: debería reflejar la evolución del contrato. Para la semántica de resolución en cascada, el contrato del pipe de inject y ejemplos completos que cubren el enrutamiento entre namespaces y entre regiones, consulta architecture/06-data-taxonomy-and-composition.md §3 y templates/expansion-matrix.md.

Leer los valores publicados de una vinculación

Una Recipe lee las Features vinculadas a su componente en .features.<instance-name> y las Features de credenciales en .features.<slot>. Ambas tienen la misma forma de vinculación — .type, .values, .infra, .provides —, de modo que una vinculación se lee de la misma manera sea cual sea el mapa que la contiene; lo que las diferencia es lo que produce la vinculación.

.provides es la salida publicada de la vinculación, resuelta a partir de la FeatureRecipe enlazada a ella. Es la contraparte del bloque provides: de arriba, vista desde el lado consumidor: donde una Recipe publica hacia sus llamadores, una vinculación publica hacia su componente anfitrión.

workload: |
# The identity attachment emits a ServiceAccount and publishes its name;
# the pod binds to that published name rather than restating it.
serviceAccount: "{{ .features.identity.provides.name }}"
containers:
main:
env:
DB_SECRET: "{{ .features.app_credentials.provides.name }}"

Leer el valor publicado en lugar de recalcularlo a partir de las mismas entradas values/infra es la diferencia entre una única declaración de un nombre y dos que pueden divergir. La forma completa campo por campo, incluidas las reglas de disponibilidad, está en templates/template-context-contract.md.

Una vinculación escrita en una de las conexiones del componente — una credencial que el componente presenta a un destino — se lee con la misma forma bajo esa conexión, en .context.uses.<alias>.features.<slot>, y nunca está entre las .features. Una Recipe que llega a varios destinos lee la credencial propia de cada destino bajo el alias de ese destino, y un bucle sobre .features que selecciona vinculaciones por tipo solo encuentra las del propio componente:

artifacts:
routes.yaml: |
{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
{{- end }}{{ end }}
{{- end }}

Consulta Las vinculaciones de una conexión para la forma y para el orden en que una plantilla recorre las conexiones.

El campo pipeline:

Recipe.spec.pipeline: es un array secuencial de pasos de pipeline Wasm que se ejecutan después del renderizado sobre el conjunto de documentos renderizados, cada uno de los cuales devuelve parches RFC 6902 y efectos secundarios. Cada entrada declara un id (identificador del paso: letras, dígitos y guiones bajos), un plugin (la entidad Plugin que ejecuta el paso, delimitada por su tipo de plugin — pipeline-step/<name>, opcionalmente con una versión; una referencia .wasm sin más o una referencia a un artefacto se rechaza), una function (el export del plugin que se invoca), un cuerpo de plantilla Go with: opcional que proporciona el payload del plugin, y una plantilla Go when: opcional que determina si el paso se ejecuta — un resultado falso omite el paso como pass-through, dejando sin cambios el conjunto de documentos. La condición when:, su independencia de optional: y su regla de veracidad se tratan por completo en entities/featurerecipe.md «Pasos condicionales — when:»:

spec:
capability: helm
implements: core/web-server:1.0.0
source: { kind: helm-oci-chart, url: "oci://…", version: "…" }
pipeline:
- id: inject_sidecar
plugin: pipeline-step/envoy-sidecar:1.0.0
function: Inject
with: |
target_container: "{{ .locals.primary_compute }}"
envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"

El compilador ejecuta los pasos pipeline: de una Recipe base en el orden declarado, de la misma manera en que ejecuta el pipeline: de una FeatureRecipe: invoca el plugin Wasm nombrado por cada paso sobre la salida renderizada, aplica las operaciones JSON Patch devueltas a los documentos direccionados y emite los efectos secundarios del paso. El campo pipeline: de la FeatureRecipe comparte la misma forma de esquema y la misma ejecución — consulta entities/featurerecipe.md «Contrato de autoría» y Estado del lenguaje para el estado de ejecución de cada superficie.

La mecánica del campo refleja la semántica de la FeatureRecipe: evaluación secuencial en el orden declarado, operaciones JSON Patch aplicadas a los documentos renderizados, efectos secundarios emitidos junto a ellas y errores informados con una procedencia que apunta al paso causante. Un paso cuya condición when: se renderiza como falsa se omite como pass-through, dejando sin cambios el conjunto de documentos para el paso siguiente.

El bloque assertions:

Recipe.spec.assertions: es un mapa opcional de reglas con nombre que expresan invariantes de implementación de la Recipe — reglas entre campos que se cumplen dado el chart o módulo concreto del que la Recipe toma su fuente. Cada clave es un identificador de regla que aparece en el mensaje de fallo; cada valor es un cuerpo de plantilla Go. A diferencia de las aserciones del Component (que expresan invariantes a nivel de contrato independientemente de qué Recipe se enlace), las aserciones de la Recipe son propiedades de la implementación concreta elegida.

spec:
implements: core/datastore/mariadb:^1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "20.0.0"
assertions:
# Bitnami 20.x: serviceMonitor namespace requirement.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}

La regla anterior es específica del chart Bitnami 20.x; no se aplica si se enlaza una Recipe de MariaDB distinta. Las reglas a nivel de Component del contrato se siguen aplicando en paralelo, evaluadas en una fase anterior del pipeline.

Las aserciones de la Recipe se evalúan después del enlace de la Recipe y antes del renderizado, una vez resueltos los locals y provides de cada nodo. El contexto de la plantilla incluye .provides, .locals y .recipe.source de la Recipe además de los campos de la instancia de entidad (.values, .infra, .uses, .features). Allí, .uses y .features son las formas más restringidas de la superficie de aserciones, no las de una plantilla de Recipe: la entrada de una conexión lleva su destino y su alias, las labels del destino, los values propios de la conexión y las vinculaciones escritas en ella bajo features, pero nada de lo que publica el destino; y la entrada de una vinculación, la del propio componente o la de una conexión, lleva su type, su resolved_version y sus values, pero ni su infra ni su provides — la FeatureRecipe de una vinculación aún no ha resuelto sus provides cuando se ejecuta la aserción. Por tanto, una referencia a .features.<name>.provides detiene la compilación, y una lectura que tiene en cuenta la presencia devuelve su valor de reserva. Para la gramática de autoría completa, el reparto de responsabilidades entre reglas a nivel de contrato y reglas a nivel de implementación, y ejemplos completos, consulta templates/assertions-block.md.

El campo omits: — dejar documentos renderizados fuera de una fuente

La mayoría de las Recipes nunca lo necesitan. Sirve para una fuente que tomas tal como está — casi siempre un chart obtenido de un registro — que renderiza un documento que tu Release no debe entregar: un Secret que el chart genera de nuevo en cada renderizado, por ejemplo, lo que hace que dos compilaciones difieran y, una vez aplicado, sobrescribe el Secret que proporcionó el operador. No editas un chart obtenido, y ninguna regla de exclusión llega a su interior, así que omits: es la forma en que una Recipe deja fuera de la compilación un documento así. Un archivo compose obtenido es el mismo caso: puede incluir un servicio, un volumen o una config que la Release no debe tener, y una superposición valuesMapping: puede modificar uno pero nunca eliminarlo. Lo mismo ocurre con una plantilla CloudFormation obtenida, que puede declarar un recurso que la Release no debe crear: un valuesMapping: puede rellenar los parámetros que declara pero nunca eliminar uno de sus recursos.

spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/gateway
version: "2.4.0"
omits:
# The chart generates this key on every render; the operator supplies it.
- kind: Secret
name: "{{ .context.rendered_name }}-session-key"
# Left out only where the Release asks for it.
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: "{{ .context.rendered_name }}-dashboards"
namespace: monitoring

Qué abarca. Solo lo que source: renderiza. Un workload: y las entradas de artifacts: nunca se filtran: esos los escribes tú en la Recipe, así que un documento que no quieres ahí es uno que simplemente no escribes. La clave requiere source:; un documento que incumple esa regla se rechaza al leerse, indicando la regla.

Una entrada. Cada entrada nombra lo que se deja fuera mediante tres campos, y un cuarto decide si se aplica. Lo que nombran los tres primeros es el vocabulario propio del proveedor para lo que renderiza su fuente, expuesto por proveedor en la tabla siguiente:

  • kind — el tipo de lo que renderiza la fuente: para un chart, el kind de un documento renderizado — Secret, ConfigMap, Deployment; para un archivo compose, service, volume o config; para una plantilla CloudFormation, el Type de un recurso — AWS::S3::Bucket. No tiene relación con el kind: que lleva un source: estructurado, que indica cómo se obtiene la fuente.
  • name — su nombre: el metadata.name de un documento; la clave de una unidad compose bajo services:, volumes: o configs:; el ID lógico de un recurso CloudFormation, su clave bajo Resources.
  • namespace (opcional) — el namespace en el que está el documento, para un proveedor cuya salida tiene namespaces. Sin él, la entrada nombra el kind y el nombre en cualquier namespace; un namespace que se renderiza vacío se trata como ausente.
  • when (opcional) — si la entrada se aplica a esta compilación. Se evalúa primero y se lee con la misma regla que el when: de un paso de pipeline: un resultado falso descarta la entrada, de modo que sus demás campos no se evalúan y no se entrega al proveedor ni se comprueba, mientras que un when: ausente o vacío la conserva.

kind y name son obligatorios, y una entrada que lleve cualquier otro campo se rechaza cuando se lee la Recipe.

Cada valor es una plantilla, evaluada en el mismo contexto que valuesMapping:. Ese contexto lleva .context.rendered_name, el nombre que el proveedor da a los recursos del nodo y el que un chart suele usar para nombrarlos, de modo que una entrada puede nombrar un documento exactamente como lo hará el chart. Una plantilla que no logra renderizarse detiene la compilación igual que una plantilla valuesMapping: que falla.

Toda entrada que se aplica debe dejar algo fuera. El proveedor informa cuántas unidades dejó fuera cada entrada, y una entrada que no dejó ninguna fuera detiene la compilación, nombrando la entrada; consulta An omits entry left out nothing the source rendered (Una entrada omits no dejó fuera nada de lo que renderizó la fuente). La causa habitual es una actualización de la fuente que renombra o elimina el documento, y la detención es lo que impide que un documento renombrado llegue a tu salida sin que lo notes. Para dejar fuera un documento solo a veces, indícalo con when: en lugar de confiar en que el documento esté ausente.

La fuente se sigue renderizando por completo. Solo se filtra su salida: cada plantilla del chart se sigue ejecutando, de modo que una plantilla que falla sigue haciendo fallar la compilación, y un documento dejado fuera se renderiza y luego se descarta. Una vez descartado, no llega a nada de lo que la compilación hace después — ningún archivo emitido, ningún nombre comparado con los nombres de otros componentes, ningún hecho que una Feature lea sobre el renderizado, nada que se entregue a un paso de pipeline.

Una Release llega a la clave a través de infra y parameters. La clave pertenece a la Recipe, así que una Release no puede escribirla. Aun así, puede decidir qué hace una entrada: las plantillas de una entrada leen el infra que completa la Release, y los parameters que proporciona llegan a los .values de la Recipe allí donde el Aggregate los encamine. Así, una Release activa o desactiva una entrada con when:, como hace la segunda entrada de arriba, o decide qué nombra.

Lo que dejas fuera es responsabilidad tuya. Nada en la compilación sabe para qué sirve un documento. Dejar fuera uno del que depende el resto del chart en tiempo de ejecución — el Secret que monta un Deployment, el ServiceAccount con el que se ejecuta un pod — produce una salida que se compila sin errores y luego falla al aplicarse, a menos que otra cosa aplicada junto a ella proporcione ese documento. Para un archivo compose y una plantilla CloudFormation la compilación sí lo comprueba, porque cada uno declara sus propias referencias: lo que queda y aún nombra una unidad dejada fuera — un servicio que nombra un servicio dejado fuera, un recurso o una salida que nombra un recurso dejado fuera — detiene la compilación, como describe la tabla siguiente.

Qué proveedores lo respetan. Dejar fuera un documento es algo que solo el proveedor puede hacer, porque solo el proveedor sabe lo que renderiza su fuente, así que si un proveedor respeta la clave forma parte de la declaración propia del proveedor. Una Recipe que declara omits: y cuyo proveedor no lo respeta se rechaza antes de que se renderice nada, sea cual sea el resultado del renderizado de los when: de sus entradas; consulta The provider does not support omits (El proveedor no admite omits).

Provideromits:
helmRespetado. Una entrada nombra un documento que el chart renderiza — desde una plantilla o desde su directorio crds/ — por el kind y el metadata.name propios del documento y, cuando la entrada nombra uno, por el namespace en el que está el documento. Consulta helm → Modo con fuente.
composeRespetado. Una entrada nombra un service, un volume o un config del archivo compose de origen por su clave bajo services:, volumes: o configs:, comparada una vez que valuesMapping: se ha fusionado en el archivo, y no nombra ningún namespace: una entrada que nombra otro kind, o un namespace, detiene la compilación cuando se renderiza el componente. Un archivo en el que lo que queda aún nombra una unidad dejada fuera — mediante depends_on, links, volumes_from, un modo de red o de namespace service:, extends, un contexto de compilación, o una entrada volumes: o configs: — detiene la compilación, nombrando cada referencia. Consulta compose → Modo con fuente.
cloudformationRespetado. Una entrada nombra un recurso de la plantilla de origen por su Type y su ID lógico, en cada plantilla de una fuente de tipo directorio, y no nombra ningún namespace: una entrada que lleve uno detiene la compilación cuando se renderiza el componente. Una plantilla en la que lo que queda aún nombra un recurso dejado fuera — mediante Ref, Fn::GetAtt, DependsOn o una variable Fn::Sub — detiene la compilación, nombrando cada referencia. Consulta cloudformation → Dejar recursos fuera de una plantilla de origen.
helm-chart, terraformRechazado: el proveedor entrega su fuente para que se renderice al desplegarse, así que en tiempo de compilación no existe ningún documento que dejar fuera. Para un chart o un módulo local, una línea en el .aggregaignore junto a la Recipe deja fuera, en su lugar, uno de sus archivos.

La misma clave se escribe en una FeatureRecipe; consulta entities/featurerecipe.md.

Para un ejemplo completo — el Secret generado de un chart obtenido dejado fuera, la detención por determinismo que el mismo chart encuentra sin la entrada, y la detención en una entrada que no coincide con nada, cada uno de una compilación real — consulta ai-gateway-own-webhook-certificate.