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

FeatureRecipe

El papel conceptual de la entidad FeatureRecipe (Dominio 3 — la implementación de una interfaz de Feature impulsada por plugins Wasm) se describe en architecture/04-entity-taxonomy.md. Esta página cubre la superficie de autoría del catálogo para la FeatureRecipe.

Ubicación en el catálogo

Las FeatureRecipes se organizan con el provider en el primer segmento de la ruta (el mismo patrón que las Recipes):

aggrega-catalog/
└── feature-recipe/
└── {provider}/ # e.g., `helm`, `compose`
└── {feature-recipe-name}/
└── {version}/
└── recipe.yaml

URI OCI: hub.aggrega.ai/featurerecipe/{provider}/{name}:{version} (p. ej., hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).

Contrato de autoría

Las FeatureRecipes se vinculan a una interfaz de Feature mediante implements y declaran un provider concreto. Su superficie de autoría es el conjunto completo de tipos de entrada de la Recipe base más dos bloques específicos de la FeatureRecipe:

  1. Los tres tipos de entrada — source + valuesMapping (con origen), workload (sintetizado) y artifacts: idénticos en forma a los de la Recipe base (consulta Composición de entradas de la Recipe y entities/recipe.md). Una FeatureRecipe que lleva cualquiera de ellos es generadora de recursos — renderiza recursos junto al componente base. El lugar donde acaban esos recursos lleva el componente al que está vinculada la Feature y luego el nombre con el que está vinculada, en la de las dos formas que admita la disposición propia del destino: como directorio {component}--{instance}/ junto al de su anfitrión, bajo el directorio en el que ese destino coloca a sus contribuyentes, en un destino cuyo provider da a cada contribuyente una posición propia; como prefijo de nombre de archivo {component}--{instance}-- junto a los archivos propios del componente, en un destino que solo lee los archivos situados directamente en un directorio. En un provider que compone a sus contribuyentes en un único documento, los recursos se integran en cambio en ese documento — sea cual sea la familia a la que pertenezca la Feature: una CRD ServiceMonitor o ExternalSecret como artifacts: en línea o con $import; un chart o módulo externo mediante source: + valuesMapping:; o su propio cómputo (por ejemplo, un Deployment de agente sidecar) mediante workload:. valuesMapping: comparte los tres modos de autoría de la Recipe base (block scalar en línea, $import: de archivo, $import: de biblioteca hacia una entrada de una MappingLibrary) — consulta entities/recipe.md «El campo valuesMapping — tres modos de autoría». Por convención, una FeatureRecipe modifica el componente base o añade recursos junto a él, pero el esquema no restringe qué tipos de entrada puede usar — el compilador renderiza lo que la FeatureRecipe declare, limitado solo por la capacidad del provider asociado, y permanece sin opiniones propias sobre si un tipo dado es «apropiado para un modificador» (consulta los invariantes fundacionales). La síntesis (workload:) requiere un provider que la admita; de lo contrario, el build se detiene en el renderizado con el diagnóstico de capacidad del provider.
  2. injectMapping (interceptación previa al renderizado): un bloque de plantilla Go nativo que se ejecuta antes de que se renderice la Recipe base. Produce un diccionario JSON o YAML que el compilador fusiona de forma nativa y profunda sobre la tubería de memoria .context.inject del llamador, lo que permite una mutación del lado del llamador, sin Wasm, de variables de entorno y cadenas de conexión.
  3. pipeline: un array secuencial de pasos de plugins WebAssembly (Wasm) para la mutación de Workload posterior al renderizado (p. ej., inyectar un sidecar de Envoy mediante JSONPatch o montar un volumen de secreto). El campo plugin de cada paso nombra una entidad Plugin por su URI, siempre acotada por el tipo de socket propio del plugin (<pluginType>/<name>, opcionalmente con versión, como en parser/yaml o parser/yaml:1.0.0); el build resuelve la entidad en su artefacto .wasm direccionado por contenido, localizado a partir de la identidad del plugin y del registro configurado, y aquí no se acepta un .wasm sin más ni una referencia de artefacto. Consulta la guía para desarrolladores de plugins Wasm para crear y referenciar un plugin, y architecture/04-entity-taxonomy.md §«Dominio 3: base de infraestructura» para el principio del Plugin en dos partes (Fetcher / Injector). El compilador ejecuta cada paso en el orden declarado: despacha la exportación guest del plugin nombrado sobre la salida renderizada y aplica los JSON Patches devueltos y los efectos secundarios emitidos; consulta Estado del lenguaje para conocer el estado de ejecución de cada superficie del pipeline. Un pipeline: se sostiene por sí solo: una FeatureRecipe puede declarar uno y ningún tipo de entrada, en cuyo caso no emite recursos propios y todo su efecto es lo que sus pasos aplican como parche a los documentos que el build ya ha renderizado, o emiten junto a ellos.

Una FeatureRecipe también puede no llevar ninguno de estos bloques: una Feature de cableado puro cuyo efecto es la arista uses que lleva no renderiza nada, y su FeatureRecipe existe solo para satisfacer la resolución — cada instancia de feature se resuelve en una FeatureRecipe, igual que cada componente se resuelve en una Recipe. Entre los bloques anteriores, injectMapping es el único campo sin equivalente en la Recipe base; los tres tipos de entrada y pipeline se comparten con la Recipe base.

Lo que se fija junto a una FeatureRecipe es lo que se fija junto a una Recipe: el digest de cada archivo que importa una entrada artifacts, y de cada source: remota cuyas coordenadas están escritas por completo, en un entity.lock en el directorio propio de la FeatureRecipe, que aggrega pin escribe y que tú confirmas junto a ella. Un pull sobre una FeatureRecipe cuyo lock no registra esos pins se detiene y nombra ese paso, a menos que se pida al pull que lo ejecute. Un build se detiene cuando un archivo importado ya no coincide con su digest, y cuando el digest de un origen no concuerda con el que registra el lockfile de la Release (un origen escrito en un ref: de git se registra en el commit al que se resolvió y no se compara); el propio archivo de la FeatureRecipe nunca se escribe. aggrega pull describe el archivo y cómo responder a cada detención.

Plantillas en el campo source

El source: de una FeatureRecipe es una superficie de plantillas en los mismos términos que el de una Recipe: la plantilla se evalúa al resolver la fuente, y lo que produjo es lo que la compilación resuelve después. Ambas formas aceptan plantillas de Go — la forma de cadena universal y la forma de objeto estructurado, cuyos subcampos con valor de cadena se evalúan como plantilla mientras que los subcampos que no son cadenas pasan sin cambios. El inventario de formas, el tratamiento de los esquemas y la lectura del anclaje son los que se exponen en entities/recipe.md «Plantillas en el campo source», «Inventario de esquemas del campo source» y «Cómo se ancla una ruta source:»; esta sección indica solo lo que cambia para una vinculación.

locals:
chart_dir: ./charts/exporter
source: "{{ .locals.chart_dir }}"

Respecto a qué se resuelve un resultado relativo. El directorio que contiene el documento FeatureRecipe que lo declaró — el propio archivo de la vinculación, nunca el del componente — y el resultado debe permanecer dentro de ese directorio, exactamente como para una Recipe: un resultado que sale de él, o que es una ruta absoluta, nombra un archivo que no viajaría con la FeatureRecipe y detiene la compilación. Uno que lleva un esquema de transporte se descarga en lugar de unirse a un directorio. Una FeatureRecipe resuelta desde un registro se lee de los archivos que contiene su archivo publicado, dispuestos en la caché de contenido, de modo que un resultado relativo se resuelve dentro de lo publicado exactamente como se resuelve junto a la FeatureRecipe en un directorio del catálogo, sujeto al mismo límite.

Qué puede leer la plantilla. El conjunto de referencias es aquel con el que se comprueban las entradas locals: de la propia FeatureRecipe, que difiere del de una Recipe en dos aspectos que se derivan de que se resuelve una vinculación y no un componente:

  • .attachment_name está disponible y nombra la instancia con la que se vincula la Feature. La plantilla de fuente de una Recipe lo rechaza, porque la fuente de una Recipe se resuelve para un nodo y no hay ninguna vinculación en juego.
  • .context.instance_id nombra el componente anfitrión para el que se está resolviendo la vinculación, no la vinculación, y .context.rendered_name lleva el nombre que el propio proveedor del anfitrión informa para el anfitrión — presente solo donde ese proveedor informa uno, y deteniendo la compilación donde no lo hace. Consulta Nombrar un recurso renderizado.

