Variables de las plantillas de ruta
Los campos directory: y subDirectory: de un límite de una Release son plantillas Go evaluadas en tiempo de compilación. Controlan dónde quedan en disco los artefactos renderizados y, por extensión, qué artefactos se ensamblan juntos — dos límites que se evalúan a la misma tupla (path, provider) comparten un ensamblador y producen una única salida fusionada (un Chart.yaml, un docker-compose.yaml). Esta página es la referencia de autoría para las variables a las que pueden hacer referencia esas plantillas, la semántica de evaluación estricta y las reglas de cascada que permiten a los límites heredar de sus padres.
Para el tratamiento conceptual de la separación espacial y del despacho por (path, provider), consulta architecture/16-recipe-input-composition.md. Para la superficie de autoría de la Release a nivel de entidad, consulta entities/release.md. Las consecuencias del lado del proveedor están en providers/architecture.md y en las páginas de cada proveedor.
Evaluación estricta: missingkey=error
Las plantillas de ruta se evalúan con el modo missingkey=error de Go. Una referencia a un campo no declarado, a una clave parameters.X no establecida o una errata como {{ .parmaeters.region }} produce un error explícito en lugar de renderizar silenciosamente una cadena vacía en una ruta.
Esta rigurosidad es asimétrica respecto al resto del compilador — valuesMapping, injectMapping y otras superficies de renderizado de valores usan missingkey=zero según la convención de Helm/Sprig. La emisión de rutas es estructuralmente distinta: una plantilla de renderizado de valores que produce una cadena vacía acaba en un campo de manifiesto, donde la consecuencia está acotada; una plantilla de ruta que produce una cadena vacía acaba en una estructura de directorios, donde la consecuencia no está acotada (colisiones, ensamblaje roto, rutas fantasma). El régimen estricto de las plantillas de ruta existe para que esos fallos salgan a la luz en tiempo de compilación y no en tiempo de despliegue.
Validación con lista de permitidos en tiempo de análisis
Además de la rigurosidad en tiempo de ejecución, las plantillas de ruta se validan en tiempo de análisis frente a una lista cerrada de nombres de variable permitidos. Una referencia a un nombre de variable que no está en la lista de permitidos detiene la compilación antes de que empiece cualquier trabajo de renderizado, con un diagnóstico que nombra el campo infractor y el límite en el que aparece.
La lista de permitidos es cerrada por diseño: superficies como .context.inject, .values y .locals no se exponen deliberadamente a las plantillas de ruta. La emisión de rutas es una cuestión estructural, no de renderizado de valores; vincular las rutas de ensamblaje a valores por componente haría que el grafo de rutas dependiera de los datos y erosionaría la invariante de salida determinista.
La matriz de variables
| Variable | directory: | subDirectory: | Descripción |
|---|---|---|---|
{{ .capability }} | sí | sí | La capacidad de renderizado (helm, helm-chart, compose, terraform, cloudformation) que declara la Recipe del componente contribuyente, para los artefactos que se emiten en esta ruta. |
{{ .boundary_name }} | sí | sí | El nombre escrito del límite en la Release (p. ej., production, eu-prod). |
{{ .parameters.X }} | sí | sí | Cualquier parámetro tipado declarado en el Aggregate y satisfecho por la Release. Acceso estricto — hacer referencia a .parameters.unknown detiene la compilación. |
{{ .manifest.recipe_name }} | sí | sí | El nombre de la Recipe resuelto a través del Manifest para el componente contribuyente. Útil para enrutar los artefactos de cada Recipe a subcarpetas por Recipe. |
{{ .parent_boundary.* }} | sí | sí | Acceso en cascada a los valores evaluados del límite que lo contiene. Consulta Cascada del límite padre más abajo. |
{{ .component_id }} | — | sí | El ID de instancia del componente que contribuye. Para una Feature asociada a una frontera cuya FeatureRecipe se ejecuta una sola vez para la frontera (executionScope: boundary), es la identidad compuesta que los recursos de esa asociación llevan en su etiqueta aggrega.ai/component-id — bfr--app--shared para una asociación shared en la frontera app, acortada allí donde el proveedor de la asociación limita los nombres — de modo que la salida de la asociación acaba en un directorio con el nombre de esa etiqueta. Disponible solo en subDirectory: porque directory: es una propiedad por frontera — la cadena del directorio se calcula una vez por frontera, antes de que ocurra cualquier enrutamiento por componente. |
El campo directory: toma por defecto boundaries/ seguido de la ruta del límite (un identificador estable en tiempo de compilación derivado del árbol de límites); una Release que enumera sus componentes sin declarar límites los escribe sin ningún segmento de directorio. El campo subDirectory: toma por defecto {{ .capability }}, de modo que los artefactos de cada capacidad quedan en su propia subcarpeta bajo el directorio del límite — tanto si se omite como si se escribe como subDirectory: "", que se lee exactamente igual que uno omitido. Establecer subDirectory: ".", o escribir una plantilla que se evalúe a una cadena vacía, aplana esa agrupación.
Lo que estas plantillas no deciden: la ubicación de artifacts:
Hay un segmento de la ruta de salida que no le corresponde fijar a una plantilla de ruta. Un archivo que nombra el bloque artifacts: de una Recipe se escribe bajo un directorio con el nombre del componente que lo declaró, dentro de aquello a lo que se evalúe subDirectory:. Ese segmento es fijo y siempre está presente, para un destino que escribe los archivos de sus contribuyentes uno junto a otro en lugar de anidar cada contribuyente en un chart o un módulo propio.
La razón es lo que da nombre al archivo. Un manifiesto que un destino renderiza o sintetiza recibe del destino el nombre del componente al que pertenece, así que ya identifica su componente. Un artefacto recibe el nombre de la clave que escribió su autor — app-config.yaml, netpol.yaml — y esa clave no dice nada del componente, porque la Recipe que lo declara no sabe qué componentes se enlazarán a ella. Dos componentes de un límite enlazados a una misma Recipe escribirían una única ruta, y ni el autor de la Recipe ni el autor de la Release tienen una superficie en la que separarlos.
Solo se añade el directorio; el nombre de archivo sigue siendo la clave escrita, así que el archivo que un autor vuelve a leer en la salida lleva el nombre que escribió.
Lo que subDirectory: sigue aportando, y cómo se combinan ambos. subDirectory: mueve cada archivo que emite un contribuyente — manifiestos renderizados, manifiestos sintetizados y artefactos juntos —, así que es la herramienta para dar a un componente un directorio propio para herramientas posteriores que operan sobre el conjunto completo de manifiestos de un único componente, o para enrutar varios componentes a una carpeta compartida. El segmento de artifacts: se aplica por debajo de aquello a lo que se evalúe. Escribir subDirectory: "{{ .capability }}/{{ .component_id }}" en un componente cuya Recipe declara artifacts: produce, por tanto, el nombre del componente dos veces — el artefacto queda en <capability>/<component>/<component>/<key> mientras que los manifiestos renderizados de ese componente quedan en <capability>/<component>/<key>. Recurre a la sobrescritura cuando quieras reunir la salida completa del componente, y prescinde de ella cuando solo necesites separar los artefactos, cosa que ya hace el valor por defecto.
.capability se resuelve por componente, y el directory: de un límite se evalúa con dos propósitos distintos. La evaluación por límite que publica .parent_boundary.directory a los límites hijos se ejecuta antes de que se enlace cualquier componente, así que .capability está vacío allí. La evaluación por componente que fija dónde quedan realmente los artefactos de un contribuyente lleva la capacidad de ese componente. Un padre que escribe directory: "d-{{ .capability }}" publica, por tanto, d- cascada abajo, mientras que sus propios artefactos quedan bajo d-compose.
Cascada del límite padre
Los límites anidados reciben una vista .parent_boundary que expone la ruta evaluada del límite padre inmediato y sus propios datos resueltos en cascada. La cascada es de un nivel — el .parent_boundary de un límite es su padre directo, no el abuelo. Para llegar más arriba, el propio límite padre usa .parent_boundary en sus propias plantillas, propagando los valores árbol abajo de forma explícita.
Campos disponibles bajo .parent_boundary:
| Campo | Descripción |
|---|---|
.parent_boundary.directory | El valor evaluado de directory: del límite padre (tras la plantilla). |
.parent_boundary.boundary_name | El nombre escrito del límite padre. |
.parent_boundary.parameters | El mismo mapa .parameters.* que vio el límite padre (los valores de los parámetros son globales de la Release, pero el alias se proporciona por simetría). |
.parent_boundary.annotations | Las anotaciones resueltas en cascada del límite padre. |
El patrón canónico: un límite padre que escribe un directory: una vez, más límites hijos que enrutan sus artefactos bajo el padre declarando directory: "{{ .parent_boundary.directory }}". Esto hace converger a los hijos en la ruta de ensamblaje del padre, produciendo una única salida fusionada que contiene contribuyentes de cada hijo. La Feature core/compose-bridge se basa exactamente en esto: un límite padre que contiene la funcionalidad bridge, dos límites hijos (por ejemplo services-net y data-net) que comparten el directory: del padre, y un único docker-compose.yaml fusionado que contiene cada componente más el servicio bridge.
El caso inverso: omite .parent_boundary.directory en los hijos (o haz que se evalúen a una ruta distinta) y cada hijo obtiene su propio ensamblaje. Ambas formas son igual de válidas.
Ejemplos de disposiciones
Disposición 1 — separación predeterminada por límite
spec: boundaries: api-prod: directory: "deploy/api-prod" components: api: {} cache: {} data-prod: directory: "deploy/data-prod" components: db: {}Cada límite se evalúa a un directory: distinto, así que cada uno obtiene su propio ensamblaje:
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...El valor por defecto subDirectory: "{{ .capability }}" separa los artefactos por capacidad dentro del directorio de cada límite. Dos límites, dos salidas de ensamblaje por capacidad, sin fusión.
Disposición 2 — ensamblaje unificado mediante un directorio padre compartido
spec: boundaries: cluster: directory: "deploy/cluster" annotations: aggrega.ai/chart-name: "cluster-umbrella" features: bridge: type: core/compose-bridge:1.0.0 boundaries: services-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: services } components: api: {} data-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: data } components: db: {}Ambos límites hijos evalúan directory: a deploy/cluster (el directorio del padre), así que todos los contribuyentes se fusionan en una única ruta de ensamblaje. Con el valor por defecto subDirectory: "{{ .capability }}", los contribuyentes compose de ambos hijos quedan en deploy/cluster/compose/ y producen un único docker-compose.yaml fusionado. La Feature compose-bridge vinculada al padre se ejecuta una sola vez (despacho con ámbito de límite) y aporta el servicio bridge al mismo archivo fusionado.
La anotación aggrega.ai/chart-name: "cluster-umbrella" del padre se propaga en cascada a ambos hijos; si los límites también contuvieran contribuyentes helm-chart, los subcharts helm-chart de ambos hijos se compondrían bajo un único umbrella llamado cluster-umbrella. Valores de chart-name discordantes entre contribuyentes de una misma ruta detienen la compilación.
Disposición 3 — enrutamiento por componente mediante subDirectory: más parámetros
spec: parameters: region: "eu-west-1" boundaries: eu-prod: directory: "deploy/{{ .parameters.region }}" components: api: subDirectory: "{{ .capability }}/{{ .component_id }}" db: subDirectory: "{{ .capability }}/{{ .component_id }}" ingress: subDirectory: "shared"El directory: del límite se evalúa a deploy/eu-west-1 (sustitución de parámetros). Las sobrescrituras de subDirectory: por componente enrutan cada contribuyente a una subcarpeta por componente, con el componente ingress sobrescribiendo hacia una subcarpeta plana shared para artefactos transversales:
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...Este patrón encaja con empresas que quieren directorios de artefactos por componente para herramientas posteriores que operan sobre los manifiestos de un único componente. Cuando la Recipe de un componente también declara artifacts:, lee Lo que estas plantillas no deciden más arriba antes de elegir esta forma: esos archivos ya llevan un segmento de componente, así que esta sobrescritura añade un segundo.
Diagnósticos
La superficie de las plantillas de ruta detiene la compilación en cada una de las situaciones siguientes, y errors/fatal-halts.md las documenta con estos nombres. Esa página cita el mensaje que emite cada detención; compara la salida de la compilación con ese texto.
- Path-template references a variable outside the allowlist (La plantilla de ruta hace referencia a una variable fuera de la lista de permitidos) — en tiempo de análisis: una plantilla de ruta hace referencia a una variable que no está en la lista de permitidos.
- Path collision (Colisión de rutas) — en tiempo de ensamblaje: dos contribuyentes de límite se evalúan a la misma ruta pero discrepan en una propiedad que debe ser uniforme entre los contribuyentes de esa ruta.
- Instance-ID collision (Colisión de ID de instancia) — en tiempo de ensamblaje: dos límites que se evalúan a la misma tupla
(path, provider)aportan componentes con ID de instancia idénticos. - Chart-name mismatch (Nombre de chart discordante) — en tiempo de ensamblaje: un ensamblaje helm-chart fusionado recibe contribuyentes con anotaciones
aggrega.ai/chart-nameresueltas en cascada que entran en conflicto. - Missing template key (Clave de plantilla ausente) — una plantilla de ruta hace referencia a un campo bajo una variable abierta que no se resuelve en ningún valor (p. ej.,
{{ .parameters.region }}cuando la Release omiteregion, o una clave de.parent_boundaryen un límite de nivel superior que no tiene padre);missingkey=errorproduce un mensaje explícito que nombra el límite, el campo de la plantilla (directory:osubDirectory:) y la clave faltante..parametersy.parent_boundaryson abiertas — sus claves son datos escritos por el autor —, mientras que.manifestdeclara sus claves, así que una clave mal escrita bajo.manifestse rechaza en cambio en tiempo de análisis como referencia desconocida, con el diagnóstico enumerando las claves que.manifestdefine.
Referencias cruzadas
entities/release.md— autoría de la Release, incluida la separación espacial y los camposdirectory:/subDirectory:.providers/architecture.md— despacho a los proveedores y el modelo de ensamblaje por(path, provider).providers/compose.md— salida del lado de compose por(path, provider), incluido el escenario de ruta fusionada.providers/helm-chart.md— composición umbrella de helm-chart y la regla de cascada del chart-name para rutas fusionadas.entities/featurerecipe.md— FeatureRecipes con ámbito de límite (la Featurecore/compose-bridgese basa en el modelo de ensamblaje de ruta fusionada documentado aquí).errors/fatal-halts.md— catálogo completo de diagnósticos, incluidas las detenciones del despacho de rutas enumeradas arriba.