Matrice d’expansion des templates
Référence de l’expansion des templates — la matrice complète
Le DSL d’Aggrega prend en charge l’expansion text/template de Go (avec la bibliothèque Sprig préenregistrée) à plusieurs emplacements des entités YAML. Chaque emplacement dispose d’un ensemble spécifique de références disponibles, déterminé par le moment où les données deviennent concrètes au fil de la compilation. Cette page est la référence de ce qui peut être référencé et où.
1. L’arbre chronologique du pipeline (quand les données deviennent concrètes)
Comprendre quelles références sont disponibles nécessite de comprendre quand chaque donnée est résolue. Les phases ci-dessous sont listées dans l’ordre dans lequel elles s’exécutent, et chacune porte le nom de ce qu’elle fait — c’est sous ce nom que le reste de cette page y fait référence :
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 available2. La matrice d’expansion des templates
Chaque emplacement du DSL où des expressions de template Go sont évaluées, et exactement quelles références sont disponibles :
| # | Location | Entité | Évalué dans | Références disponibles |
|---|---|---|---|---|
| 1 | {{ .parameters.X }} dans les chaînes YAML de l’Aggregate | Aggregate | Résolution (interpolation) | .parameters uniquement. Toutes les autres données ne sont pas encore résolues. |
| 2 | {{ .parameters.X }} dans les chaînes YAML de la Release | Release | Non évalué | Aucune. Les chaînes d’une Release sont lues telles qu’elles sont écrites : un {{ .parameters.X }} sous infra:, dans une annotation ou comme valeur de parameters: atteint sa destination sous la forme de ce texte littéral. La Release fournit les valeurs des paramètres (la map parameters: en ligne et les valeurs chargées par $import: combinées dans la map de paramètres fusionnée) ; les chaînes de l’Aggregate les lisent (#1), tout comme les templates de chemin (#3). |
| 3 | Templates directory / subDirectory | Frontière de la Release | Rendu (évaluation des chemins) | .capability, .boundary_name, .parameters.X, .manifest.recipe_name, .parent_boundary.* et .component_id (subDirectory: uniquement — un template directory: le refuse). |
| 4 | Chaînes value: de inject du Component | Composant de l’Aggregate | Résolution de self-inject | .values, .infra, .context.instance_id, .context.labels, .context.annotations.* (les 3 compartiments), .metadata.* (release_name, release_version, environment, aggregate_name). INTERDIT : .context.inject (circulaire — le pipe est en cours de construction), .context.uses (utilisez plutôt uses[].inject pour le câblage entre composants). Le template se trouve dans le texte de l’Aggregate, que l’interpolation des paramètres de #1 lit en premier, écrivez-le donc échappé — value: '{{"{{"}} .metadata.release_name }}' — pour qu’il atteigne cette phase ; écrit tel quel, l’interpolation l’évalue et s’arrête, puisque le texte d’un Aggregate ne définit aucune racine hormis .parameters. |
| 5 | Chaînes du champ source (chaîne de premier niveau OU sous-champs à valeur chaîne d’une map source: structurée) | Recipe / FeatureRecipe | Résolution de la source | Deux surfaces, déterminées par ce que nomme la source. Une coordonnée distante — les version, chart, ref et module_subdir d’un bloc structuré nommant un registre, un dépôt de charts ou un dépôt git — est évaluée lorsque aggrega pull résout l’artefact pour l’épingler : .values, .infra, .locals et chaînes statiques uniquement, avec les helpers propres d’Aggrega (optional, capitalizedWords, index) et aucune des fonctions de Sprig, et sans racine .context. Les entrées de .locals évaluées à cet endroit sont celles que lisent ces champs, directement ou par une autre entrée — toutes les entrées lorsqu’un champ lit .locals d’une façon qui ne nomme aucune entrée en particulier —, de sorte qu’une entrée qu’aucun champ ne lit est laissée au rendu. Une source nommant un chemin dans l’espace de travail est évaluée pendant le rendu de l’entité : .context.instance_id, .values, .infra, .locals (l’ensemble du bloc résolu de l’entité déclarante), chaînes statiques. Là, la source d’une FeatureRecipe lit en outre .attachment_name — c’est un rattachement qui est résolu — et son .context.instance_id nomme le composant hôte, à côté de .context.rendered_name, le nom rapporté du composant hôte (voir #9) ; une FeatureRecipe de portée frontière lit .boundary.* et aucun des piliers par composant. INTERDIT sur les deux : .context.inject, .context.uses, .provides (invariant d’autonomie — la surface de source de l’espace de travail partage son contexte avec les propres locals de l’entité déclarante, de sorte que les deux admettent et refusent les mêmes références, et une coordonnée distante lit un sous-ensemble de ce contexte ; la résolution de la source doit être terminée avant que le pipe de topologie soit hydraté et avant que tout chart, module ou corps d’artefact soit chargé). |
| 6 | Templates provides de la Recipe | Recipe | Évaluation des provides | .context.instance_id, .context.rendered_name (le nom que le fournisseur du nœud donne à la sortie qu’il rend pour le nœud — à partir d’une source fournie par l’auteur, ou d’un workload qu’il synthétise ; le lire sur un nœud dont le fournisseur ne rapporte aucun nom de ce type provoque un arrêt — voir Nommer une ressource rendue), .values, .infra, .locals (l’ensemble du bloc résolu du nœud — les locals se résolvent dans le préambule de cette phase, avant les provides), chaînes statiques. INTERDIT : toute autre racine — .context.inject, .context.uses (entre nœuds), .context.annotations.*, .context.labels, .context.metadata, .metadata.* (lié au placement/déploiement) et .attachment_name (aucun rattachement n’est résolu pendant l’évaluation des provides d’une Recipe de base). La vérification est une allowlist positive : référencer toute racine que le contexte des provides n’expose pas provoque un arrêt (invariant d’autonomie — permet l’évaluation parallèle sans aucun tri topologique). Un .locals.<key> nommant une clé que le bloc des locals ne déclare pas provoque aussi un arrêt, puisque le pilier est une map à clés ouverte que la seule vérification des racines ne peut pas contrôler. |
| 7 | valuesMapping de la Recipe (en ligne, $import: de fichier ou $import: de bibliothèque) | Recipe | Rendu de base | Contexte de template complet : .values, .infra, .context.* (instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. Une référence .context.rendered_name écrite en ligne provoque un arrêt sur un nœud dont le fournisseur ne rapporte aucun nom de ce type, comme en #6 ; une référence à l’intérieur d’un corps chargé par $import: n’est pas vérifiée et produit un rendu vide sur un tel nœud. |
| 8 | injectMapping de la FeatureRecipe | FeatureRecipe | Mapping d’inject | Contexte de template complet : .values, .infra, .context.* (y compris .context.inject — le pipe en cours d’interception — et .context.uses). .context.used_by est vide ici : la sortie du mapping aboutit sur le propre pipe de livraison de l’hôte. .context.render_facts est absent : le mapping s’exécute avant le rendu de l’hôte. .context.rendered_name est le nom rapporté du composant hôte, comme en #9 ; un mapping qui le lit n’est pas vérifié, et le rend vide sur un hôte dont le fournisseur n’en rapporte aucun. Le même contexte quel que soit le executionScope de la FeatureRecipe : le mapping d’une FeatureRecipe de portée frontière s’exécute une fois pour chaque composant qu’atteint le rattachement, lit le .context.* de ce composant, et lit .features.<attachment>.provides et .locals comme l’unique évaluation de la frontière. INTERDIT : .boundary, que le contexte d’aucun composant ne porte — une référence arrête le build. |
| 9 | valuesMapping de la FeatureRecipe (et ses workload: et artifacts:) | FeatureRecipe | Rendu de base | Contexte de template complet + .attachment_name, .inject (les propres entrées inject: du rattachement, lorsque le rattachement rédige un bloc inject:), .context.render_facts — ce que le fournisseur de l’hôte a rapporté au sujet du rendu de l’hôte — et .context.used_by — les composants qui utilisent l’hôte, chacun portant ses propres faits de rendu lorsque la FeatureRecipe définit readsCallerRenderFacts: true. Chaque connexion sur .context.uses porte les faits de rendu de sa cible, à .render_facts, lorsque la FeatureRecipe définit readsTargetRenderFacts: true. .context.instance_id et .context.rendered_name sont l’identité du composant hôte et le nom que le propre fournisseur de l’hôte rapporte pour lui — la même valeur que lit la Recipe de l’hôte, sur les locals: et provides: de la FeatureRecipe aussi — et une référence à .context.rendered_name écrite en ligne provoque un arrêt sur un hôte dont le fournisseur ne rapporte aucun nom de ce type. .source est le propre source: évalué de la FeatureRecipe, jamais celui du composant hôte, et ne contient rien lorsque la FeatureRecipe n’en déclare aucun. |
| 10 | Blocs with: du pipeline | Recipe / FeatureRecipe | Le pipeline de plugins | Contexte de template complet + .steps (sorties entre étapes provenant des étapes précédentes du pipeline). .context.used_by est vide ici, et aucune connexion sur .context.uses ne porte les faits de rendu de sa cible : une étape peut réécrire les propres documents de l’hôte. L’étape d’une FeatureRecipe rattachée lit .context.render_facts, les propres faits de rendu de l’hôte, comme le fait #9. |
| 11 | Corps workload: de la Recipe (chaque champ templaté à l’intérieur, qu’il soit en ligne ou chargé par $import:) | Recipe | Rendu de base | Contexte de template complet. Chaque champ à l’intérieur du corps du Workload — replicas, containers.<name>.image, containers.<name>.variables.<KEY>, containers.<name>.ports.<port>, services.<name>.ports.<port>, volumes.<name>.*, health.* — fait partie de la même évaluation de template qui consomme toute la chaîne du Workload. Le contenu du Workload est un template Go unique évalué une seule fois par rapport au contexte de template complet ; les templates au niveau des champs à l’intérieur se résolvent dans la même évaluation plutôt que dans une évaluation distincte. |
Note sur l’autonomie. Les chaînes source (#5) partagent l’invariant d’autonomie de provides (#6) : les deux surfaces rejettent les références à .context.inject et .context.uses. La résolution de la source s’exécute avant l’hydratation d’inject qui renseigne .context.inject, et avant que quoi que ce soit en aval ne consomme la source résolue — la règle et sa justification valent donc pour les deux surfaces. Là où les deux diffèrent, c’est sur le pilier provides : une source de l’espace de travail partage son contexte avec les locals de l’entité déclarante, et une coordonnée distante en lit un sous-ensemble, de sorte que les deux refusent .provides, tandis que provides est lui-même la surface en cours de résolution. Les deux lisent .locals. La règle atteint la source d’une FeatureRecipe dans les mêmes conditions que celle d’une Recipe, chacune vérifiée par rapport à la propre surface locals de cette entité.
Note sur les templates du corps du Workload (#11). Le corps du Workload est une chaîne templatée unique que le moteur de rendu évalue dans son ensemble, avant d’analyser le résultat comme un document Workload. Les templates au niveau des champs à l’intérieur (un replicas: {{ .infra.replicas | default 1 }} ici, un LOG_LEVEL: "{{ .values.log_level }}" dans containers.app.variables là) ne sont pas des emplacements d’évaluation de template distincts — ils participent tous à l’unique évaluation du rendu de base qui produit le Workload. Les auteurs n’ont pas besoin d’une règle de disponibilité distincte pour les champs internes au Workload ; la règle pour le Workload dans son ensemble (#11) couvre chaque template au niveau des champs à l’intérieur.
Repli tenant compte du discriminant à l’intérieur du corps du Workload. L’exemple replicas: {{ .infra.replicas | default 1 }} ci-dessus confond « l’auteur n’a pas défini replicas » avec « l’auteur a défini replicas à 0 » — default se déclenche dans les deux cas. Lorsqu’une Release rédige légitimement infra.replicas: 0 pour exprimer le scale-to-zero (un pattern Knative / KEDA courant), la forme | default 1 remplace silencieusement l’intention. La forme tenant compte du discriminant est replicas: {{ optional .infra "replicas" 1 }} — optional vérifie la présence de la clé et renvoie la valeur rédigée (zéro rédigé compris) lorsque la clé est définie, en ne se rabattant sur 1 que lorsque la clé est absente. Voir sprig-functions.md pour la sémantique complète et les indications sur quand la préférer.
3. Références interdites & justification
| Location | Référence interdite | Justification |
|---|---|---|
value: de inject du Component (#4) | .context.inject | Le pipe d’inject est en cours de construction à ce stade — un template value: de self-inject ne peut pas lire depuis le pipe auquel il contribue. |
value: de inject du Component (#4) | .context.uses | Le câblage entre composants se trouve dans uses[].inject. Les templates value: de self-inject d’un composant restent fermés sur les propres données du composant. |
provides de la Recipe (#6) | .context.inject | Les templates de provides sont évalués dans n’importe quel ordre et ne se ferment que sur les propres données du nœud (.values, .infra, .locals, .context.instance_id, .context.rendered_name). Le pipe d’inject n’est pas renseigné avant l’hydratation d’inject, qui s’exécute après l’évaluation des provides de chaque nœud. |
provides de la Recipe (#6) | .attachment_name | Le passage des provides d’une Recipe de base ne résout aucun rattachement, de sorte que le nom serait rendu vide. La racine est refusée plutôt que livrée vide. |
source (#5) | .provides | Aucune des deux surfaces de source ne porte de pilier provides : la surface de source de l’espace de travail partage son contexte avec les propres locals de l’entité déclarante, qui n’en a pas, et une coordonnée distante lit un sous-ensemble de ce contexte. Les locals se résolvent avant les provides afin que provides: puisse lire .locals ; le template de source lit les mêmes locals plutôt que de remonter jusqu’aux provides. |
locals de la Recipe (préambule de #6) | .provides | Les locals se résolvent avant les provides, de sorte que les propres provides du nœud n’existent pas encore lorsqu’un local est évalué. Un local qui a besoin d’une valeur que les provides publient aussi la calcule directement à partir de .values / .infra — et l’entrée provides lit ensuite le local. |
locals de la Recipe (préambule de #6) | .context.rendered_name | Les locals d’une Recipe partagent leur contexte avec son template source (#5), et cette surface n’offre pas le nom : le fait que le nœud fournisse une source, ce que décide le template source, est l’une des choses dont dépend le nom. La référence s’arrête avec le diagnostic de racine inconnue, qui liste .context.instance_id comme ce que .context y définit. Lisez plutôt la clé dans une entrée provides, ou dans un template de la phase de rendu de base. |
provides de la Recipe (#6) | .context.uses | .context.uses fait référence aux provides d’autres nœuds, et l’évaluation des provides les exécute dans un ordre arbitraire. Les templates de provides restent autonomes afin que l’évaluation reste indépendante de l’ordre. |
locals, provides, source (#5) d’une FeatureRecipe et templates de rendu en ligne (#9, #10), sur un hôte dont le fournisseur ne rapporte aucun nom | .context.rendered_name | Sur un rattachement de Feature, la clé porte le nom rapporté du composant hôte, et un hôte qui place seul un ensemble d’artefacts, ou qui effectue son rendu au moyen d’un fournisseur qui ne dérive aucun nom de ce type, n’en a aucun à porter. La référence s’arrête avec le diagnostic de racine inconnue, qui liste .context.instance_id parmi ce que .context y définit ; lisez plutôt l’identité, qui est ce d’après quoi sont nommées les propres ressources de l’hôte sur un tel hôte. |
source (#5) | .context.inject | La résolution de la source s’exécute avant l’hydratation d’inject qui renseigne .context.inject. Le pipe n’est pas encore renseigné lorsque l’URI de la source est évaluée. |
source (#5) | .context.uses | La résolution de la source doit être terminée avant que quoi que ce soit en aval ne charge le chart, le module ou le corps d’artefact de l’entité déclarante. Autoriser des références entre nœuds couplerait la résolution de la source à l’ordre d’itération de la topologie, ce qu’elle évite délibérément. |
| Paramètres (partout sauf dans les templates de chemin) | Toute surface de template de valeur après l’interpolation | L’interpolation consomme chaque référence {{ .parameters.X }} dans le YAML rédigé et écrit la valeur résolue à sa place, de sorte qu’une surface de template de valeur reçoit le littéral résolu plutôt que le pilier des paramètres. Les templates de chemin rédigés par l’opérateur sont la seule exception et lisent .parameters.X directement. |
4. Le chemin de résolution de self-inject
La résolution de self-inject est la première moitié de l’hydratation d’inject, et elle s’exécute après l’évaluation des provides de chaque nœud. Lorsqu’un composant déclare un bloc inject: au niveau du composant, le compilateur l’évalue à ce moment-là :
- Chaînes
value:littérales : si la valeur contient des expressions de template Go, le compilateur les évalue avec le contexte de la ligne #4 de la matrice (.values,.infra,.context.instance_id,.metadata.*, etc.), écrites échappées comme le montre la ligne #4. Les chaînes simples passent inchangées. - Références
from:: le compilateur recherche la clé dans le propre dictionnaireprovidesdu nœud, déjà résolu à ce stade. Si la clé n’existe pas, le compilateur arrête le build avec une erreur de clé d’inject invalide. - Vérification des collisions : avant la fusion dans le pipe
.context.inject, le compilateur vérifie qu’aucune clé n’entre en collision avec les clés de uses-inject que résout la seconde moitié de l’hydratation d’inject. Les collisions arrêtent le build avec une erreur de clé de livraison en double.
Les chaînes obtenues sont fusionnées dans .context.inject.env, .context.inject.file, .context.inject.arg (et tout mécanisme personnalisé), à côté de ces résolutions de uses-inject. Au moment où le mapping d’inject (injectMapping) s’exécute, le pipe contient toutes les valeurs d’inject rédigées par le développeur issues des deux origines.