FeatureRecipe
Le rôle conceptuel de l’entité FeatureRecipe (Domaine 3 — l’implémentation d’une interface de Feature pilotée par des plugins Wasm) est décrit dans architecture/04-entity-taxonomy.md. Cette page couvre la surface d’écriture du catalogue pour la FeatureRecipe.
Emplacement dans le catalogue
Les FeatureRecipes sont organisées avec le provider dans le premier segment du chemin (même schéma que les Recipes) :
aggrega-catalog/└── feature-recipe/ └── {provider}/ # e.g., `helm`, `compose` └── {feature-recipe-name}/ └── {version}/ └── recipe.yamlURI OCI : hub.aggrega.ai/featurerecipe/{provider}/{name}:{version} (par ex. hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).
Contrat de rédaction
Les FeatureRecipes se lient à une interface de Feature via implements et déclarent un provider concret. Leur surface d’écriture est l’ensemble complet des types d’entrée de la Recipe de base, plus deux blocs propres à la FeatureRecipe :
- Les trois types d’entrée —
source+valuesMapping(sourcé),workload(synthétisé) etartifacts: de forme identique à ceux de la Recipe de base (voir Composition des entrées de la Recipe etentities/recipe.md). Une FeatureRecipe qui porte l’un d’eux est génératrice de ressources — elle rend des ressources à côté du composant de base. L’emplacement de ces ressources porte le composant auquel la Feature est rattachée, puis le nom sous lequel elle est rattachée, sous celle des deux formes qu’admet la disposition propre de la cible : comme répertoire{component}--{instance}/à côté de celui de son hôte, sous le répertoire où cette cible place ses contributeurs, sur une cible dont le provider donne à chaque contributeur une position propre ; comme préfixe de nom de fichier{component}--{instance}--à côté des fichiers propres du composant, sur une cible qui ne lit que les fichiers situés directement dans un répertoire. Sur un provider qui compose ses contributeurs en un seul document, les ressources sont plutôt intégrées à ce document — quelle que soit la famille à laquelle appartient la Feature : une CRDServiceMonitorouExternalSecretcommeartifacts:inline ou$import; un chart ou module externe viasource:+valuesMapping:; ou ses propres ressources de calcul (par exemple un Deployment d’agent sidecar) viaworkload:.valuesMapping:partage les trois modes d’écriture de la Recipe de base (block scalar inline,$import:de fichier,$import:de bibliothèque vers une entrée de MappingLibrary) — voirentities/recipe.md« Le champvaluesMapping— trois modes d’écriture ». Par convention, une FeatureRecipe modifie le composant de base ou ajoute des ressources à côté de celui-ci, mais le schéma ne restreint pas les types d’entrée qu’elle peut utiliser — le compilateur rend tout ce que la FeatureRecipe déclare, limité seulement par la capacité du provider lié, et reste sans parti pris quant à savoir si un type donné est « approprié à un modificateur » (voir les invariants fondateurs). La synthèse (workload:) requiert un provider qui la prend en charge ; sinon, le build s’arrête au rendu avec le diagnostic de capacité du provider. injectMapping(interception avant rendu) : un bloc de template Go natif exécuté avant le rendu de la Recipe de base. Il produit un dictionnaire JSON ou YAML que le compilateur fusionne nativement en profondeur par-dessus le canal mémoire.context.injectde l’appelant, permettant une mutation côté appelant, sans Wasm, des variables d’environnement et des chaînes de connexion.pipeline: un tableau séquentiel d’étapes de plugins WebAssembly (Wasm) pour la mutation de Workload après rendu (par ex. l’injection d’un sidecar Envoy via JSONPatch, ou le montage d’un volume secret). Le champpluginde chaque étape nomme une entitéPluginpar son URI, toujours qualifiée par le type de socket propre au plugin (<pluginType>/<name>, éventuellement versionné, comme dansparser/yamlouparser/yaml:1.0.0) ; le build résout l’entité en son artefact.wasmadressé par contenu, localisé à partir de l’identité du plugin et du registre configuré, et un.wasmnu ou une référence d’artefact n’est pas accepté ici. Voir le guide du développeur de plugins Wasm pour écrire et référencer un plugin, et architecture/04-entity-taxonomy.md §« Domaine 3 : base d’infrastructure » pour le principe du Plugin en deux parties (Fetcher / Injector). Le compilateur exécute chaque étape dans l’ordre déclaré : il distribue l’export guest du plugin nommé sur la sortie rendue et applique les JSON Patches renvoyés et les effets de bord émis ; voir État du langage pour l’état d’exécution de chaque surface du pipeline. Unpipeline:se suffit à lui-même : une FeatureRecipe peut en déclarer un et aucun type d’entrée, auquel cas elle n’émet aucune ressource propre et tout son effet est ce que ses étapes appliquent comme patch aux documents que le build a déjà rendus, ou émettent à côté d’eux.
Une FeatureRecipe peut aussi ne porter aucun de ces blocs : une Feature de pur câblage dont l’effet est l’arête uses qu’elle porte ne rend rien, et sa FeatureRecipe n’existe que pour satisfaire la résolution — chaque instance de feature se résout en une FeatureRecipe, de la même manière que chaque composant se résout en une Recipe. Parmi les blocs ci-dessus, injectMapping est le seul champ sans équivalent dans la Recipe de base ; les trois types d’entrée et pipeline sont partagés avec la Recipe de base.
Ce qui est épinglé à côté d’une FeatureRecipe est ce qui est épinglé à côté d’une Recipe : le digest de chaque fichier qu’importe une entrée artifacts, et de chaque source: distante dont les coordonnées sont écrites en entier, dans un entity.lock situé dans le répertoire propre de la FeatureRecipe, que aggrega pin écrit et que vous committez à côté. Un pull sur une FeatureRecipe dont le lock n’enregistre pas ces épinglages s’arrête et nomme cette étape, sauf si l’on demande au pull de l’exécuter. Un build s’arrête lorsqu’un fichier importé ne correspond plus à son digest, et lorsque le digest d’une source diffère de celui qu’enregistre le lockfile de la Release (une source écrite à un ref: git est enregistrée au commit vers lequel elle s’est résolue et n’est pas comparée) ; le fichier de la FeatureRecipe lui-même n’est jamais modifié. aggrega pull décrit le fichier et comment répondre à chaque arrêt.
Templating du champ source
Le source: d’une FeatureRecipe est une surface de templating aux mêmes conditions que celui d’une Recipe : le template est évalué lors de la résolution de la source, et ce qu’il a produit est ce que le build résout ensuite. Les deux formes acceptent des templates Go — la forme chaîne universelle, et la forme objet structurée dont les sous-champs à valeur chaîne sont évalués comme templates tandis que les sous-champs non chaîne passent tels quels. L’inventaire des formes, le traitement des schémas et la lecture de l’ancrage sont ceux exposés dans entities/recipe.md « Templating du champ source », « Inventaire des schémas du champ source » et « Comment un chemin source: est ancré » ; cette section n’indique que ce qui diffère pour un rattachement.
locals: chart_dir: ./charts/exportersource: "{{ .locals.chart_dir }}"Par rapport à quoi un résultat relatif est résolu. Le répertoire qui contient le document FeatureRecipe qui l’a déclaré — le fichier propre du rattachement, jamais celui du composant — et le résultat doit rester dans ce répertoire, exactement comme pour une Recipe : un résultat qui en sort, ou qui est un chemin absolu, désigne un fichier qui ne voyagerait pas avec la FeatureRecipe et interrompt le build. Un résultat portant un schéma de transport est récupéré au lieu d’être joint à un répertoire. Une FeatureRecipe résolue depuis un registre est lue à partir des fichiers que contient son archive publiée, disposés dans le cache de contenu, de sorte qu’un résultat relatif se résout à l’intérieur de ce qui a été publié exactement comme il se résout à côté de la FeatureRecipe dans un répertoire de catalogue, soumis à la même limite.
Ce que le template peut lire. L’ensemble de références est celui par rapport auquel les entrées locals: de la FeatureRecipe elle-même sont vérifiées, et il diffère de celui d’une Recipe de deux façons qui découlent du fait qu’un rattachement est résolu plutôt qu’un composant :
.attachment_nameest disponible et nomme l’instance sous laquelle la Feature est rattachée. Le template de source d’une Recipe le refuse, car la source d’une Recipe se résout pour un nœud et aucun rattachement n’est en jeu..context.instance_idnomme le composant hôte pour lequel le rattachement est résolu, et non le rattachement, et.context.rendered_nameporte le nom que le fournisseur propre de l’hôte indique pour l’hôte — présent uniquement là où ce fournisseur en indique un, et interrompant le build là où il ne le fait pas. Voir Nommer une ressource rendue.
.locals porte l’ensemble que lisent les autres templates de cette FeatureRecipe : son propre bloc résolu, avec celui de la Recipe hôte en dessous, de sorte qu’une clé déclarée par le rattachement l’emporte sur une clé de l’hôte du même nom. Une référence à une clé que cet ensemble ne contient pas interrompt le build et la nomme, au lieu de faire disparaître la clé au rendu. .provides, .context.inject et .context.uses sont refusés pour les mêmes raisons d’autonomie que celles pour lesquelles la surface de source d’une Recipe les refuse.
Une FeatureRecipe de portée frontière lit plutôt la frontière. Une Feature dont la FeatureRecipe déclare executionScope: boundary effectue son rendu une fois pour la frontière plutôt qu’une fois par composant, de sorte que son template de source n’a aucun composant hôte à lire. Il lit .boundary.* — les mêmes piliers que lisent ses locals: et provides: — et les piliers par composant (.context, .workload, .attachment_name, .inject) ne lui sont pas disponibles.
Un résultat vide. Un template qui ne produit rien laisse le rattachement sans source, ce qui est le mode sans source — la même lecture que celle de la source d’une Recipe, et distincte du fait d’écrire vous-même source: "".
Ce que .source lit ensuite. La source est évaluée avant le valuesMapping:, comme celle d’une Recipe l’est avant le sien, et ce qu’elle a produit est .source dans chaque template exécuté après elle : le valuesMapping:, l’omits:, les corps workload: et artifacts:, et les étapes pipeline:. Ainsi, un valuesMapping: qui lit .source lit la source propre de cette FeatureRecipe, jamais la source du composant auquel elle est rattachée, et ne lit rien lorsque cette FeatureRecipe ne déclare aucune source ou que son template ne produit rien. Une FeatureRecipe de portée boundary lit sa propre source de la même manière. L’injectMapping: s’exécute avant que la source du rattachement soit évaluée ; .source y est donc celle du composant hôte.
Exclusivité de injectMapping
Le champ injectMapping est exclusif aux FeatureRecipes — il est volontairement absent du schéma de base Recipe. Cette exclusivité isole l’interception des variables de valuesMapping : le valuesMapping de la Recipe de base consomme sans le savoir les chaînes .context.inject réécrites générées par les blocs injectMapping de la FeatureRecipe, de sorte que les deux restent découplés. Voir la section sur l’interception par inject mapping ci-dessous pour le fonctionnement du mécanisme, et architecture/10-compilation-pipeline.md sur l’inject mapping pour la sémantique complète de l’interception avant rendu.
Interception par inject mapping : comment fonctionne injectMapping
Lorsqu’un appelant a besoin que la chaîne de connexion vers sa cible ait une forme différente du .provides.host non modifié de la cible — en ajoutant un namespace pour le DNS Kubernetes inter-frontières, en préfixant un code de région pour une passerelle multirégion, ou en ajoutant un suffixe de mode SSL à un DSN — injectMapping gère la modification côté appelant, avant même que le valuesMapping de la Recipe de base ne voie le canal d’injection.
Le champ injectMapping est un text/template Go que le moteur de rendu évalue lors de l’inject mapping, avant l’exécution du rendu de la Recipe de base. Le template produit un dictionnaire JSON ou YAML avec des clés de mécanisme facultatives (env, file, arg, ou un mécanisme personnalisé que la Recipe du composant lit dans .context.inject.<name>) — ou une map plate qui vaut env par défaut — et le moteur de rendu fusionne en profondeur cette surcouche sur le canal .context.inject du nœud appelant. Le routage côté appelant via injectMapping s’exécute lors de l’inject mapping sans invoquer de sandbox Wasm pour une simple manipulation de chaînes ; les plugins Wasm restent réservés aux modifications structurelles de l’AST via le tableau pipeline.
Écrivez chaque valeur via toJson. Le moteur de rendu lit la sortie du template comme du YAML, de sorte qu’une valeur interpolée telle quelle entre guillemets casse cette sortie ou est relue modifiée dès qu’elle contient un guillemet double ou une barre oblique inverse — un mot de passe est le cas habituel. toJson écrit la valeur sous forme de chaîne JSON, que YAML relit exactement, de sorte que la valeur est livrée avec chacun des caractères qu’elle contient :
injectMapping: | env: {{ .values.key }}: {{ .values.origin | toJson }}Une valeur assemblée à partir de plusieurs éléments est d’abord assemblée, puis écrite une seule fois via toJson, comme le font les exemples ci-dessous.
Une sortie illisible arrête le build. Lorsque la sortie du template ne se lit sous aucune des deux formes — la cause habituelle est un scalaire entre guillemets cassé par la valeur qu’il contient —, aucune de ses clés ne pourrait être livrée, de sorte que le build s’arrête en nommant le rattachement et la FeatureRecipe au lieu de rendre le composant comme si rien n’avait été livré ; voir fatal-halts.md « An attached Feature’s injectMapping output cannot be read (La sortie injectMapping d’une Feature rattachée ne peut pas être lue) ». La raison indiquée est masquée lorsqu’elle dépend d’une valeur déclarée sensible. Une sortie vide, ou qui s’analyse comme un dictionnaire ne livrant rien, ne livre rien et n’est pas un échec.
Une clé de premier niveau est un mécanisme, et all n’en est pas un. Chaque clé de premier niveau d’une sortie sous forme de dictionnaire nomme le mécanisme par lequel ses entrées sont livrées : env, file et arg, ou tout autre nom, qui est livré comme un mécanisme à part entière sous ce nom. .context.inject.all est construit à partir de ces mécanismes après la fusion et n’est jamais fusionné depuis une sortie, de sorte que des entrées écrites sous all: n’atteindraient rien ; le build s’arrête à la place, en nommant le rattachement, la clé et la FeatureRecipe, et en indiquant quelles clés une sortie peut contenir — voir fatal-halts.md « An attached Feature’s injectMapping output writes deliveries under a key nothing delivers (La sortie injectMapping d’une Feature rattachée écrit des livraisons sous une clé que rien ne livre) ». Écrivez de telles entrées sous le mécanisme dans lequel le composant les lit.
La modification est strictement locale à l’appelant. La FeatureRecipe ne modifie que le canal d’injection du nœud auquel elle est rattachée, jamais la sortie .provides de la cible. Le .provides.host d’une cible est consommé par potentiellement de nombreux appelants dans tout le cluster ; injectMapping côté appelant ne fusionne que dans le canal de l’appelant concerné, de sorte que les modifications de routage restent limitées à l’arête qui les a demandées.
Ce qu’un mapping peut réécrire. Chaque bloc inject: a déjà livré au moment où les mappings effectuent leur rendu, de sorte que la sortie d’un mapping est toujours fusionnée sur des clés qu’autre chose a déjà écrites — et c’est l’auteur d’une clé qui décide de ce qui se passe. Une clé livrée par le propre bloc inject: de l’appelant ou par le bloc inject: de l’une de ses connexions peut être réécrite par le mapping : c’est de l’interception, et la valeur du mapping remplace cette seule entrée. Une clé que le propre rattachement du mapping a livrée via son bloc inject: peut de même être réécrite par lui. Une clé qu’une Feature rattachée différente a déjà livrée — via son propre bloc inject: ou via l’injectMapping de sa propre FeatureRecipe — ne peut pas l’être : le build s’interrompt en nommant les deux rattachements, plutôt que de laisser le mapping exécuté en dernier décider de la valeur que lit l’appelant. Ainsi, deux Features de routage peuvent chacune qualifier une clé qui leur est propre, mais deux Features ne peuvent pas livrer toutes deux une même clé — y compris deux Features de routage réécrivant la clé de la même connexion, puisque la première est une interception et que la seconde rencontre la livraison de la première ; voir fatal-halts.md « Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping » (Deux Features rattachées livrent une même clé, la seconde via l’injectMapping de sa FeatureRecipe).
Inférence de la cible sans couplage
Comme le compilateur intègre les annotations en cascade de chaque cible dans le canal .context.uses de l’appelant, le template injectMapping peut extraire les coordonnées de routage sans que les Ops ne codent en dur l’identité de la cible dans l’infra de la Feature :
- Le template parcourt
.context.usespour trouver l’arête topologique exacte qui a injecté la variable demandée par le développeur. - Il extrait les
release_annotationsen cascade de la cible (par ex.aggrega.ai/namespace). - Il formate le nom de domaine pleinement qualifié (FQDN) ou la chaîne de connexion.
- Il émet le dictionnaire de surcharge.
Le compilateur reste agnostique vis-à-vis de la sémantique réseau — namespaces Kubernetes, régions cloud, topologies bridge-proxy — et exécute simplement la fusion en profondeur avec ce que le template a produit. Lorsque le valuesMapping de la Recipe de base s’exécute ensuite, il consomme les chaînes interceptées et réécrites de .context.inject.env comme s’il s’agissait des originaux du développeur.
Exemple détaillé : résolveur DNS K8s
Le catalogue standard le fournit sous la forme core/k8s-dns-resolver avec une FeatureRecipe helm. Comme les noms des variables d’environnement doivent être uniques au sein d’un conteneur, la target_var (par ex. API_HOST) sert d’identifiant globalement unique pour un contrat d’injection précis au sein de l’appelant. En parcourant les arêtes explicites de .context.uses et en vérifiant quelle arête a revendiqué la target_var, le template localise le bon nœud cible et lit son namespace. Le seul paramètre est la variable à réécrire ; la cible et son namespace sont découverts, jamais codés en dur.
Le schéma de la Feature de routage (core/k8s-dns-resolver) :
infra: { target_var: string # Ops dictates WHICH injected var to rewrite}L’implémentation de la FeatureRecipe :
injectMapping: | # 1. Grab the atomic base host directly from the flattened pipe, or an # empty value when nothing was injected under target_var {{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable {{ $target_edge := dict }} {{ range $alias, $edge := .context.uses }} {{ if hasKey $edge.inject.env $.infra.target_var }} {{ $target_edge = $edge }} {{ end }} {{ end }}
# 3. Read the target's namespace from its cascaded release annotation, # coalescing an absent namespace to "default" {{ $ns := "default" }} {{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }} {{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }} {{ if $raw }}{{ $ns = $raw }}{{ end }} {{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection # and a base host were actually found, so a target_var that matches no # connection injects nothing instead of a spurious variable. An unset # namespace resolves to "default", where the helm provider deploys an # unannotated workload, so the qualified host always matches the service's # actual location and is never malformed. {{ if and $target_edge $base_host }} {{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge env: {{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }} {{ end }}Cas d’usage au-delà du routage
injectMapping est le plus souvent utilisé pour la résolution d’adresses inter-frontières (comme le résolveur DNS K8s ci-dessus), mais cette modification côté appelant s’applique à tout scénario qui exige d’intercepter et de formater l’intention du développeur avant le rendu de l’infrastructure. Deux autres modèles illustrent l’étendue des possibilités.
Formatage dynamique de la sécurité (l’ajout SSL). Si une entreprise impose que toutes les connexions à des bases de données externes utilisent une vérification TLS stricte, une Feature peut intercepter le DB_URL demandé par le développeur et y ajouter le mode SSL requis, afin que l’application démarre avec les bons paramètres de sécurité.
# Inside force-ssl-featureinjectMapping: | {{ $base_url := index .context.inject.env .infra.target_var }} env: {{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}Préfixage de passerelle multirégion. Si un composant d’API générique est déployé mondialement, une Feature de routage régional peut consulter de manière autonome les annotations de sa propre frontière d’environnement pour préfixer les chaînes de connexion injectées pour ses appelants.
# Inside regional-routerinjectMapping: | {{ $base_host := index .context.inject.env .infra.target_var }} {{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }} env: {{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}La limite de injectMapping. Le mécanisme se borne à modifier le canal mémoire .context.inject (le contrat de livraison). Il ne peut pas ajouter de nouveaux conteneurs, monter des volumes ni modifier la sortie du valuesMapping de la Recipe de base. Toute modification qui exige des changements structurels de l’AST rendu (comme des tableaux JSON ou YAML) relève du tableau pipeline de la FeatureRecipe, exécuté via des plugins WebAssembly.
La limite des cibles de patch de pipeline. Une étape pipeline ne patche que la sortie que le fournisseur rend sous forme d’arbre structuré. La sortie de forme YAML et JSON est structurée — y compris les modules Terraform .tf.json écrits en JSON — de sorte que le JSONPatch d’une étape modifie sur place les valeurs adressées, en laissant intact chaque autre octet (commentaires, ordre, mise en forme). La sortie que le fournisseur émet sous forme de corps opaque, comme une configuration Terraform en HCL natif, n’est pas une cible de patch : un patch sur un corps opaque interrompt le build avec un diagnostic plutôt que de modifier un texte qu’il ne peut pas adresser structurellement. Écrire une étape pipeline sur une sortie opaque est donc une erreur de conception signalée par un arrêt explicite, et non un no-op silencieux.
Les entrées d’un module Terraform vendorisé ne sont pas une cible de patch, et cette absence mérite d’être signalée. Ce sont les arguments du bloc module de ce composant, que le fournisseur terraform écrit dans la configuration racine de la frontière : du HCL natif, donc opaque selon la règle ci-dessus, et un artefact de toute la frontière plutôt que du nœud dont l’étape patche la sortie. Il n’existe donc aucune position depuis laquelle une étape pipeline pourrait les adresser, ni rien qu’elle puisse faire pour changer ce que reçoit un module Terraform référencé par source. Ces valeurs sont façonnées là où elles sont écrites — dans le valuesMapping: de la Recipe de base.
Étapes conditionnelles — when:
Une étape pipeline peut porter un champ when: facultatif : un template Go inline que le compilateur évalue lors du parcours du pipeline, avec le même contexte de template et le même évaluateur que ceux qu’utilise le corps with: de l’étape. Le résultat rendu décide si l’étape s’exécute.
- Un résultat falsy saute l’étape comme un simple passage : l’ensemble de documents passe inchangé à l’étape suivante, et l’étape sautée n’apporte rien — aucun patch, aucun effet de bord, aucune trace d’exécution.
- Un
when:vide ou absent exécute toujours l’étape.
when: et optional: sont indépendants. when: décide si une étape s’exécute ou non ; optional: atténue l’échec d’une étape en cours d’exécution. Une étape peut déclarer les deux — when: contrôle l’entrée et, si l’étape s’exécute, optional: régit la façon dont un échec en son sein est traité. Un template when: dont le rendu échoue est un défaut de rédaction et interrompt le build indépendamment de optional:.
Le texte when: rendu est jugé selon la règle partagée des templates booléens : les chaînes true, True et TRUE, tout nombre non nul et toute autre chaîne non vide sont vrais ; les chaînes false, False et FALSE, la chaîne vide et un nombre nul sont faux.
Modèle de FeatureRecipe pour identifiants
Lorsqu’une FeatureRecipe implémente une Feature d’identifiants (une Feature portant le label feature.aggrega.ai/kind: secret), elle peut suivre le principe du Plugin en deux parties : un pipeline qui enchaîne un plugin Fetcher (qui génère la CRD propre au coffre) et un plugin Injector (qui monte le secret dans le conteneur cible), la forme que décrit examples/04-secrets. Les FeatureRecipes d’identifiants de la bibliothèque standard ne déclarent aucun pipeline: et rendent elles-mêmes la ressource de secret ; voir examples/05-credential-features.
Une FeatureRecipe d’identifiants effectue son rendu dans la même passe de génération de ressources que celle de tout autre rattachement, et son pipeline: s’exécute aux mêmes conditions : le compilateur parcourt chaque rattachement qui a du travail dans cette passe comme une seule séquence ordonnée et exécute le pipeline déclaré de chacun, avec la même sémantique des ensembles de documents /own et /host. Un rattachement rejoint cette séquence pour l’une de deux raisons — sa FeatureRecipe déclare un type d’entrée, et génère donc ses propres ressources, ou elle déclare un pipeline:, et réécrit donc des documents déjà émis. Un rattachement d’identifiants peut donc agir sur les documents rendus du composant hôte — monter un volume de secret, ajouter une référence env — exactement comme un rattachement opérationnel, et la seule différence entre les deux est l’endroit où atterrissent ses propres fichiers générés.
Sur un composant, une déclaration de sensibilité sur la Feature suit le valuesMapping: de la FeatureRecipe exactement comme celle d’un Component suit celui de sa Recipe. Là où une FeatureRecipe effectue le rendu à partir d’une source: sans valuesMapping:, les valeurs que reçoit sa cible ont pour clés les chemins de feuilles que déclare la Feature, de sorte qu’une feuille déclarée sensitive: true marque sa clé rendue. Là où la FeatureRecipe déclare un valuesMapping:, les clés sont l’invention propre de ce template, aucune déclaration ne les nomme, et le build affiche un avertissement par feuille de ce type, nommant le rattachement, la feuille et la FeatureRecipe. Une Feature rattachée à une frontière n’en produit aucun : son .values est toujours vide, de sorte qu’aucune feuille déclarée n’a de valeur à marquer — voir A declared-sensitive value reaches the target through a values mapping (Une valeur déclarée sensible atteint la cible via un values mapping).
Le bloc provides: — publication vers le consommateur
Le bloc provides: d’une FeatureRecipe est sa sortie publiée : une map à valeurs chaîne de templates Go évalués dans la portée propre du rattachement (.values, .infra, les .locals entièrement résolus de la FeatureRecipe, et .context.instance_id et .context.rendered_name du nœud hôte). Les locals sont résolus en premier, de sorte qu’une entrée provides: les lit et reçoit des valeurs résolues ; nommer une clé que le bloc locals: ne déclare pas interrompt le build. C’est ainsi qu’un rattachement indique à son consommateur ce qu’il a produit — le nom d’une ressource émise, une clé de données générée, une identité cloud — sans que le consommateur ne redérive cette identité à partir des mêmes entrées.
Le consommateur la lit à .features.<instance-name>.provides.<key> (ou .features.<slot>.provides.<key> pour un rattachement d’identifiants), à l’image de .context.uses.<alias>.provides pour une arête uses. Là où le rattachement est écrit sur l’une des connexions du consommateur, le consommateur lit la même map sous cette connexion, à .context.uses.<alias>.features.<slot>.provides.<key>, et le rattachement ne figure pas parmi ses .features (voir Les rattachements d’une connexion). Le propre bloc inject: du rattachement résout ses références from: par rapport à la même map, de sorte qu’un auteur peut choisir l’un ou l’autre canal : provides pour une lecture de template, inject pour une livraison dans une variable d’environnement, un fichier ou un argument.
# FeatureRecipe: emits a ServiceAccount and publishes its name.provides: name: "{{ .infra.service_account_name }}"# Consuming Recipe: binds the pod to what the attachment published.workload: | serviceAccount: "{{ .features.identity.provides.name }}"Lorsque la Feature que cette FeatureRecipe implements déclare un contrat schema.provides, le contrat est appliqué à la FeatureRecipe : chaque clé que déclare la Feature doit apparaître dans le provides: de la FeatureRecipe, faute de quoi le build s’interrompt en nommant la clé manquante. Des clés publiées supplémentaires sont autorisées — le contrat est un plancher, pas un plafond. Les valeurs ne sont jamais inspectées ; ce sont des pointeurs déterministes opaques que le runtime résout.
La résolution a lieu une fois par rattachement, avant le rendu du consommateur, et la même map résolue alimente la lecture du consommateur, la vérification du contrat et la génération de ressources propre au rattachement — de sorte que ce que lit le consommateur et ce qu’émet le rattachement ne peuvent pas diverger.
Provider & implements
spec.capability est obligatoire et nomme le fournisseur dont le plugin de rendu Wasm effectue le rendu de la sortie de la FeatureRecipe (helm, helm-chart, compose, etc.), aux conditions qui s’appliquent au spec.capability d’une Recipe (voir entities/recipe.md) : un pin de version sélectionne la version de ce plugin qui en effectue le rendu, et ne fait pas partie du nom de la FeatureRecipe — un Manifest mappe une FeatureRecipe déclarant capability: "compose:1.2.3" en tant que compose/<name>:<version>, et une valeur de mapping qui écrit le pin dans le nom est refusée comme référence de recette mal formée (E0095) avant toute recherche. Le champ implements lie la FeatureRecipe à son interface de Feature et prend en charge la correspondance exacte, par plage compatible avec la version majeure, ou sans version — voir vocabulary/inheritance-and-interface pour la sémantique de correspondance de version de implements.
Portée d’exécution — spec.executionScope
L’énumération facultative spec.executionScope sélectionne le modèle de dispatch de la génération de ressources. Deux valeurs sont acceptées ; lorsque le champ est omis, la valeur par défaut est component.
component(par défaut). La génération de ressources de la FeatureRecipe s’exécute une fois par instance de composant rattachée. Chaque invocation reçoit un contexte de template par composant, enraciné en.context.*:.context.instance_id,.context.inject,.context.uses,.context.annotations, etc. SesvaluesMapping:,workload:etartifacts:lisent également.context.used_by, les composants dont les entréesusespointent vers l’hôte — chacun avec son identité, son socket, ce qu’il publie, ainsi que le namespace et la frontière dans lesquels il est placé —, ce qu’aucun template rendu par l’hôte lui-même ne peut voir.boundary. La génération de ressources s’exécute une fois par frontière rattachée, quel que soit le nombre de composants du sous-arbre de la frontière qui consomment la fonctionnalité. Chaque invocation reçoit un contexte de template de portée frontière, enraciné en.boundary.*au lieu de.context.*.
L’interception injectMapping décrite ci-dessus est toujours par consommateur, quelle que soit la valeur de executionScope. Chaque composant qui utilise la fonctionnalité reçoit toujours sa propre réécriture côté appelant de .context.inject. Seule l’étape de génération de ressources (source/valuesMapping et le tableau pipeline) est dédupliquée à la portée frontière.
Les templates d’une FeatureRecipe de portée frontière s’exécutent donc dans deux portées. Son injectMapping s’exécute une fois pour chaque composant que le rattachement atteint, sur le contexte de ce composant — celui que lit l’injectMapping d’une FeatureRecipe de portée composant : .context.*, .attachment_name, .features, ainsi que les .values, .infra et .locals propres au rattachement. Son .infra est le bloc infra: du rattachement à la frontière, et son .locals est le bloc évalué une seule fois pour la frontière. Tout autre template qu’elle écrit — dont ses locals:, provides:, source:, valuesMapping: et artifacts: ainsi que les with: et when: des étapes de son pipeline — s’exécute une fois pour la frontière, sur le contexte de portée frontière décrit ci-dessous. Chaque template est vérifié par rapport à la portée dans laquelle il s’exécute : un valuesMapping: qui lit .context.instance_id arrête la build, et un injectMapping qui le lit rend l’identité de ce composant. .boundary n’est défini dans le contexte d’aucun composant, de sorte qu’un injectMapping qui le lit arrête la build en nommant la référence, quel que soit l’executionScope de la FeatureRecipe.
Contexte de template de portée frontière
Lorsque executionScope: boundary, les templates de la FeatureRecipe autres que son injectMapping sont évalués sur une vue .boundary.* de la frontière à laquelle la fonctionnalité est rattachée. La vue expose :
.boundary.path— le chemin de la frontière de la Release à laquelle la fonctionnalité est rattachée : les noms des frontières, de la plus externe vers l’intérieur, joints par/(bridge,bridge/frontend). Il nomme la frontière, et non le répertoire dans lequel sa sortie est écrite, que fixedirectory:(remplace.context.instance_id)..boundary.assembly_path— le répertoire, relatif au répertoire de sortie de la build, dans lequel la sortie propre au rattachement est assemblée : lesdirectory:etsubDirectory:évalués de la frontière, c’est-à-dire le répertoire vers lequel la build achemine cette sortie (bridge/compose). Il est égal ausource_assembly_pathou autarget_assembly_pathd’une extrémité de connexion exactement lorsque cette extrémité est rendue dans le même fichier assemblé ; une FeatureRecipe les compare donc pour distinguer une connexion interne à son propre fichier d’une connexion dans un autre fichier..boundary.boundary_name— le nom de la frontière tel qu’il est écrit dans la Release..boundary.components— une map indexée par ID d’instance contenant chaque composant du sous-arbre de la frontière (instance_id,component,resolved_version,boundary_path)..boundary.internal_uses_edges— les arêtesuses:dont les deux extrémités se trouvent dans le sous-arbre de cette frontière (le motif compose-bridge les énumère, en conservant les arêtes dont les deux extrémités sont assemblées dans son propre fichier compose et placées sur des réseaux différents de celui-ci, pour en dériver sa configuration de proxy par arête). Chaque arête porte les provides résolus de ses extrémités, les variables d’environnement injectées et le placement de chaque extrémité :source_namespaceettarget_namespace, l’annotationaggrega.ai/namespacequi s’applique à cette extrémité — le réglage de sa propre entrée de Release lorsqu’elle en a un, sinon celui de sa frontière ;source_boundary_pathettarget_boundary_path, le chemin de la frontière de la Release qui la contient ; etsource_assembly_pathettarget_assembly_path, le répertoire, sous le répertoire de sortie de la build, dans lequel son provider l’assemble, composé à partir desdirectory:etsubDirectory:évalués de sa frontière (bridge/compose). Deux extrémités ayant le même chemin d’assemblage sont rendues dans un même fichier assemblé, et le provider compose lit le chemin d’assemblage comme le réseau de l’extrémité lorsqu’aucun namespace ne s’applique..boundary.outgoing_cross_boundary_uses_edges— les arêtes dont la source est dans le sous-arbre et la cible à l’extérieur..boundary.incoming_cross_boundary_uses_edges— les arêtes dont la cible est dans le sous-arbre et la source à l’extérieur (utilisées par les agrégateurs de type ingress)..boundary.cross_boundary_uses_edges— l’union des arêtes inter-frontières entrantes et sortantes, lorsque la FeatureRecipe veut la vue inter-frontières complète..boundary.labels— l’union des labels du sous-arbre, en préservant l’ordre d’écriture..boundary.annotations— les annotations propres de la frontière, plus la cascade..boundary.feature_attachments— chaque fonctionnalité rattachée à cette frontière (afin qu’une FR de portée frontière puisse examiner ses voisines si nécessaire).
Le pilier .infra d’une FR de portée frontière se résout en le bloc infra: de la fonctionnalité rattachée à la frontière (le dimensionnement physique écrit côté Release pour ce rattachement à la frontière). .values est toujours vide pour les FR de portée frontière : la règle de séparation des piliers du schéma de la Release interdit values: sur les rattachements de Feature au niveau de la Release, de sorte qu’une fonctionnalité rattachée à une frontière ne porte aucune valeur à projeter. Les FR de portée frontière qui ont besoin de données en forme de paramètres devraient les consommer via .infra (la surface d’écriture de l’opérateur pour la configuration des fonctionnalités de frontière) ou via .boundary.annotations (des valeurs de chaîne résolubles par cascade, écrites sur la frontière ou sur n’importe quel ancêtre) ; .parameters ne fait pas partie de la vue, et un template qui le lit s’arrête en nommant les racines que la vue définit. .locals reste le bloc locals propre à la FR. .steps et .metadata restent inchangés.
Liste d’autorisation des champs des templates de portée frontière
Les FR de portée frontière ne peuvent référencer que les champs disponibles dans la vue de portée frontière, dans chaque template sauf l’injectMapping. Écrire un tel template qui référence un champ propre à la portée composant (par ex. .context.instance_id, .context.inject, .context.uses) lorsque executionScope: boundary fait échouer la validation de la FeatureRecipe au moment de l’analyse, avec une erreur nommant la FR, le champ fautif et les champs que la vue de portée frontière définit. La règle symétrique s’applique dans l’autre sens : une FR de portée composant qui référence des champs .boundary.* échoue au même validateur. L’injectMapping est vérifié par rapport au contexte du composant dans lequel il s’exécute, quelle que soit la portée ; il peut donc lire .context.*, et une référence à .boundary en son sein s’arrête en nommant la référence et les racines que ce contexte définit.
Le validateur effectue le même parcours de l’AST des templates que celui qu’utilise la liste d’autorisation des variables des templates de chemin, avec un ensemble de références différent pour chaque portée.
Déduplication et sortie de la génération de ressources
Pour executionScope: boundary, le compilateur déduplique la génération de ressources selon le tuple (boundary_path, FR-instance). Deux composants du même sous-arbre de frontière qui consomment tous deux la même fonctionnalité rattachée à la frontière déclenchent une seule invocation de la FR, et non deux. Les rattachements d’une même fonctionnalité à des frontières différentes s’exécutent indépendamment pour chaque frontière.
Une FR de portée frontière émet un ensemble de fichiers non intermédiaires par tuple (boundary_path, FR-instance), et leur emplacement découle de la manière dont le provider combine la sortie de sa frontière. Le nom d’instance seul est ici la coordonnée, alors qu’un rattachement de portée composant porte aussi son composant : une fonctionnalité de portée frontière est rattachée à la frontière plutôt qu’à un composant, de sorte que le répertoire de frontière englobant dit déjà tout ce que dirait un segment de composant, et il n’y a aucun composant à nommer.
Un provider qui écrit chaque document directement dans le répertoire de la frontière déclare que sa cible ne lit que les fichiers situés directement dans un répertoire. Il n’existe donc aucun répertoire englobant dans lequel placer un rattachement, et le nom d’instance devient à la place un préfixe de nom de fichier : <boundary_directory>/<fr-provider>/<feature-instance>--<file>, à côté des fichiers propres de la frontière. Le nom d’instance est encodé, car un nom de fichier n’a pas de séparateur sur lequel se replier, et il rejoint le nom propre du fichier à une limite de deux caractères qu’aucune coordonnée encodée ne peut contenir — si bien que deux rattachements émettant un même nom de fichier aboutissent tout de même à deux fichiers.
Un provider qui compose la sortie de sa frontière en une structure englobante — un chart contenant un chart par contributeur, une configuration racine contenant un module par contributeur — place chaque contributeur dans un sous-répertoire qui lui est propre, et un rattachement à une frontière est un contributeur comme un autre. Sa sortie se trouve alors dans <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/, où <contributors-directory> est le nom que cette cible donne à l’endroit où résident ses unités enfants. Le sous-répertoire porte le nom d’instance du rattachement, c’est-à-dire le nom sous lequel vous l’avez écrit dans le bloc features: de la frontière, de sorte que le répertoire produit par une build est un répertoire que vous pouvez retrouver dans ce que vous avez écrit.
La sortie intermédiaire est acheminée vers l’assembleur par (chemin, provider) de la frontière, au chemin évalué de la FR et sous la spec.capability propre à la FR — c’est le mécanisme que la Feature core/compose-bridge utilise pour fusionner un service de pont aux côtés des contributeurs compose par composant au même chemin d’assemblage. Une telle sortie n’est écrite que comme partie du fichier assemblé à cet endroit à partir des composants de la frontière ; lorsqu’aucun d’eux n’aboutit à ce chemin — chaque composant envoyé ailleurs par son subDirectory:, par exemple —, la build s’arrête en nommant la frontière, la Feature, le chemin vers lequel sa sortie a été acheminée et le provider, plutôt que d’écrire la sortie nulle part (voir « A boundary-level Feature’s output reaches no assembled file (La sortie d’une Feature au niveau d’une frontière n’atteint aucun fichier assemblé) » dans fatal-halts.md).
Résolution de provides: tenant compte de la cascade
Les FR de portée frontière produisent un ensemble provides: par tuple (boundary_path, FR-instance), évalué une seule fois. Le template provides: de la FR est évalué avec le contexte de template de portée frontière (il peut donc référencer .boundary.components, .boundary.path, .infra, mais ni les champs par consommateur ni .values). Les valeurs des provides sont des constantes relativement aux consommateurs — chaque consommateur du sous-arbre de la frontière voit les mêmes valeurs fournies.
La résolution côté consommateur des provides d’une FR de portée frontière lit partout cette unique évaluation. Chaque composant que le rattachement atteint la lit en .features.<instance-name>.provides.<key> — dans les templates de sa propre Recipe et dans l’injectMapping propre à la FeatureRecipe, qui s’exécute dans le contexte de ce composant. Un Component consommateur qui lit via une arête uses portée par le rattachement, en .context.uses.<feature-alias>.provides.<provided-name>, obtient les mêmes valeurs : le compilateur la résout en le provides: de la FeatureRecipe de portée frontière pour la frontière dans laquelle se trouve le consommateur, en allant de l’arête uses du consommateur — qui porte l’identité de l’instance de fonctionnalité par rattachement — jusqu’au provides: de la FR de portée frontière. Une pré-passe évalue ces provides avant l’assemblage des consommateurs, de sorte que les valeurs sont présentes lorsque le pipe du consommateur est construit.
Un effet par consommateur est une table dans provides: lue par injectMapping. Une FeatureRecipe de portée frontière qui doit modifier quelque chose pour chaque consommateur calcule une seule fois, dans son provides:, une table indexée par consommateur à partir des connexions de la frontière, et son injectMapping lit les lignes du composant courant — (index .features .attachment_name).provides, indexées par .context.instance_id — et les livre par le pipe propre au consommateur, selon la règle que suit tout mapping (voir Ce qu’un mapping peut réécrire). Le compilateur achemine la table que la FeatureRecipe a écrite et n’y lit rien.
Le modèle compose-bridge
La FeatureRecipe compose-bridge est le modèle canonique de FR à portée boundary, et c’est du contenu de catalogue écrit avec les mécanismes ci-dessus : ni le compilateur ni le provider compose ne contiennent de logique propre au bridge, de sorte qu’un catalogue peut réaliser la Feature core/compose-bridge différemment. Une feature core/compose-bridge est attachée à une boundary parente qui contient deux sous-boundaries (par ex. services-net et data-net) avec un directory: partagé, chacune portant sa propre annotation aggrega.ai/namespace (aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net) afin que chacune aboutisse sur un réseau qui lui est propre ; sans ces annotations, les deux partagent l’unique réseau nommé d’après le chemin de leur fichier compose et se joignent mutuellement sans bridge. Son executionScope: boundary exécute la FR une fois par attachement à la boundary parente.
Son provides: calcule la table du bridge, une seule fois. À partir de .boundary.internal_uses_edges, il conserve les arêtes dont les deux extrémités sont assemblées dans son propre fichier compose — source_assembly_path et target_assembly_path tous deux égaux à .boundary.assembly_path — et se trouvent sur des réseaux différents de ce fichier, le réseau d’une extrémité étant son aggrega.ai/namespace, à défaut son chemin d’assemblage. Une arête entre deux fichiers compose n’est pas pontée, et son consommateur conserve le nom propre de la cible. Chaque arête pontée reçoit un port d’écoute — le port propre de la cible ou, lorsqu’une arête précédente écoute déjà sur celui-ci, le premier port libre égal ou supérieur au portBase de l’attachement (par défaut 10000) — et un upstream, l’hôte publié de la cible (le champ provides que nomme le providesField de l’attachement, par défaut host) et son port ; l’upstream est dérivé de l’arête, jamais écrit à la main. À partir de la même table, il calcule la réécriture de chaque consommateur : une variable que l’arête livre depuis le champ host devient aggrega-gw:<listen port>, ou aggrega-gw lorsque la même arête livre aussi une variable depuis port, qui devient alors le port d’écoute.
Son injectMapping livre les lignes de chaque consommateur. Exécuté dans le contexte de chaque consommateur, il lit les lignes de ce consommateur dans la table à .features.<attachment>.provides et les livre par-dessus les valeurs livrées par la propre connexion du consommateur (par ex. DB_HOST), ce qui constitue une interception ; un consommateur sans ligne ne reçoit rien. Lorsqu’une autre Feature attachée au consommateur a livré cette clé — via son bloc inject: ou son injectMapping — le build s’arrête en nommant les deux Features plutôt que de remplacer cette livraison (voir « Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Deux Features attachées livrent une même clé, la seconde via l’injectMapping de sa FeatureRecipe) » dans fatal-halts.md). Le listen de la passerelle et la réécriture du consommateur sont lus depuis une seule table, de sorte qu’ils concordent par arête par construction, y compris les collisions réattribuées via portBase.
Son valuesMapping écrit la passerelle. Le fragment compose propre à la FeatureRecipe déclare le service aggrega-gw. Lorsque quelque chose est ponté, son valuesMapping ajoute un bloc nginx stream server par arête pontée (listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;, sous une directive resolver afin que chaque upstream soit résolu au moment de la connexion plutôt qu’une seule fois au démarrage ; le $ de ces variables s’écrit $$ afin que l’interpolation $ de Docker Compose laisse un $ littéral pour nginx), livré sous forme de configuration compose montée — une entrée configs: de premier niveau avec un content: en ligne, référencée depuis aggrega-gw et montée à /etc/nginx/nginx.conf (ainsi nginx la charge sans command: écrit par l’auteur). configs.content en ligne nécessite Docker Compose ≥ 2.23.1. Il nomme aussi chaque extrémité pontée sous le x-aggrega-networks-of de la passerelle, que le provider compose résout en réseaux sur lesquels ces extrémités sont placées, de sorte que la passerelle rejoint chaque réseau que couvrent ses arêtes pontées (le réseau du consommateur et celui de la cible) — à l’exécution, le consommateur peut joindre aggrega-gw:<port> et la passerelle peut faire un proxy_pass vers la cible. Lorsque rien n’est ponté, la passerelle que déclare le fragment est tout de même rendue, inactive : aucune configuration, aucun réseau supplémentaire et aucune réécriture.
L’assembleur compose par (chemin, provider) fusionne la passerelle avec les contributeurs par composant au même chemin évalué : un unique docker-compose.yaml contenant chaque composant plus la passerelle du bridge. Lorsqu’aucun des composants de la boundary n’est assemblé dans le fichier de la passerelle, le build s’arrête plutôt que d’écrire la passerelle nulle part. L’upstream est un pointeur déterministe, fixé à la compilation, vers un service compose ; le DNS d’exécution de compose le résout (aucune résolution d’exécution à la compilation).
Rendu après les appelants — spec.readsCallerRenderFacts
Le champ facultatif spec.readsCallerRenderFacts (booléen, par défaut false) déclare que les templates de cette FeatureRecipe lisent ce qu’ont rendu les composants qui se connectent à son hôte : les faits de rendu que le provider de chacun de ces appelants rapporte sur la sortie qu’il a émise. Ce qu’un provider rapporte, et sous quels noms, relève du contrat propre à ce provider ; Rapporter des faits sur ce qu’un guest a émis décrit les faits qu’un provider peut rapporter.
Quand un tel attachement est rendu. Le build rend ses composants un par un, dans un ordre fixe, et un attachement est normalement rendu juste après le composant auquel il est attaché. Un composant qui se connecte à l’hôte et vient plus tard dans cet ordre n’a pas encore été rendu à ce moment-là, de sorte que rien de ce qu’il a émis n’existe pour être lu. Un attachement dont la FeatureRecipe définit readsCallerRenderFacts: true est au contraire rendu une fois que chaque composant du build a été rendu, avec chaque attachement qui ne définit ni cette clé ni readsTargetRenderFacts — ainsi le rendu de chaque appelant est complet avant que l’attachement ne soit évalué. Sa sortie aboutit là où elle aurait abouti et sous les mêmes noms ; la clé change le moment où l’attachement est rendu, pas ce qu’il rend. Un ordre découle de ce rendu ultérieur : lorsque la FeatureRecipe porte une pipeline qui réécrit les documents de son composant hôte et que le provider de l’hôte écrit des documents distincts, ces étapes s’exécutent après les pipelines des autres attachements de l’hôte plutôt que dans leur ordre d’attachement.
Ce qu’il lit. Avec la clé définie, chaque entrée de .context.used_by porte .render_facts : les faits de rendu de l’appelant, indexés par nom de fait. Chaque fait de rendu est une liste, de sorte qu’un template la parcourt toujours avec range — même lorsqu’elle ne contient qu’une seule entrée. Ses entrées peuvent provenir du rendu propre de l’appelant et des rendus des Features attachées à l’appelant : les listes qu’un nom obtient de chacun sont réunies en une seule, d’abord les appels du provider propre de l’appelant, puis chacune de ses Features dans l’ordre où elles ont été rendues. Une Feature de l’appelant qui définit elle-même la clé est elle aussi rendue après chaque composant, de sorte que ce qu’elle a rapporté n’en fait pas partie. Un appelant dont les providers ne rapportent rien porte un .render_facts vide, de sorte qu’un nom que personne n’a rapporté se lit comme rien :
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}Les noms de faits qui existent, et ce que contient chaque entrée, relèvent du contrat documenté du provider de l’appelant — ceux du provider helm, par exemple, sont ses faits de rendu, qui nomment les labels des pods qu’il a rendus. Les faits des appelants se trouvent sur les connexions que lisent valuesMapping:, workload: et artifacts: de la FeatureRecipe ; les with: et when: d’une étape pipeline: ne voient pas du tout les composants qui se connectent à l’hôte, de sorte qu’une étape ne lit que les faits propres de l’hôte. Chaque FeatureRecipe attachée à un composant — qu’elle définisse ou non la clé — lit les faits propres du composant à .context.render_facts, sous la même forme ; le contexte des templates décrit les deux.
Déclarez-la chaque fois qu’un template lit les faits. Un template écrit en ligne dans une FeatureRecipe qui ne définit pas la clé — son valuesMapping:, son workload: ou une entrée artifacts: — et qui lit render_facts sous .context.used_by arrête le build avant que quoi que ce soit ne soit rendu, en nommant la référence et le champ dans lequel elle a été écrite (voir « A template reads its callers’ render facts without declaring it (Un template lit les faits de rendu de ses appelants sans le déclarer) » dans fatal-halts.md). La vérification lit le template tel qu’il est écrit, de sorte qu’elle ne voit pas une référence construite pendant l’exécution du template, ni une référence écrite dans du contenu importé d’un fichier ou d’une bibliothèque — et un template qui lit un champ nommé render_facts sur une autre liste à côté de .context.used_by, ou qui lit les faits propres de l’hôte sous la forme .render_facts dans {{ with .context }} à côté de celle-ci, est traité comme lisant les faits des appelants ; écrivez ceux de l’hôte en entier sous la forme .context.render_facts. C’est la clé, et non la vérification, qui décide du moment où l’attachement est rendu ; définissez-la donc sur chaque FeatureRecipe dont les templates lisent les faits de rendu de leurs appelants, quelle que soit la façon dont ils les atteignent ; la définir ne coûte rien d’autre que le rendu ultérieur.
Une étape de pipeline ne lit que les faits propres de son hôte. Une étape peut réécrire les documents propres du composant hôte, et la sortie propre d’un composant reste la même quel que soit celui qui s’y connecte, de sorte que les with: et when: d’une étape ne voient jamais les composants qui se connectent à l’hôte — que la FeatureRecipe définisse ou non la clé, qui décide du moment où l’attachement est rendu et de rien concernant ce que voit une étape. Un with: ou when: d’une étape écrit en ligne qui lit render_facts sous .context.used_by arrête donc le build avant que quoi que ce soit ne soit rendu, avec le code court E0326, en nommant la référence et le champ de l’étape — plutôt que de rendre une valeur vide. Lisez les faits propres de l’hôte dans une étape à .context.render_facts, écrit en entier, et lisez les faits des appelants dans valuesMapping:, workload: ou artifacts: de la FeatureRecipe. Cette vérification lit le template tel qu’il est écrit, avec les mêmes limites que celle ci-dessus.
Portée. La clé s’applique à une FeatureRecipe qui est rendue une fois par composant — executionScope: component, la valeur par défaut. Une FeatureRecipe qui déclare executionScope: boundary est rendue là où elle l’est toujours, qu’elle définisse ou non la clé, et les templates qui produisent ses ressources lisent .boundary plutôt que .context.
Rendu après les cibles — spec.readsTargetRenderFacts
Le champ facultatif spec.readsTargetRenderFacts (booléen, par défaut false) déclare que les templates de cette FeatureRecipe lisent ce qu’ont rendu les composants auxquels son hôte est relié : les faits de rendu que le provider de chacune de ces cibles rapporte sur la sortie qu’il a émise. Il lit l’autre extrémité d’une connexion par rapport à readsCallerRenderFacts — les composants vers lesquels pointent les entrées uses de l’hôte, plutôt que les composants dont les entrées uses pointent vers l’hôte — et tout ce qui concerne les faits eux-mêmes se lit de la même manière.
L’une ou l’autre clé fait rendre l’attachement après chaque composant. Un attachement dont la FeatureRecipe définit readsCallerRenderFacts: true, readsTargetRenderFacts: true, ou les deux, est rendu une fois que chaque composant du build a été rendu, comme le décrit la section ci-dessus — il n’existe qu’un seul rendu ultérieur de ce type, et ce qu’il implique pour l’endroit où aboutit la sortie de l’attachement et pour l’ordre de ses étapes de pipeline est identique quelle que soit la clé qui y a déplacé l’attachement. Les deux clés ne diffèrent que par les connexions qui portent des faits dans le contexte de l’attachement : une cible qui vient après l’hôte dans l’ordre du build a été rendue d’ici là, de sorte que ce qu’elle a émis est disponible à la lecture.
Ce qu’il lit. Avec la clé définie, chaque entrée de .context.uses porte .render_facts : les faits de rendu de la cible, indexés par nom de fait, sous la forme que porte l’entrée d’un appelant. Chaque fait de rendu est une liste, de sorte qu’un template la parcourt toujours avec range. Ses entrées peuvent provenir du rendu propre de la cible et des rendus des Features attachées à la cible, d’abord les appels du provider propre de la cible, puis chacune de ses Features dans l’ordre où elles ont été rendues ; une Feature de la cible qui est elle-même rendue après chaque composant n’en fait pas partie. Une cible dont les providers ne rapportent rien porte un .render_facts vide. Un template lit les faits d’une connexion sous son alias, .context.uses.<alias>.render_facts.<name>, ou ceux de chaque connexion tour à tour :
artifacts: targets.yaml: | targets: {{- range .context.uses }} - component: {{ .target }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}Une FeatureRecipe qui ne définit pas la clé ne voit aucun .render_facts sur aucune connexion, quoi qu’elle définisse par ailleurs. Les noms de faits qui existent relèvent du contrat documenté du provider de chaque cible — ceux du provider helm sont ses faits de rendu, qui nomment les labels, les sélecteurs de contrôleur et les ports de conteneur des pods qu’il a rendus, et donc ce dont une politique d’egress a besoin pour sélectionner exactement les pods que son hôte peut joindre.
Déclarez-la chaque fois qu’un template lit les faits. Un template écrit en ligne dans une FeatureRecipe qui ne définit pas la clé — son valuesMapping:, son workload: ou une entrée artifacts: — et qui lit render_facts sous .context.uses arrête le build avant que quoi que ce soit ne soit rendu, avec le code court E0347, en nommant la référence et le champ dans lequel elle a été écrite (voir « A template reads its targets’ render facts without declaring it (Un template lit les faits de rendu de ses cibles sans le déclarer) » dans fatal-halts.md). Définir readsCallerRenderFacts ne la lève pas. La vérification lit le template tel qu’il est écrit, avec les limites de la vérification des appelants : elle ne voit pas une référence construite pendant l’exécution du template, ni une référence écrite dans du contenu importé d’un fichier ou d’une bibliothèque — et un template qui lit .context.uses d’une manière quelconque et lit aussi un champ nommé render_facts sur une autre valeur, y compris l’entrée d’un appelant dans {{ range .context.used_by }}, est traité comme lisant les faits de ses cibles. Un template qui lit les faits des deux extrémités définit les deux clés.
Une étape de pipeline ne lit que les faits propres de son hôte. Les with: et when: d’une étape lisent les connexions qu’établit l’hôte, comme les lit la Recipe propre de l’hôte, et jamais les faits de rendu de leurs cibles — que la FeatureRecipe définisse ou non la clé. Une étape peut réécrire les documents propres du composant hôte, et le rendu propre de l’hôte lit ce que ses cibles publient, jamais ce qu’elles ont émis. Un with: ou when: d’une étape écrit en ligne qui lit render_facts sous .context.uses arrête donc le build avant que quoi que ce soit ne soit rendu, avec le code court E0348, en nommant la référence et le champ de l’étape — plutôt que de rendre une valeur vide. Lisez les faits des cibles dans valuesMapping:, workload: ou artifacts: de la FeatureRecipe.
Portée. Comme pour la clé des appelants : elle s’applique à une FeatureRecipe qui est rendue une fois par composant. Une FeatureRecipe qui déclare executionScope: boundary est rendue là où elle l’est toujours, qu’elle définisse ou non la clé, et les connexions qu’elle lit sous .boundary ne portent aucun fait de rendu.
Le bloc locals:
FeatureRecipe.spec.locals: est une map facultative de chaînes de template Go nommées dont la sortie rendue expose une map .locals.* à tous les autres templates de la même FeatureRecipe. C’est l’équivalent, privé à la FeatureRecipe, du locals: de la Recipe — un endroit où calculer une seule fois des chaînes dérivées et les référencer depuis injectMapping, valuesMapping, pipeline[].with et provides sans les recalculer. Les assertions: de la FeatureRecipe ne les lisent pas : les .locals d’une assertion sont ceux de la Recipe du composant hôte, comme l’indique assertions-block.md. La sortie rendue de chaque entrée est stockée sans ses espaces de début et de fin. Le bloc est une map, et non un corps de template unique ; un scalaire à cette position est rejeté par le schéma.
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: regional-routerspec: implements: core/regional-router:^1.0.0 capability: helm locals: region_prefix: "{{ .infra.region | lower }}" fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}" injectMapping: | env: "{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}".locals.* est propre à chaque invocation : chaque invocation de FR résout son propre bloc locals:, et le résultat n’est visible que par les templates en aval de cette invocation. Le bloc est résolu avant l’évaluation des autres templates de la surface de rédaction de la FR, de sorte que chacun d’eux voit des valeurs résolues.
Chaque entrée est évaluée par rapport à un contexte autonome : .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra et les entrées de ce même bloc déjà résolues. Ce contexte est délibérément plus restreint que celui que lisent les autres templates de la FR — une entrée de locals: ne peut pas atteindre .context.annotations, .context.inject, .context.uses ou .provides, et une référence à l’un d’eux interrompt le build en nommant la référence. Les valeurs dérivées qui ont besoin de ces piliers ont leur place dans le template qui les lit, et non dans locals:.
Les noms de ce contexte répondent à des questions différentes, et une entrée de locals: les lit exactement comme le font les autres templates de la FeatureRecipe :
.context.instance_idest le composant hôte pour lequel le rattachement est résolu. Il désigne le composant hôte sur chaque surface de template que le compilateur évalue, de sorte que la même référence se lit de la même façon quelle que soit l’entité dont vous écrivez le bloc..context.rendered_nameest le nom du composant hôte tel que son propre provider le rapporte — soushelm, le nom de la release, c’est-à-dire l’identité de l’hôte écrite dans l’alphabet qu’admet un nom Kubernetes. Il n’est présent que là où le provider de l’hôte rapporte un nom, et le lire sur un hôte dont le provider n’en rapporte aucun interrompt le build..attachment_nameest l’instance de rattachement en cours de résolution — l’emplacement qu’elle occupe dans lefeaturesSchemade l’entité propriétaire, ou le nom libre que vous lui avez donné.
Ainsi, une entrée de locals: qui dérive un nom pour une ressource émise compose l’hôte et le rattachement, exactement comme le ferait un template de artifacts: :
spec: locals: scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_targetLorsque le nom doit être accepté par la plateforme et que le provider de l’hôte en rapporte un, composez-le plutôt à partir de .context.rendered_name : pour un hôte nommé my_api sous helm et un rattachement scrape, {{ .context.rendered_name }}-{{ .attachment_name }} donne my-zuapi-scrape, là où l’identité donnerait my_api-scrape, qu’un nom Kubernetes refuse. Voir Nommer une ressource rendue.
.values et .infra dans une entrée de locals: sont les piliers propres au rattachement, rédigés sur la déclaration du rattachement — et non ceux du composant hôte.
L’ordre d’écriture est déterminant
Les entrées sont résolues dans l’ordre où elles sont écrites, et une entrée peut lire une entrée sœur définie au-dessus d’elle, recevant la valeur résolue de cette entrée sœur :
spec: locals: region_prefix: "{{ .infra.region | lower }}" # defined first bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry aboveLe chaînage ne fonctionne que vers le bas. Lorsqu’une entrée en lit une autre, l’ordre des entrées décide si le build réussit : déplacez region_prefix sous bucket et le build s’interrompt. Le compilateur ne réordonne jamais le bloc pour qu’une référence se résolve ; réordonner un bloc locals: est donc un changement de comportement, et non un changement cosmétique.
Une référence à une entrée que le bloc définit plus loin interrompt le build en nommant l’erreur d’ordre (déplacez la définition au-dessus de son lecteur) ; une référence à une clé que le bloc ne déclare pas du tout l’interrompt en nommant la clé (corrigez l’orthographe). La vérification suit un alias du bloc : une clé atteinte via le point qu’un corps with .locals relie à nouveau, ou via une variable liée à .locals, interrompt le build exactement dans les mêmes termes que l’écriture directe, tout comme une clé lue sur le bloc entre parenthèses — {{ (.locals).nope }} ou {{ ($.locals).nope }}. Une seule écriture y échappe : une clé atteinte via un appel dont le texte du template ne peut pas nommer le résultat — {{ index .locals "nope" }}, ou {{ (default dict .locals).nope }}. Un champ lu sur le résultat d’un tel appel n’interrompt pas le build et rend le texte littéral <no value> ; la lecture avec index l’interrompt en nommant la clé, car index interrompt le build sur chaque surface de template lorsque la map qu’il lit ne contient pas la clé — voir errors/fatal-halts.md « A template indexes a map with a key the map does not hold (Un template indexe une map avec une clé que la map ne contient pas) ». provides: lit le bloc entièrement résolu, car les locals de cette FeatureRecipe sont résolus avant ses provides ; un template de provides: qui nomme une clé non déclarée interrompt le build. Ce sont les mêmes règles que suit le bloc locals: d’une Recipe — voir entities/recipe.md « Le bloc locals: ».
Comportement selon la portée. Pour executionScope: component (par défaut), locals: est évalué pour chaque instance de composant rattachée, par rapport au contexte autonome ci-dessus. Pour executionScope: boundary, locals: est évalué pour chaque rattachement de frontière, par rapport à la vue de portée frontière enracinée en .boundary.* ; les champs par composant (.context.instance_id, .context.inject, .context.uses) et .attachment_name ne sont pas disponibles, car la FeatureRecipe s’exécute une fois pour la frontière plutôt qu’une fois par composant. La liste d’autorisation des champs de template de portée frontière s’applique à locals: de la même manière qu’aux autres templates de la surface de rédaction de la FR. L’injectMapping, qui s’exécute pour chaque composant que le rattachement atteint, lit cette unique évaluation de frontière comme son .locals. Le contrat d’évaluation — ordre d’écriture, lectures des entrées sœurs uniquement vers le bas, les deux interruptions — est identique aux deux portées ; seule la forme du contexte environnant diffère.
Distinction avec les overlays de injectMapping et les mappings de pipeline[].with. locals: produit une map visible dans le contexte pour les templates en aval ; il ne contribue à aucune sortie. injectMapping écrit dans le pipe .context.inject du consommateur (mutation côté appelant). pipeline[].with fournit le payload args du plugin Wasm. Les trois surfaces sont orthogonales — une FeatureRecipe utilise couramment les trois ensemble, locals: portant les chaînes dérivées partagées que les deux autres référencent.
Le bloc assertions:
FeatureRecipe.spec.assertions: est une map facultative de règles nommées exprimant des invariants d’implémentation de la FeatureRecipe — des règles inter-champs qui valent compte tenu du pipeline de plugins Wasm, du chart ou du mécanisme spécifique sur lequel la FeatureRecipe est construite. Chaque clé est un identifiant de règle qui apparaît dans le message d’échec ; chaque valeur est un corps de template Go. Comme les assertions de Recipe, les assertions de FeatureRecipe sont des propriétés de l’implémentation spécifique ; les règles de contrat au niveau de la Feature s’appliquent indépendamment, à une phase antérieure du pipeline.
spec: implements: core/referenced-secret:^1.0.0 pipeline: - id: fetch_secret plugin: pipeline-step/aws-secrets-manager:1.2.0 function: step assertions: # aws-secrets-manager plugin 1.x requires an explicit region when none is # implied through the Aggregate's infra block. region-supplied-for-secrets-manager: | {{- if not .values.region -}} {{- if not .infra.aws.region -}} {{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}} {{- end -}} {{- end -}}La règle ci-dessus est propre au plugin aws-secrets-manager 1.x ; elle ne s’applique pas si une autre FeatureRecipe core/referenced-secret est liée. Les règles de contrat au niveau de la Feature issues de la définition de la Feature s’appliquent toujours en parallèle.
Les assertions de FeatureRecipe sont évaluées après la liaison de la FeatureRecipe et avant la génération des ressources. Le contexte de template des FR de portée composant reprend le contexte des assertions de Recipe (champs de l’instance d’entité, plus .provides, .locals, .recipe.metadata, .recipe.source) ; pour les FR de portée frontière (executionScope: boundary), les assertions sont évaluées par rapport à la vue de portée frontière (champs .boundary.* disponibles ; champs par composant non disponibles). Pour la grammaire de rédaction complète et des exemples détaillés, voir templates/assertions-block.md.
Le champ omits: — exclure des documents rendus d’une source
La plupart des FeatureRecipes n’en ont jamais besoin. Il s’adresse à une FeatureRecipe dont le source: est un chart que vous prenez tel quel — le plus souvent un chart récupéré depuis un registre — et qui rend un document que le rattachement ne doit pas émettre : un Secret que le chart régénère à chaque rendu, ou un objet que le composant hôte ou l’opérateur fournit déjà. omits: exclut un tel document de ce que la FeatureRecipe génère — ou, pour un fichier compose que la FeatureRecipe utilise comme source, un service, un volume ou une config que le rattachement ne doit pas apporter, et pour un template CloudFormation qu’elle utilise comme source, une ressource.
spec: capability: helm implements: core/observability/collector:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/collector version: "0.9.1" omits: # The collector chart ships its own ServiceAccount; the host supplies one. - kind: ServiceAccount name: collector - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: collector-dashboardsLa clé s’écrit de façon identique sur une Recipe, et Recipe → Le champ omits: en est la référence complète : ce que sélectionne chaque champ d’une entrée, le fait que when: est évalué en premier et qu’une valeur fausse écarte l’entrée, que chaque entrée qui s’applique doit exclure quelque chose, faute de quoi le build s’interrompt en la nommant, que la source est toujours rendue en entier et que seule sa sortie est filtrée, et quels providers respectent la clé. Sur une FeatureRecipe, seul diffère l’endroit où les templates sont évalués :
- Les templates de chaque entrée sont évalués par rapport au contexte dans lequel le
valuesMapping:de cette FeatureRecipe est évalué, à la portée que sélectionne sonexecutionScope. Les entrées d’une FeatureRecipe de portée composant sont évaluées une fois par rattachement, par rapport aux.valueset.infrade ce rattachement ; celles d’une FeatureRecipe de portée frontière une fois par frontière, par rapport à la vue de portée frontière et au.infradu rattachement de frontière. Les règles sur ce que les templates d’un rattachement peuvent lire s’appliquent aux entrées comme à sonvaluesMapping:. - Seul ce que rend le
source:propre à cette FeatureRecipe est filtré. Sonworkload:et sesartifacts:ne le sont pas, ni la sortie du composant hôte : les entrées d’un rattachement atteignent son propre chart, son propre fichier compose ou son propre template CloudFormation, et rien d’autre — un service compose que l’hôte déclare sous la même clé dans ledocker-compose.yamloù les deux sont assemblés n’est pas touché, pas plus qu’une ressource que l’hôte déclare sous le même ID logique dans la stack où les deux sont assemblés. Pour modifier un document que l’hôte rend, la Recipe de l’hôte déclare l’entrée, ou une étapepipeline:le corrige.
Une interruption sur une entrée nomme le nœud, le provider, cette FeatureRecipe et la position de l’entrée dans sa liste omits: ; pour une FeatureRecipe de portée frontière, la ligne au-dessus du message nomme le rattachement et sa frontière.
Pour un exemple détaillé de la clé, rédigée sur une Recipe — le Secret généré d’un chart récupéré exclu, et les interruptions sans l’entrée et sur une entrée qui ne correspond à rien —, voir ai-gateway-own-webhook-certificate.