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

Contrato del contexto de plantillas

Esta página documenta la vista de ejecución que el compilador inyecta en las plantillas Go de Recipe y FeatureRecipe: la forma del contexto de plantilla, la disponibilidad por campo a lo largo del pipeline de compilación y el contrato canónico que necesitan los autores avanzados al escribir plantillas que consumen estado entre componentes. La disponibilidad por sitio de plantilla (qué campos están presentes en qué sitio de evaluación) se encuentra en expansion-matrix.md; esta página documenta las formas de los campos y su semántica.

Descripción general

El compilador ensambla un contexto de plantilla por nodo durante el renderizado y lo inyecta en cada plantilla Go que evalúa el renderizador para ese nodo. El contexto existe solo en memoria — nunca se persiste en disco y nunca cruza la ABI de Wasm como una única carga útil. Cada sitio de plantilla recibe una vista del mismo objeto de contexto; algunos campos se rellenan tarde (.workload llega en la síntesis del workload; .source, en la resolución del origen; .steps lo rellena la ejecución de pipeline: a medida que se completa cada paso, consulta Estado del lenguaje → Fases del pipeline de compilación).

El esquema de la forma de ejecución es template-context-v1beta1.schema.json (se distribuye con la distribución de esquemas de Aggrega).

Campos de nivel superior

Los campos de nivel superior se encuentran en la raíz del contexto de plantilla — se accede a ellos como .field desde dentro de una plantilla.

  • .values (mapa). Carga útil cognitiva escrita por el desarrollador, procedente del Aggregate. Los valores por componente fluyen hasta la Recipe renderizada en este campo. Validado por el schema: del catálogo (la declaración JSON Schema 2020-12 del Component o de la Feature) en la resolución. Cuando el cero / vacío / falso escrito de un campo es semánticamente distinto de la ausencia del campo, usa optional (consulta sprig-functions.md) en lugar de default.
  • .infra (mapa). Dimensionamiento físico escrito por Ops, procedente de la Release. Validado por el schema: del catálogo (la declaración JSON Schema 2020-12 del Component o de la Feature) en la resolución. Se aplica la misma indicación optional-vs-default que para .values — prefiere optional cuando un cero o un falso escrito por el autor es una intención legítima (escalado a cero, sin reintentos, feature flag desactivado).
  • .locals (mapa de valores de cadena). Estado privado de la Recipe — nombres declarados en el bloque locals: de la Recipe, resueltos en el preámbulo de locals y publicados en este pilar en la resolución del origen. Las entradas se resuelven en el orden del autor y una entrada puede leer una entrada hermana definida por encima de ella, así que el orden es determinante dondequiera que una entrada lea otra. Accesible solo dentro de las plantillas propias de la Recipe; nunca se expone a los llamadores.
  • .provides (mapa de valores de cadena). Las cadenas de salida públicas de la Recipe — el contrato contra el que los bloques inject: de los llamadores resuelven las referencias from:. Se rellena en la evaluación de provides.
  • .features (mapa de vinculaciones). Itera las Features vinculadas a este Component (nivel de Aggregate + nivel de subsistema + nivel de Release + impulsadas por anotaciones del Manifest, según el modelo de cebolla de 5 niveles), con el nombre de instancia que el autor dio a la vinculación como clave. Cada entrada lleva los mismos campos — consulta la forma de la vinculación más abajo. Una vinculación escrita en una de las conexiones del Component no está entre ellas: se lee bajo esa conexión, en .context.uses.<alias>.features.<slot>, de modo que una plantilla que recorre .features solo encuentra las vinculaciones propias del Component.
  • .metadata (struct). Identidad de la Release para una nomenclatura determinista: release_name, release_version, environment, aggregate_name. Se rellena en cada renderizado; los valores proceden del bloque metadata: de la Release.
  • .source. El source: de la Recipe, resuelto por la evaluación de plantilla de la resolución del origen. nil para las Recipes sin origen; nil antes de que se ejecute la resolución del origen. En las plantillas de una FeatureRecipe es el source: propio de esa FeatureRecipe, nunca el del componente host — consulta Superficie de la FeatureRecipe de una vinculación.
  • .workload. El objeto Workload analizado, que se rellena una vez que el documento workload: renderizado se ha decodificado y ha superado la validación que lo condiciona: el esquema del Workload, el featuresSchema del Component para cada vinculación que declaran sus contenedores y la resolubilidad de lo que referencia cada vinculación. nil para las Recipes no sintetizadas; nil antes de que se ejecute la síntesis del workload.
  • .steps (mapa de salidas de pasos). Lo rellena la ejecución de pipeline: a medida que se ejecutan los plugins de Wasm, y expone las salidas devueltas por un paso completado a los pasos siguientes mediante .steps.<id>.outputs. Un paso lee las salidas de un paso anterior desde su propia plantilla with; los outputs de un paso solo se vuelven visibles para los pasos declarados después de él. Vacío cuando el nodo no declara ningún pipeline, y antes de que se complete el primer paso del nodo.

Un campo de nivel superior que no contiene nada para este nodo — .workload en una Recipe que no sintetiza ninguno, .source en una Recipe sin origen, .features en un Component sin vinculaciones — se lee como vacío en una plantilla de valor, exactamente como una clave no establecida bajo .values: {{ .workload }} no renderiza nada, un default sobre él proporciona su valor de respaldo, y un if o un with sobre él toma su rama falsa. Un range sobre él no itera nada. Una lectura por debajo de él — {{ .workload.containers }} — se detiene de todos modos, porque no hay nada en lo que descender. Y una plantilla que a la vez imprime un campo así donde siempre se ejecuta — fuera de todo if, with y range — y lo recorre se detiene nombrando el campo, como ocurre con cualquier ruta que no contiene nada y se lee de ambas maneras, porque ningún valor único se imprime como nada e itera como nada: consulta A template reads and iterates a path that holds nothing (Una plantilla lee e itera una ruta que no contiene nada).

La forma de la vinculación

