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

Matriz de expansión de plantillas

Referencia de la expansión de plantillas — la matriz completa

El DSL de Aggrega admite la expansión text/template de Go (con la biblioteca Sprig prerregistrada) en varias ubicaciones de las entidades YAML. Cada ubicación tiene un conjunto específico de referencias disponibles, determinado por el momento en que los datos se vuelven concretos a medida que avanza la compilación. Esta página es la referencia de lo que se puede referenciar y dónde.

1. El árbol temporal de la pipeline (cuándo se vuelven concretos los datos)

Entender qué referencias están disponibles requiere entender cuándo se resuelve cada dato. Las fases siguientes se enumeran en el orden en que se ejecutan, y cada una recibe el nombre de lo que hace — ese nombre es como el resto de esta página se refiere a ella:

Resolution — resolver and syntax validator
├── .parameters → Interpolated into the Aggregate's text; the merged map
│ then stays readable to path templates only
├── .values → schema-validated against the Component's pillar schema, concrete
├── .infra → Release-merged into target components/features, concrete
└── Catalog entities → Resolved (extends merged, pillar schemas composed, usesSchema extracted)
Topology construction
├── .context.instance_id → Node identity, written as a name (e.g., "data-layer-zdmain-db")
└── .context.labels → From Catalog + label-transform mutations
Graph finalization
├── .context.annotations.release → Cascaded from boundary hierarchy
├── .context.annotations.catalog → From Component metadata.annotations
├── .context.annotations.aggregate → Cascaded from subsystem hierarchy
└── feature_values_mapping → 5-Tier Onion Model normalized
Rendering begins. Provides evaluation — locals preamble, then provides
├── .context.rendered_name → Asked of each node's provider before the preamble; present only where
│ that provider derives a name for the node's output
├── .locals (per node) → Block resolved in author order; an entry reads earlier siblings
└── .provides (all nodes) → Self-contained templates evaluated (any order), reading .locals
Inject hydration — self-inject resolution
└── component.inject → value: literals expanded, from: own provides resolved
Inject hydration — uses-inject resolution
└── uses[].inject → from: target provides resolved
Inject mapping — injectMapping interception
└── .context.inject → Fully populated pipe, intercepted by FeatureRecipe injectMappings
Base rendering
└── Full template context → Everything available
The plugin pipeline — post-render mutation
└── Full template context + .steps → Inter-step pipeline outputs available

2. La matriz de expansión de plantillas

Cada ubicación del DSL donde se evalúan expresiones de plantilla Go, y exactamente qué referencias están disponibles:

#LocationEntidadEvaluado enReferencias disponibles
1{{ .parameters.X }} en cadenas YAML del AggregateAggregateResolución (interpolación)Solo .parameters. Todos los demás datos aún no están resueltos.
2{{ .parameters.X }} en cadenas YAML de la ReleaseReleaseNo evaluadoNinguna. Las cadenas de una Release se leen tal como están escritas: un {{ .parameters.X }} bajo infra:, en una anotación o como valor de parameters: llega a su destino como ese texto literal. La Release aporta los valores de los parámetros (el mapa parameters: en línea y los valores cargados con $import: combinados en el mapa de parámetros fusionado); las cadenas del Aggregate los leen (#1), y también las plantillas de ruta (#3).
3Plantillas directory / subDirectoryLímite de la ReleaseRenderizado (evaluación de rutas).capability, .boundary_name, .parameters.X, .manifest.recipe_name, .parent_boundary.* y .component_id (solo subDirectory: — una plantilla directory: lo rechaza).
4Cadenas value: de inject del ComponentComponente del AggregateResolución de self-inject.values, .infra, .context.instance_id, .context.labels, .context.annotations.* (los 3 contenedores), .metadata.* (release_name, release_version, environment, aggregate_name). PROHIBIDO: .context.inject (circular — la tubería se está construyendo), .context.uses (usa en su lugar uses[].inject para el cableado entre componentes). La plantilla está en el texto del Aggregate, que la interpolación de parámetros de #1 lee primero, así que escríbela escapada — value: '{{"{{"}} .metadata.release_name }}' — para que llegue a esta fase; escrita sin escapar, la interpolación la evalúa y se detiene, ya que el texto de un Aggregate no define ninguna raíz salvo .parameters.
5Cadenas del campo source (cadena de nivel superior O subcampos con valor de cadena de un mapa source: estructurado)Recipe / FeatureRecipeResolución de la fuenteDos superficies, decididas por lo que nombra la fuente. Una coordenada remota — los version, chart, ref y module_subdir de un bloque estructurado que nombra un registro, un repositorio de charts o un repositorio git — se evalúa cuando aggrega pull resuelve el artefacto para fijarlo: solo .values, .infra, .locals y cadenas estáticas, con los helpers propios de Aggrega (optional, capitalizedWords, index) y ninguna de las funciones de Sprig, y sin raíz .context. Las entradas de .locals evaluadas allí son las que leen esos campos, directamente o a través de otra entrada — todas las entradas cuando un campo lee .locals de una forma que no nombra ninguna entrada concreta —, de modo que una entrada que ningún campo lee se deja para el renderizado. Una fuente que nombra una ruta en el espacio de trabajo se evalúa cuando la entidad se renderiza: .context.instance_id, .values, .infra, .locals (todo el bloque resuelto de la entidad declarante), cadenas estáticas. Allí la fuente de una FeatureRecipe lee además .attachment_name — lo que se resuelve es una vinculación — y su .context.instance_id nombra el componente host, junto a .context.rendered_name, el nombre informado del componente host (consulta #9); una FeatureRecipe con ámbito de límite lee .boundary.* y ninguno de los pilares por componente. PROHIBIDO en ambas: .context.inject, .context.uses, .provides (invariante de autocontención — la superficie de fuente del espacio de trabajo comparte su contexto con los locals propios de la entidad declarante, así que ambas admiten y rechazan las mismas referencias, y una coordenada remota lee un subconjunto de ese contexto; la resolución de la fuente debe completarse antes de que la tubería de topología se hidrate y antes de que se cargue cualquier chart, módulo o cuerpo de artefacto).
6Plantillas provides de la RecipeRecipeEvaluación de provides.context.instance_id, .context.rendered_name (el nombre que el proveedor del nodo da a la salida que renderiza para el nodo — a partir de un origen que aportó el autor, o de un workload que sintetiza; leerlo en un nodo cuyo proveedor no informa ningún nombre de ese tipo provoca una detención — consulta Nombrar un recurso renderizado), .values, .infra, .locals (todo el bloque resuelto del nodo — los locals se resuelven en el preámbulo de esta fase, antes de provides), cadenas estáticas. PROHIBIDO: cualquier otra raíz — .context.inject, .context.uses (entre nodos), .context.annotations.*, .context.labels, .context.metadata, .metadata.* (ligado a ubicación/despliegue) y .attachment_name (no se resuelve ninguna vinculación durante la evaluación de provides de una Recipe base). La comprobación es una allowlist positiva: hacer referencia a cualquier raíz que el contexto de provides no expone provoca una detención (invariante de autocontención — permite la evaluación en paralelo sin ninguna ordenación topológica). Un .locals.<key> que nombra una clave que el bloque de locals no declara también provoca una detención, ya que el pilar es un mapa abierto con claves que la comprobación de raíz por sí sola no puede vigilar.
7valuesMapping de la Recipe (en línea, $import: de archivo o $import: de biblioteca)RecipeRenderizado baseContexto de plantilla completo: .values, .infra, .context.* (instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. Una referencia .context.rendered_name escrita en línea provoca una detención en un nodo cuyo proveedor no informa ningún nombre de ese tipo, como en #6; una dentro de un cuerpo cargado con $import: no se comprueba, y se renderiza vacía en un nodo así.
8injectMapping de la FeatureRecipeFeatureRecipeMapeo de injectContexto de plantilla completo: .values, .infra, .context.* (incluidos .context.inject — la tubería que se intercepta — y .context.uses). .context.used_by está vacío aquí: la salida del mapeo llega a la propia tubería de entrega del host. .context.render_facts está ausente: el mapeo se ejecuta antes de que el host se renderice. .context.rendered_name es el nombre informado del componente host, como en #9; un mapeo que lo lee no se comprueba, y lo renderiza vacío en un host cuyo proveedor no informa ninguno. El mismo contexto sea cual sea el executionScope de la FeatureRecipe: el mapeo de una FeatureRecipe con ámbito de límite se ejecuta una vez por cada componente al que llega la vinculación, lee el .context.* de ese componente, y lee .features.<attachment>.provides y .locals como la única evaluación del límite. PROHIBIDO: .boundary, que no lleva el contexto de ningún componente — una referencia detiene la compilación.
9valuesMapping de la FeatureRecipe (y sus workload: y artifacts:)FeatureRecipeRenderizado baseContexto de plantilla completo + .attachment_name, .inject (las entradas inject: propias de la vinculación, cuando la vinculación escribe un bloque inject:), .context.render_facts — lo que el proveedor del host informó sobre el renderizado del host — y .context.used_by — los componentes que usan el host, cada uno con sus propios hechos de renderizado cuando la FeatureRecipe establece readsCallerRenderFacts: true. Cada conexión en .context.uses lleva los hechos de renderizado de su destino, en .render_facts, cuando la FeatureRecipe establece readsTargetRenderFacts: true. .context.instance_id y .context.rendered_name son la identidad del componente host y el nombre que el propio proveedor del host informa para él — el mismo valor que lee la Recipe del host, también en los locals: y provides: de la FeatureRecipe — y una referencia a .context.rendered_name escrita en línea provoca una detención en un host cuyo proveedor no informa ningún nombre de ese tipo. .source es el source: evaluado propio de la FeatureRecipe, nunca el del componente host, y no contiene nada cuando la FeatureRecipe no declara ninguno.
10Bloques with: de la pipelineRecipe / FeatureRecipeLa pipeline de pluginsContexto de plantilla completo + .steps (salidas entre pasos procedentes de los pasos anteriores de la pipeline). .context.used_by está vacío aquí, y ninguna conexión en .context.uses lleva los hechos de renderizado de su destino: un paso puede reescribir los propios documentos del host. El paso de una FeatureRecipe vinculada lee .context.render_facts, los propios hechos de renderizado del host, como hace #9.
11Cuerpo workload: de la Recipe (cada campo con plantilla en su interior, ya sea en línea o cargado con $import:)RecipeRenderizado baseContexto de plantilla completo. Cada campo dentro del cuerpo del Workload — replicas, containers.<name>.image, containers.<name>.variables.<KEY>, containers.<name>.ports.<port>, services.<name>.ports.<port>, volumes.<name>.*, health.* — forma parte de la misma evaluación de plantilla que consume toda la cadena del Workload. El contenido del Workload es una única plantilla Go evaluada una sola vez con respecto al contexto de plantilla completo; las plantillas a nivel de campo en su interior se resuelven en la misma evaluación y no en una aparte.

Nota de autocontención. Las cadenas source (#5) comparten el invariante de autocontención de provides (#6): ambas superficies rechazan las referencias a .context.inject y .context.uses. La resolución de la fuente se ejecuta antes de la hidratación de inject que rellena .context.inject, y antes de que nada posterior consuma la fuente resuelta — así que la regla y su justificación valen para ambas superficies. En lo que difieren las dos es en el pilar provides: una source del espacio de trabajo comparte su contexto con los locals de la entidad declarante, y una coordenada remota lee un subconjunto de él, así que ambas rechazan .provides, mientras que provides es en sí la superficie que se está resolviendo. Ambas leen .locals. La regla alcanza la source de una FeatureRecipe en los mismos términos en que alcanza la de una Recipe, cada una comprobada con respecto a la propia superficie locals de esa entidad.

Nota sobre plantillas en el cuerpo del Workload (#11). El cuerpo del Workload es una única cadena con plantillas que el renderizador evalúa en su conjunto, para luego analizar el resultado como un documento Workload. Las plantillas a nivel de campo en su interior (un replicas: {{ .infra.replicas | default 1 }} aquí, un LOG_LEVEL: "{{ .values.log_level }}" dentro de containers.app.variables allá) no son puntos de evaluación de plantillas separados — todas participan en la única evaluación del renderizado base que produce el Workload. Los autores no necesitan una regla de disponibilidad aparte para los campos internos del Workload; la regla para el Workload en su conjunto (#11) cubre cada plantilla a nivel de campo en su interior.

Respaldo consciente del discriminante dentro del cuerpo del Workload. El ejemplo replicas: {{ .infra.replicas | default 1 }} de arriba confunde «el autor no estableció replicas» con «el autor estableció replicas en 0» — default se activa en ambos casos. Cuando una Release escribe legítimamente infra.replicas: 0 para expresar el escalado a cero (un patrón habitual de Knative / KEDA), la forma | default 1 anula silenciosamente la intención. La forma consciente del discriminante es replicas: {{ optional .infra "replicas" 1 }} — optional comprueba la presencia de la clave y devuelve el valor escrito (incluido un cero escrito) cuando la clave está establecida, y recurre a 1 solo cuando la clave está ausente. Consulta sprig-functions.md para la semántica completa y la orientación sobre cuándo preferirla.

3. Referencias prohibidas & justificación

LocationReferencia prohibidaJustificación
value: de inject del Component (#4).context.injectLa tubería de inject se está construyendo en ese momento — una plantilla value: de self-inject no puede leer de la tubería a la que contribuye.
value: de inject del Component (#4).context.usesEl cableado entre componentes está en uses[].inject. Las plantillas value: de self-inject de un componente permanecen cerradas sobre los propios datos del componente.
provides de la Recipe (#6).context.injectLas plantillas de provides se evalúan en cualquier orden y se cierran solo sobre los propios datos del nodo (.values, .infra, .locals, .context.instance_id, .context.rendered_name). La tubería de inject no se rellena hasta la hidratación de inject, que se ejecuta después de que se evalúan los provides de cada nodo.
provides de la Recipe (#6).attachment_nameLa pasada de provides de una Recipe base no resuelve ninguna vinculación, así que el nombre se renderizaría vacío. La raíz se rechaza en lugar de entregarse vacía.
source (#5).providesNinguna de las dos superficies de fuente lleva un pilar provides: la superficie de fuente del espacio de trabajo comparte su contexto con los locals propios de la entidad declarante, que no tiene ninguno, y una coordenada remota lee un subconjunto de ese contexto. Los locals se resuelven antes que los provides para que provides: pueda leer .locals; la plantilla de la fuente lee los mismos locals en lugar de volver atrás a buscar los provides.
locals de la Recipe (preámbulo de #6).providesLos locals se resuelven antes que los provides, así que los propios provides del nodo aún no existen cuando se evalúa un local. Un local que necesita un valor que los provides también publican lo calcula directamente a partir de .values / .infra — y la entrada provides lee luego el local.
locals de la Recipe (preámbulo de #6).context.rendered_nameLos locals de una Recipe comparten su contexto con su plantilla source (#5), y esa superficie no ofrece el nombre: si el nodo aporta un origen, algo que decide la plantilla source, es una de las cosas de las que depende el nombre. La referencia se detiene con el diagnóstico de raíz desconocida, que enumera .context.instance_id como lo que .context define allí. Lee en su lugar la clave en una entrada provides, o en una plantilla de la fase de renderizado base.
provides de la Recipe (#6).context.uses.context.uses hace referencia a los provides de otros nodos, y la evaluación de provides los ejecuta en orden arbitrario. Las plantillas de provides permanecen autocontenidas para que la evaluación siga siendo independiente del orden.
locals, provides, source (#5) de una FeatureRecipe y plantillas de renderizado en línea (#9, #10), en un host cuyo proveedor no informa ningún nombre.context.rendered_nameEn una vinculación de Feature la clave lleva el nombre informado del componente host, y un host que coloca un conjunto de artefactos por sí solo, o que se renderiza a través de un proveedor que no deriva ningún nombre de ese tipo, no tiene ninguno que llevar. La referencia se detiene con el diagnóstico de raíz desconocida, que enumera .context.instance_id entre lo que .context define allí; lee en su lugar la identidad, que es aquello según lo cual se nombran los propios recursos del host en un host así.
source (#5).context.injectLa resolución de la fuente se ejecuta antes de la hidratación de inject que rellena .context.inject. La tubería aún no está rellena cuando se evalúa la URI de la fuente.
source (#5).context.usesLa resolución de la fuente debe completarse antes de que nada posterior cargue el chart, el módulo o el cuerpo de artefacto de la entidad declarante. Permitir referencias entre nodos acoplaría la resolución de la fuente al orden de iteración de la topología, algo que evita deliberadamente.
Parámetros (en todas partes excepto en las plantillas de ruta)Cualquier superficie de plantilla de valor después de la interpolaciónLa interpolación consume cada referencia {{ .parameters.X }} del YAML escrito y escribe el valor resuelto en su lugar, de modo que una superficie de plantilla de valor recibe el literal resuelto en lugar del pilar de parámetros. Las plantillas de ruta escritas por el operador son la única excepción y leen .parameters.X directamente.

4. La ruta de resolución de self-inject

La resolución de self-inject es la primera mitad de la hidratación de inject, y se ejecuta después de que se hayan evaluado los provides de cada nodo. Cuando un componente declara un bloque inject: a nivel de componente, el compilador lo evalúa allí:

  1. Cadenas value: literales: si el valor contiene expresiones de plantilla Go, el compilador las evalúa con el contexto de la fila #4 de la matriz (.values, .infra, .context.instance_id, .metadata.*, etc.), escritas escapadas como muestra la fila #4. Las cadenas simples pasan sin cambios.
  2. Referencias from:: el compilador busca la clave en el propio diccionario provides del nodo, ya resuelto para entonces. Si la clave no existe, el compilador detiene la compilación con un error de clave de inject no válida.
  3. Comprobación de colisiones: antes de fusionar en la tubería .context.inject, el compilador verifica que ninguna clave colisione con las claves de uses-inject que resuelve la segunda mitad de la hidratación de inject. Las colisiones detienen la compilación con un error de clave de entrega duplicada.

Las cadenas resultantes se fusionan en .context.inject.env, .context.inject.file, .context.inject.arg (y cualquier mecanismo personalizado), junto a esas resoluciones de uses-inject. Para cuando se ejecuta el mapeo de inject (injectMapping), la tubería contiene todos los valores de inject escritos por el desarrollador procedentes de ambos orígenes.