.locals lleva el conjunto que leen las demás plantillas de esta FeatureRecipe: su propio bloque resuelto, con el de la Recipe anfitriona debajo, de modo que una clave que declara la vinculación prevalece sobre una clave del anfitrión con el mismo nombre. Una referencia a una clave que ese conjunto no contiene detiene la compilación y la nombra, en lugar de hacer desaparecer la clave al renderizar. .provides, .context.inject y .context.uses se rechazan por las mismas razones de autocontención por las que los rechaza la superficie de fuente de una Recipe.

Una FeatureRecipe con ámbito de frontera lee la frontera en su lugar. Una Feature cuya FeatureRecipe declara executionScope: boundary se renderiza una vez para la frontera en lugar de una vez por componente, por lo que su plantilla de fuente no tiene ningún componente anfitrión que leer. Lee .boundary.* — los mismos pilares que leen sus locals: y provides: — y los pilares por componente (.context, .workload, .attachment_name, .inject) no están disponibles para ella.

Un resultado vacío. Una plantilla que no produce nada deja la vinculación sin fuente, que es el modo sin fuente — la misma lectura que adopta la fuente de una Recipe, y distinta de escribir tú mismo source: "".

Qué lee .source después. El source se evalúa antes del valuesMapping:, como el de una Recipe antes del suyo propio, y lo que produjo es .source en cada plantilla que se ejecuta después: el valuesMapping:, el omits:, los cuerpos de workload: y artifacts:, y los pasos de pipeline:. Así, un valuesMapping: que lee .source lee el source propio de esta FeatureRecipe, nunca el source del componente al que está asociada, y no lee nada cuando esta FeatureRecipe no declara ningún source o su plantilla no produce nada. Una FeatureRecipe de ámbito boundary lee su propio source de la misma manera. El injectMapping: se ejecuta antes de que se evalúe el source de la asociación, así que allí .source es el del componente anfitrión.

Exclusividad de injectMapping

El campo injectMapping es exclusivo de las FeatureRecipes — está ausente a propósito del esquema base de Recipe. Esta exclusividad aísla la interceptació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. Consulta más abajo la sección sobre la interceptación del inject mapping para ver cómo funciona el mecanismo, y architecture/10-compilation-pipeline.md sobre el inject mapping para la semántica completa de la interceptación previa al renderizado.

Interceptación del inject mapping: cómo funciona injectMapping

Cuando un llamador necesita que la cadena de conexión a su destino tenga una forma distinta del .provides.host sin modificar del destino — añadiendo un namespace para el DNS de Kubernetes entre fronteras, anteponiendo un código de región para una pasarela multirregión o añadiendo un sufijo de modo SSL a un DSN —, injectMapping gestiona la modificación en el llamador, antes de que el valuesMapping de la Recipe base llegue a ver el canal de inyección.

El campo injectMapping es un text/template de Go que el renderizador evalúa en el inject mapping, antes de que se ejecute el renderizado de la Recipe base. La plantilla produce un diccionario JSON o YAML con claves de mecanismo opcionales (env, file, arg, o un mecanismo personalizado que la Recipe del componente lee en .context.inject.<name>) — o un mapa plano que por defecto es env — y el renderizador fusiona en profundidad esta superposición sobre el canal .context.inject del nodo llamador. El enrutamiento del lado del llamador mediante injectMapping se ejecuta en el inject mapping sin invocar un sandbox Wasm para la manipulación sencilla de cadenas; los plugins Wasm quedan reservados para cambios estructurales del AST mediante el array pipeline.

Escribe cada valor mediante toJson. El renderizador lee la salida de la plantilla como YAML, por lo que un valor interpolado tal cual entre comillas rompe esa salida o se vuelve a leer modificado en cuanto contiene una comilla doble o una barra invertida — una contraseña es el caso habitual. toJson escribe el valor como una cadena JSON, que YAML vuelve a leer exactamente, de modo que el valor se entrega con cada carácter que contiene:

injectMapping: |
env:
{{ .values.key }}: {{ .values.origin | toJson }}

Un valor compuesto por varias piezas se compone primero y se escribe una sola vez mediante toJson, como hacen los ejemplos siguientes.

Una salida que no se puede leer detiene la compilación. Cuando la salida de la plantilla no se lee como ninguna de las dos formas — la causa habitual es un escalar entre comillas roto por el valor que contiene —, ninguna de sus claves podría entregarse, por lo que la compilación se detiene nombrando la vinculación y la FeatureRecipe en lugar de renderizar el componente como si no se hubiera entregado nada; consulta fatal-halts.md «An attached Feature’s injectMapping output cannot be read (La salida de injectMapping de una Feature vinculada no se puede leer)». El motivo que da se omite cuando depende de un valor declarado sensible. Una salida vacía, o que se analiza como un diccionario que no entrega nada, no entrega nada y no es un fallo.

Una clave de primer nivel es un mecanismo, y all no lo es. Cada clave de primer nivel de una salida en forma de diccionario nombra el mecanismo a través del cual se entregan sus entradas: env, file y arg, o cualquier otro nombre, que se entrega como un mecanismo propio con ese nombre. .context.inject.all se construye a partir de esos mecanismos después de la fusión y nunca se fusiona desde una salida, por lo que las entradas escritas bajo all: no llegarían a nada; en su lugar, la compilación se detiene, nombrando la vinculación, la clave y la FeatureRecipe, e indicando qué claves puede contener una salida — consulta fatal-halts.md «An attached Feature’s injectMapping output writes deliveries under a key nothing delivers (La salida de injectMapping de una Feature vinculada escribe entregas bajo una clave que nada entrega)». Escribe esas entradas bajo el mecanismo desde el que el componente las lee.

La modificación es estrictamente local al llamador. La FeatureRecipe modifica solo el canal de inyección del nodo al que está vinculada, nunca la salida .provides del destino. El .provides.host de un destino lo consumen potencialmente muchos llamadores en todo el clúster; injectMapping del lado del llamador solo se fusiona en el canal del llamador concreto, de modo que las modificaciones de enrutamiento quedan circunscritas a la arista que las solicitó.

Qué puede reescribir un mapeo. Cada bloque inject: ya ha entregado para cuando se renderizan los mapeos, por lo que la salida de un mapeo siempre se fusiona sobre claves que otra cosa ya escribió — y quién escribió una clave decide lo que ocurre. Una clave que entregó el propio bloque inject: del llamador o el bloque inject: de una de sus conexiones puede reescribirla el mapeo: eso es interceptación, y el valor del mapeo sustituye esa única entrada. Una clave que la propia vinculación del mapeo entregó mediante su bloque inject: también puede reescribirla. Una clave que una Feature vinculada distinta ya entregó — mediante su propio bloque inject: o mediante el injectMapping de su propia FeatureRecipe — no: la compilación se detiene nombrando ambas vinculaciones, en lugar de dejar que el mapeo que se ejecutó en último lugar decida qué valor lee el llamador. Así, dos Features de enrutamiento pueden calificar cada una una clave propia, pero dos Features no pueden entregar ambas una misma clave — incluidas dos Features de enrutamiento que reescriben la clave de la misma conexión, ya que la primera es interceptación y la segunda se encuentra con la entrega de la primera; consulta fatal-halts.md «Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping» (Dos Features vinculadas entregan una misma clave, la segunda mediante el injectMapping de su FeatureRecipe).

Inferencia del destino sin acoplamiento

Como el compilador incrusta las anotaciones en cascada de cada destino en el canal .context.uses del llamador, la plantilla injectMapping puede extraer coordenadas de enrutamiento sin que Ops codifique de forma fija la identidad del destino en el infra de la Feature:

  1. La plantilla busca en .context.uses la arista topológica exacta que inyectó la variable solicitada por el desarrollador.
  2. Extrae las release_annotations en cascada del destino (p. ej., aggrega.ai/namespace).
  3. Formatea el nombre de dominio completo (FQDN) o la cadena de conexión.
  4. Emite el diccionario de sobrescritura.

El compilador permanece agnóstico respecto a la semántica de red — namespaces de Kubernetes, regiones de la nube, topologías bridge-proxy — y simplemente ejecuta la fusión en profundidad con lo que haya producido la plantilla. Cuando a continuación se ejecuta el valuesMapping de la Recipe base, consume las cadenas interceptadas y reescritas de .context.inject.env como si fueran las originales del desarrollador.

Ejemplo completo: resolvedor DNS de K8s

