Recipe
Le rôle conceptuel de l’entité Recipe (le modèle de traduction rédigé par Ops qui projette le Developer Intent dans le format physique) est décrit dans architecture/04-entity-taxonomy.md. Cette page couvre la surface de rédaction de la Recipe — le pointeur (source), le mapper (valuesMapping:), la prise en charge native de l’IaC et des exemples détaillés.
L’architecture de la Recipe : pointeurs et mappers
Une Recipe remplit exactement deux fonctions :
- Le pointeur (
source) : indique au compilateur exactement où se trouve le code d’infrastructure. - Le mapper (
valuesMapping) : injecte le contexte abstrait d’Aggrega dans les variables spécifiques qu’attend le code sous-jacent. Le champ est une surface unique de template Go avec trois modes de rédaction — block scalar inline,$import:de fichier ou$import:de bibliothèque — sélectionnés selon la forme du contenu. Voir Le champvaluesMapping— trois modes de rédaction ci-dessous.
Comme une Recipe correspond strictement 1:1 à une capacité de rendu, cette capacité (spec.capability) est déclarée explicitement au niveau racine, ce qui garantit que le compilateur Go sait exactement quel plugin de rendu Wasm en aval invoquer.
spec.implements déclare quel type de composant du catalogue la Recipe est capable d’implémenter. Le compilateur s’en sert pour vérifier les mappages du Manifest (le implements d’une Recipe mappée doit correspondre au type mappé) et pour suggérer des candidates — les recipes listées dans un diagnostic d’absence de mappage et classées en premier dans la complétion de l’éditeur. Il ne résout jamais un build : le mappage du Manifest est le choix de déploiement explicite de l’utilisateur, figé dans le lockfile. Une Recipe dont le implements est sans version, exact ou une plage compatible avec la version majeure ne fait toujours que se proposer pour un type ; l’utilisateur fige le choix. FeatureRecipe.spec.implements joue le même rôle pour les types de feature.
A. Schémas de source pilotés par Wasm
Pour tenir les biais d’implémentation à l’écart du compilateur, le bloc source n’est pas un ensemble fixe de champs d’infrastructure. Le champ source prend en charge deux formats :
- La chaîne universelle (rapide et propre) : idéale pour les chemins locaux, les artefacts OCI et les dépôts Git. Le compilateur déduit la méthode de récupération du préfixe et du suffixe de la chaîne (
./src,https://github.com/example/module.git,oci://...) : une URL se terminant par.git, ou écrite avecgit://oussh://, est un dépôt Git récupéré sur sa branche par défaut, et une URLhttps://ne désignant ni un dépôt ni un chart.tgzou un fragment.yamlest refusée comme ambiguë. - L’objet structuré ouvert : un dictionnaire ouvert (
additionalProperties: true) dont les clés sont définies par le provider et exposées aux templates de la Recipe sous la forme.source.*(par exemple.source.chart). L’intention de conception est que le socket WebAssembly de chaque provider définisse et valide sa propre forme de source (p. ex.registry/chart/appVersionpour Helm).
Ce que le cœur résout. Aucun provider ne valide de clés de source qui lui soient propres. Une source récupérée est résolue par une identité intégrée dont le kind sélectionne un résolveur — helm-oci-chart, helm-https-chart, compose-https-fragment et git-repository. Une source destinée à être récupérée doit porter kind et url ; la coordonnée supplémentaire qui sélectionne le contenu dépend du kind. Les kinds chart et fragment prennent version, et l’épinglent telle qu’elle est écrite. git-repository prend ref — un tag, une branche ou un commit — et, facultativement, module_subdir, qui désigne le répertoire du dépôt constituant l’artefact ; comme seul un commit désigne un contenu qui ne peut pas être redirigé, la référence est résolue au moment du verrouillage et le lockfile enregistre à la fois la référence rédigée et le commit vers lequel elle a été résolue. Un module_subdir qui, tel qu’il est écrit, remonte au-dessus du dépôt — une barre oblique inverse compte comme séparateur — est refusé avant toute récupération. Le dépôt est archivé à partir de sa propre extraction : un lien symbolique qu’il commite est archivé comme le fichier ou le répertoire vers lequel il pointe lorsque celui-ci se trouve dans le dépôt, et un lien qui en sort interrompt le pull, en nommant le lien par son emplacement dans le dépôt. Une source structurée dont le champ url: désigne un chemin du système de fichiers n’est pas récupérée : elle est lue depuis le disque dans les mêmes conditions qu’une simple chaîne de chemin, un champ url: relatif étant ancré au répertoire qui contient le fichier d’entité qui le déclare. Une source structurée qui omet kind/url n’est pas récupérée non plus, et si une récupération était prévue, le build s’interrompt explicitement lors de la descente des sources au moment du verrouillage plutôt que de se résoudre silencieusement en rien. Le contenu est toujours épinglé à l’avance ; le compilateur ne récupère jamais l’état d’exécution en direct.
Ce qui est épinglé à côté de la Recipe. Pour une source récupérée dont kind, url, chart, module_subdir, version et ref sont tous écrits en clair plutôt que générés par template, aggrega pin enregistre l’empreinte de ce qu’il a récupéré dans entity.lock, un fichier du répertoire propre de la Recipe que vous commitez à côté d’elle. L’épinglage est une étape de l’auteur de la Recipe et ne nécessite aucune Release ; un pull sur une Recipe dont le lock n’enregistre pas l’épinglage s’interrompt et le nomme, sauf si l’on demande au pull d’exécuter la même étape. Un build compare cette empreinte à celle que le lockfile de la Release enregistre pour la même source, et s’interrompt lorsque les deux divergent — sauf pour une source écrite avec un ref: git, dont la ligne est enregistrée au commit vers lequel la ref a été résolue et n’est pas comparée. Une source récupérée dont les coordonnées sont remplies à partir d’un template est épinglée par Release à la place, dans le lockfile de chaque Release. Une source qui désigne un répertoire ou un fichier à côté de la Recipe n’est pas récupérée : aggrega pin enregistre une empreinte par fichier qu’elle apporte à ce que contient une publication de la Recipe — chaque fichier du répertoire de la Recipe, pour une source écrite comme template — et, une fois que le lock les enregistre, un build compare la source à ces empreintes avant que le provider ne la lise, et s’interrompt sur un fichier ajouté, modifié ou supprimé depuis l’épinglage — avec E0305, ou d’abord avec E0130 lorsque le lockfile de la Release, écrit avant la modification, enregistre la Recipe par ce qu’elle contient. Un lock qui n’enregistre aucun épinglage pour une telle source ne laisse rien à comparer à un build, et un pull ou une publication qui n’épingle pas la refuse. Le fichier de la Recipe lui-même n’est jamais modifié. aggrega pull décrit le fichier et la manière de répondre à chaque interruption.
spec.capability peut porter un épinglage de version sous les formes que prend implements — exacte (helm:<version>) ou une plage caret (helm:^<version>) — qui sélectionne la version du plugin du provider qui rend la Recipe ; un épinglage qu’aucune version disponible ne satisfait interrompt le build. Sans épinglage (spec.capability: "helm"), c’est la plus haute version disponible qui la rend. Les versions disponibles sont celles qu’affiche aggrega plugin list : les providers intégrés à aggrega portent la version du compilateur lui-même. L’épinglage ne fait pas partie du nom de la Recipe : un Manifest mappe une Recipe déclarant capability: "compose:1.2.3" comme compose/<name>:<version>, exactement comme une Recipe non épinglée, et changer l’épinglage ne la renomme jamais ; une valeur de mappage qui écrit l’épinglage dans le nom (compose:1.2.3/<name>:<version>) est refusée comme référence de recipe malformée (E0095) avant toute recherche.
Modèle mental : spec.capability nomme le format de sortie souhaité (p. ex. helm, terraform, compose) ; le compilateur le résout vers le plugin Wasm qui rend ce format (p. ex. provider/helm). Vous déclarez le format ; Aggrega associe l’outil.
B. Injection de contexte : la couche de mappage sémantique
Pour éviter que le compilateur n’effectue des deep-merges dangereux et non déterministes entre plusieurs environnements, une Recipe n’autorise qu’une source unique de vérité pour sa couche de mappage.
Les ingénieurs Ops rédigent le contenu de mappage pour traduire le contexte abstrait avant l’exécution du plugin de rendu Wasm. Le langage de mappage est le template Go (text/template + Sprig) ; la bibliothèque Sprig est préenregistrée ; les actions standard define et template sont prises en charge, et include n’est pas enregistrée.
| Nom du champ | Portée et phase d’exécution | Cas d’usage idéal |
|---|---|---|
injectMapping (FeatureRecipe uniquement) | Interception avant rendu. Évalué dans la mémoire Go avant la Recipe de base. Fusionne nativement en profondeur son dictionnaire de sortie strictement par-dessus le pipe .context.inject de l’appelant. Volontairement absent du schéma Recipe de base — voir entities/featurerecipe pour la justification architecturale. | Réécrire de façon ciblée les variables env injectées ou formater des FQDN pour un appelant sans recourir à un JSONPatch Wasm. |
valuesMapping | Rendu de base (template Go). Évalué pour mapper les variables dans le chart/module d’infrastructure source sous-jacent. Un seul champ, trois modes de rédaction (inline, $import: de fichier, $import: de bibliothèque). Voir la sous-section ci-dessous pour le mécanisme de sélection. | Mapper des variables standard (comme les réplicas ou les tags d’image) dans un chart Helm directement dans le YAML de la Recipe, ou référencer un template partagé via $import: pour une réutilisation d’une Recipe à l’autre. |
Remarque : injectMapping est réservé aux FeatureRecipes et 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.
Une clé que valuesMapping écrit comme null parvient au provider comme null, et ce qu’il en fait relève du provider, si bien que chaque page de provider le précise : helm supprime la valeur par défaut du chart pour cette clé, helm-chart l’écrit dans les values de l’umbrella, compose l’écrit dans le fichier compose, terraform l’écrit comme argument de module null, et cloudformation la refuse.
Le champ valuesMapping — trois modes de rédaction
Le valuesMapping: d’une Recipe est une surface unique de template Go qui accepte trois modes de sélection. Le compilateur sélectionne selon la forme du contenu du champ ; aucune annotation $mode: n’est nécessaire.
Mode 1 : template Go inline (block scalar YAML). La valeur du champ est une chaîne écrite sous la forme block scalar YAML | :
spec: valuesMapping: | {{- with .values -}} image: tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }} pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }} architecture: {{ optional . `architecture` "standalone" }} primary: replicaCount: {{ optional .primary `replicaCount` 1 }} {{- end }}Le mode inline est la forme de rédaction typique pour les Recipes dont le contenu de mappage est de taille petite à moyenne (moins de ~50 lignes). Le corps du template se trouve inline avec le reste de l’enveloppe de la Recipe ; le contenu de la Recipe est autonome.
Mode 2 : $import: de fichier. La valeur du champ est une map contenant uniquement $import: avec un chemin de fichier local :
spec: valuesMapping: $import: ./mappings/api-server.tmplLe compilateur charge le contenu du fichier (un template Go), en effectue le rendu avec le contexte de template standard de la Recipe et traite le résultat comme la sortie du mappage. La résolution du chemin est relative au répertoire de la Recipe — un chemin relatif est ancré au répertoire qui contient le recipe.yaml qui le déclare, et non au répertoire depuis lequel le build est lancé — et le chemin doit rester à l’intérieur de ce répertoire, comme l’explique Les chemins de contenu restent dans le répertoire propre de la Recipe. Le mode fichier convient aux contenus de mappage moyens à volumineux (~50+ lignes) et aux pratiques de revue où les modifications de mappage apparaissent comme des diffs de fichiers distincts.
Mode 3 : $import: de bibliothèque. La valeur du champ est une map contenant uniquement $import: avec une référence d’identité par simple nom vers une entrée de MappingLibrary :
spec: valuesMapping: $import: DatastoreHelpers#/mappings/MariaDBCoreLe compilateur résout la référence par rapport à l’ensemble de MappingLibrary résolu (le catalogue local plus toutes les bibliothèques épinglées dans le lockfile), charge le contenu de l’entrée et le traite comme la sortie du mappage ; une entrée dont le corps est lui-même un $import: à la racine du champ est résolue récursivement. La référence ne porte aucun hôte de registry — le nom de la bibliothèque est résolu par identité et la version provient du lockfile par Release, avec un plancher de version minimale facultatif :<version> (<Library>:<version>#/mappings/<entry>). Le contenu de bibliothèque partage le contexte de template standard de la Recipe. Le mode bibliothèque convient à la réutilisation d’une Recipe à l’autre — des motifs de mappage qui reviennent dans de nombreuses Recipes (plusieurs Recipes de datastore partageant une logique d’assistance pour datastore ; plusieurs Recipes du provider Helm partageant des motifs de pod template). L’entité MappingLibrary fournit le versionnage, l’épinglage dans le lockfile et l’exposition dans l’interface du hub.
Règles de sélection. Le compilateur parcourt le nœud YAML et sélectionne selon la forme du contenu :
- Si le nœud est un scalaire de type chaîne, on sélectionne le mode inline (Mode 1).
- Sinon, le nœud est une map ; on vérifie la présence de la clé
$import:. - Si la valeur de
$import:est une référence de bibliothèque par simple nom (<Library>#/mappings/<Entry>, éventuellement avec un plancher:<version>), on sélectionne le mode bibliothèque (Mode 3). - Sinon (un chemin de fichier local), on sélectionne le mode fichier (Mode 2).
- Toute autre forme (une map sans
$import:, une map avec des clés supplémentaires au-delà de$import:, etc.) produit une erreur au moment du build.
$import: à source unique uniquement. $import: accepte une seule source. La fusion de plusieurs sources n’est pas prise en charge dans valuesMapping:. Une Recipe qui doit composer plusieurs fragments de mappage utilise une entrée de MappingLibrary avec une composition interne define / template de template Go, un fichier local avec des directives template de template Go qui invoquent des fichiers voisins, ou une composition inline pour un contenu court. Voir entities/mappinglibrary pour l’entité de bibliothèque, et vocabulary/cross-document-ref pour la distinction plus générale $ref: / $import:.
Provenance. Les messages d’erreur issus d’échecs de rendu de template citent la provenance appropriée à chaque mode : les templates inline citent le fichier:ligne de la Recipe où commence le block scalar ; les imports de fichier citent le contenu du fichier importé ; les imports de bibliothèque citent la position source de l’entrée de la MappingLibrary, avec l’identité de bibliothèque sans hôte (<Library>#/mappings/<entry>) comme pointeur canonique pour des références stables — un hôte de registry dans une référence est refusé, de sorte que l’emplacement physique n’entre jamais dans le pointeur.
C. Prise en charge native de l’IaC
Une équipe Ops qui apporte son propre infrastructure-as-code le conserve dans le répertoire propre de la Recipe — un répertoire de module ou de template tel que ./src, désigné par source: — ou le récupère avec un source: structuré (un module Terraform depuis son dépôt git, avec kind: git-repository), ou l’écrit sous forme de corps templatés sous artifacts:. La couche de mappage (valuesMapping: — inline, import de fichier ou import de bibliothèque) fournit le contexte abstrait à ce code, et le provider émet le résultat dans le format propre à la cible ; aucun langage de configuration n’est converti en un autre :
- Terraform : un module est copié fichier par fichier, et un corps rédigé est émis exactement tel qu’il est écrit, en HCL natif (
main.tf) comme en Terraform JSON (.tf.json) — la CLIterraformlit les deux. La configuration racine du boundary,aggrega.modules.tf, appelle le répertoire de chaque composant comme un blocmodule, et la sortievaluesMapping:d’un module sourcé devient les arguments de ce bloc. Voir le provider terraform. - CloudFormation : un template sourcé, YAML ou JSON, et les fragments de ressources qu’une Recipe rédige sont normalisés en JSON au format long et fusionnés en un seul template de stack par boundary, la sortie
valuesMapping:remplissant les paramètres que déclare un template sourcé. Voir le provider cloudformation.
Une valeur qui n’existe qu’une fois l’infrastructure appliquée reste un pointeur que la cible résout — une interpolation Terraform ${ ... }, un Ref ou un Fn::GetAtt CloudFormation — et n’est jamais évaluée au moment du build.
Exemple A : le chart Helm distant (mapping inline et contrat des locals)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-chart version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:1.0.0 source: # The shipped fetch form: { kind, url, version }. 'kind' selects a built-in # resolver (helm-oci-chart, helm-https-chart, compose-https-fragment). kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb # Default chart version. Override via infra.source_version. version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals: primary_compute: mariadb listen_port: "3306" volumes_path: "/spec/template/spec/volumes" root_path: "/-" # The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm # pipeline: the suffix it follows the rendered name with. A local cannot read # .context.rendered_name, so each template writing the full name joins the two. secret_target_db_password: "mariadb-auth"
provides: # The chart's primary Service, named by the fullnameOverride pinned below host: "{{ .context.rendered_name }}" port: "3306" # Every key the Component's provides contract declares is published user: "{{ .values.user }}" database: "{{ .values.database }}" protocol: "mariadb"
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}" auth: # Reads the suffix from the local rather than restating it, so the secret # name is authored once and every reader follows that one definition existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}" primary: persistence: size: "{{ .infra.storage.size }}"Exemple B : le module Terraform local (mapping par fichier)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-s3-tf version: 1.0.0spec: capability: terraform implements: aws/s3-bucket:1.0.0 source: "./src"
locals: primary_compute: bucket_instance resource_path: "/resource/aws_s3_bucket/main" root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments valuesMapping: | bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" region: "{{ .infra.aws_region }}"Exemple C : Recipe de Component concrète (lie l’infrastructure) Ops fait correspondre l’interface générique à la réalité physique. (C’est ici que les détails réseau L4 sont liés — soit codés en dur, soit, comme pour le port du proxy ci-dessous, tirés du bloc infra que la Release renseigne.)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: kong-gateway version: 1.0.0spec: capability: helm implements: core/gateway/kong:1.0.0 source: # A chart repository root paired with the chart's name. kind: helm-https-chart url: https://charts.konghq.com chart: kong version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides: # The chart's proxy Service: it suffixes the name pinned below with "-proxy" host: "{{ .context.rendered_name }}-proxy" port: "{{ .infra.proxy_port }}" protocol: "http" # The contract's other keys: empty while nothing is wired to the models # socket, and while metrics are off endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}' model: '{{ optional .values "model" "" }}' metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}"Discipline de nommage des ressources cloud.
Les Recipes qui émettent des noms de ressources cloud — noms de buckets S3, identifiants de bases de données RDS, noms de rôles IAM, noms de stacks CloudFormation et tout autre champ dont la valeur occupe un espace de noms global chez le fournisseur cloud — doivent concaténer {{ .metadata.release_name }} et/ou {{ .context.instance_id }} dans le nom rendu afin d’éviter les collisions lorsque la même Recipe s’exécute sur plusieurs Releases ou instances de composant. Le bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" de l’exemple B est le modèle canonique.
La discipline s’applique partout où un espace de noms global unique contraint le nom. Les noms de buckets AWS S3 partagent un espace de noms global entre tous les comptes d’une région ; deux Releases du même Aggregate (prod-billing et staging-billing) ne peuvent pas toutes deux déployer des buckets nommés customer-data — le second déploiement échoue à l’exécution avec un rejet côté AWS. Concaténer release_name différencie la Release ; concaténer context.instance_id différencie par instance de composant ; concaténer les deux différencie par composant et par Release.
Ce que le compilateur vérifie et ne vérifie pas. Le compilateur n’inspecte pas les sorties de valuesMapping: à la recherche de champs de noms de ressources cloud dépourvus de ces interpolations. La discipline est maintenue par les auteurs de Recipe (qui savent quels champs nomment des ressources globalement uniques pour le provider cible) et par les relecteurs (qui repèrent les motifs de ressources non nommées lors de la revue de PR). Un plugin linter pourrait signaler les Recipes dont les sorties de valuesMapping: référencent des champs de noms de ressources cloud sans interpolation de release_name / instance_id ; le socket linter est livré et s’exécute via aggrega lint (voir plugins/plugin-contract.md « Critère de placement : le socket linter face aux rôles de verdict de gouvernance »), et aucune des règles du linter de publication ne vérifie cela.
Cette discipline est l’un de plusieurs contrats sociaux maintenus par convention — une discipline d’écriture que les auteurs apprennent dans la documentation plutôt que par l’application du compilateur. Voir vocabulary/social-contracts.md pour la liste complète des conventions et la justification architecturale de la classification de chaque contrat.
Templating du champ source. Le champ source d’une Recipe est lui-même une surface de templating. Les deux formes de source acceptent des templates Go : la forme chaîne universelle
source: "{{ optional .infra `module_path` \"./src\" }}"et la forme objet structuré (chaque sous-champ à valeur chaîne est évalué comme template ; les sous-champs non-chaîne passent tels quels). Ce qu’un template de source peut lire dépend du fait que la source désigne ou non un artefact distant. La coordonnée d’une source distante — version, chart, ref et module_subdir d’un bloc structuré désignant 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, avec .values, .infra et .locals uniquement, avec les helpers propres à Aggrega (optional, capitalizedWords et index) et aucune des fonctions de Sprig. .context n’est pas disponible sur cette surface : l’artefact épinglé pour un composant est donc décidé par les values et l’infra qu’il reçoit, et jamais par son nom d’instance. Les entrées locals: évaluées à ce stade sont celles que ces champs lisent, et celles qu’une telle entrée lit à son tour : une entrée qu’aucun champ de source ne lit n’est pas évaluée pendant la résolution de la source, de sorte qu’un local dont seul le rendu a besoin — un local qui appelle une fonction Sprig, ou qui lit .context.instance_id — n’affecte pas l’épinglage et est évalué lorsque le nœud est rendu. Un champ qui lit .locals d’une manière ne désignant aucune entrée précise, comme {{ index .locals "version" }}, fait évaluer toutes les entrées. Une source désignant un chemin dans le workspace, comme celle ci-dessus, n’est pas résolue pour l’épinglage : son template est évalué lorsque le nœud est rendu, dans le même contexte autonome que les locals d’une Recipe — .context.instance_id, .values, .infra et .locals, l’ensemble du bloc résolu du nœud — de sorte qu’elle admet et refuse les mêmes racines de référence qu’une entrée locals:, avec une différence en sa faveur : elle peut lire n’importe quelle entrée déclarée par le bloc, et pas seulement les entrées situées au-dessus d’elle. Une coordonnée distante peut de même lire n’importe quelle entrée déclarée par le bloc. .provides n’est disponible dans aucun des deux contextes, et un template de source qui cherche à atteindre les provides de son propre nœud arrête le build et nomme la référence fautive. C’est une propriété fixe de la surface et non une lacune en attente de travaux ultérieurs — les locals d’un nœud sont résolus avant ses provides afin que provides: puisse lire .locals, et un template de source lit ces mêmes locals résolus au lieu d’aller chercher en avant les provides. Les références à .context.inject et .context.uses sont interdites pour les mêmes raisons d’autonomie ; l’URI de la source doit être résolue avant que le pipe de topologie ne soit hydraté et avant que quoi que ce soit en aval ne charge le chart, le module ou le corps d’artefact vers lequel pointe l’URI. Les règles complètes de disponibilité et la justification des références interdites se trouvent dans la ligne #5 de la matrice d’expansion des templates. L’usage canonique est une surcharge infra.source_version exposée par le Component et transmise au champ de version de la source — voir entities/component « Le pilier infra » — afin qu’un catalogue n’ait pas à republier une Recipe à chaque montée de version amont compatible.
Inventaire des schémas du champ source. Le champ source: accepte plusieurs variantes de forme dans le schéma. La prise en charge à l’exécution de chaque variante varie selon le provider ; le tableau ci-dessous documente ce que fait chaque forme.
| Forme | Exemple | Statut |
|---|---|---|
| Chemin relatif simple du système de fichiers | source: "./charts/postgres" | available — chaque provider livré (helm, helm-chart, compose, terraform, cloudformation) accepte une chaîne de chemin simple du système de fichiers. |
| Chemin absolu simple du système de fichiers | source: "/abs/path/to/chart" | accepted but blocked — le schéma l’accepte et chaque commande qui lit la Recipe le refuse : un chemin absolu désigne un emplacement sur la machine où il a été écrit plutôt qu’un contenu situé dans le répertoire propre de la Recipe, il ne voyagerait donc pas avec la Recipe. Déplacez le chart dans le répertoire de la Recipe et désignez-le relativement à celui-ci ; voir Les chemins de contenu restent dans le répertoire propre de la Recipe. |
| Chaîne vide | source: "" | accepted but blocked — le schéma accepte la chaîne vide et chaque commande qui charge la Recipe la refuse au moment où la Recipe est lue, car une chaîne vide ne nomme aucun des deux modes. Le refus nomme l’ambiguïté ainsi que les deux façons d’en sortir : omettre le champ pour le mode sans source, ou lui donner un vrai chemin ou une vraie URI pour le mode avec source. aggrega validate <recipe-file> la signale pour la Recipe, et aggrega pull, aggrega build et aggrega validate --release la signalent pour une Release qui atteint la Recipe. Voir errors/fatal-halts.md « Recipe source: is an empty string (Le champ source de la Recipe est une chaîne vide) ». |
Objet structuré dont le url: porte un schéma de transport | source: { url: "oci://…/mariadb", version: "25.0.8" } | available — le source-resolver intégré lit la forme {kind, url, version, chart, ref, module_subdir} (le schéma de url: sélectionne le type — oci:// → chart OCI, https://….tgz → archive de chart, racine de dépôt https:// associée à chart: → chart de dépôt — ou on le nomme avec kind:), récupère et épingle l’artefact lors de aggrega pull, et le build l’extrait du cache. Le vendoring local d’un chart est pris en charge comme alternative, et n’est pas obligatoire. Le schéma accepte un objet structuré ouvert. Voir providers/helm.md « Jeu de clés source: ». |
Objet structuré dont le url: désigne un chemin du système de fichiers | source: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" } | available — un url: sans schéma de transport désigne un chemin : rien n’est donc récupéré ni épinglé ; le build lit le contenu depuis le disque. Un url: relatif est ancré au répertoire contenant le recipe.yaml qui le déclare, et celui qui sort de ce répertoire — y compris s’il est absolu — est refusé : la même lecture que celle des deux lignes de chemin simple ci-dessus, et la forme dans laquelle vous l’avez écrit n’y change rien. Seul url: décide d’où le contenu est lu ; les autres champs sélectionnent ce qui serait récupéré, et atteignent toujours les templates de la Recipe sous la forme .source.*. |
URI OCI (oci://...) | source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0" | planned — objectif de conception pour la distribution de catalogues. Le résolveur actuel à trois niveaux (les fichiers qu’une Release désigne par chemin, les catalogues du workspace, le registre OCI distant) est documenté dans architecture/13-catalog-and-registry.md ; le résolveur au niveau des entités consomme les URI OCI à travers cette cascade, mais la forme OCI du champ source: propre à chaque Recipe n’est pas branchée aujourd’hui dans les providers. |
Autres schémas d’URL (https://, git+https://, etc.) | (à titre d’illustration) | planned — documenté comme intention de conception dans la feuille de route de l’architecture pour les sources enfichables ; aucune prise en charge par un provider aujourd’hui. |
Comment un chemin source: est ancré. L’ancrage s’applique aux chemins du système de fichiers et à rien d’autre, et il s’applique quelle que soit celle des deux formes qui porte le chemin. Un chemin relatif est ancré au répertoire contenant le recipe.yaml qui le déclare, et un chemin qui sort de ce répertoire — y compris un chemin absolu — est refusé, comme l’explique Les chemins de contenu restent dans le répertoire propre de la Recipe. Une référence portant un schéma de transport — oci://, https://, http://, git://, ssh://, git+ssh://, ou toute référence se terminant par .git — désigne quelque chose à récupérer plutôt qu’un chemin : elle est donc transmise exactement telle que vous l’avez écrite et n’est jamais jointe à un répertoire.
Dans la forme structurée, le chemin est le champ url:, et il est lu de la même manière : un url: relatif est ancré au répertoire contenant le recipe.yaml, celui qui sort de ce répertoire est refusé, et celui qui porte un schéma de transport est récupéré. Tous les autres champs d’un source: structuré sont transmis tels quels, y compris ceux définis par le provider.
Un source: écrit sous forme de template est ancré par rapport à la valeur que le template produit, et non par rapport au texte propre du template. Un template ne désigne rien tant qu’il n’a pas été évalué ; la lecture ci-dessus s’applique donc à son résultat : un résultat qui est un chemin relatif est ancré au répertoire contenant le recipe.yaml, celui qui sort de ce répertoire — y compris un chemin absolu — arrête le build, et celui qui porte un schéma de transport est transmis et récupéré. Un template est donc libre de produire n’importe laquelle des formes de l’inventaire ci-dessus, et chacune est traitée exactement comme le serait la même valeur écrite littéralement ; la seule différence porte sur le moment où le chemin peut être jugé, qui pour un template est celui où le build l’évalue plutôt que celui où la Recipe est lue.
Un template qui ne produit rien — un résultat vide — laisse la Recipe sans source, ce qui correspond au mode sans source. C’est différent d’écrire vous-même source: "", qui ne désigne aucun des deux modes et est refusé ; voir la ligne de l’inventaire ci-dessus.
L’inventaire est la référence canonique de ce que les auteurs peuvent mettre dans source: ; ses libellés sont ceux que définit 10-status.md.
Les chemins de contenu restent dans le répertoire propre de la Recipe
Le contenu d’une Recipe réside dans le répertoire propre de la Recipe, car chaque fichier qu’une publication de celle-ci emporte est pris à cet endroit. Chaque chemin qu’une Recipe écrit pour un contenu qu’elle emporte — son source:, qu’il s’agisse d’un chemin simple ou du url: de la forme structurée, et chaque fichier que ses entrées valuesMapping:, workload: et artifacts: importent avec $import: — est lu par rapport au répertoire contenant le recipe.yaml et doit y rester. Ces chemins sont aussi ce qu’une publication emporte : les fichiers qu’ils désignent voyagent avec la Recipe, et rien d’autre de son répertoire ne le fait (voir aggrega push). Un chemin qui sort du répertoire pointe vers un fichier qui ne voyagerait pas avec la Recipe : le fichier n’est donc pas là pour qui la consomme, et un pin enregistré dessus garantirait des octets que celui-ci ne peut pas obtenir.
Deux formes sortent du répertoire, et toutes deux sont refusées :
- un chemin qui remonte au-dessus de celui-ci, comme
../shared/charts/app; - un chemin absolu, comme
/opt/charts/app, qui désigne un emplacement sur la machine où il a été écrit.
Un chemin qui remonte puis revient à l’intérieur est un chemin ordinaire à l’intérieur du répertoire : ./charts/../values.tmpl désigne le values.tmpl situé à côté de la Recipe. Ce qui est jugé, c’est l’endroit où le chemin aboutit, mesuré depuis le répertoire de la Recipe sans le quitter — ainsi, une remontée vers l’extérieur qui nomme à nouveau le répertoire au retour, comme ../1.0.0/values.tmpl écrit dans un répertoire appelé 1.0.0, est refusée elle aussi. Le nom propre du répertoire ne voyage pas : une Recipe publiée est lue depuis un répertoire que nomme le cache du consommateur, où ce nom ne trouve rien.
Où il est refusé. Chaque commande qui lit la Recipe refuse un tel chemin au moment où elle le lit, avant que quoi que ce soit ne soit récupéré, rendu ou publié : aggrega validate, sur le catalogue ou sur le fichier propre de la Recipe, aggrega pull, aggrega build, aggrega pin et aggrega push. Un source: écrit sous forme de template ne désigne rien tant que le build ne l’a pas évalué ; un template produisant un chemin hors du répertoire est donc refusé par le build, au moment où la valeur existe. L’arrêt est A path names content outside the entity’s own directory (Un chemin désigne un contenu situé hors du répertoire propre de l’entité), et il nomme le chemin que vous avez écrit.
Que faire à la place. Placez le fichier dans le répertoire de la Recipe, ou dans un répertoire situé en dessous, et désignez-le relativement à la Recipe : ./charts/app, ./extras/netpol.yaml. Un chart utilisé par plusieurs Recipes est copié dans le répertoire de chaque Recipe, puisque chaque Recipe est publiée séparément ; un corps de mapping, de workload ou d’artefact partagé par plusieurs Recipes a sa place dans une MappingLibrary, une WorkloadLibrary ou une ArtifactLibrary, que chaque Recipe référence par identité.
Pourquoi une Release est différente. Une Release pointe vers d’autres entités — son Aggregate, son Manifest, la Release qu’elle étend — et n’est jamais publiée : rien de ce qu’elle lit ne voyage donc nulle part. Ces références, ainsi que le fichier qu’importe son parameters:, sont lues telles qu’elles sont écrites, et c’est ce qui permet à un même Aggregate d’être partagé par des variantes de Release placées dans des sous-répertoires. Voir entities/release.md.
La même limite s’applique à une FeatureRecipe, et à chaque schéma qu’un Component ou une Feature importe.
Le champ workload: — type d’entrée synthétisé
Recipe.spec.workload: déclare le corps de Workload que le compilateur synthétise en ressources natives du provider. C’est l’un des trois types d’entrée qu’une Recipe peut déclarer, aux côtés de source: (rendu à partir d’une source) et de artifacts: (manifestes auxiliaires). Au moins l’un des trois doit être présent, quel que soit le provider ; un service que le build ne provisionne pas déclare un workload: avec form: reference.
Le champ accepte trois modes d’écriture — block scalar inline, $import: de fichier ou $import: de bibliothèque. Le compilateur aiguille selon la forme du contenu du champ ; aucune annotation $mode: n’est nécessaire.
Mode 1 : inline (scalaire chaîne de template Go). La valeur est un block scalar YAML dont la sortie est analysée comme aggrega.ai/v1beta1 Workload :
spec: capability: helm implements: core/web-server:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra "replicas" 1 }} containers: app: image: "{{ .values.image }}" ports: http: 8080Les champs d’un Workload se trouvent à la racine du document — il n’y a pas d’enveloppe spec: — et containers: ainsi que les ports: de chaque conteneur sont des maps indexées par nom plutôt que des séquences, l’ordre de l’auteur étant préservé. Le provider traduit cette forme dans sa propre forme native : une entrée de la map des conteneurs apparaît ainsi dans la sortie rendue de helm comme un élément containers[] nommé d’après sa clé ; la forme écrite est la map, pas la liste rendue.
Mode 2 : $import: de fichier. La valeur est une map avec une seule clé $import: pointant vers un fichier local de template Go :
spec: workload: $import: ./workload/web-server.yaml.tmplLa résolution des chemins est la même que pour valuesMapping: : un chemin relatif est ancré au répertoire contenant le recipe.yaml qui le déclare, et non au répertoire depuis lequel le build est lancé, et il doit rester à l’intérieur de ce répertoire. Le corps importé est un template Go évalué dans le contexte de rendu de la Recipe, exactement comme un corps inline.
Mode 3 : $import: de bibliothèque. La valeur est une map avec une seule clé $import: portant une référence d’identité par nom simple vers une entrée d’une WorkloadLibrary :
spec: workload: $import: BaseWorkloads#/workloads/StatelessServiceC’est le fragment #/workloads/ qui sélectionne une entrée Workload, et c’est lui qui distingue cette référence de la forme #/mappings/ qu’utilise valuesMapping: — celle-ci adresse une entrée d’une MappingLibrary et ne désigne pas un corps de Workload. La référence ne porte aucun hôte de registre, la version résolue provient du lockfile propre à chaque Release, un plancher de version minimale :<version> facultatif peut être exprimé sous la forme <Library>:<version>#/workloads/<Entry>, et une entrée dont le corps est lui-même un $import: à la racine du champ se résout récursivement. Le corps importé est un template Go évalué dans le contexte de rendu de la Recipe qui le consomme, de sorte que .values, .infra et .features y circulent exactement comme dans un corps inline. Voir entities/workloadlibrary pour l’entité bibliothèque et la grammaire complète des références.
Le provider cible doit prendre en charge la synthèse (le catalogue de la bibliothèque standard déclare workloadSchema sur de tels providers par convention) ; cibler un provider qui ne peut pas synthétiser est refusé lorsque le nœud est rendu, avec le diagnostic de capacité du provider — fondé sur la capacité du provider, et non sur la présence de workloadSchema. Pour la grammaire complète de Workload, les champs transmis tels quels de forme K8s et le comportement de traduction propre à chaque provider, voir entities/workload.md. Pour le modèle plus large des trois types d’entrée et l’assembleur qui fusionne la synthèse avec la sortie rendue depuis la source et les artefacts, voir architecture/16-recipe-input-composition.md.
Fournir les valeurs propres d’un composant à l’image du développeur. Selon la convention du catalogue de la bibliothèque standard, une Recipe qui exécute une image construite par le développeur est censée fournir tout ce que les blocs inject: du développeur ont résolu, à partir de .context.inject, et peut aussi fournir les valeurs propres du composant sous des noms qu’elle choisit elle-même. Lorsque le Component déclare spec.inject, c’est le bloc du développeur lui-même qui choisit les noms, et .context.self_inject indique à la Recipe l’unique valeur propre que lit le template de chaque entrée — values.<key> pour une entrée qui lit exactement une valeur propre et rien d’autre. La convention du catalogue de la bibliothèque standard consiste à traiter les noms qu’une Recipe donne à ces valeurs comme des valeurs par défaut plutôt que comme un contrat que le code du développeur doit lire, en ne fournissant une valeur sous son nom par défaut que lorsqu’aucune entrée ne la mappe ; un catalogue d’entreprise peut faire un autre choix. Le contrat du contexte de template donne les règles exactes de la map et un exemple de template complet.
Le champ artifacts: — manifestes auxiliaires
Recipe.spec.artifacts: est une map de nom d’entrée → définition d’un corps d’artefact dont les entrées émettent des fichiers manifestes supplémentaires à côté de la sortie principale de la Recipe, issue d’une source ou synthétisée. C’est l’un des trois types d’entrée (issue d’une source / synthétisée / artefacts) — une Recipe peut déclarer artifacts: seul, ou avec workload: et/ou source:.
La valeur de chaque entrée adopte l’un de trois modes, choisis selon la forme du contenu et parallèles à ceux de workload: — contenu inline, un $import: de fichier ou un $import: de bibliothèque. Le compilateur choisit le mode d’après la forme du contenu de la valeur ; aucune annotation $mode: n’est nécessaire. Dans les trois modes, la clé de la map nomme ce que l’entrée émet : pour les deux modes à fichier unique, c’est le nom du fichier de sortie, et pour le mode bundle, c’est le répertoire sous lequel les fichiers du bundle sont imbriqués. Comme la clé nomme la sortie, elle est limitée à ce que peut être un nom de fichier unique : une lettre ou un chiffre en tête, puis des lettres, des chiffres, des points, des tirets et des tirets bas. Les points conservent l’extension qu’une clé porte par convention — main.tf, template.yaml, serviceaccount.yaml — tandis que l’alphabet n’admet aucun /, qui ferait d’une clé le nom d’un chemin plutôt que d’un fichier, ni de . en tête, de sorte qu’une clé ne peut jamais être le segment du répertoire parent. Une clé hors de cet alphabet échoue à la validation de l’enveloppe au chargement de l’espace de travail, dans aggrega validate et dans les diagnostics de l’éditeur.
spec: capability: helm implements: core/web-server:1.0.0 artifacts: extra-configmap.yaml: | apiVersion: v1 kind: ConfigMap metadata: name: "{{ .context.instance_id }}-extras" data: threshold: "{{ .values.threshold }}" network-policy.yaml: $import: ./artifacts/network-policy.tmpl operator-support: $import: PlatformArtifacts#/artifacts/OperatorSupportMode 1 : inline (scalaire chaîne de template Go). La valeur est un scalaire de bloc, et la clé de la map est le nom du fichier de sortie, utilisé tel qu’il est écrit — la première entrée ci-dessus émet extra-configmap.yaml.
Mode 2 : $import: de fichier. La valeur est une map avec une seule clé $import: qui pointe vers un fichier local de template Go, et la clé de la map est le nom du fichier de sortie, exactement comme dans le mode 1. Le fichier importé fournit le contenu ; il ne fournit pas le nom. La deuxième entrée ci-dessus a la clé network-policy.yaml et émet network-policy.yaml, même si le fichier qu’elle importe s’appelle network-policy.tmpl. Un auteur qui veut un nom de fichier de sortie particulier l’écrit donc comme clé, et deux entrées qui importent des fichiers différents portant par hasard le même nom — ./extras/shared.yaml et ./overrides/shared.yaml — sont deux sorties distinctes. La résolution des chemins est la même que pour valuesMapping: et workload: : un chemin relatif est ancré au répertoire qui contient le recipe.yaml qui le déclare, et non au répertoire depuis lequel le build est lancé, et il doit rester à l’intérieur de ce répertoire.
Mode 3 : $import: de bibliothèque. La valeur est une map avec une seule clé $import: portant une référence d’identité par nom simple vers un bundle d’une ArtifactLibrary, <Library>#/artifacts/<name>. Un bundle est un ensemble de fichiers importés comme une seule unité, donc une entrée se développe en une sortie par fichier du bundle, chacune imbriquée sous la clé de la map en tant que <key>/<filename> — la clé nomme le point d’utilisation et constitue le répertoire où ces fichiers aboutissent, plutôt que le nom de l’un d’eux. La troisième entrée ci-dessus a la clé operator-support ; si PlatformArtifacts#/artifacts/OperatorSupport déclare crd.yaml et rbac.yaml, cette seule entrée émet operator-support/crd.yaml et operator-support/rbac.yaml. La référence ne porte aucun hôte de registry — une forme oci://… avec hôte est rejetée —, la version résolue provient du lockfile par Release, et un plancher de version minimale :<version> facultatif peut être indiqué sous la forme <Library>:<version>#/artifacts/<name>. Voir entities/artifactlibrary pour l’entité bibliothèque et la grammaire complète de la référence.
Un $import: de fichier est épinglé à côté de la Recipe. aggrega pin enregistre l’empreinte des octets de chaque fichier importé dans le fichier entity.lock du répertoire de la Recipe, indexée par la clé de map de l’entrée, et aggrega build recalcule l’empreinte du fichier et s’arrête avec [CATALOG_ERROR E0026] lorsqu’elle ne correspond plus — ou d’abord avec E0130 lorsque le lockfile de la Release, écrit avant la modification, enregistre la Recipe d’après ce qu’elle contient —, de sorte qu’un fichier modifié après avoir été épinglé n’est jamais rendu sans vérification. Si la modification était voulue, exécutez aggrega pin sur la Recipe pour enregistrer la nouvelle empreinte ; sinon, restaurez le fichier. Une entrée inline fait partie du fichier de la Recipe, et une entrée de bibliothèque est épinglée par la version de bibliothèque que le lockfile enregistre, si bien qu’aucune des deux ne porte d’épinglage propre. aggrega pull décrit le fichier.
Le template de chaque entrée d’artefact est évalué avec le même contexte de template que valuesMapping:, quel que soit le mode qui a fourni son corps. Deux sorties portant le même nom de fichier arrêtent le build lors du rendu du nœud. Deux entrées d’une même map artifacts: ne peuvent pas nommer une même sortie : une clé de map est unique au sein d’un document et écrit un seul nom de fichier, donc la sortie d’une entrée à fichier unique est sa clé et les fichiers d’une entrée bundle se trouvent sous un répertoire nommé d’après sa clé — le premier segment de chaque chemin qu’une entrée émet est la clé qui l’a produit, de sorte que des clés distinctes restent des noms de sortie distincts, quel que soit le nom des fichiers importés. Ce que couvre l’arrêt, c’est un même nom de fichier fourni par deux types d’entrée différents — un template de chart et une entrée d’artefact produisant tous deux servicemonitor.yaml —, signalé pour cette Recipe avec un diagnostic qui nomme chaque origine contributrice.
Cas d’usage. artifacts: est l’emplacement des ressources auxiliaires que le chart ou le module principal ne produit pas : une NetworkPolicy accompagnant une charge de travail, un HPA associé à un Deployment, une ConfigMap sidecar indexée sur instance_id. Les ressources auxiliaires transversales qui s’appliquent à de nombreux composants (un sidecar de sauvegarde attaché à chaque datastore, par exemple) relèvent de la Resource Generation de la FeatureRecipe plutôt que des artifacts: de chaque Recipe — voir entities/featurerecipe.md pour la surface d’extension de la FeatureRecipe.
Le bloc boundary: — fichiers pour la sortie partagée de la boundary
La plupart des Recipes n’en ont jamais besoin. Tout ce qu’une Recipe écrit par ailleurs appartient à son propre composant : le fournisseur le place à l’emplacement propre à ce composant dans la sortie de la boundary. Certains fichiers appartiennent au contraire à la boundary dans son ensemble — un fichier que la cible lit une seule fois pour tout ce que la boundary déploie. La configuration des fournisseurs de Terraform en est le cas courant : la documentation de Terraform tient les blocs provider hors d’un module qu’une autre configuration appelle, et un module qui en porte un en propre ne peut pas être appelé avec depends_on, count ou for_each. spec.boundary.artifacts est l’endroit où une Recipe écrit un tel fichier.
spec: capability: terraform implements: core/api-gateway/azure-api-management:1.0.0 artifacts: main.tf: $import: ./module/main.tf boundary: artifacts: # Terraform reads this beside the root configuration; one copy serves every # component of the boundary that declares it. provider-azurerm.tf: | provider "azurerm" { features {} }Le bloc est artifacts: à une seconde portée. artifacts est son unique membre, et il prend exactement la forme du propre artifacts: de la Recipe : les trois mêmes modes — contenu inline, un $import: de fichier, un $import: de bibliothèque dont les fichiers s’imbriquent sous la clé de l’entrée en tant que <key>/<filename> —, la même règle de la clé au nom de fichier et le même alphabet pour une clé, et le même contexte de template, de sorte qu’une entrée lit .values, .infra, .locals et le reste exactement comme le fait une entrée d’artifacts:. Il nécessite au moins une entrée, et tout autre membre sous boundary: est refusé à la lecture de la Recipe. Une FeatureRecipe n’a pas de tel bloc.
Où un fichier est écrit. Une seule fois, dans le répertoire qui contient la sortie assemblée de la boundary, à côté des fichiers que l’assemblage propre au fournisseur y écrit — pour terraform, à côté de la configuration racine aggrega.modules.tf plutôt qu’à l’intérieur du module du composant. Aucun de ces fichiers n’est transmis au fournisseur : le compilateur les évalue et les écrit lui-même, et n’y inscrit rien qui indique de quel composant il provient, car il appartient à chaque composant qui l’a déclaré. Une entrée dont le template ne produit rien au rendu n’écrit aucun fichier.
Comment plusieurs contributeurs se rencontrent. Chaque entrée est évaluée pour chaque composant que la Recipe rend dans la boundary, et les fichiers déclarés par tous les contributeurs de la boundary sont fusionnés par nom. Un nom évalué aux mêmes octets — par deux composants liés à une même Recipe, ou par deux Recipes configurant un même fournisseur de manière identique — est un seul fichier. Un nom évalué à des octets différents arrête le build, en nommant le fichier et chaque contributeur, car aucun fichier unique ne correspond à ce que tous ont écrit ; il en va de même pour un nom que l’assemblage propre au fournisseur écrit, comme aggrega.modules.tf. Les deux constituent la collision de sortie assemblée. Deux Recipes configurant un même fournisseur sous deux noms de fichier différents ne sont pas fusionnées — chaque fichier est écrit — et c’est alors la cible qui signale la configuration en double ; les Recipes destinées à partager une configuration de fournisseur en partagent donc le nom de fichier, par convention un nom tiré du fournisseur qu’elle configure.
Quels fournisseurs l’acceptent. Le fait qu’un fichier placé à côté de la sortie assemblée d’une boundary ait un sens est une propriété de la cible du fournisseur ; cela fait donc partie de la déclaration propre au fournisseur. Une Recipe qui déclare le bloc alors que son fournisseur ne l’accepte pas est refusée avant tout rendu, quel que soit le résultat du rendu de ses entrées ; voir The provider does not support boundary artifacts (Le fournisseur ne prend pas en charge les artefacts de frontière). La grille des capacités indique ce que déclare chaque fournisseur.
| Provider | boundary.artifacts: |
|---|---|
terraform | Accepté. Chaque fichier est écrit à côté de la configuration racine de la boundary, que Terraform lit avec tous les autres fichiers de configuration de ce répertoire. |
helm, compose, helm-chart, cloudformation | Refusé avant tout rendu. |
Un $import: de fichier est ici épinglé comme celui qu’importe une entrée d’artifacts:. Le verrou d’entité enregistre son empreinte dans la même liste artifactDigests, sous boundary/<key> plutôt que sous la clé seule, de sorte qu’une entrée de chaque bloc écrite sous une même clé est épinglée séparément. L’étape d’épinglage l’enregistre, un pull qui n’épingle pas s’arrête là où son épinglage manque ou ne correspond plus, et un build refuse un fichier modifié depuis son épinglage exactement comme il refuse un fichier d’artifacts:.
Le champ outputLabels: — labels déclarés par l’auteur sur la sortie rendue
Recipe.spec.outputLabels: est une map de clé de label → valeur que le fournisseur appose sur chaque objet produit par la sortie rendue de la Recipe. C’est l’emplacement honnête d’un trait de réalisation — une propriété de la manière dont une Recipe particulière réalise un composant, par opposition à ce qu’est le composant. Prenons le stockage avec lequel une réalisation persiste ses données, écrit ci-dessous sous la clé illustrative example.io/storage-backing : une Recipe Helm qui monte un PersistentVolumeClaim et une Recipe Compose qui monte un volume nommé réalisent le même composant par des mécanismes différents ; elles portent donc des outputLabels différents, et les outils en aval (répartition des coûts, politique, inventaire) peuvent les distinguer sur les ressources émises. La clé est illustrative — example.io/ est un espace de noms d’exemple, et un catalogue choisit les clés que ses propres outils lisent.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/storage-backing: persistent-volume example.io/team: platformLes labels de sortie empruntent le même rail que les labels fixes de provenance du build : ils sont fusionnés dans l’ensemble de labels que chaque surface d’émission appose, si bien qu’ils arrivent partout où arrive la provenance. Ce qui diffère, c’est la propriété — les clés de provenance appartiennent au compilateur, les outputLabels à l’auteur de la Recipe.
Le label d’identité propre à un composant ne se saisit pas ici — une convention du catalogue, pas une règle que le compilateur impose. Les clés qui indiquent ce que le composant est plutôt que la manière dont une Recipe le réalise — sa catégorie cognitive, son type opérationnel, ses labels de capacité par rôle, qui exploite la ressource sous-jacente, la classe de licence de ce qu’il encapsule — se déclarent dans les metadata.labels du Component ; voir entities/component « La taxonomie sémantique des labels » pour les axes. Une Recipe porte l’une d’elles sur sa sortie rendue en nommant la clé dans outputComponentLabels: ci-dessous, et non en saisissant ici la clé et une valeur. La raison en est qu’une entrée littérale est une seconde copie d’une valeur que le composant porte déjà, et qu’une seconde copie peut contredire la première : l’auteur d’une Recipe peut saisir une posture sur un nœud dont le Component en déclare une autre, et dire ainsi à un lecteur en aval quelque chose que le graphe ne dit pas. Une entrée promue copie par référence et n’a donc pas de seconde copie susceptible de diverger. Le cœur accepte ce que vous écrivez, quoi que ce soit, hormis la règle des espaces de noms réservés ci-dessous ; la convention est respectée par les auteurs de catalogues.
Espaces de noms réservés. Les espaces de noms aggrega.ai/ et app.kubernetes.io/ sont réservés à la provenance native de la plateforme. Une Recipe qui déclare une clé outputLabels sous l’un ou l’autre préfixe est rejetée au chargement avec une erreur de catalogue claire qui nomme la clé en cause. Toute autre clé est acceptée. Le cœur ne contrôle pas autrement la clé ou la valeur — une clé ou une valeur non valide pour la surface de labels du moteur cible relève de la responsabilité de l’auteur, et l’environnement d’exécution en aval la rejette ; le compilateur n’intervient pas au-delà de la règle des espaces de noms réservés.
Exposition par fournisseur. Chaque fournisseur transpose les labels sur sa propre surface de sortie :
- helm, synthèse de workload — à la fois sur les
metadata.labelsde l’objet et sur lesmetadata.labelsdu template de pod, là où la synthèse place la provenance. - helm, rendu depuis la source et artefacts — sur les
metadata.labelsde l’objet. - compose — sur la map
labels:de chaque service. - terraform — sous forme de tags par ressource sur les corps d’artefact
.tf.jsonadressables structurellement, au mieux : un bloc de ressource qui déclare déjà une maptags(AWS/azurerm) oulabels(Google) y reçoit les labels de sortie, une clé déclarée par l’auteur n’est jamais écrasée, et une ressource sans un tel attribut est laissée intacte (un attribut n’est jamais inventé). Les corps en HCL natif (main.tf,*.tf) et les modules vendorisés sont émis tels quels et ne portent aucun tag injecté. La provenance Terraform continue de circuler dans son fichier de commentaires associé, séparé du rail des tags.
Les labels de sortie ne sont que des labels ; il n’existe pas de surface distincte pour des annotations de sortie. outputLabels est déclaré par l’auteur de la Recipe (la couche de réalisation rédigée par Ops), pas par l’Aggregate — il décrit la réalisation, jamais l’identité du graphe abstrait du développeur.
Le champ outputComponentLabels: — promouvoir les labels propres à un composant
Recipe.spec.outputComponentLabels: est une liste de clés de labels, et non de paires clé-valeur. Pour chaque clé qu’elle nomme, le fournisseur appose cette clé sur la sortie rendue avec la valeur que la clé porte sur l’instance de composant en cours de rendu. Là où outputLabels indique une valeur, outputComponentLabels indique où lire la valeur.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/team: platform outputComponentLabels: - component.aggrega.ai/hostingSoit un Component dont les metadata.labels déclarent component.aggrega.ai/hosting: managed : chaque objet que cette Recipe rend pour ce composant porte component.aggrega.ai/hosting: managed. Liez la même Recipe à un composant qui déclare self-hosted, et les objets de ce composant portent self-hosted à la place — une Recipe, une clé nommée, une valeur par composant.
La promotion se fait par référence, et c’est tout l’intérêt. La valeur est lue sur le composant chaque fois que la sortie est rendue ; elle ne peut donc pas diverger de l’identité dont elle provient : il n’y a pas de seconde copie à maintenir alignée quand le label du composant change. Une entrée littérale d’outputLabels qui reprend le label d’un composant est cette seconde copie, et les deux divergent dès que l’une ou l’autre bouge. Utilisez donc outputLabels quand la valeur est une propriété de la manière dont cette Recipe réalise le composant, et outputComponentLabels quand la valeur existe déjà sur le composant et que la sortie rendue doit la porter aussi.
Une clé promue arrive exactement sur la même surface qu’une clé littérale — l’exposition par fournisseur décrite ci-dessus s’applique sans changement, et aucun fournisseur ne distingue une clé promue d’une clé écrite sur place.
Espaces de noms réservés. Les espaces de noms aggrega.ai/ et app.kubernetes.io/ sont réservés à la provenance native de la plateforme, et une clé promue sous l’un ou l’autre préfixe est rejetée au chargement avec une erreur de catalogue qui nomme la clé et le champ où elle figure. Le critère est le préfixe nu : une clé telle que component.aggrega.ai/hosting se trouve dans un espace de noms qui lui est propre plutôt que sous la racine réservée, et peut être promue.
Une clé appartient à l’un ou l’autre bloc. Déclarer la même clé à la fois dans outputLabels et dans outputComponentLabels est rejeté au chargement, de sorte que chaque clé apposée a une source unique — soit la valeur littérale écrite sur la Recipe, soit le label propre au composant, jamais les deux.
Une clé promue que le composant ne déclare pas n’appose rien. Le build continue et émet un avertissement qui nomme le nœud, la Recipe et la clé manquante. C’est délibéré : une Recipe liée à des composants dont les ensembles de labels diffèrent est tout de même rendue, et l’écart est signalé au lieu d’arrêter le build.
Composants à posture unique — une convention, pas une règle. La promotion transporte la valeur que le composant déclare, quelle qu’elle soit, et le compilateur n’interprète pas cette valeur. Un composant dont le label d’identité contient un espace réservé tenant lieu de « varie » promeut donc cet espace réservé sur chaque objet rendu pour lui. Lorsqu’un composant a réellement plus d’une posture, la convention du catalogue de la bibliothèque standard veut que chaque Recipe indique la posture de sa propre réalisation au moyen d’une clé outputLabels dont la Recipe est propriétaire, plutôt qu’au moyen de la clé d’identité du composant, que la même convention fait passer par outputComponentLabels: — ou qu’elle n’appose rien du tout. Les deux clés répondent à des questions différentes et aucune ne remplace l’autre : la clé d’identité dit ce qu’est le composant à travers toutes ses réalisations, la clé propre à la Recipe dit ce que fait cette réalisation-là. C’est une convention du catalogue respectée par ses auteurs, pas une contrainte que le compilateur impose.
Le bloc locals:
Recipe.spec.locals: est l’état privé d’Ops — une map de chaînes de template Go nommées dont la sortie rendue expose une map .locals.* aux templates ultérieurs de la Recipe. C’est l’espace de travail où calculer une seule fois des réalités physiques (conteneurs cibles, chemins JSON, noms d’hôte dérivés) et les réutiliser dans les payloads de provides:, source:, valuesMapping:, workload:, artifacts:, assertions: et pipeline[].with sans les recalculer. La sortie rendue de chaque entrée est stockée sans ses espaces de début et de fin.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql locals: primary_compute: postgresql listen_port: "5432" secret_target_db_password: "postgres-auth" volumes_path: "/spec/template/spec/volumes" valuesMapping: | primary: auth: existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"locals: n’est jamais exposé aux appelants — les composants en aval qui consomment cette Recipe via uses: ne voient que provides:. Les templates provides:, source:, valuesMapping:, workload:, artifacts:, assertions: et pipeline[].with de la Recipe elle-même voient tous la map .locals.* résolue. Les valeurs par clé peuvent être des chaînes simples ou des templates Go ; le compilateur résout tout le bloc dans le préambule des locals, avant le provides: de ce nœud, si bien que chaque template ultérieur observe des valeurs résolues stables.
Chaque entrée est évaluée dans un contexte autonome, local au nœud : .context.instance_id, .values, .infra et les entrées de ce même bloc déjà résolues. Un local ne peut pas lire .provides — ce pilier n’est pas sur cette surface, et une entrée qui y fait appel arrête le build. Il ne peut pas non plus lire .context.rendered_name, le nom qu’un fournisseur tel que helm donne aux ressources qu’il rend pour le nœud ; un local qui nomme l’une de ces ressources ne porte donc que la partie qui suit ce nom, comme le fait secret_target_db_password ci-dessus, et le template qui écrit le nom complet joint les deux.
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: db_identifier: "{{ .context.instance_id }}-postgres" # defined first secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry aboveL’enchaînement va uniquement 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 db_identifier sous secret_target et le build s’arrête. Le compilateur ne trie ni ne réordonne jamais le bloc pour qu’une référence se résolve ; l’ordre écrit est donc le contrat — réordonner un bloc locals: est un changement de comportement, pas un changement cosmétique.
Deux arrêts distinguent les deux erreurs qu’un auteur peut commettre, car elles se corrigent différemment :
- Une référence à une entrée que le bloc définit plus loin arrête le build en nommant l’erreur d’ordre ; la correction consiste à déplacer la définition au-dessus de son lecteur.
- Une référence à une clé que le bloc ne déclare pas du tout arrête le build en nommant la clé ; la correction consiste à rectifier l’orthographe.
La vérification suit un alias du bloc. Une clé atteinte par le point qu’un corps with .locals lie à nouveau, ou par une variable liée à .locals, est vérifiée exactement dans les mêmes conditions que l’écriture directe : {{ with .locals }}{{ .nope }}{{ end }} et {{ $l := .locals }}{{ $l.nope }} arrêtent tous deux le build en nommant .locals.nope, comme le fait {{ .locals.nope }}, et il en va de même pour {{ (.locals).nope }} et {{ ($.locals).nope }}, car les parenthèses produisent le bloc lui-même et rien de plus. Une seule écriture échappe à la vérification : une clé atteinte par un appel dont le texte du template ne peut pas nommer le résultat — {{ index .locals "nope" }}, ou {{ (default dict .locals).nope }} — car ce que produit un tel appel est décidé à l’exécution du template et non par ce qui est écrit. Une clé absente lue comme champ du résultat d’un tel appel n’arrête pas le build, et elle est rendue sous la forme du texte littéral <no value> plutôt que de rien du tout. Une clé absente atteinte par index arrête le build, en nommant la clé, car index s’arrête sur toute surface de template lorsque la map qu’il lit ne contient pas la clé demandée — un signalement différent de celui de cette vérification, documenté dans errors/fatal-halts.md sous « 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) ». index reste donc le moyen d’atteindre une clé dont le nom est lui-même calculé, comme {{ index .locals (printf "secret_target_%s" .values.slot) }}, et un nom calculé que le bloc ne déclare pas est toujours signalé par sa clé.
provides: lit .locals et reçoit des valeurs résolues, car les locals d’un nœud sont résolus avant ses provides. Un template provides: qui nomme une clé que le bloc locals ne déclare pas arrête le build. Cela signifie qu’une valeur dont ont besoin à la fois une entrée provides: et un artefact est rédigée une seule fois, dans locals:, et lue aux deux endroits.
Pour son pendant côté API publique, voir Le bloc provides: ci-dessous. La surface de la FeatureRecipe suit les mêmes règles — voir entities/featurerecipe.md « Le bloc locals: ».
Le bloc provides:
Recipe.spec.provides: est l’API publique pour les développeurs — une map nom → chaîne de template Go qui déclare les valeurs que cette Recipe fournit aux pipes .context.inject et .context.uses des appelants en aval. Le compilateur évalue les templates provides: lors de l’évaluation des provides (autonome, dans n’importe quel ordre) ; les clés inject des appelants se résolvent par rapport à ces valeurs lors de l’hydratation des injections.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql provides: # The Service this chart names after its release name, suffixed "-postgresql" host: "{{ .context.rendered_name }}-postgresql" port: "5432" database: "{{ .values.db_name }}"Le template de chaque entrée est évalué sur la surface autonome d’évaluation des provides — .context.instance_id, .context.rendered_name lorsque le fournisseur du nœud en indique un, .values, .infra, les .locals résolus du nœud, et du texte statique. Le namespace dans lequel le nœud est placé n’en fait pas partie, de sorte qu’un hôte publié n’en porte aucun : un consommateur situé dans un autre namespace le qualifie de son propre côté. .locals en fait partie parce que les locals du nœud se résolvent dans le préambule de la même étape, avant ses provides ; un template provides qui nomme une clé que le bloc locals ne déclare pas arrête le build. Séparer l’évaluation des provides de l’hydratation des injections est essentiel : le provides: d’une Recipe ne peut référencer l’état d’aucun appelant, car les appelants n’ont pas encore été résolus lorsque l’évaluation des provides s’exécute — provides: est autonome conformément à l’invariant architectural. Les appelants lisent ensuite ces valeurs via .context.uses.<alias>.provides.<provided-name> dans leurs propres templates — les noms fournis sont imbriqués sous provides sur l’arête, à côté des autres champs de l’arête. Un appelant qui déclare une liste d’autorisation inject: sur l’arête atteint plutôt les mêmes valeurs par son pipe .context.inject.
Les clés provides: font partie de la surface contractuelle de la Recipe. Renommer ou supprimer une clé est un changement incompatible pour chaque appelant qui dépend de l’ancien nom ; la version d’interface implements: devrait refléter l’évolution du contrat. Pour la sémantique de résolution en cascade, le contrat du pipe d’injection et des exemples détaillés couvrant le routage entre namespaces et entre régions, consultez architecture/06-data-taxonomy-and-composition.md §3 et templates/expansion-matrix.md.
Lire les valeurs publiées d’un rattachement
Une Recipe lit les Features rattachées à son composant dans .features.<instance-name> et les Features d’identifiants dans .features.<slot>. Les deux ont la même forme de rattachement — .type, .values, .infra, .provides — de sorte qu’un rattachement se lit de la même manière quelle que soit la map qui le porte ; ce qui les distingue, c’est ce que le rattachement produit.
.provides est la sortie publiée du rattachement, résolue à partir de la FeatureRecipe qui lui est liée. C’est le pendant du bloc provides: ci-dessus, vu du côté consommateur : là où une Recipe publie vers ses appelants, un rattachement publie vers son composant hôte.
workload: | # The identity attachment emits a ServiceAccount and publishes its name; # the pod binds to that published name rather than restating it. serviceAccount: "{{ .features.identity.provides.name }}" containers: main: env: DB_SECRET: "{{ .features.app_credentials.provides.name }}"Lire la valeur publiée plutôt que de la recalculer à partir des mêmes entrées values/infra, c’est la différence entre une seule déclaration d’un nom et deux qui peuvent diverger. La forme complète champ par champ, règles de disponibilité comprises, se trouve dans templates/template-context-contract.md.
Un rattachement écrit sur l’une des connexions du composant — un identifiant que le composant présente à une cible — se lit sous la même forme sous cette connexion, à .context.uses.<alias>.features.<slot>, et ne figure jamais parmi .features. Une Recipe qui atteint plusieurs cibles lit l’identifiant propre à chaque cible sous l’alias de cette cible, et une boucle sur .features qui sélectionne les rattachements par type ne rencontre que ceux du composant lui-même :
artifacts: routes.yaml: | {{- range $alias, $edge := .context.uses }} - name: {{ $alias }} {{- with $edge.features }}{{ with .credential }} api_key_secret: {{ .provides.name }} {{- end }}{{ end }} {{- end }}Voir Les rattachements d’une connexion pour la forme et pour l’ordre dans lequel un template parcourt les connexions.
Le champ pipeline:
Recipe.spec.pipeline: est un tableau séquentiel d’étapes de pipeline Wasm qui s’exécutent après le rendu sur l’ensemble des documents rendus, chacune renvoyant des patchs RFC 6902 et des effets de bord. Chaque entrée déclare un id (identifiant de l’étape : lettres, chiffres et traits de soulignement), un plugin (l’entité Plugin que l’étape exécute, qualifiée par son type de plugin — pipeline-step/<name>, éventuellement avec une version ; une simple référence .wasm ou une référence à un artefact est refusée), une function (l’export du plugin à invoquer), un corps de template Go with: facultatif qui fournit la charge utile du plugin, et un template Go when: facultatif qui détermine si l’étape s’exécute — un résultat faux ignore l’étape comme un pass-through, laissant l’ensemble des documents inchangé. La condition when:, son indépendance vis-à-vis de optional: et sa règle de véracité sont traitées en détail dans entities/featurerecipe.md « Étapes conditionnelles — when: » :
spec: capability: helm implements: core/web-server:1.0.0 source: { kind: helm-oci-chart, url: "oci://…", version: "…" } pipeline: - id: inject_sidecar plugin: pipeline-step/envoy-sidecar:1.0.0 function: Inject with: | target_container: "{{ .locals.primary_compute }}" envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"Le compilateur exécute les étapes pipeline: d’une Recipe de base dans l’ordre déclaré, de la même manière qu’il exécute le pipeline: d’une FeatureRecipe : il invoque le plugin Wasm nommé par chaque étape sur la sortie rendue, applique les opérations JSON Patch renvoyées aux documents ciblés et émet les effets de bord de l’étape. Le champ pipeline: de la FeatureRecipe partage la même forme de schéma et la même exécution — voir entities/featurerecipe.md « Contrat de rédaction » et Statut du langage pour l’état d’exécution de chaque surface.
La mécanique du champ reflète la sémantique de la FeatureRecipe : évaluation séquentielle dans l’ordre déclaré, opérations JSON Patch appliquées aux documents rendus, effets de bord émis à côté, et erreurs remontées avec une provenance pointant vers l’étape fautive. Une étape dont la condition when: est rendue fausse est ignorée comme un pass-through, laissant l’ensemble des documents inchangé pour l’étape suivante.
Le bloc assertions:
Recipe.spec.assertions: est une map facultative de règles nommées exprimant des invariants d’implémentation de la Recipe — des règles inter-champs qui valent pour le chart ou le module précis dont la Recipe tire sa source. Chaque clé est un identifiant de règle qui apparaît dans le message d’échec ; chaque valeur est un corps de template Go. Contrairement aux assertions du Component (qui expriment des invariants au niveau du contrat quelle que soit la Recipe liée), les assertions de la Recipe sont des propriétés de l’implémentation précise choisie.
spec: implements: core/datastore/mariadb:^1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "20.0.0" assertions: # Bitnami 20.x: serviceMonitor namespace requirement. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}La règle ci-dessus est propre au chart Bitnami 20.x ; elle ne s’applique pas si une autre Recipe MariaDB est liée. Les règles de niveau Component issues du contrat s’appliquent toujours en parallèle, évaluées à une phase antérieure du pipeline.
Les assertions de la Recipe sont évaluées après la liaison de la Recipe et avant le rendu, une fois que les locals et les provides de chaque nœud sont résolus. Le contexte du template inclut les .provides, .locals et .recipe.source de la Recipe en plus des champs de l’instance d’entité (.values, .infra, .uses, .features). Là, .uses et .features sont les formes plus restreintes de la surface des assertions, et non celles d’un template de Recipe : l’entrée d’une connexion porte sa cible et son alias, les labels de la cible, les values propres à la connexion et les rattachements écrits sur elle sous features, mais rien de ce que la cible publie ; et l’entrée d’un rattachement, celui du composant lui-même ou celui d’une connexion, porte son type, sa resolved_version et ses values, mais ni son infra ni ses provides — la FeatureRecipe d’un rattachement n’a pas encore résolu ses provides lorsque l’assertion s’exécute. Une référence à .features.<name>.provides arrête donc le build, et une lecture tenant compte de la présence renvoie sa valeur de repli. Pour la grammaire de rédaction complète, la répartition des responsabilités entre règles de niveau contrat et règles de niveau implémentation, et des exemples détaillés, consultez templates/assertions-block.md.
Le champ omits: — exclure des documents rendus d’une source
La plupart des Recipes n’en ont jamais besoin. Il sert pour une source que vous prenez telle quelle — le plus souvent un chart récupéré depuis un registre — qui rend un document que votre Release ne doit pas livrer : un Secret que le chart génère à nouveau à chaque rendu, par exemple, ce qui fait différer deux builds et, une fois appliqué, écrase le Secret fourni par l’opérateur. Vous ne modifiez pas un chart récupéré, et aucune règle d’exclusion n’y pénètre, donc omits: est la manière dont une Recipe laisse un tel document hors du build. Un fichier compose récupéré relève du même cas : il peut embarquer un service, un volume ou une config que la Release ne doit pas avoir, et une surcouche valuesMapping: peut en modifier un mais jamais le supprimer. Il en va de même d’un template CloudFormation récupéré, qui peut déclarer une ressource que la Release ne doit pas créer : un valuesMapping: peut renseigner les paramètres qu’il déclare mais jamais supprimer l’une de ses ressources.
spec: capability: helm implements: core/gateway/kong:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/gateway version: "2.4.0" omits: # The chart generates this key on every render; the operator supplies it. - kind: Secret name: "{{ .context.rendered_name }}-session-key" # Left out only where the Release asks for it. - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: "{{ .context.rendered_name }}-dashboards" namespace: monitoringCe qu’il couvre. Uniquement ce que source: rend. Un workload: et les entrées artifacts: ne sont jamais filtrés : c’est vous qui les écrivez dans la Recipe, donc un document dont vous ne voulez pas là est un document que vous n’écrivez simplement pas. La clé exige source: ; un document qui enfreint cette règle est refusé à sa lecture, avec le nom de la règle.
Une entrée. Chaque entrée désigne ce qu’il faut laisser de côté au moyen de trois champs, et un quatrième décide si elle s’applique. Ce que désignent les trois premiers est le vocabulaire propre au fournisseur pour ce que sa source rend, présenté fournisseur par fournisseur dans le tableau ci-dessous :
kind— le type de ce que la source rend : pour un chart, le kind d’un document rendu —Secret,ConfigMap,Deployment; pour un fichier compose,service,volumeouconfig; pour un template CloudFormation, leTyped’une ressource —AWS::S3::Bucket. Il est sans rapport avec lekind:que porte unesource:structurée, qui indique comment la source est récupérée.name— son nom : lemetadata.named’un document ; la clé d’une unité compose sousservices:,volumes:ouconfigs:; l’ID logique d’une ressource CloudFormation, sa clé sousResources.namespace(facultatif) — le namespace dans lequel se trouve le document, pour un fournisseur dont la sortie a des namespaces. Sans lui, l’entrée désigne le kind et le nom dans n’importe quel namespace ; unnamespacedont le rendu est vide est traité comme absent.when(facultatif) — si l’entrée s’applique à ce build. Il est évalué en premier et lu selon la même règle que lewhen:d’une étape de pipeline : un résultat faux écarte l’entrée, de sorte que ses autres champs ne sont pas évalués et qu’elle n’est ni transmise au fournisseur ni vérifiée, tandis qu’unwhen:absent ou vide la conserve.
kind et name sont obligatoires, et une entrée portant tout autre champ est refusée à la lecture de la Recipe.
Chaque valeur est un template, évalué dans le même contexte que valuesMapping:. Ce contexte porte .context.rendered_name, le nom que le fournisseur donne aux ressources du nœud et celui d’après lequel un chart les nomme généralement, de sorte qu’une entrée peut nommer un document exactement comme le fera le chart. Un template dont le rendu échoue arrête le build comme le fait un template valuesMapping: en échec.
Chaque entrée qui s’applique doit laisser quelque chose de côté. Le fournisseur indique combien d’unités chaque entrée a laissées de côté, et une entrée qui n’en a laissé aucune arrête le build en nommant l’entrée ; voir An omits entry left out nothing the source rendered (Une entrée omits n’a rien laissé de côté de ce que la source a rendu). Une mise à niveau de la source qui renomme ou supprime le document en est la cause habituelle, et l’arrêt est ce qui empêche un document renommé d’atteindre votre sortie sans que vous le remarquiez. Pour ne laisser un document de côté que dans certains cas, dites-le avec when: plutôt que de compter sur l’absence du document.
La source est tout de même rendue en entier. Seule sa sortie est filtrée : chaque template du chart s’exécute toujours, de sorte qu’un template qui échoue fait toujours échouer le build, et un document laissé de côté est rendu puis écarté. Une fois écarté, il n’atteint plus rien de ce que fait le build ensuite — aucun fichier émis, aucun nom comparé aux noms d’autres composants, aucun fait qu’une Feature lit sur le rendu, rien de ce qui est transmis à une étape de pipeline.
Une Release atteint la clé par infra et parameters. La clé appartient à la Recipe, donc une Release ne peut pas l’écrire. Elle peut néanmoins décider de ce que fait une entrée : les templates d’une entrée lisent l’infra que la Release renseigne, et les parameters qu’elle fournit atteignent les .values de la Recipe partout où l’Aggregate les y achemine. Une Release active ou désactive donc une entrée avec when:, comme le fait la deuxième entrée ci-dessus, ou décide de ce qu’elle désigne.
Ce que vous laissez de côté relève de votre responsabilité. Rien dans le build ne sait à quoi sert un document. Laisser de côté un document dont le reste du chart dépend à l’exécution — le Secret qu’un Deployment monte, le ServiceAccount sous lequel un pod s’exécute — produit une sortie qui se construit proprement puis échoue lorsqu’elle est appliquée, à moins qu’autre chose appliqué à côté ne fournisse ce document. Pour un fichier compose et un template CloudFormation, le build vérifie bel et bien, car chacun énonce ses propres références : ce qui reste et nomme encore une unité laissée de côté — un service nommant un service laissé de côté, une ressource ou une sortie nommant une ressource laissée de côté — arrête le build, comme le décrit le tableau ci-dessous.
Quels fournisseurs le prennent en charge. Laisser un document de côté est une chose que seul le fournisseur peut faire, car seul le fournisseur sait ce que sa source rend ; la prise en charge de la clé par un fournisseur fait donc partie de la déclaration propre du fournisseur. Une Recipe déclarant omits: dont le fournisseur ne le prend pas en charge est refusée avant tout rendu, quel que soit le rendu des when: de ses entrées ; voir The provider does not support omits (Le fournisseur ne prend pas en charge omits).
| Provider | omits: |
|---|---|
helm | Pris en charge. Une entrée désigne un document que le chart rend — à partir d’un template ou de son répertoire crds/ — par le kind et le metadata.name propres au document et, lorsque l’entrée en indique un, par le namespace dans lequel se trouve le document. Voir helm → Mode avec source. |
compose | Pris en charge. Une entrée désigne un service, un volume ou un config du fichier compose source par sa clé sous services:, volumes: ou configs:, comparée une fois valuesMapping: fusionné dans le fichier, et ne désigne aucun namespace : une entrée désignant un autre kind, ou un namespace, arrête le build lorsque le composant est rendu. Un fichier dans lequel ce qui reste nomme encore une unité laissée de côté — par depends_on, links, volumes_from, un mode réseau ou namespace service:, extends, un contexte de build, ou une entrée volumes: ou configs: — arrête le build en nommant chaque référence. Voir compose → Mode avec source. |
cloudformation | Pris en charge. Une entrée désigne une ressource du template source par son Type et son ID logique, dans chaque template d’une source de type répertoire, et ne désigne aucun namespace : une entrée qui en porte un arrête le build lorsque le composant est rendu. Un template dans lequel ce qui reste nomme encore une ressource laissée de côté — par Ref, Fn::GetAtt, DependsOn ou une variable Fn::Sub — arrête le build en nommant chaque référence. Voir cloudformation → Laisser des ressources hors d’un template source. |
helm-chart, terraform | Refusé : le fournisseur transmet sa source pour qu’elle soit rendue au moment du déploiement, donc aucun document n’existe au moment du build qui pourrait être laissé de côté. Pour un chart ou un module local, une ligne dans le .aggregaignore à côté de la Recipe laisse plutôt de côté l’un de ses fichiers. |
La même clé s’écrit sur une FeatureRecipe ; voir entities/featurerecipe.md.
Pour un exemple détaillé — le Secret généré d’un chart récupéré laissé de côté, l’arrêt pour déterminisme que rencontre le même chart sans l’entrée, et l’arrêt sur une entrée qui ne correspond à rien, chacun issu d’un build réel — voir ai-gateway-own-webhook-certificate.