.features.<name> y .features.<slot> tienen la misma forma — una vinculación, leída de una sola manera:

  • .type (cadena). El URI de catálogo de la Feature vinculada.
  • .resolved_version (cadena). La versión de la Feature vinculada tras la resolución del Manifest — la versión realmente asignada a esta compilación, en lugar de una versión fijada repetida en el lado consumidor. Refleja .context.uses.<alias>.resolved_version. Vacío cuando el type de la vinculación no se resuelve en ninguna entidad de catálogo.
  • .labels (mapa de valores de cadena). Las etiquetas de catálogo de la Feature vinculada, transmitidas literalmente en el orden en que la Feature las declara — nada se filtra, se renombra ni se despoja de prefijo, de modo que una plantilla lee exactamente lo que escribió el autor de la Feature. Refleja .context.uses.<alias>.labels. Ausente cuando la Feature no declara etiquetas, y cuando el type de la vinculación no se resuelve en ninguna entidad de catálogo.
  • .values (mapa). El pilar propio de la intención del desarrollador de la vinculación, escrito en la declaración de la vinculación en el Aggregate. Distinto del .values de nivel superior del componente host.
  • .infra (mapa). El pilar propio del dimensionamiento operativo de la vinculación, escrito en la declaración de la vinculación en la Release. Distinto del .infra de nivel superior del componente host.
  • .provides (mapa de valores de cadena). El contrato público resuelto de la FeatureRecipe asignada a esta vinculación — el nombre del recurso emitido, su clave de datos, una identidad de nube y cualquier clave adicional que la FeatureRecipe publique. Se lee como .features.<name>.provides.<key>, a semejanza de .context.uses.<alias>.provides: el consumidor lee lo que publicó el productor en lugar de volver a derivarlo. Una vinculación cuya FeatureRecipe asignada no publica nada no lleva ninguna clave provides, en lugar de un mapa vacío, así que comprueba su presencia antes de acceder a una clave individual.

.provides es lo que hace que una vinculación sea consumible en lugar de simplemente presente. Una Feature que declara un contrato schema.provides ve ese contrato aplicado a la FeatureRecipe que la realiza — la FeatureRecipe debe publicar cada clave declarada — y el consumidor lee el resultado aquí. Así, una Feature de identidad que emite un ServiceAccount y publica su nombre permite que la Recipe consumidora se vincule a él:

workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

El nombre emitido se declara una sola vez, por el productor, y se consume — nunca se repite en el lado consumidor, donde ambos podrían discrepar. El ejemplo workload-identity-binding lo renderiza de extremo a extremo.

.labels es lo que permite a una plantilla adaptarse a qué es una vinculación sin comparar su nombre ni analizar su URI. El compilador no lee ninguna de ellas — transporta las cadenas, y el autor de la plantilla decide qué significan.

Una Feature que no declara etiquetas no lleva ningún .labels, en lugar de un mapa vacío, así que comprueba su presencia antes de acceder a una etiqueta individual — acceder a través de una clave que no existe detiene la compilación. Lee una etiqueta que la Feature podría no declarar mediante optional, porque index se detiene nombrando la clave cuando el mapa no la contiene:

{{ if .features.db.labels }}
{{ if eq (optional .features.db.labels "feature.aggrega.ai/kind" "") "secret" }}...{{ end }}
{{ end }}

Como las etiquetas llegan literalmente, el namespace propio del autor de un catálogo llega a la plantilla sin cambios, y una Recipe lee la misma clave que declara la Feature.

El bloque .context

.context es el contexto de ejecución ensamblado por el compilador para un único nodo — los datos de identidad, de topología y de la tubería de entrega que el renderizador hace pasar por cada punto de plantilla. Sus campos:

  • .context.instance_id (cadena). La identidad del nodo como nombre — el valor que la propia compilación usa para nombrar y etiquetar lo que emite, de modo que una plantilla que compone a partir de él un nombre de recurso o una dirección interna del clúster predice el nombre que la compilación produce realmente. Es el nombre que escribiste para un nodo que declara tu propio Aggregate. Para un nodo que aporta un Aggregate importado, es la identidad aplanada con el separador de módulo escrito por extenso (data-layer.main-db pasa a ser data-layer-zdmain-db), porque un punto no es un carácter que un nombre de recurso pueda contener y, dentro de una dirección del clúster, separa un servicio de su namespace. La forma con puntos es la que tus documentos y los diagnósticos de la compilación usan para referirse a ese nodo; consulta Convenciones de nomenclatura.
  • .context.rendered_name (cadena). El nombre que el proveedor del nodo da a los recursos que renderiza para el nodo — a partir de la fuente que proporcionaste, como el nombre de la release que lee un chart, y a partir de un workload que sintetiza cuando nombra los recursos de ese workload según un nombre propio, como hace helm con el mismo nombre de la release. Presente solo donde ese proveedor deriva uno. En las plantillas de una vinculación de Feature es el nombre del componente host, igual que .context.instance_id es allí la identidad del host; consulta Nombrar un recurso renderizado.
  • .context.labels (mapa de valores de cadena). Etiquetas escritas en el catálogo más cualquier adición de label-transform hecha durante la construcción de la topología.
  • .context.annotations (tres contenedores, ver más abajo). Anotaciones en cascada agrupadas por origen.
  • .context.inject (mapa de mecanismos, ver más abajo). La tubería de entrega prehidratada e interceptada — la superficie estándar que las plantillas de Recipe leen para obtener valores entre componentes.
  • .context.uses (mapa de conexiones, ver más abajo). La proyección JOIN sobre las aristas topológicas salientes.
  • .context.self_inject (mapa de mecanismos, ver más abajo). Para cada nombre que el desarrollador escribió en el propio bloque inject: del componente, la clave provides propia que esa entrada entrega o el único valor propio que lee su plantilla.
  • .context.used_by (lista, ver más abajo). Los componentes cuyas entradas uses apuntan a este. Lo lee una FeatureRecipe vinculada al componente, en las plantillas que producen los recursos propios de la vinculación; vacío en cualquier otro lugar.
  • .context.render_facts (mapa de listas, ver más abajo). Lo que el proveedor del componente informó sobre la salida que renderizó, indexado por nombre de hecho. Lo lee una FeatureRecipe vinculada al componente, en cada una de sus plantillas que se ejecuta después de que el componente se haya renderizado; ausente en cualquier otro lugar.

.context.annotations — tres contenedores