El catálogo estándar lo distribuye como core/k8s-dns-resolver con una FeatureRecipe de helm. Como los nombres de las variables de entorno deben ser únicos dentro de un contenedor, la target_var (p. ej., API_HOST) actúa como identificador globalmente único de un contrato de inyección concreto dentro del llamador. Recorriendo las aristas explícitas de .context.uses y comprobando qué arista reclamó la target_var, la plantilla localiza el nodo de destino correcto y lee su namespace. El único parámetro es la variable que se va a reescribir; el destino y su namespace se descubren, nunca se codifican de forma fija.

El esquema de la Feature de enrutamiento (core/k8s-dns-resolver):

infra: {
target_var: string # Ops dictates WHICH injected var to rewrite
}

La implementación de la FeatureRecipe:

injectMapping: |
# 1. Grab the atomic base host directly from the flattened pipe, or an
# empty value when nothing was injected under target_var
{{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable
{{ $target_edge := dict }}
{{ range $alias, $edge := .context.uses }}
{{ if hasKey $edge.inject.env $.infra.target_var }}
{{ $target_edge = $edge }}
{{ end }}
{{ end }}
# 3. Read the target's namespace from its cascaded release annotation,
# coalescing an absent namespace to "default"
{{ $ns := "default" }}
{{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }}
{{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }}
{{ if $raw }}{{ $ns = $raw }}{{ end }}
{{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection
# and a base host were actually found, so a target_var that matches no
# connection injects nothing instead of a spurious variable. An unset
# namespace resolves to "default", where the helm provider deploys an
# unannotated workload, so the qualified host always matches the service's
# actual location and is never malformed.
{{ if and $target_edge $base_host }}
{{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge
env:
{{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }}
{{ end }}

Casos de uso más allá del enrutamiento

injectMapping se usa con mayor frecuencia para la resolución de direcciones entre fronteras (como el resolvedor DNS de K8s anterior), pero esa modificación del lado del llamador se aplica a cualquier escenario que requiera interceptar y formatear la intención del desarrollador antes del renderizado de la infraestructura. Otros dos patrones ilustran el alcance.

Formateo dinámico de seguridad (el anexador SSL). Si una empresa exige que todas las conexiones a bases de datos externas usen una verificación TLS estricta, una Feature puede interceptar el DB_URL solicitado por el desarrollador y añadir el modo SSL necesario, de modo que la aplicación arranque con los parámetros de seguridad correctos.

# Inside force-ssl-feature
injectMapping: |
{{ $base_url := index .context.inject.env .infra.target_var }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}

Prefijado de pasarelas multirregión. Si un componente de API genérico se despliega globalmente, una Feature de enrutamiento regional puede consultar de forma autónoma las anotaciones de su propia frontera de entorno para anteponer un prefijo a las cadenas de conexión inyectadas para sus llamadores.

# Inside regional-router
injectMapping: |
{{ $base_host := index .context.inject.env .infra.target_var }}
{{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}

El límite de injectMapping. El mecanismo se limita a modificar el canal de memoria .context.inject (el contrato de entrega). No puede añadir contenedores nuevos, montar volúmenes ni alterar la salida del valuesMapping de la Recipe base. Cualquier modificación que requiera cambios estructurales en el AST renderizado (como arrays JSON o YAML) corresponde al array pipeline de la FeatureRecipe, ejecutado mediante plugins WebAssembly.

El límite de los objetivos de parche de pipeline. Un paso de pipeline aplica parches solo a la salida que el proveedor renderiza en un árbol estructurado. La salida con forma YAML y JSON es estructurada — incluidos los módulos de Terraform .tf.json escritos en JSON —, de modo que el JSONPatch de un paso edita in situ los valores direccionados y deja intacto cualquier otro byte (comentarios, orden, formato). La salida que el proveedor emite como cuerpo opaco, como la configuración de Terraform en HCL nativo, no es un objetivo de parche: un parche sobre un cuerpo opaco detiene la compilación con un diagnóstico en lugar de modificar un texto que no puede direccionar estructuralmente. Escribir un paso de pipeline sobre una salida opaca es, por tanto, un error de diseño que aflora como una detención explícita, no como un no-op silencioso.

Las entradas de un módulo de Terraform incluido como vendor no son un objetivo de parche, y conviene dejar constancia de esa ausencia. Son los argumentos del bloque module de ese componente, que el proveedor terraform escribe en la configuración raíz de la frontera: HCL nativo, por tanto opaco según la regla anterior, y un artefacto de toda la frontera y no del nodo cuya salida parchea el paso. Así que no existe ninguna posición desde la que un paso de pipeline pueda direccionarlas, ni nada que pueda hacer para cambiar lo que recibe un módulo de Terraform obtenido mediante source. Esos valores se moldean donde se escriben — en el valuesMapping: de la Recipe base.

Pasos condicionales — when:

Un paso de pipeline puede llevar un campo when: opcional: una plantilla de Go inline que el compilador evalúa al recorrer el pipeline, con el mismo contexto de plantilla y el mismo evaluador que usa el cuerpo with: del paso. El resultado renderizado decide si el paso se ejecuta.

  • Un resultado falsy omite el paso como un paso directo: el conjunto de documentos fluye sin cambios al siguiente paso, y el paso omitido no aporta nada — ningún parche, ningún efecto secundario, ningún registro de haberse ejecutado.
  • Un when: vacío o ausente siempre ejecuta el paso.

when: y optional: son independientes. when: decide si un paso se ejecuta o no; optional: suaviza el fallo de un paso en ejecución. Un paso puede declarar ambos — when: controla la entrada y, si el paso se ejecuta, optional: rige cómo se gestiona un fallo dentro de él. Una plantilla when: que no se puede renderizar es un defecto de autoría y detiene la compilación independientemente de optional:.

El texto when: renderizado se juzga según la regla compartida de plantillas booleanas: las cadenas true, True y TRUE, cualquier número distinto de cero y cualquier otra cadena no vacía son verdaderos; las cadenas false, False y FALSE, la cadena vacía y un número cero son falsos.

Patrón de FeatureRecipe de credenciales

Cuando una FeatureRecipe implementa una Feature de credenciales (una etiquetada con feature.aggrega.ai/kind: secret), puede seguir el principio del Plugin en dos partes: una pipeline que encadena un plugin Fetcher (que genera la CRD específica del vault) y un plugin Injector (que monta el secreto en el contenedor de destino), la forma que describe examples/04-secrets. Las FeatureRecipes de credenciales de la biblioteca estándar no declaran ninguna pipeline: y renderizan ellas mismas el recurso del secreto; consulta examples/05-credential-features.

Una FeatureRecipe de credenciales se renderiza a través de la misma pasada de generación de recursos que la de cualquier otra vinculación, y su pipeline: se ejecuta en los mismos términos: el compilador recorre cada vinculación que tiene trabajo en esa pasada como una única secuencia ordenada y ejecuta el pipeline declarado de cada una, con la misma semántica de conjuntos de documentos /own y /host. Una vinculación se une a esa secuencia por una de dos razones — su FeatureRecipe declara un tipo de entrada, por lo que genera recursos propios, o declara un pipeline:, por lo que reescribe documentos ya emitidos. Por tanto, una vinculación de credenciales puede intervenir en los documentos renderizados del componente anfitrión — montando un volumen de secreto, añadiendo una referencia env — exactamente como una vinculación operativa, y la única diferencia entre ambas es dónde acaban sus propios archivos generados.

En un componente, una declaración de sensibilidad en la Feature sigue el valuesMapping: de la FeatureRecipe exactamente como la de un Component sigue el de su Recipe. Donde una FeatureRecipe renderiza desde un source: sin valuesMapping:, los valores que recibe su destino tienen como claves las rutas de hoja que declara la Feature, de modo que una hoja declarada sensitive: true marca su clave renderizada. Donde la FeatureRecipe declara un valuesMapping:, las claves son invención propia de esa plantilla, ninguna declaración las nombra, y la compilación imprime un aviso por cada hoja de ese tipo, nombrando la vinculación, la hoja y la FeatureRecipe. Una Feature vinculada a una frontera no genera ninguno: su .values siempre está vacío, de modo que ninguna hoja declarada tiene un valor que marcar — consulta A declared-sensitive value reaches the target through a values mapping (Un valor declarado sensible llega al destino a través de un values mapping).

El bloque provides: — publicación hacia el consumidor

El bloque provides: de una FeatureRecipe es su salida publicada: un mapa con valores de cadena de plantillas de Go evaluadas en el ámbito propio de la vinculación (.values, .infra, los .locals completamente resueltos de la FeatureRecipe, y .context.instance_id y .context.rendered_name del nodo anfitrión). Los locals se resuelven primero, de modo que una entrada de provides: los lee y recibe valores resueltos; nombrar una clave que el bloque locals: no declara detiene la compilación. Es la forma en que una vinculación le dice a su consumidor lo que produjo — el nombre de un recurso emitido, una clave de datos generada, una identidad en la nube — sin que el consumidor vuelva a derivar esa identidad de las mismas entradas.

El consumidor lo lee en .features.<instance-name>.provides.<key> (o .features.<slot>.provides.<key> para una vinculación de credenciales), en paralelo a .context.uses.<alias>.provides para una arista uses. Donde la vinculación está escrita en una de las conexiones del consumidor, el consumidor lee el mismo mapa bajo esa conexión, en .context.uses.<alias>.features.<slot>.provides.<key>, y la vinculación no está entre sus .features (consulta Las vinculaciones de una conexión). El propio bloque inject: de la vinculación resuelve sus referencias from: contra el mismo mapa, de modo que un autor puede elegir cualquiera de los dos canales: provides para una lectura desde plantilla, inject para la entrega en una variable de entorno, un archivo o un argumento.

# FeatureRecipe: emits a ServiceAccount and publishes its name.
provides:
name: "{{ .infra.service_account_name }}"
# Consuming Recipe: binds the pod to what the attachment published.
workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

Cuando la Feature que esta FeatureRecipe implements declara un contrato schema.provides, el contrato se aplica a la FeatureRecipe: cada clave que declara la Feature debe aparecer en el provides: de la FeatureRecipe, o la compilación se detiene nombrando la clave que falta. Se permiten claves publicadas adicionales — el contrato es un mínimo, no un máximo. Los valores nunca se inspeccionan; son punteros deterministas opacos que resuelve el entorno de ejecución.

La resolución ocurre una vez por vinculación, antes de que se renderice el consumidor, y el mismo mapa resuelto alimenta la lectura del consumidor, la comprobación del contrato y la propia generación de recursos de la vinculación — de modo que lo que lee el consumidor y lo que emite la vinculación no pueden discrepar.

Provider & implements

spec.capability es obligatorio y nombra el proveedor cuyo plugin de renderizado Wasm renderiza la salida de la FeatureRecipe (helm, helm-chart, compose, etc.), en los mismos términos que el spec.capability de una Recipe (consulta entities/recipe.md): un pin de versión selecciona qué versión de ese plugin la renderiza, y no forma parte del nombre de la FeatureRecipe — un Manifest asigna una FeatureRecipe que declara capability: "compose:1.2.3" como compose/<name>:<version>, y un valor de asignación que escribe el pin en el nombre se rechaza como referencia de receta mal formada (E0095) antes de buscar nada. El campo implements vincula la FeatureRecipe a su interfaz de Feature y admite coincidencia exacta, por rango compatible con la versión mayor o sin versión — consulta vocabulary/inheritance-and-interface para la semántica de coincidencia de versiones de implements.

Ámbito de ejecución — spec.executionScope

El enum opcional spec.executionScope selecciona el modelo de despacho de la generación de recursos. Se aceptan dos valores; cuando se omite el campo, el valor predeterminado es component.

  • component (predeterminado). La generación de recursos de la FeatureRecipe se ejecuta una vez por cada instancia de componente vinculada. Cada invocación recibe un contexto de plantilla por componente con raíz en .context.*: .context.instance_id, .context.inject, .context.uses, .context.annotations, etc. Sus valuesMapping:, workload: y artifacts: también leen .context.used_by, los componentes cuyas entradas uses apuntan al host — cada uno con su identidad, su socket, lo que publica, y el namespace y la frontera en los que está ubicado —, que ninguna plantilla que renderiza el propio host puede ver.
  • boundary. La generación de recursos se ejecuta una vez por cada frontera vinculada, independientemente de cuántos componentes del subárbol de la frontera consuman la funcionalidad. Cada invocación recibe un contexto de plantilla con ámbito de frontera con raíz en .boundary.* en lugar de .context.*.

La intercepción injectMapping descrita arriba es siempre por consumidor, independientemente de executionScope. Cada componente que usa la funcionalidad sigue recibiendo su propia reescritura del lado del llamador de .context.inject. Solo el paso de generación de recursos (source/valuesMapping y el array pipeline) se deduplica con ámbito de frontera.

Por tanto, las plantillas de una FeatureRecipe con ámbito de frontera se ejecutan en dos ámbitos. Su injectMapping se ejecuta una vez por cada componente al que llega la vinculación, contra el contexto de ese componente — el mismo que lee el injectMapping de una FeatureRecipe con ámbito de componente: .context.*, .attachment_name, .features y los .values, .infra y .locals propios de la vinculación. Su .infra es el bloque infra: de la vinculación a la frontera, y su .locals es el bloque evaluado una sola vez para la frontera. Cualquier otra plantilla que escribe — entre ellas sus locals:, provides:, source:, valuesMapping: y artifacts: y los with: y when: de los pasos de su pipeline — se ejecuta una vez para la frontera, contra el contexto con ámbito de frontera descrito abajo. Cada plantilla se comprueba contra el ámbito en el que se ejecuta: un valuesMapping: que lee .context.instance_id detiene la build, y un injectMapping que lo lee renderiza la identidad de ese componente. .boundary no está definido en el contexto de ningún componente, por lo que un injectMapping que lo lee detiene la build nombrando la referencia, sea cual sea el executionScope de la FeatureRecipe.

Contexto de plantilla con ámbito de frontera

Cuando executionScope: boundary, las plantillas de la FeatureRecipe distintas de su injectMapping se evalúan contra una vista .boundary.* de la frontera a la que está vinculada la funcionalidad. La vista expone:

  • .boundary.path — la ruta de la frontera de la Release a la que está vinculada la funcionalidad: los nombres de las fronteras desde la más externa hacia dentro, unidos con / (bridge, bridge/frontend). Nombra la frontera, no el directorio en el que se escribe su salida, que fija directory: (sustituye a .context.instance_id).
  • .boundary.assembly_path — el directorio, relativo al directorio de salida de la build, en el que se ensambla la salida propia de la vinculación: los directory: y subDirectory: evaluados de la frontera, es decir, el directorio al que la build dirige esa salida (bridge/compose). Es igual al source_assembly_path o al target_assembly_path de un extremo de conexión exactamente cuando ese extremo se renderiza en el mismo archivo ensamblado, de modo que una FeatureRecipe los compara para distinguir una conexión dentro de su propio archivo de una en otro archivo.
  • .boundary.boundary_name — el nombre de la frontera tal como está escrito en la Release.
  • .boundary.components — un mapa indexado por ID de instancia que contiene cada componente del subárbol de la frontera (instance_id, component, resolved_version, boundary_path).
  • .boundary.internal_uses_edges — aristas uses: cuyos dos extremos están dentro del subárbol de esta frontera (el patrón compose-bridge las enumera, conservando las aristas cuyos dos extremos se ensamblan en su propio archivo compose y se ubican en redes distintas de él, para derivar su configuración de proxy por arista). Cada arista lleva los provides resueltos de sus extremos, las variables de entorno inyectadas y la ubicación de cada extremo: source_namespace y target_namespace, la anotación aggrega.ai/namespace que se aplica a ese extremo — el ajuste de su propia entrada de la Release cuando la tiene, y si no, el de su frontera; source_boundary_path y target_boundary_path, la ruta de la frontera de la Release que lo contiene; y source_assembly_path y target_assembly_path, el directorio bajo el directorio de salida de la build en el que su provider lo ensambla, compuesto a partir de los directory: y subDirectory: evaluados de su frontera (bridge/compose). Dos extremos con la misma ruta de ensamblado se renderizan en un único archivo ensamblado, y el provider de compose lee la ruta de ensamblado como la red del extremo cuando no se aplica ningún namespace.
  • .boundary.outgoing_cross_boundary_uses_edges — aristas con el origen dentro del subárbol y el destino fuera.
  • .boundary.incoming_cross_boundary_uses_edges — aristas con el destino dentro del subárbol y el origen fuera (usadas por agregadores de tipo ingress).
  • .boundary.cross_boundary_uses_edges — la unión de las aristas entre fronteras entrantes y salientes, cuando la FeatureRecipe quiere la vista completa entre fronteras.
  • .boundary.labels — la unión de las labels del subárbol, conservando el orden de escritura.
  • .boundary.annotations — las anotaciones propias de la frontera más la cascada.
  • .boundary.feature_attachments — cada funcionalidad vinculada a esta frontera (para que una FR con ámbito de frontera pueda inspeccionar sus hermanas si es necesario).

El pilar .infra en una FR con ámbito de frontera se resuelve en el bloque infra: de la funcionalidad vinculada a la frontera (el dimensionamiento físico escrito del lado de la Release para esa vinculación a la frontera). .values está siempre vacío para las FR con ámbito de frontera: la regla de separación de pilares del esquema de la Release prohíbe values: en las vinculaciones de Feature a nivel de Release, por lo que una funcionalidad vinculada a una frontera no lleva valores que proyectar. Las FR con ámbito de frontera que necesiten datos con forma de parámetros deberían consumirlos mediante .infra (la superficie de autoría del operador para la configuración de funcionalidades de frontera) o mediante .boundary.annotations (valores de cadena resolubles en cascada, escritos en la frontera o en cualquier ancestro); .parameters no forma parte de la vista, y una plantilla que lo lee se detiene nombrando las raíces que define la vista. .locals sigue siendo el propio bloque locals de la FR. .steps y .metadata permanecen sin cambios.

Lista de campos permitidos en las plantillas con ámbito de frontera

Las FR con ámbito de frontera solo pueden referenciar campos disponibles en la vista con ámbito de frontera, en todas las plantillas salvo el injectMapping. Escribir una plantilla de ese tipo que referencie un campo exclusivo del ámbito de componente (p. ej., .context.instance_id, .context.inject, .context.uses) cuando executionScope: boundary hace que la FeatureRecipe falle la validación en el momento del análisis, con un error que nombra la FR, el campo infractor y los campos que define la vista con ámbito de frontera. La regla simétrica se aplica en la dirección contraria: una FR con ámbito de componente que referencia campos .boundary.* falla en el mismo validador. El injectMapping se comprueba contra el contexto del componente en el que se ejecuta, en cualquiera de los dos ámbitos, por lo que puede leer .context.*, y una referencia a .boundary en él se detiene nombrando la referencia y las raíces que define ese contexto.

El validador ejecuta el mismo recorrido del AST de las plantillas que usa la lista de variables permitidas de las plantillas de ruta, con un conjunto de referencias distinto para cada ámbito.

Deduplicación y salida de la generación de recursos

Para executionScope: boundary, el compilador deduplica la generación de recursos por la tupla (boundary_path, FR-instance). Dos componentes del mismo subárbol de frontera que consumen ambos la misma funcionalidad vinculada a la frontera desencadenan una sola invocación de la FR, no dos. Las vinculaciones de la misma funcionalidad en fronteras distintas se ejecutan de forma independiente para cada frontera.

Una FR con ámbito de frontera emite un conjunto de archivos no intermedios por cada tupla (boundary_path, FR-instance), y su ubicación se deriva de cómo el provider combina la salida de su frontera. Aquí la coordenada es solo el nombre de la instancia, mientras que una vinculación con ámbito de componente lleva también su componente: una funcionalidad con ámbito de frontera está vinculada a la frontera y no a un componente, de modo que el directorio de la frontera que la contiene ya dice todo lo que diría un segmento de componente, y no hay ningún componente que nombrar.

Un provider que escribe cada documento directamente en el directorio de la frontera declara que su destino solo lee los archivos situados directamente en un directorio. Por tanto, no hay ningún directorio contenedor en el que situar una vinculación, y el nombre de la instancia se convierte en cambio en un prefijo del nombre de archivo: <boundary_directory>/<fr-provider>/<feature-instance>--<file>, junto a los archivos propios de la frontera. El nombre de la instancia se codifica, porque un nombre de archivo no tiene un separador al que recurrir, y se une al nombre propio del archivo en un límite de dos caracteres que ninguna coordenada codificada puede contener — así que dos vinculaciones que emiten el mismo nombre de archivo siguen llegando a dos archivos.

Un provider que compone la salida de su frontera en una estructura contenedora — un chart que contiene un chart por contribuidor, una configuración raíz que contiene un módulo por contribuidor — sitúa cada contribuidor en un subdirectorio propio, y una vinculación a una frontera es un contribuidor como cualquier otro. Su salida queda entonces en <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/, donde <contributors-directory> es como ese destino llame al lugar donde residen sus unidades hijas. El subdirectorio lleva el nombre de instancia de la vinculación, que es el nombre con el que la escribiste en el bloque features: de la frontera, de modo que el directorio que produce una build es uno que puedes encontrar en lo que escribiste.

La salida intermedia fluye hacia el ensamblador por (ruta, provider) de la frontera, en la ruta evaluada de la FR y bajo la spec.capability propia de la FR — este es el mecanismo que usa la Feature core/compose-bridge para fusionar un servicio de puente junto a los contribuidores de compose por componente en la misma ruta de ensamblado. Esa salida solo se escribe como parte del archivo ensamblado allí a partir de los componentes de la frontera, de modo que cuando ninguno de ellos acaba en esa ruta — porque su subDirectory: envía cada componente a otro lugar, por ejemplo —, la build se detiene nombrando la frontera, la Feature, la ruta a la que se dirigió su salida y el provider, en lugar de escribir la salida en ninguna parte (consulta «A boundary-level Feature’s output reaches no assembled file (La salida de una Feature a nivel de frontera no llega a ningún archivo ensamblado)» en fatal-halts.md).

Resolución de provides: consciente de la cascada

Las FR con ámbito de frontera producen un conjunto de provides: por cada tupla (boundary_path, FR-instance), evaluado una sola vez. La plantilla provides: de la FR se evalúa con el contexto de plantilla con ámbito de frontera (por lo que puede referenciar .boundary.components, .boundary.path, .infra, pero no campos por consumidor ni .values). Los valores de provides son constantes respecto a los consumidores — todos los consumidores del subárbol de la frontera ven los mismos valores proporcionados.

La resolución del lado del consumidor de los provides de una FR con ámbito de frontera lee esa única evaluación en todas partes. Cada componente al que llega la vinculación la lee en .features.<instance-name>.provides.<key> — en las plantillas de su propia Recipe y en el injectMapping propio de la FeatureRecipe, que se ejecuta en el contexto de ese componente. Un Component consumidor que lee a través de una arista uses que lleva la vinculación, en .context.uses.<feature-alias>.provides.<provided-name>, obtiene los mismos valores: el compilador lo resuelve en el provides: de la FeatureRecipe con ámbito de frontera para la frontera en la que se encuentra el consumidor, recorriendo desde la arista uses del consumidor — que lleva la identidad de la instancia de funcionalidad por vinculación — hasta el provides: de la FR con ámbito de frontera. Una pasada previa evalúa esos provides antes del ensamblado de los consumidores, de modo que los valores están presentes cuando se construye el canal del consumidor.

Un efecto por consumidor es una tabla en provides: leída por injectMapping. Una FeatureRecipe con ámbito de frontera que tiene que cambiar algo para cada consumidor calcula una sola vez, en su provides:, una tabla indexada por consumidor a partir de las conexiones de la frontera, y su injectMapping lee las filas del componente actual — (index .features .attachment_name).provides, indexadas por .context.instance_id — y las entrega a través del propio canal del consumidor, según la regla que sigue todo mapping (consulta Qué puede reescribir un mapping). El compilador canaliza la tabla que escribió la FeatureRecipe y no lee nada de ella.

El patrón compose-bridge

La FeatureRecipe compose-bridge es el patrón canónico de FR con alcance boundary, y es contenido de catálogo escrito con los mecanismos anteriores: ni el compilador ni el provider compose contienen lógica alguna del bridge, por lo que un catálogo puede realizar la Feature core/compose-bridge de otra manera. Una feature core/compose-bridge se adjunta a un boundary padre que contiene dos sub-boundaries (p. ej., services-net y data-net) con un directory: compartido, cada uno con su propia anotación aggrega.ai/namespace (aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net) para que cada uno quede en una red propia; sin las anotaciones, ambos comparten la única red nombrada según la ruta de su archivo compose y se alcanzan entre sí sin bridge. Su executionScope: boundary ejecuta la FR una vez por cada adjunto al boundary padre.

Su provides: calcula la tabla del bridge, una sola vez. De .boundary.internal_uses_edges conserva las aristas cuyos dos extremos se ensamblan en su propio archivo compose — source_assembly_path y target_assembly_path ambos iguales a .boundary.assembly_path — y están en redes distintas de ese archivo, siendo la red de un extremo su aggrega.ai/namespace, o en su defecto su ruta de ensamblado. Una arista entre dos archivos compose no se puentea, y su consumidor conserva el nombre propio del destino. Cada arista puenteada recibe un puerto de escucha — el puerto propio del destino o, donde una arista anterior ya escucha en él, el primer puerto libre igual o superior al portBase del adjunto (por defecto 10000) — y un upstream, el host publicado del destino (el campo provides que nombra el providesField del adjunto, por defecto host) y su port; el upstream se deriva de la arista, nunca se escribe a mano. A partir de la misma tabla calcula la reescritura de cada consumidor: una variable que la arista entrega desde el campo host pasa a ser aggrega-gw:<listen port>, o aggrega-gw donde la misma arista entrega también una variable desde port, que pasa entonces a ser el puerto de escucha.

Su injectMapping entrega las filas de cada consumidor. Ejecutándose en el contexto de cada consumidor, lee las filas de ese consumidor en la tabla en .features.<attachment>.provides y las entrega por encima de los valores que entregó la propia conexión del consumidor (p. ej., DB_HOST), lo cual es una interceptación; un consumidor sin fila no recibe nada. Donde otra Feature adjunta al consumidor entregó esa clave — mediante su bloque inject: o su injectMapping — la build se detiene nombrando ambas Features en lugar de reemplazar esa entrega (consulta «Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Dos Features adjuntas entregan una misma clave, la posterior mediante el injectMapping de su FeatureRecipe)» en fatal-halts.md). El listen del gateway y la reescritura del consumidor se leen de una sola tabla, por lo que coinciden por arista por construcción, incluidas las colisiones reasignadas mediante portBase.

Su valuesMapping escribe el gateway. El fragmento compose propio de la FeatureRecipe declara el servicio aggrega-gw. Donde algo se puentea, su valuesMapping añade un bloque nginx stream server por cada arista puenteada (listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;, bajo una directiva resolver para que cada upstream se resuelva en el momento de la conexión en lugar de una sola vez al arrancar; el $ de esas variables se escribe $$ para que la interpolación $ de Docker Compose deje un $ literal para nginx), entregado como una configuración compose montada — una entrada configs: de nivel superior con content: en línea, referenciada desde aggrega-gw y montada en /etc/nginx/nginx.conf (para que nginx la cargue sin un command: escrito por el autor). configs.content en línea requiere Docker Compose ≥ 2.23.1. También nombra cada extremo puenteado bajo el x-aggrega-networks-of del gateway, que el provider compose resuelve en las redes en las que se colocan esos extremos, de modo que el gateway se une a cada red que abarcan sus aristas puenteadas (la red del consumidor y la del destino) — en tiempo de ejecución el consumidor puede alcanzar aggrega-gw:<port> y el gateway puede hacer proxy_pass al destino. Donde nada se puentea, el gateway que declara el fragmento se renderiza igualmente, inactivo: sin configuración, sin red adicional y sin reescritura.

El ensamblador compose por (ruta, provider) fusiona el gateway junto a los contribuyentes por componente en la misma ruta evaluada: un único docker-compose.yaml que contiene cada componente más el gateway del bridge. Donde ninguno de los componentes del boundary se ensambla en el archivo del gateway, la build se detiene en lugar de escribir el gateway en ninguna parte. El upstream es un puntero determinista, fijado en tiempo de compilación, a un servicio compose; el DNS de tiempo de ejecución de compose lo resuelve (sin resolución de tiempo de ejecución en tiempo de compilación).

Renderizado después de los llamadores — spec.readsCallerRenderFacts

El campo opcional spec.readsCallerRenderFacts (booleano, por defecto false) declara que las plantillas de esta FeatureRecipe leen lo que renderizaron los componentes que se conectan a su host: los hechos de renderizado que el provider de cada uno de esos llamadores informa sobre la salida que emitió. Qué informa un provider, y con qué nombres, es el contrato propio de ese provider; Informar hechos sobre lo que emitió un guest describe los hechos que un provider puede informar.

Cuándo se renderiza un adjunto así. La build renderiza sus componentes uno a uno, en un orden fijo, y un adjunto normalmente se renderiza justo después del componente al que está adjunto. Un componente que se conecta al host y viene más tarde en ese orden aún no se ha renderizado en ese momento, por lo que no existe nada de lo que emitió para leer. Un adjunto cuya FeatureRecipe establece readsCallerRenderFacts: true se renderiza en cambio una vez que todos los componentes de la build se han renderizado, junto con todos los adjuntos que no establecen ni esta clave ni readsTargetRenderFacts — así el renderizado de cada llamador está completo antes de que se evalúe el adjunto. Su salida queda donde habría quedado y con los mismos nombres; la clave cambia cuándo se renderiza el adjunto, no qué renderiza. Del renderizado posterior se deriva un orden: donde la FeatureRecipe lleva una pipeline que reescribe los documentos de su componente host y el provider del host escribe documentos discretos, esos pasos se ejecutan después de las pipelines de los demás adjuntos del host en lugar de en su orden de adjunción.

Qué lee. Con la clave establecida, cada entrada de .context.used_by lleva .render_facts: los hechos de renderizado del llamador, indexados por nombre de hecho. Cada hecho de renderizado es una lista, por lo que una plantilla siempre la recorre con range — incluso cuando contiene una sola entrada. Sus entradas pueden provenir del renderizado propio del llamador y de los renderizados de las Features adjuntas al llamador: las listas que un nombre obtiene de cada uno se unen en una sola, primero las llamadas del provider propio del llamador y luego cada una de sus Features en el orden en que se renderizaron. Una Feature del llamador que establece ella misma la clave también se renderiza después de todos los componentes, por lo que lo que informó no está entre ellas. Un llamador cuyos providers no informan nada lleva un .render_facts vacío, por lo que un nombre que nadie informó se lee como nada:

artifacts:
callers.yaml: |
callers:
{{- range .context.used_by }}
- component: {{ .component_id }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

Qué nombres de hecho existen, y qué contiene cada entrada, es el contrato documentado del provider del llamador — los del provider helm, por ejemplo, son sus hechos de renderizado, que nombran las etiquetas de los pods que renderizó. Los hechos de los llamadores están en las conexiones que leen valuesMapping:, workload: y artifacts: de la FeatureRecipe; with: y when: de un paso pipeline: no ven en absoluto los componentes que se conectan al host, por lo que un paso lee solo los hechos propios del host. Cada FeatureRecipe adjunta a un componente — establezca o no la clave — lee los hechos propios del componente en .context.render_facts, con la misma forma; el contexto de plantillas describe ambos.

Declárala siempre que una plantilla lea los hechos. Una plantilla escrita en línea en una FeatureRecipe que no establece la clave — su valuesMapping:, su workload: o una entrada de artifacts: — que lee render_facts bajo .context.used_by detiene la build antes de que se renderice nada, nombrando la referencia y el campo en el que se escribió (consulta «A template reads its callers’ render facts without declaring it (Una plantilla lee los hechos de renderizado de sus llamadores sin declararlo)» en fatal-halts.md). La comprobación lee la plantilla tal como está escrita, por lo que no ve una referencia construida mientras se ejecuta la plantilla, ni una escrita en contenido importado de un archivo o una biblioteca — y una plantilla que lee un campo llamado render_facts de alguna otra lista junto a .context.used_by, o que lee los hechos propios del host como .render_facts dentro de {{ with .context }} junto a ella, se trata como si leyera los hechos de los llamadores; escribe los propios del host completos como .context.render_facts. Es la clave, no la comprobación, la que decide cuándo se renderiza el adjunto, así que establécela en cada FeatureRecipe cuyas plantillas lean los hechos de renderizado de sus llamadores, de cualquier forma que los alcancen; establecerla no cuesta nada salvo el renderizado posterior.

Un paso de pipeline lee solo los hechos propios de su host. Un paso puede reescribir los documentos propios del componente host, y la salida propia de un componente sigue siendo la misma sea quien sea quien se conecte a él, por lo que with: y when: de un paso nunca ven los componentes que se conectan al host — establezca o no la FeatureRecipe la clave, que decide cuándo se renderiza el adjunto y nada sobre lo que ve un paso. Un with: o when: de un paso escrito en línea que lee render_facts bajo .context.used_by detiene por tanto la build antes de que se renderice nada, con el código corto E0326, nombrando la referencia y el campo del paso — en lugar de renderizar un valor vacío. Lee los hechos propios del host en un paso en .context.render_facts, escrito completo, y lee los hechos de los llamadores en valuesMapping:, workload: o artifacts: de la FeatureRecipe. Esta comprobación lee la plantilla tal como está escrita, con los mismos límites que la anterior.

Alcance. La clave se aplica a una FeatureRecipe que se renderiza una vez por componente — executionScope: component, el valor por defecto. Una FeatureRecipe que declara executionScope: boundary se renderiza donde siempre lo hace, establezca o no la clave, y las plantillas que producen sus recursos leen .boundary en lugar de .context.

Renderizado después de los destinos — spec.readsTargetRenderFacts

El campo opcional spec.readsTargetRenderFacts (booleano, por defecto false) declara que las plantillas de esta FeatureRecipe leen lo que renderizaron los componentes a los que está conectado su host: los hechos de renderizado que el provider de cada uno de esos destinos informa sobre la salida que emitió. Lee el otro extremo de una conexión respecto a readsCallerRenderFacts — los componentes a los que apuntan las entradas uses del host, en lugar de los componentes cuyas entradas uses apuntan al host — y todo lo relativo a los hechos en sí se lee igual.

Cualquiera de las dos claves hace que el adjunto se renderice después de todos los componentes. Un adjunto cuya FeatureRecipe establece readsCallerRenderFacts: true, readsTargetRenderFacts: true, o ambas, se renderiza una vez que todos los componentes de la build se han renderizado, como describe la sección anterior — hay un único renderizado posterior de este tipo, y lo que implica para dónde queda la salida del adjunto y para el orden de sus pasos de pipeline es lo mismo sea cual sea la clave que llevó allí el adjunto. Las dos claves solo difieren en qué conexiones llevan hechos en el contexto del adjunto: un destino que viene después del host en el orden de la build ya se ha renderizado para entonces, por lo que lo que emitió está ahí para leerse.

Qué lee. Con la clave establecida, cada entrada de .context.uses lleva .render_facts: los hechos de renderizado del destino, indexados por nombre de hecho, con la forma que lleva la entrada de un llamador. Cada hecho de renderizado es una lista, por lo que una plantilla siempre la recorre con range. Sus entradas pueden provenir del renderizado propio del destino y de los renderizados de las Features adjuntas al destino, primero las llamadas del provider propio del destino y luego cada una de sus Features en el orden en que se renderizaron; una Feature del destino que se renderiza ella misma después de todos los componentes no está entre ellas. Un destino cuyos providers no informan nada lleva un .render_facts vacío. Una plantilla lee los hechos de una conexión bajo su alias, .context.uses.<alias>.render_facts.<name>, o los de cada conexión por turno:

artifacts:
targets.yaml: |
targets:
{{- range .context.uses }}
- component: {{ .target }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

Una FeatureRecipe que no establece la clave no ve ningún .render_facts en ninguna conexión, establezca lo que establezca además. Qué nombres de hecho existen es el contrato documentado del provider de cada destino — los del provider helm son sus hechos de renderizado, que nombran las etiquetas, los selectores de controlador y los puertos de contenedor de los pods que renderizó, y por tanto lo que una política de egress necesita para seleccionar exactamente los pods que su host puede alcanzar.

Declárala siempre que una plantilla lea los hechos. Una plantilla escrita en línea en una FeatureRecipe que no establece la clave — su valuesMapping:, su workload: o una entrada de artifacts: — que lee render_facts bajo .context.uses detiene la build antes de que se renderice nada, con el código corto E0347, nombrando la referencia y el campo en el que se escribió (consulta «A template reads its targets’ render facts without declaring it (Una plantilla lee los hechos de renderizado de sus destinos sin declararlo)» en fatal-halts.md). Establecer readsCallerRenderFacts no lo evita. La comprobación lee la plantilla tal como está escrita, con los límites de la comprobación de los llamadores: no ve una referencia construida mientras se ejecuta la plantilla, ni una escrita en contenido importado de un archivo o una biblioteca — y una plantilla que lee .context.uses de cualquier modo y además lee un campo llamado render_facts de algún otro valor, incluida la entrada de un llamador dentro de {{ range .context.used_by }}, se trata como si leyera los hechos de sus destinos. Una plantilla que lee los hechos de ambos extremos establece ambas claves.

Un paso de pipeline lee solo los hechos propios de su host. with: y when: de un paso leen las conexiones que establece el host, tal como las lee la Recipe propia del host, y nunca los hechos de renderizado de sus destinos — establezca o no la FeatureRecipe la clave. Un paso puede reescribir los documentos propios del componente host, y el renderizado propio del host lee lo que sus destinos publican, nunca lo que emitieron. Un with: o when: de un paso escrito en línea que lee render_facts bajo .context.uses detiene por tanto la build antes de que se renderice nada, con el código corto E0348, nombrando la referencia y el campo del paso — en lugar de renderizar un valor vacío. Lee los hechos de los destinos en valuesMapping:, workload: o artifacts: de la FeatureRecipe.

Alcance. Como para la clave de los llamadores: se aplica a una FeatureRecipe que se renderiza una vez por componente. Una FeatureRecipe que declara executionScope: boundary se renderiza donde siempre lo hace, establezca o no la clave, y las conexiones que lee bajo .boundary no llevan hechos de renderizado.

El bloque locals:

FeatureRecipe.spec.locals: es un mapa opcional de cadenas de plantilla Go con nombre cuya salida renderizada expone un mapa .locals.* a todas las demás plantillas dentro de la misma FeatureRecipe. Es el equivalente, privado de la FeatureRecipe, del locals: de la Recipe — un lugar donde calcular una sola vez cadenas derivadas y referenciarlas desde injectMapping, valuesMapping, pipeline[].with y provides sin recalcularlas. Las assertions: de la FeatureRecipe no las leen: los .locals de una aserción son los de la Recipe del componente anfitrión, como indica assertions-block.md. La salida renderizada de cada entrada se almacena sin sus espacios en blanco iniciales y finales. El bloque es un mapa, no un único cuerpo de plantilla; el esquema rechaza un escalar en esta posición.

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: regional-router
spec:
implements: core/regional-router:^1.0.0
capability: helm
locals:
region_prefix: "{{ .infra.region | lower }}"
fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}"
injectMapping: |
env:
"{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}"

.locals.* es por invocación: cada invocación de una FR resuelve su propio bloque locals:, y el resultado solo es visible para las plantillas posteriores de esa invocación. El bloque se resuelve antes de que se evalúen las demás plantillas de la superficie de autoría de la FR, de modo que todas ellas ven valores resueltos.

Cada entrada se evalúa contra un contexto autónomo: .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra y las entradas de este mismo bloque ya resueltas. Es deliberadamente más restringido que el contexto que leen las otras plantillas de la FR — una entrada de locals: no puede alcanzar .context.annotations, .context.inject, .context.uses ni .provides, y una referencia a cualquiera de ellos detiene la compilación indicando la referencia. Los valores derivados que necesitan esos pilares pertenecen a la plantilla que los lee, no a locals:.

Los nombres de ese contexto responden a preguntas distintas, y una entrada de locals: los lee exactamente como lo hacen las demás plantillas de la FeatureRecipe:

  • .context.instance_id es el componente anfitrión para el que se está resolviendo la vinculación. Designa el componente anfitrión en toda superficie de plantilla que evalúa el compilador, de modo que la misma referencia se lee igual sea cual sea la entidad cuyo bloque estés escribiendo.
  • .context.rendered_name es el nombre del componente anfitrión tal como lo informa su propio provider — con helm, el nombre de la release, que es la identidad del anfitrión escrita en el alfabeto que admite un nombre de Kubernetes. Solo está presente donde el provider del anfitrión informa un nombre, y leerlo en un anfitrión cuyo provider no informa ninguno detiene la compilación.
  • .attachment_name es la instancia de vinculación que se está resolviendo — el slot que ocupa en el featuresSchema de la entidad propietaria, o el nombre libre que le diste.

Así, una entrada de locals: que deriva un nombre para un recurso emitido compone el anfitrión y la vinculación, exactamente como lo haría una plantilla de artifacts::

spec:
locals:
scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_target

Donde el nombre tenga que ser uno que la plataforma acepte y el provider del anfitrión informe uno, compónlo en su lugar a partir de .context.rendered_name: para un anfitrión llamado my_api con helm y una vinculación scrape, {{ .context.rendered_name }}-{{ .attachment_name }} da my-zuapi-scrape, mientras que la identidad daría my_api-scrape, que un nombre de Kubernetes rechaza. Consulta Nombrar un recurso renderizado.

.values e .infra en una entrada de locals: son los pilares propios de la vinculación, escritos en la declaración de la vinculación — no los del componente anfitrión.

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:
region_prefix: "{{ .infra.region | lower }}" # defined first
bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry above

El encadenamiento funciona solo hacia abajo. Donde una entrada lee otra, el orden de las entradas decide si la compilación tiene éxito: mueve region_prefix debajo de bucket y la compilación se detiene. El compilador nunca reordena el bloque para que una referencia se resuelva, así que reordenar un bloque locals: es un cambio de comportamiento, no cosmético.

Una referencia a una entrada que el bloque define más adelante detiene la compilación indicando el fallo de orden (mueve la definición encima de quien la lee); una referencia a una clave que el bloque no declara en absoluto la detiene indicando la clave (corrige la ortografía). La comprobación sigue un alias del bloque: una clave alcanzada a través del punto que vuelve a vincular un cuerpo with .locals, o a través de una variable vinculada a .locals, detiene la compilación exactamente en los mismos términos que la escritura directa, y lo mismo ocurre con una clave leída del bloque entre paréntesis — {{ (.locals).nope }} o {{ ($.locals).nope }}. Una sola escritura escapa a ella: una clave alcanzada a través de una llamada cuyo resultado el texto de la plantilla no puede nombrar — {{ index .locals "nope" }}, o {{ (default dict .locals).nope }}. Un campo leído del resultado de una llamada así no detiene la compilación y renderiza el texto literal <no value>; la lectura con index la detiene indicando la clave, porque index detiene la compilación en toda superficie de plantilla cuando el mapa que lee no contiene la clave — consulta errors/fatal-halts.md «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)». provides: lee el bloque completamente resuelto, porque los locals de esta FeatureRecipe se resuelven antes que sus provides; una plantilla de provides: que nombra una clave no declarada detiene la compilación. Son las mismas reglas que sigue el bloque locals: de una Recipe — consulta entities/recipe.md «El bloque locals:».

Comportamiento según el ámbito. Para executionScope: component (predeterminado), locals: se evalúa por cada instancia de componente vinculada contra el contexto autónomo anterior. Para executionScope: boundary, locals: se evalúa por cada vinculación de frontera contra la vista de ámbito de frontera con raíz en .boundary.*; los campos por componente (.context.instance_id, .context.inject, .context.uses) y .attachment_name no están disponibles, porque la FeatureRecipe se ejecuta una vez para la frontera en lugar de una vez por componente. La lista de permitidos de campos de plantilla del ámbito de frontera se aplica a locals: del mismo modo que a las demás plantillas de la superficie de autoría de la FR. El injectMapping, que se ejecuta para cada componente que alcanza la vinculación, lee esa única evaluación de frontera como su .locals. El contrato de evaluación — orden de escritura, lecturas de entradas hermanas solo hacia abajo, las dos detenciones — es idéntico en ambos ámbitos; solo difiere la forma del contexto circundante.

Diferencia con los overlays de injectMapping y los mapeos de pipeline[].with. locals: produce un mapa visible en el contexto para las plantillas posteriores; no aporta salida. injectMapping escribe en el pipe .context.inject del consumidor (mutación del lado del llamador). pipeline[].with proporciona el payload args del plugin Wasm. Las tres superficies son ortogonales — una FeatureRecipe usa habitualmente las tres juntas, con locals: llevando las cadenas derivadas compartidas a las que hacen referencia las otras dos.

El bloque assertions:

FeatureRecipe.spec.assertions: es un mapa opcional de reglas con nombre que expresan invariantes de implementación de la FeatureRecipe — reglas entre campos que se cumplen dado el pipeline específico de plugins Wasm, el chart o el mecanismo sobre el que está construida la FeatureRecipe. Cada clave es un identificador de regla que aparece en el mensaje de error; cada valor es un cuerpo de plantilla Go. Al igual que las aserciones de la Recipe, las aserciones de la FeatureRecipe son propiedades de la implementación específica; las reglas de contrato a nivel de Feature se aplican de forma independiente en una fase anterior del pipeline.

spec:
implements: core/referenced-secret:^1.0.0
pipeline:
- id: fetch_secret
plugin: pipeline-step/aws-secrets-manager:1.2.0
function: step
assertions:
# aws-secrets-manager plugin 1.x requires an explicit region when none is
# implied through the Aggregate's infra block.
region-supplied-for-secrets-manager: |
{{- if not .values.region -}}
{{- if not .infra.aws.region -}}
{{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}}
{{- end -}}
{{- end -}}

La regla anterior es específica del plugin aws-secrets-manager 1.x; no se aplica si se vincula otra FeatureRecipe core/referenced-secret. Las reglas de contrato a nivel de Feature de la definición de la Feature siguen aplicándose en paralelo.

Las aserciones de la FeatureRecipe se evalúan después del enlace de la FeatureRecipe y antes de la generación de recursos. El contexto de plantilla de las FR de ámbito de componente refleja el contexto de las aserciones de la Recipe (campos de la instancia de la entidad más .provides, .locals, .recipe.metadata, .recipe.source); para las FR de ámbito de frontera (executionScope: boundary), las aserciones se evalúan contra la vista de ámbito de frontera (campos .boundary.* disponibles; campos por componente no). Para la gramática de autoría completa y ejemplos desarrollados, consulta templates/assertions-block.md.

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

La mayoría de las FeatureRecipes nunca lo necesitan. Está pensado para una FeatureRecipe cuyo source: es un chart que tomas tal cual — casi siempre uno obtenido de un registro — y que renderiza un documento que la vinculación no debe emitir: un Secret que el chart genera de nuevo en cada renderizado, o un objeto que el componente anfitrión o el operador ya proporciona. omits: deja ese documento fuera de lo que genera la FeatureRecipe — o, para un archivo compose que la FeatureRecipe usa como fuente, un servicio, un volumen o una config que la vinculación no debe aportar, y para una plantilla de CloudFormation que usa como fuente, un recurso.

spec:
capability: helm
implements: core/observability/collector:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/collector
version: "0.9.1"
omits:
# The collector chart ships its own ServiceAccount; the host supplies one.
- kind: ServiceAccount
name: collector
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: collector-dashboards

La clave se escribe de forma idéntica en una Recipe, y Recipe → El campo omits: es su referencia completa: qué selecciona cada campo de una entrada, que when: se evalúa primero y uno falso descarta la entrada, que toda entrada que se aplica debe dejar algo fuera o la compilación se detiene indicándola, que la fuente se sigue renderizando por completo y solo se filtra su salida, y qué providers respetan la clave. Lo único que cambia en una FeatureRecipe es dónde se evalúan las plantillas:

  • Las plantillas de cada entrada se evalúan contra el contexto contra el que se evalúa el valuesMapping: de esta FeatureRecipe, en el ámbito que selecciona su executionScope. Las entradas de una FeatureRecipe de ámbito de componente se evalúan una vez por vinculación, contra los .values y el .infra de esa vinculación; las de una de ámbito de frontera, una vez por frontera, contra la vista de ámbito de frontera y el .infra de la vinculación de frontera. Las reglas sobre lo que pueden leer las plantillas de una vinculación se aplican a las entradas igual que a su valuesMapping:.
  • Solo se filtra lo que renderiza el propio source: de esta FeatureRecipe. Su workload: y sus artifacts: no, ni tampoco la salida del componente anfitrión: las entradas de una vinculación alcanzan su propio chart, su propio archivo compose o su propia plantilla de CloudFormation, y nada más — un servicio compose que el anfitrión declara con la misma clave en el docker-compose.yaml en el que ambos se ensamblan queda intacto, igual que un recurso que el anfitrión declara con el mismo ID lógico en el stack en el que ambos se ensamblan. Para cambiar un documento que renderiza el anfitrión, la Recipe del anfitrión declara la entrada, o un paso de pipeline: lo parchea.

Una detención en una entrada indica el nodo, el provider, esta FeatureRecipe y la posición de la entrada en su lista omits:; para una FeatureRecipe de ámbito de frontera, la línea encima del mensaje indica la vinculación y su frontera.

Para un ejemplo desarrollado de la clave, escrita en una Recipe — el Secret generado de un chart obtenido, dejado fuera, y las detenciones sin la entrada y con una entrada que no coincide con nada —, consulta ai-gateway-own-webhook-certificate.