Variables des modèles de chemin
Les champs directory: et subDirectory: d’une frontière de Release sont des modèles Go évalués au moment du build. Ils contrôlent où les artefacts rendus arrivent sur le disque et, par extension, quels artefacts sont assemblés ensemble — deux frontières qui s’évaluent au même tuple (path, provider) partagent un assembleur et produisent une seule sortie fusionnée (un Chart.yaml, un docker-compose.yaml). Cette page est la référence de rédaction pour les variables que ces modèles peuvent référencer, la sémantique d’évaluation stricte et les règles de cascade qui permettent aux frontières d’hériter de leurs parents.
Pour le traitement conceptuel de la séparation spatiale et de la répartition par (path, provider), voir architecture/16-recipe-input-composition.md. Pour la surface de rédaction de la Release au niveau de l’entité, voir entities/release.md. Les conséquences côté fournisseur se trouvent dans providers/architecture.md et dans les pages de chaque fournisseur.
Évaluation stricte : missingkey=error
Les modèles de chemin sont évalués avec le mode missingkey=error de Go. Une référence à un champ non déclaré, à une clé parameters.X non définie ou une faute de frappe comme {{ .parmaeters.region }} produit une erreur explicite au lieu de rendre silencieusement une chaîne vide dans un chemin.
Cette rigueur est asymétrique par rapport au reste du compilateur — valuesMapping, injectMapping et les autres surfaces de rendu de valeurs utilisent missingkey=zero selon la convention de Helm/Sprig. L’émission de chemins est structurellement différente : un modèle de rendu de valeurs qui produit une chaîne vide arrive dans un champ de manifeste, où la conséquence est bornée ; un modèle de chemin qui produit une chaîne vide arrive dans une arborescence de répertoires, où la conséquence n’est pas bornée (collisions, assemblage cassé, chemins fantômes). Le régime strict des modèles de chemin existe pour faire apparaître ces échecs au moment du build plutôt qu’au moment du déploiement.
Validation par liste d’autorisation à l’analyse
En plus de la rigueur à l’exécution, les modèles de chemin sont validés à l’analyse par rapport à une liste d’autorisation fermée de noms de variables. Une référence à un nom de variable absent de la liste d’autorisation arrête le build avant que tout travail de rendu ne commence, avec un diagnostic nommant le champ fautif et la frontière sur laquelle il apparaît.
La liste d’autorisation est fermée à dessein : des surfaces telles que .context.inject, .values et .locals ne sont délibérément pas exposées aux modèles de chemin. L’émission de chemins est une préoccupation structurelle, et non une préoccupation de rendu de valeurs ; lier les chemins d’assemblage à des valeurs par composant rendrait le graphe des chemins dépendant des données et éroderait l’invariant de sortie déterministe.
La matrice des variables
| Variable | directory: | subDirectory: | Description |
|---|---|---|---|
{{ .capability }} | oui | oui | La capacité de rendu (helm, helm-chart, compose, terraform, cloudformation) que déclare la Recipe du composant contributeur, pour les artefacts émis à ce chemin. |
{{ .boundary_name }} | oui | oui | Le nom écrit de la frontière dans la Release (par ex. production, eu-prod). |
{{ .parameters.X }} | oui | oui | Tout paramètre typé déclaré sur l’Aggregate et satisfait par la Release. Accès strict — référencer .parameters.unknown arrête le build. |
{{ .manifest.recipe_name }} | oui | oui | Le nom de la Recipe résolu via le Manifest pour le composant contributeur. Utile pour router les artefacts propres à chaque Recipe dans des sous-dossiers par Recipe. |
{{ .parent_boundary.* }} | oui | oui | Accès en cascade aux valeurs évaluées de la frontière englobante. Voir Cascade de la frontière parente ci-dessous. |
{{ .component_id }} | — | oui | L’identifiant d’instance du composant contributeur. Pour une Feature attachée à une frontière dont la FeatureRecipe s’exécute une seule fois pour la frontière (executionScope: boundary), il s’agit de l’identité composée que les ressources de cet attachement portent dans leur label aggrega.ai/component-id — bfr--app--shared pour un attachement shared à la frontière app, raccourcie là où le fournisseur de l’attachement limite les noms — si bien que la sortie de l’attachement aboutit dans un répertoire nommé d’après ce label. Disponible uniquement dans subDirectory: car directory: est une propriété par frontière — la chaîne du répertoire est calculée une fois par frontière, avant tout routage par composant. |
Le champ directory: vaut par défaut boundaries/ suivi du chemin de la frontière (un identifiant stable au moment du build, dérivé de l’arbre des frontières) ; une Release qui liste ses composants sans déclarer de frontières les écrit sans aucun segment de répertoire. Le champ subDirectory: vaut par défaut {{ .capability }}, si bien que les artefacts de chaque capacité arrivent dans leur propre sous-dossier sous le répertoire de la frontière — qu’il soit omis ou écrit subDirectory: "", qui se lit exactement comme un champ omis. Définir subDirectory: ".", ou écrire un modèle qui s’évalue en chaîne vide, aplatit ce regroupement.
Ce que ces modèles ne décident pas : le placement de artifacts:
Un segment du chemin de sortie n’est pas du ressort d’un modèle de chemin. Un fichier que nomme le bloc artifacts: d’une Recipe est écrit sous un répertoire nommé d’après le composant qui l’a déclaré, à l’intérieur de ce en quoi subDirectory: s’évalue. Ce segment est fixe et toujours présent, pour une cible qui écrit les fichiers de ses contributeurs côte à côte plutôt que d’imbriquer chaque contributeur dans un chart ou un module qui lui est propre.
La raison tient à ce qui nomme le fichier. Un manifeste qu’une cible rend ou synthétise est nommé par la cible d’après le composant auquel il appartient, si bien qu’il identifie déjà son composant. Un artefact est nommé d’après la clé que son auteur a écrite — app-config.yaml, netpol.yaml — et cette clé ne dit rien du composant, car la Recipe qui le déclare ne sait pas quels composants lui seront liés. Deux composants d’une même frontière liés à une même Recipe écriraient un seul chemin, et ni l’auteur de la Recipe ni l’auteur de la Release ne disposent d’une surface sur laquelle les séparer.
Seul le répertoire est ajouté ; le nom de fichier reste la clé écrite, si bien que le fichier qu’un auteur relit dans la sortie porte le nom qu’il a écrit.
Ce que subDirectory: apporte encore, et comment les deux se combinent. subDirectory: déplace chaque fichier qu’un contributeur émet — manifestes rendus, manifestes synthétisés et artefacts ensemble — c’est donc l’outil pour donner à un composant son propre répertoire pour un outillage en aval qui opère sur l’ensemble des manifestes d’un seul composant, ou pour router plusieurs composants dans un dossier partagé. Le segment de artifacts: s’applique en dessous de ce en quoi il s’évalue. Écrire subDirectory: "{{ .capability }}/{{ .component_id }}" sur un composant dont la Recipe déclare artifacts: produit donc le nom du composant deux fois — l’artefact arrive à <capability>/<component>/<component>/<key> tandis que les manifestes rendus de ce composant arrivent à <capability>/<component>/<key>. Recourez au remplacement lorsque vous voulez regrouper la sortie entière du composant, et laissez-le de côté lorsque séparer les artefacts suffit, ce que fait déjà la valeur par défaut.
.capability est résolu par composant, et la directory: d’une frontière est évaluée à deux fins distinctes. L’évaluation par frontière qui publie .parent_boundary.directory vers les frontières enfants s’exécute avant qu’aucun composant ne soit lié, si bien que .capability y est vide. L’évaluation par composant qui fixe où les artefacts d’un contributeur arrivent réellement porte la capacité de ce composant. Un parent qui écrit directory: "d-{{ .capability }}" publie donc d- le long de la cascade, tandis que ses propres artefacts arrivent sous d-compose.
Cascade de la frontière parente
Les frontières imbriquées reçoivent une vue .parent_boundary qui expose le chemin évalué de la frontière parente immédiate et ses propres données résolues en cascade. La cascade porte sur un seul niveau — le .parent_boundary d’une frontière est son parent direct, pas son grand-parent. Pour remonter plus haut, la frontière parente utilise elle-même .parent_boundary dans ses propres modèles, propageant explicitement les valeurs vers le bas de l’arbre.
Champs disponibles sous .parent_boundary :
| Champ | Description |
|---|---|
.parent_boundary.directory | La valeur évaluée de directory: de la frontière parente (après le modèle). |
.parent_boundary.boundary_name | Le nom écrit de la frontière parente. |
.parent_boundary.parameters | La même map .parameters.* que la frontière parente a vue (les valeurs des paramètres sont globales à la Release, mais l’alias est fourni par symétrie). |
.parent_boundary.annotations | Les annotations résolues en cascade de la frontière parente. |
Le motif canonique : une frontière parente qui écrit une directory: une seule fois, plus des frontières enfants qui routent leurs artefacts sous le parent en déclarant directory: "{{ .parent_boundary.directory }}". Cela rabat les enfants sur le chemin d’assemblage du parent, produisant une seule sortie fusionnée qui contient des contributeurs de chaque enfant. La Feature core/compose-bridge repose exactement sur ce point : une frontière parente portant la fonctionnalité bridge, deux frontières enfants (par exemple services-net et data-net) partageant la directory: du parent, et un seul docker-compose.yaml fusionné contenant chaque composant plus le service bridge.
Le cas inverse : omettez .parent_boundary.directory sur les enfants (ou faites-les s’évaluer en un chemin distinct) et chaque enfant obtient son propre assemblage. Les deux formes sont des options à part entière.
Exemples de dispositions
Disposition 1 — séparation par défaut par frontière
spec: boundaries: api-prod: directory: "deploy/api-prod" components: api: {} cache: {} data-prod: directory: "deploy/data-prod" components: db: {}Chaque frontière s’évalue en une directory: distincte, si bien que chacune obtient son propre assemblage :
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...La valeur par défaut subDirectory: "{{ .capability }}" sépare les artefacts par capacité à l’intérieur du répertoire de chaque frontière. Deux frontières, deux sorties d’assemblage par capacité, aucune fusion.
Disposition 2 — assemblage regroupé via un répertoire parent partagé
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: {}Les deux frontières enfants évaluent directory: en deploy/cluster (le répertoire du parent), si bien que tous les contributeurs fusionnent à un même chemin d’assemblage. Avec la valeur par défaut subDirectory: "{{ .capability }}", les contributeurs compose des deux enfants arrivent dans deploy/cluster/compose/ et produisent un seul docker-compose.yaml fusionné. La Feature compose-bridge rattachée au parent s’exécute une seule fois (répartition à portée de frontière) et apporte le service bridge au même fichier fusionné.
L’annotation aggrega.ai/chart-name: "cluster-umbrella" du parent se propage en cascade aux deux enfants ; si les frontières contenaient aussi des contributeurs helm-chart, les sous-charts helm-chart des deux enfants se composeraient sous un seul umbrella nommé cluster-umbrella. Des valeurs de chart-name divergentes entre contributeurs à un même chemin arrêtent le build.
Disposition 3 — routage par composant via subDirectory: plus des paramètres
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"La directory: de la frontière s’évalue en deploy/eu-west-1 (substitution de paramètres). Des remplacements de subDirectory: par composant routent chaque contributeur vers un sous-dossier par composant, le composant ingress remplaçant vers un sous-dossier plat shared pour les artefacts transversaux :
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...Ce motif convient aux entreprises qui veulent des répertoires d’artefacts par composant pour un outillage en aval qui opère sur les manifestes d’un seul composant. Lorsque la Recipe d’un composant déclare aussi artifacts:, lisez Ce que ces modèles ne décident pas ci-dessus avant de choisir cette forme : ces fichiers portent déjà un segment de composant, si bien que ce remplacement en ajoute un second.
Diagnostics
La surface des modèles de chemin arrête le build dans chacune des situations suivantes, et errors/fatal-halts.md les documente sous ces noms. Cette page cite le message qu’émet chaque arrêt ; comparez la sortie du build à ce texte.
- Path-template references a variable outside the allowlist (Le template de chemin référence une variable en dehors de la liste d’autorisation) — à l’analyse : un modèle de chemin référence une variable absente de la liste d’autorisation.
- Path collision (Collision de chemins) — à l’assemblage : deux contributeurs de frontière s’évaluent au même chemin mais divergent sur une propriété qui doit être uniforme entre les contributeurs de ce chemin.
- Instance-ID collision (Collision d’ID d’instance) — à l’assemblage : deux frontières qui s’évaluent au même tuple
(path, provider)apportent des composants aux ID d’instance identiques. - Chart-name mismatch (Nom de chart discordant) — à l’assemblage : un assemblage helm-chart fusionné reçoit des contributeurs dont les annotations
aggrega.ai/chart-namerésolues en cascade sont en conflit. - Missing template key (Clé de template manquante) — un modèle de chemin référence un champ sous une variable ouverte qui ne se résout en aucune valeur (par ex.
{{ .parameters.region }}lorsque la Release ometregion, ou une clé de.parent_boundarysur une frontière de premier niveau qui n’a pas de parent) ;missingkey=errorproduit un message explicite nommant la frontière, le champ du modèle (directory:ousubDirectory:) et la clé manquante..parameterset.parent_boundarysont ouvertes — leurs clés sont des données écrites par l’auteur — tandis que.manifestdéclare ses clés, si bien qu’une clé mal saisie sous.manifestest plutôt refusée à l’analyse comme référence inconnue, le diagnostic listant les clés que.manifestdéfinit.
Références croisées
entities/release.md— rédaction de la Release, y compris la séparation spatiale et les champsdirectory:/subDirectory:.providers/architecture.md— répartition vers les fournisseurs et modèle d’assemblage par(path, provider).providers/compose.md— sortie côté compose par(path, provider), y compris le scénario du chemin fusionné.providers/helm-chart.md— composition umbrella de helm-chart et règle de cascade du chart-name pour les chemins fusionnés.entities/featurerecipe.md— FeatureRecipes à portée de frontière (la Featurecore/compose-bridgerepose sur le modèle d’assemblage à chemin fusionné documenté ici).errors/fatal-halts.md— catalogue complet des diagnostics, y compris les arrêts de répartition des chemins énumérés ci-dessus.