Las anotaciones se propagan en cascada a tres contenedores indexados por origen:

  • .context.annotations.release — anotaciones del límite de la Release (Dominio 4). Se usan para gobernar realidades físicas; los renderizadores las encaminan hacia campos infra: cuando corresponde. Las anotaciones conocidas aggrega.ai/* residen en este contenedor.
  • .context.annotations.catalog — anotaciones de metadatos del Component procedentes del Dominio 2. Rasgos intrínsecos inmutables escritos por el Architect; consumidos principalmente por plugins de políticas Wasm.
  • .context.annotations.aggregate — anotaciones de subsistema del Aggregate procedentes del Dominio 1. Metadatos cognitivos; los renderizadores las encaminan hacia payloads values: cuando corresponde.

Cada contenedor es un mapa plano de cadena a cadena. Según las reglas de separación de la arquitectura, los contenedores están pensados para usos distintos; el motor no impone la separación, así que es la disciplina de autoría la que mantiene los contenedores alineados con su semántica prevista. Consulta capítulo 6 §2 Flujo 5 para el diseño de las anotaciones en cascada.

.context.inject — la tubería de entrega

La tubería es el mapa de entrega preresuelto del compilador. Para cuando una plantilla de Recipe se ejecuta en el renderizado base, cada fuente de inject (literales self-inject escritos por el desarrollador, referencias from: self-inject resueltas contra los propios provides, referencias uses[].inject entre componentes resueltas contra los provides del destino, intercepciones injectMapping de FeatureRecipe) se ha resuelto en un valor de cadena final y se ha fusionado en este mapa.

Campos:

  • .context.inject.env — mapa de valores de cadena de nombre de variable de entorno → valor resuelto.
  • .context.inject.file — mapa de valores de cadena de ruta de archivo → valor resuelto.
  • .context.inject.arg — mapa de valores de cadena de flag de argumento → valor resuelto.
  • .context.inject.all — mapa de valores de cadena que combina los mecanismos env/file/arg/personalizados en un único diccionario plano; útil para serializar la tubería completa ({{ toJson .context.inject.all }}).

Un mecanismo está en la tubería solo cuando algo entrega a través de él. Una plantilla que lee uno a través del cual nada entrega — .context.inject.file sin ninguna entrega de archivos — lo lee como vacío, igual que una plantilla de valor lee cualquier clave ausente, y un range sobre él no renderiza nada; esa lectura aporta el valor vacío para toda la plantilla, de modo que un {{ toJson .context.inject }} en la misma plantilla muestra "file": "". hasKey .context.inject "file" indica si algo entrega a través de él.

  • Mecanismos personalizados (p. ej., ssm_param) — legibles bajo su propio nombre de campo, .context.inject.<mechanism>.<key>, exactamente como los tres principales. Los valores de un mecanismo personalizado llegan a la tubería desde el self-inject a nivel de componente, desde una arista uses[].inject, desde el mapeo inject: de una vinculación de Feature y desde la salida injectMapping de una FeatureRecipe. Para el self-inject a nivel de componente, la allowlist spec.inject del Component debe nombrar el mecanismo, y un mecanismo que la allowlist no nombra detiene la compilación. Las entradas de un mecanismo personalizado también aparecen en .context.inject.all junto a los tres principales. Un mecanismo personalizado puede tener cualquier nombre excepto all: ese nombre es la propia vista fusionada, por lo que un mecanismo con ese nombre nunca podría leerse por sí solo. Un bloque inject que nombra un mecanismo all, y una allowlist de un Component o de una Feature (spec.inject, el inject de un socket) que lo enumera, detienen la compilación al cargarse el documento, y el rechazo explica que el nombre pertenece a esta vista fusionada. Los nombres distinguen entre mayúsculas y minúsculas, así que ALL es un mecanismo personalizado corriente.

La tubería es el estado posterior a la intercepción — los bloques injectMapping de FeatureRecipe ya han fusionado en profundidad sus sustituciones sobre esta tubería durante el mapeo de inject, para cuando las plantillas de Recipe la leen. Un mapeo puede sustituir una clave que entregó el propio bloque inject: del componente, uno de los bloques inject: de sus conexiones o el bloque inject: de su propia vinculación; una clave que dos Features vinculadas entregan ambas, a través de sus bloques inject: o de sus mapeos, detiene la compilación en lugar de llegar a esta tubería con uno de los dos valores. Una Feature vinculada a un límite de la Release llega al componente de la misma manera, a través del injectMapping de su FeatureRecipe, que se ejecuta en el propio contexto del componente sea cual sea el executionScope de la FeatureRecipe — la reescritura, por parte del bridge de compose, de la variable de host de un consumidor es uno de esos mapeos, sujeto a la misma regla.

.context.self_inject — qué valor propio entrega cada uno de los nombres del desarrollador

Cuando un Component declara spec.inject, el desarrollador puede escribir un bloque inject: en el propio componente y elegir los nombres bajo los que se entregan los valores y los provides propios del componente. .context.inject contiene aquello en lo que se resolvieron esas entradas y .inject_raw las contiene tal como se escribieron; .context.self_inject indica, para cada una, la clave provides propia del componente que entrega o el único valor propio que lee su plantilla. Tiene la forma que tiene el .context.uses.<alias>.inject de una conexión — mecanismo, después el nombre del desarrollador, después una clave —, con la clave nombrando uno de los provides o de los valores propios del componente:

  • provides.<key> — una entrada escrita con from: <key>, que entrega uno de los provides propios del componente.
  • values.<key> — una entrada cuya plantilla value: lee exactamente uno de los valores propios del componente y nada más, siendo <key> la clave de nivel superior de ese valor. El texto o las funciones alrededor de la lectura no importan, ni tampoco la profundidad con la que la plantilla lee dentro del valor: '{{ .values.role }}', 'role={{ .values.role | upper }}' y '{{ with .values.role }}{{ . }}{{ end }}' se corresponden todos con values.role, y '{{ .values.config.port }}', '{{ index .values.config "port" }}' y '{{ (default dict .values.config).port }}' se corresponden todos con values.config.
  • una cadena vacía — cualquier otra entrada: un literal, una plantilla que lee dos valores, una plantilla que lee algo además de los valores (.infra, .metadata, .context), y una plantilla cuya lectura de los valores el texto no atribuye a una única clave de nivel superior — los valores pasados a una función por su raíz (index .values "role"), los valores leídos completos (toJson .values, o un campo leído dentro de {{ with .values }} o a través de una variable vinculada a .values), o el contexto completo transmitido (toJson .).
# The developer's block on the component, in the Aggregate
inject:
env:
- { in: SERVICE_HOST, from: host }
- { in: AGENT_ROLE, value: '{{"{{"}} .values.role }}' }
- { in: MODE, value: batch }
- { in: ROLE_AND_GOAL, value: '{{"{{"}} .values.role }}-{{"{{"}} .values.goal }}' }
ssm_param:
- { in: /app/goal, value: '{{"{{"}} .values.goal }}' }
# What the Recipe reads at .context.self_inject
env:
SERVICE_HOST: provides.host
AGENT_ROLE: values.role
MODE: ""
ROLE_AND_GOAL: ""
ssm_param:
/app/goal: values.goal

En el Aggregate, cada plantilla value: empieza con {{"{{"}} en lugar de {{, porque todo el texto del Aggregate se lee una vez como plantilla, para la interpolación de parámetros, antes de que se evalúen las propias plantillas del bloque; las plantillas citadas en la lista anterior se muestran tal como se leen después de ese escape. Consulta Texto que contiene sus propias llaves dobles.

Esto es lo que permite que una Recipe que ejecuta la propia imagen del desarrollador trate sus propios nombres de variable para los valores propios del componente como valores predeterminados — la convención del catálogo de la biblioteca estándar, que un catálogo empresarial puede elegir de otro modo. Antes de entregar un valor propio con un nombre propio, una Recipe así comprueba si el bloque del desarrollador ya entrega ese valor, y omite su valor predeterminado cuando es así — de modo que un desarrollador que renombra un valor conserva todos los demás valores predeterminados:

workload: |
containers:
main:
variables:
{{- range $name, $value := .context.inject.env }}
{{ $name }}: {{ $value | quote }}
{{- end }}
{{- $named := dict }}
{{- with .context.self_inject.env }}{{ range $name, $key := . }}{{ $_ := set $named $key true }}{{ end }}{{ end }}
{{- if not (hasKey $named "values.role") }}
APP_ROLE: {{ .values.role | quote }}
{{- end }}

.context.self_inject está presente en cada renderizado y vacío donde el desarrollador no escribió ningún bloque. Un mecanismo aparece solo cuando el bloque lo nombra, así que protege la lectura de uno que el bloque podría no nombrar, como hace el with de arriba. Una plantilla encuentra los nombres ordenados, sea cual sea la forma en que los lea, como encuentra cualquier mapa. El mapa se lee del texto que escribió el desarrollador; nada en él es un valor resuelto, y el compilador no atribuye ningún significado a los nombres ni a las claves.

.context.uses — proyección JOIN

.context.uses es la vista enriquecida del compilador de cada arista topológica saliente del nodo actual. Cada entrada del mapa se indexa por el alias local del socket (p. ej., databases.primary pasa a ser .context.uses.primary cuando el Aggregate escribió uses: { databases: { primary: { target: ... } } }) y lleva una proyección JOIN del estado resuelto del destino más el contrato de entrega del lado del llamador:

  • .target (cadena) — ID de instancia del nodo de destino.
  • .socket (cadena) — nombre del socket del lado del llamador (la clave usesSchema).
  • .provides (mapa de valores de cadena) — las claves provides: resueltas del destino (las cadenas de salida públicas que la Recipe de destino exportó durante la evaluación de provides).
  • .inject (mapa de mecanismo → mapa de clave → valor) — directivas de inject del lado del llamador para esta arista (el bloque inject: en la declaración uses[].inject). Las claves de mecanismo son env/file/arg/personalizadas; las entradas del mapa por mecanismo son referencias clave local → clave de provides del destino.
  • .labels (mapa de valores de cadena) — las etiquetas del destino, nunca las del componente consumidor: el conjunto que lleva el propio .context.labels del destino, sus etiquetas escritas en el catálogo más cualquier adición de label-transform hecha durante la construcción de la topología.
  • .annotations (tres contenedores) — los contenedores de anotaciones release/catalog/aggregate del destino.
  • .component (cadena) — URI del tipo de Component del destino.
  • .resolved_version (cadena) — versión del Component del destino tras la resolución del Manifest.
  • .boundary_path (cadena) — ruta del límite de la Release del destino, establecida tanto si el destino reside en el límite del llamador como en otro.
  • .origin_feature (cadena) — establecido cuando la arista fue sintetizada por una vinculación de Feature (p. ej., una Feature sidecar que aporta una arista uses hacia una Feature de credenciales).
  • .values (mapa) — configuración del desarrollador por arista, resuelta, para esta conexión, escrita en la entrada uses del Aggregate. Presente solo cuando la arista lleva valores por arista.
  • .infra (mapa) — configuración del operador por arista, resuelta, para esta conexión, escrita en la entrada uses de la Release. Presente solo cuando la arista lleva infra por arista.
  • .origin_release (booleano) — true cuando fue la Release la que cableó esta conexión en lugar de declararla el Aggregate; ausente para una conexión que declara el Aggregate.
  • .features (mapa de vinculaciones) — las vinculaciones escritas en esta conexión, indexadas por el nombre del slot que declara el socket; consulta más abajo. Presente solo cuando la conexión lleva una.
  • .render_facts (mapa de listas) — lo que los renderizados del destino informaron sobre la salida que emitieron, indexado por nombre de hecho, con la misma forma que el .render_facts de un llamador en .context.used_by: cada hecho es una lista, primero las llamadas del propio proveedor del destino y luego cada una de sus Features en el orden en que se renderizaron, y las listas que un nombre recibe de cada uno se unen en una sola. Presente solo para una FeatureRecipe que establece readsTargetRenderFacts: true — sus vinculaciones se renderizan una vez que todos los componentes se han renderizado, de modo que el renderizado de cada destino está completo — y en ese caso en cada conexión, vacío para un destino cuyos proveedores no informan nada. Se lee solo en valuesMapping:, workload: y artifacts: de esa FeatureRecipe; ausente de las propias plantillas de Recipe del componente, de un injectMapping:, de with: y when: de un paso de pipeline:, y de toda FeatureRecipe que no establece la clave — una plantilla de una de ellas que lo lee detiene la compilación antes de que se renderice nada.

Ambos mapas de configuración por arista tienen ámbito de consumidor: llegan solo al contexto de renderizado del nodo consumidor, nunca al del destino.

Un valor proporcionado se lee en .provides.<name> — los nombres proporcionados se anidan bajo .provides en lugar de estar directamente en la arista, de modo que .context.uses.<alias>.<name> no direcciona ningún campo y no devuelve nada.

En una conexión cuyos dos extremos se renderizan en salidas diferentes, .provides contiene sustitutos en lugar de los valores. Cuando el proveedor cablea una conexión así con una referencia propia una vez ensambladas ambas salidas — un stack de CloudFormation que lee un valor de otro stack, por ejemplo —, cada valor que lleva .context.uses.<alias>.provides es un marcador de posición que el proveedor sustituye más tarde, por una referencia entre stacks o por el propio valor, como describe su propia página. Un valor así debe copiarse, no compararse — la misma regla que sigue el valor que una conexión así entrega por la tubería de inject, que es un marcador de posición del mismo tipo. Escríbelo entero, dentro de una cadena más larga, o mediante una función que lo deje tal cual, como quote. Una plantilla que compara un valor que lee de .provides, bifurca según él, lo mide o lo cambia estaría decidiendo en función del marcador de posición, así que la compilación se detiene en su lugar, nombrando la plantilla y cada valor que leyó; bifurca según un valor propio del componente consumidor. La detención abarca toda plantilla que lee los .provides de la conexión, incluido el injectMapping: de una FeatureRecipe vinculada, y una FeatureRecipe de ámbito de límite que lee las mismas conexiones bajo .boundary. Una conexión cuyos dos extremos se renderizan en una única salida lleva sus valores tal cual.

Un alias nombra una conexión, así que el mapa contiene una entrada por cada conexión que establece el componente. El mapa se indexa solo por alias, sea cual sea el socket en el que esté cableada una conexión, y no hay dos conexiones de un mismo componente que compartan un alias — ni en un socket ni en dos, sea cual sea el documento o la vinculación que trazó cada una. La compilación rechaza un par así, nombrando ambas conexiones y dónde se escribió cada una, antes de que se renderice nada. Una lista que nombra dos veces un mismo destino es un par así, ya que el alias de una entrada de lista es su destino; también lo es una conexión local en un socket models junto a una conexión local en un socket databases.

Las plantillas de Recipe consumen esta proyección para consultar el estado del lado del destino sin recorrer el grafo IR. Las plantillas injectMapping de FeatureRecipe la usan para acceder a las anotaciones del destino en decisiones de enrutamiento entre límites (el patrón del resolvedor DNS de K8s documentado en entities/featurerecipe.md es el ejemplo canónico desarrollado).

Una plantilla que itera sobre .context.uses ve las conexiones en orden de clave — ordenadas por alias —, no en el orden en que las escribió el Aggregate. Todo mapa sobre el que itera una plantilla se visita de esa manera, incluidos .features y los .features de una conexión, de modo que una plantilla nunca recupera el orden escrito iterando sobre un mapa; donde el orden tiene significado, la superficie de autoría lo modela como una lista. En cualquier caso, la salida renderizada es idéntica byte a byte entre compilaciones de la misma entrada.

Las vinculaciones de una conexión — .context.uses.<alias>.features

Una vinculación escrita en una conexión — bajo features: en la entrada uses de un componente en el Aggregate, o en la entrada de la Release para esa conexión — ocupa un slot que declara el socket. Es una vinculación del componente consumidor para todo lo que la compilación hace con ella: el Manifest asigna su realización, su FeatureRecipe se renderiza en el lado del consumidor, su contrato de provides se aplica. Una plantilla la lee bajo la conexión en la que se escribió:

{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
api_base: {{ $edge.provides.endpoint }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
api_key_key: {{ .provides.key }}
{{- end }}{{ end }}
{{- end }}
  • Indexadas por slot. .context.uses.<alias>.features.<slot> nombra el slot que declara el socket de la conexión — credential más arriba —, de modo que un consumidor que alcanza varios destinos lee la credencial propia de cada destino bajo el alias de ese destino. Una conexión que no lleva ninguna vinculación no tiene .features, y por eso la lectura está protegida.
  • La forma de la vinculación. Cada entrada lleva exactamente lo que .features.<name> lleva para una de las vinculaciones propias del componente — .type, .resolved_version, .labels, .values, .infra y los .provides resueltos de la FeatureRecipe asignada a ella —; consulta la forma de la vinculación. Los provides que se leen aquí son aquellos con los que se renderiza la propia FeatureRecipe de la vinculación, de modo que el nombre al que hace referencia un consumidor y el nombre del recurso que emite esa FeatureRecipe son un único valor evaluado.
  • Nunca en .features. Los .features propios del componente contienen solo las vinculaciones escritas en su propio bloque. Una Recipe que itera sobre .features y selecciona vinculaciones por tipo — {{ range $name, $f := (default dict .features) }}{{ if eq $f.type "core/referenced-secret" }}… — nunca encuentra, por tanto, la credencial de una conexión, ni siquiera una de la misma Feature: una plantilla llega a la vinculación de una conexión a través de su conexión, nunca a través de .features. Lo mismo vale en toda superficie que muestra las vinculaciones de un componente, incluido el contexto assertions.

Los componentes que usan este — .context.used_by

.context.uses mira hacia fuera, a las conexiones que establece un componente. .context.used_by mira hacia dentro, a los componentes cuyas entradas uses apuntan a este. Una FeatureRecipe vinculada al componente lo lee, y ahí es donde corresponde un recurso que describe o restringe esas conexiones — una network policy que admite solo los componentes declarados como llamadores de este, por ejemplo:

artifacts:
callers.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ .context.rendered_name }}-{{ .attachment_name }}
data:
callers: |
{{- range .context.used_by }}
- component: {{ .component_id }}
socket: {{ .socket }}
selector: {{ .provides.selector }}
{{- with .source_namespace }}
namespace: {{ . }}
{{- end }}
{{- end }}

Cada entrada lleva:

  • .component_id (cadena) — el ID de instancia del componente que se conecta en su forma aplanada (frontend, data-layer.etl), el valor que una plantilla de ruta subDirectory: lee como .component_id.
  • .socket (cadena) — el socket que la conexión ocupa en el componente que se conecta (su clave usesSchema).
  • .provides (mapa de valores de cadena) — lo que publica el componente que se conecta, restringido a las claves que declara su Component: los mismos valores que un consumidor de ese componente lee en .context.uses.<alias>.provides. Una clave que la Recipe del componente publica sin que su Component la declare no está entre ellos.
  • .source_namespace (cadena) — el namespace en el que está ubicado el componente que se conecta: la anotación aggrega.ai/namespace que se le aplica, propagada en cascada a través de sus límites, con prioridad para su propia entrada en la Release. Un componente cuya entrada en la Release establece el namespace, o lo borra con null, lleva su propia configuración en lugar de la de su límite, de modo que el valor nombra el namespace en el que se renderizan los recursos propios del componente. Ausente cuando no se aplica ningún namespace al componente; léelo mediante with o if, como hace el ejemplo, en lugar de imprimirlo directamente.
  • .source_boundary_path (cadena) — la ruta del límite de la Release que contiene el componente que se conecta, con los límites anidados unidos por / (edge, edge/inner).
  • .render_facts (mapa de listas) — lo que los renderizados del componente que se conecta informaron sobre la salida que emitieron, indexado por nombre de hecho, con la misma forma que .context.render_facts. Cada hecho es una lista, así que una plantilla siempre itera sobre él, incluso cuando contiene una sola entrada. Sus entradas pueden proceder del propio renderizado del componente que se conecta y de los renderizados de las Features vinculadas a él: las listas que un nombre recibe de cada uno se unen en una sola, primero las llamadas del propio proveedor del componente y luego cada una de sus Features en el orden en que se renderizaron. Presente solo para una FeatureRecipe que establece readsCallerRenderFacts: true — sus vinculaciones se renderizan una vez que todos los componentes se han renderizado, de modo que el renderizado de cada llamador está completo — y en ese caso en cada entrada, vacío para un llamador cuyos proveedores no informan nada. Una FeatureRecipe que no establece la clave no ve .render_facts en ninguna entrada, y una plantilla suya que los lee detiene la compilación antes de que se renderice nada.

Los dos valores de ubicación son los que una FeatureRecipe de ámbito de límite lee como source_namespace y source_boundary_path en la entrada de la misma conexión en sus listas de aristas .boundary: ambas vistas leen de la misma manera dónde está ubicado un componente, así que nunca discrepan al respecto. Una arista de esas listas lleva también la ruta de ensamblado de cada extremo — source_assembly_path y target_assembly_path, el directorio bajo el directorio de salida de la compilación en el que el proveedor del extremo lo ensambla —, que una entrada de .context.used_by no lleva.

Una FeatureRecipe que establece readsCallerRenderFacts: true lee los hechos de cada llamador de la misma manera que lee los del host. Para un proveedor que documenta un hecho llamado ports cuyas entradas llevan cada una un port:

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

Un llamador cuyo proveedor no informa ningún ports renderiza un ports: vacío en lugar de fallar, porque un nombre que nadie informó se lee como nada.

Cómo se comporta la lista:

  • En el orden escrito. Las entradas siguen el orden en que están escritos los componentes que se conectan y, después, el orden de las propias entradas uses de cada uno. Un componente que se conecta dos veces aparece dos veces, una por conexión. Como es una lista y no un mapa, un range encuentra a los llamadores en ese orden — no se ordena nada.
  • Solo donde la vinculación renderiza sus propios recursos. valuesMapping:, workload: y artifacts: de la FeatureRecipe la leen. Está vacía en las propias plantillas de Recipe del componente, en un injectMapping: y en with: y when: de un paso de pipeline:, porque lo que produce cada uno de ellos puede acabar en la propia salida renderizada del componente: un injectMapping: escribe la tubería de entrega del componente, y un paso de pipeline puede reescribir los documentos del componente. Eso es lo que mantiene igual la propia salida de un componente, lo use quien lo use — cablear un llamador más a un componente cambia la salida de una Feature vinculada a él que lee sus llamadores, y nada de lo que renderiza el propio componente.
  • Nada sobre la conexión en sí. Una entrada no lleva values ni infra por conexión ni ninguna de las vinculaciones de la conexión; esos se quedan con el componente consumidor, bajo su .context.uses.<alias>.
  • Vacía cuando nada usa el componente. Un range sobre ella no renderiza entonces nada.
  • Canalizado, nunca interpretado. La identidad, el socket, los valores publicados y la ubicación son cadenas que el compilador deja pasar, y los hechos de renderizado son lo que informaron los proveedores de cada llamador, indexados por nombre. No infiere nada de un nombre, no obtiene nada y no decide nada sobre qué llamadores debe admitir un recurso; decide la plantilla.

Lo que un proveedor ha informado sobre un renderizado — .context.render_facts

El proveedor de un componente puede informar de hechos sobre la salida que renderizó — propiedades de los documentos que escribió que solo su propio conocimiento de su formato puede ver. Qué hechos informa un proveedor, con qué nombres y con qué en cada entrada, es el contrato documentado propio de ese proveedor; consulta Informar de hechos sobre lo que emitió un guest para el lado del proveedor. El proveedor helm, por ejemplo, informa de las etiquetas de las plantillas de pod que emitió, los selectores de sus controladores y Services, y los puertos de sus contenedores — consulta sus hechos de renderizado. Una FeatureRecipe vinculada al componente lee lo que informó el proveedor del componente en .context.render_facts, indexado por nombre de hecho. Para un proveedor que documenta un hecho llamado ports cuyas entradas llevan cada una un name y un port:

artifacts:
ports.yaml: |
ports:
{{- range .context.render_facts.ports }}
- name: {{ .name }}
port: {{ .port }}
{{- end }}
  • Cada hecho es una lista. Un proveedor informa de cada hecho como una lista, incluso cuando contiene una sola entrada, así que una plantilla siempre itera sobre él — no hay un valor único que leer por sí solo.
  • Una lista por nombre, unida a lo largo del renderizado del componente. Renderizar un componente puede requerir más de una llamada de su proveedor — un renderizado de chart y una colocación de artifacts, por ejemplo — y cada llamada informa por sí misma. Las listas que un nombre recibe de esas llamadas se unen en una sola, en el orden en que se ejecutaron las llamadas. Lo que renderizaron las Features vinculadas al componente no está entre ellas aquí: una Feature lee solo el propio renderizado del componente en .context.render_facts, emitan lo que emitan las otras Features del componente.
  • En toda plantilla de una FeatureRecipe vinculada. Sus valuesMapping:, workload: y artifacts: lo leen, y también with: y when: de sus pasos de pipeline: — los hechos proceden del propio renderizado del componente, así que leerlos no hace que nada dependa de quién se conecta al componente. Está ausente de las propias plantillas de Recipe del componente y de un injectMapping:, que se ejecutan antes de que el componente se haya renderizado.
  • Vacío en lugar de ausente. Donde el proveedor del componente no informa nada, .context.render_facts es un mapa vacío, y un nombre que nadie informó se lee como nada, así que un range sobre él no renderiza nada en lugar de fallar.
  • Orden. Una lista conserva sus entradas en el orden en que el proveedor las informó. Una entrada de objeto es un mapa con claves como cualquier otro del contexto, así que una plantilla que itera sobre uno encuentra sus claves en orden de clave.
  • Canalizado, nunca interpretado. El compilador solo comprueba que el valor de cada hecho sea una lista. No lee nada de lo que significa un nombre o una entrada; la plantilla decide qué hacer con ello.

El .uses de una aserción — indexado por socket y luego por alias

Una plantilla assertions: lee las mismas conexiones a través de una vista propia más estrecha: .uses en la raíz en lugar de bajo .context, y sin nada de lo que publicó el destino de una conexión, porque ambas fases de aserción se evalúan antes del renderizado. Refleja la forma de autoría uses: <socket>: <alias>: { target: … } — indexado por socket y, bajo cada socket, por el alias de cada conexión que hay en él, de modo que una conexión escrita como entrada de lista toma su destino como alias. La entrada de cada conexión lleva target, alias y, para una conexión que trazó una vinculación de Feature, origin_feature, además de tres de los hechos que lleva .context.uses, con los mismos nombres y los mismos valores: .labels, las etiquetas del destino; .values, los valores escritos en la conexión; y .features, las vinculaciones escritas en ella, indexadas por slot. Cada uno de los tres está presente en cada entrada, vacío donde la conexión no lleva ninguno. Una vinculación bajo .features lleva solo su type, su resolved_version y sus values — la forma en que una aserción lee cada vinculación, incluidas las propias de un componente, ya que la FeatureRecipe de una vinculación aún no ha resuelto sus provides cuando se ejecuta una aserción.

Un socket que contiene una conexión y un socket que contiene varias tienen la misma forma, así que una aserción lee cualquiera de los dos de la misma manera. Para un componente cuya entrada en el Aggregate escribe uses: { models: { local: { target: llama }, fast: { target: turbo } } }:

assertions:
two-models-wired: |
{{- if lt (len (optional .uses "models" dict)) 2 -}}
{{- fail "wire two models to the models socket" -}}
{{- end -}}
local-is-llama: |
{{- if and (hasKey .uses "models") (hasKey .uses.models "local") (ne .uses.models.local.target "llama") -}}
{{- fail (printf "the local connection must point at llama; it points at %s" .uses.models.local.target) -}}
{{- end -}}

hasKey .uses "models" pregunta si el socket está cableado, len cuenta sus conexiones, un range sobre él visita cada una en orden alfabético de sus alias, y .uses.models.local.target lee una conexión. .uses.models.target no direcciona ninguna conexión y se detiene bajo el missingkey=error de la superficie de aserciones. Cada conexión tiene una entrada propia, por la misma razón que el mapa del contexto de renderizado: dos conexiones de un mismo componente nunca comparten un alias, porque la compilación lo rechaza antes de que se ejecute ninguna aserción. El contexto completo de las aserciones está documentado en assertions-block.md.

El contexto de plantilla lleva estos campos con forma de inject, cada uno con su propia semántica. Los autores de Recipe y de FeatureRecipe deberían saber qué superficie leer.

SuperficieTipoSe rellena cuandoUso
.context.injectmapa de mecanismos (siempre presente)Cada renderizadoLa tubería de entrega estándar prehidratada — léela en las plantillas valuesMapping:/workload:/artifacts: y en cualquier punto de plantilla de una FeatureRecipe.
.inject (nivel superior)mapa de mecanismos (anulable)Al renderizar la FeatureRecipe de una vinculación, cuando la vinculación escribe un bloque inject:Las entradas inject: propias de la vinculación, bajo cada mecanismo que su bloque nombra — env, file, arg o uno personalizado como vault_ref —, con cada nombre local asignado a la clave que nombra su from:. Esa clave es una que la FeatureRecipe publica en sus provides:, que el compilador también entrega en el .context.inject del componente, o una clave que una FeatureRecipe que lee .inject consume ella misma: una entrada que nombra una clave que la FeatureRecipe no publica detiene el build, a menos que una plantilla que la FeatureRecipe evalúa contra este contexto — su valuesMapping:, workload:, artifacts:, omits: o el with: o el when: de un paso del pipeline — lea .inject mediante una ruta que la plantilla nombra: .inject, .inject.env, {{ with .inject }} y similares, no un traspaso del contexto completo como toJson .. Su injectMapping: no cuenta, porque se evalúa contra el contexto del componente, donde .inject está ausente. El bloque de una vinculación no lleva literales: una entrada value: allí detiene el build, y un literal que el componente necesita se escribe en el propio bloque inject: del componente. Un mecanismo personalizado se lee en .inject.<mechanism> exactamente como .inject.env, y sus entradas aparecen en .inject.all junto a los tres principales. Una lectura con puntos de un mecanismo que la vinculación no escribe se detiene como clave desconocida, incluso dentro de un if o un with, donde .context.inject.<mechanism> se lee como vacío; lee un mecanismo que la vinculación podría no escribir mediante {{ with .inject }}{{ if hasKey . "<mechanism>" }}{{ index . "<mechanism>" "<key>" }}{{ end }}{{ end }}, que compila tanto si la vinculación escribe el mecanismo o algún bloque inject: como si no. Ausente de las plantillas de una Recipe base y de una vinculación que no escribe ningún bloque inject:.
.inject_raw (nivel superior)mapa de mecanismos (anulable)Se establece cuando el desarrollador escribió un bloque inject: en el componente padreLa intención del desarrollador sin modificar, antes de cualquier intercepción de inject-mapping. Cada mecanismo que nombra el bloque — env, file, arg o uno personalizado como ssm_param — está bajo su propio nombre y contiene las entradas exactamente como están escritas (in con from o value), en el orden escrito: .inject_raw.ssm_param lee un mecanismo personalizado del mismo modo que .inject_raw.env lee el básico. Úsalo para comprobaciones lógicas del tipo «¿solicitó originalmente el desarrollador esta clave de entrega?»; inmune a la reescritura por el injectMapping de una FeatureRecipe. nil si el desarrollador omitió el bloque inject:.
.context.self_injectmapa de mecanismos (siempre presente)Cada renderizado; vacío donde el desarrollador no escribió ningún bloque inject: en el componenteCada nombre del propio bloque inject: del componente, asignado a la clave propia que entrega su entrada — provides.<key>, values.<key> o vacío. Úsalo para omitir un nombre predeterminado para un valor propio que el desarrollador ya entrega; consulta más arriba.

Los autores que necesitan la entrega resuelta posterior a la intercepción deberían leer .context.inject. Los autores que necesitan la intención original inmutable (p. ej., para detectar una intercepción o para emitir un comportamiento de respaldo cuando el desarrollador omitió un bloque inject) deberían leer .inject_raw. Los autores que necesitan saber cuáles de los valores propios del componente ya ha nombrado el desarrollador deberían leer .context.self_inject.

Superficie de la FeatureRecipe de una vinculación

Cuando el renderizador evalúa las plantillas de la FeatureRecipe de una vinculación, se establece un campo adicional de nivel superior:

  • .attachment_name (cadena) — el nombre de instancia de la vinculación: el slot que ocupa en el featuresSchema de la entidad propietaria, o el nombre libre que le dio el autor. locals:, provides:, injectMapping:, valuesMapping: y artifacts: de una FeatureRecipe lo leen para derivar un identificador de recurso determinista — {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }} donde el proveedor del host informa un nombre renderizado, como hace helm, y {{ .context.instance_id }}-{{ .attachment_name }} donde no informa ninguno — y para nombrar la vinculación que se está procesando.

Las propias plantillas de una Recipe base no están resolviendo una vinculación, así que el campo no forma parte de su contexto: una plantilla provides:, locals: o source: de una Recipe que lo referencia se detiene nombrando la referencia en lugar de renderizar un valor vacío. Una FeatureRecipe con executionScope: boundary se renderiza una vez para el límite en lugar de una vez por componente, así que el campo tampoco está disponible para las plantillas que se ejecutan para el límite; su injectMapping: se ejecuta para cada componente al que llega la vinculación y lo lee allí.

En las plantillas que producen los recursos propios de la vinculación — sus valuesMapping:, workload: y artifacts: —, el contexto de la vinculación también enumera los componentes que usan su host, en .context.used_by, y, donde su FeatureRecipe establece readsTargetRenderFacts: true, lleva lo que renderizó cada componente al que está cableado su host, en .context.uses.<alias>.render_facts. Esas plantillas y sus pasos de pipeline: también leen lo que informó el proveedor de su host sobre el renderizado del host, en .context.render_facts. Una FeatureRecipe de ámbito de límite renderiza sus recursos para ningún componente host y sin .context; en su lugar, lee cada conexión hacia su límite bajo .boundary.internal_uses_edges y .boundary.incoming_cross_boundary_uses_edges. Su injectMapping: es la única plantilla que escribe que se ejecuta en el contexto de un componente — el de cada componente al que llega la vinculación, .context.* incluido —, y una referencia a .boundary allí detiene la compilación.

El campo es la única vía hacia el nombre de instancia de la vinculación. .context.instance_id es el componente host para el que se está resolviendo la vinculación — denota el host en toda superficie de plantilla que evalúa el compilador, incluidos los propios locals: de una FeatureRecipe —, así que los dos nombres no son intercambiables, y ninguno sustituye al otro.

.source es propio de la vinculación. La plantilla source: de una FeatureRecipe se evalúa antes que su valuesMapping:, como la de una Recipe antes que el suyo, y lo que produjo es lo que contiene .source en las plantillas que producen los recursos de la vinculación — su valuesMapping:, omits:, workload: y artifacts: — y en sus pasos pipeline:. Nunca es la fuente del componente host: una FeatureRecipe que no declara ningún source:, o cuya plantilla no produce nada, no lee nada ahí, ni siquiera en un host cuya Recipe declara uno. Una FeatureRecipe de ámbito de frontera lee su propia fuente en las mismas plantillas. La única excepción es el injectMapping:, que se ejecuta antes de que se evalúe la fuente de la vinculación y lee .source como lo hace la propia Recipe del componente host.

.context.rendered_name también es el del componente host: en toda plantilla de una vinculación por componente lleva el nombre que el propio proveedor del host informa para el host — el valor que lee la propia Recipe del host —, así que una vinculación nombra un recurso según su host con {{ .context.rendered_name }}-{{ .attachment_name }} y obtiene un nombre que la plataforma acepta incluso donde la identidad del host contiene un guion bajo o una letra mayúscula. Está presente dondequiera que el proveedor del host informa un nombre y ausente donde no informa ninguno, y leerlo en un host así detiene la compilación desde cualquier plantilla que la FeatureRecipe escribe en línea distinta de su injectMapping:; consulta Nombrar un recurso renderizado.

Disponibilidad por punto de plantilla

La disponibilidad de los campos varía según el punto de plantilla. Las plantillas provides: de una Recipe se ejecutan en la evaluación de provides con un contexto autónomo (sin .context.inject/.context.uses); el valuesMapping: de una Recipe se ejecuta en el renderizado base con el contexto de plantilla completo; el injectMapping: de una FeatureRecipe se ejecuta en el mapeo de inject con el contexto de plantilla completo, incluida la tubería de inject que se intercepta. La tabla completa de disponibilidad punto por punto está en expansion-matrix.md; esta página documenta las formas de los campos a las que apunta la columna «referencias disponibles» de la matriz.

Referencias cruzadas