Contexte de template des paramètres
Le pilier parameters: porte les valeurs de paramètres fournies par la Release et validées par rapport au contrat. Deux modèles mentaux parallèles régissent son accessibilité :
- Les surfaces de template de valeur (chaînes
values:de composant / feature / sous-aggregate à l’intérieur de l’Aggregate, ainsi quevaluesMappingde la Recipe,injectMappingetprovidesde la FeatureRecipe, les corps de Workload) consomment les valeurs des paramètres sous forme de littéraux déjà interpolés. La passe d’interpolation au sein de la résolution évalue l’ensemble du texte de l’Aggregate comme un template et remplace chaque référence{{ .parameters.<slot> }}par la valeur résolue ; les surfaces de template de valeur en aval ne voient jamais.parametersdirectement dans leur contexte de template. - Les surfaces de template de chemin (templates
directory:etsubDirectory:rédigés par l’opérateur sur les frontières de la Release) lisent.parameters.<slot>directement lors de l’évaluation des templates de chemin pendant le rendu. La map de paramètres fusionnée reste lisible jusqu’à la fin du rendu afin qu’un template de chemin puisse lire.parameterspar rapport à l’allowlist fermée.
L’octroi asymétrique — les templates de chemin lisent .parameters directement ; les templates de valeur non — permet à chaque couche de posséder ce dont elle a besoin : les values: côté développeur transmettent aux templates de valeur des données déjà résolues et propres à l’environnement ; les templates de chemin côté opérateur référencent des paramètres de région / environnement / identifiant de compte sans passer par le schéma values de l’Aggregate.
Cette page documente la passe d’interpolation, les formes de valeur par slot, les modèles d’accès dans les chaînes YAML de l’Aggregate, l’exception des templates de chemin, et combien de temps la map fusionnée reste lisible. Pour la forme plus large du contexte de template de Recipe / FeatureRecipe (.values, .infra, .uses, etc.), voir template-context-contract.md. Pour la disponibilité par emplacement de template tout au long du pipeline de compilation, voir expansion-matrix.md. Pour la forme de déclaration des contrats de paramètres typés sur l’Aggregate, voir entities/aggregate.md §« Typed parameter contracts (Contrats de paramètres typés) ». Pour l’allowlist des variables de template de chemin qui inclut .parameters.<slot> lors de l’évaluation de directory: / subDirectory: d’une frontière, voir path-template-variables.md.
Cycle de vie des paramètres
Le compilateur résout les paramètres en quatre phases ordonnées :
- Lecture du contrat — le bloc
spec.parameters:de l’Aggregate est vérifié selon ses propres termes avant qu’une quelconque valeur de la Release soit examinée, de sorte qu’un slot qui ne pourrait rien contraindre arrête le build même lorsqu’aucune Release ne le fournit. UnminLengthou unmaxLengthnégatif sur la propre déclaration d’un paramètre est refusé au chargement de l’Aggregate, en nommant le paramètre et la clé. Chaquepattern— sur le slot lui-même et à l’intérieur de tout contrat imbriqué sousitems,propertiesouvaluesType— est compilé comme une expression régulière, et un pattern qui ne se compile pas est refusé en nommant le paramètre, le pattern et la raison. Une borne de longueur à l’intérieur d’un contrat imbriqué n’est pas soumise à ce plancher ; voirentities/aggregate.md. - Remplissage des valeurs par défaut — les slots ayant un
default:défini et aucune valeur fournie par la Release reçoivent leur valeur par défaut. La map.parametersest dans la portée à ce stade. - Validation du contrat des paramètres — chaque valeur de la map fusionnée, qu’elle ait été fournie par la Release ou remplie par un
default:, est validée par rapport aux contraintestype/enum/min/max/pattern/ de structure imbriquée déclarées dansspec.parameters.<slot>de l’Aggregate ; unpatternest comparé à l’expression compilée lors de la lecture du contrat. La map.parametersexiste dans le contexte en mémoire du validateur en tant que charge utile structurée en cours de vérification. - Interpolation — le compilateur évalue l’ensemble du texte de l’Aggregate comme un template, avant de le lire comme YAML, et remplace chaque référence
{{ .parameters.<slot> }}par la valeur résolue ; tout autre{{du texte est lui aussi lu comme syntaxe de template, de sorte qu’une valeur portant ses propres doubles accolades écrit chaque{{sous la forme{{"{{"}}(voir Texte qui contient ses propres doubles accolades). L’interpolation est le chemin de substitution pour les surfaces de template de valeur — après cette passe, les contextes de template de valeur ne portent plus.parameters; ils consomment les valeurs résolues écrites dans les chaînesvalues:environnantes. La map fusionnée reste lisible après l’interpolation, pendant tout le rendu, spécifiquement pour prendre en charge l’évaluation des templates de chemin. Sa durée de lisibilité est bornée par celle du build : le compilateur remet la vue résolue à la compilation qui la consomme au lieu de la renvoyer à un appelant, de sorte que rien en dehors de ce build ne peut atteindre la map. La surface de template de chemin (directory:/subDirectory:de la Release) lit.parameters.<slot>pendant le rendu par rapport à l’allowlist fermée documentée danspath-template-variables.md.
Les templates à l’intérieur des chaînes YAML de l’Aggregate (values: de composant, values: de feature, expressions de transmission parameters: de sous-aggregate) lisent la map .parameters via la syntaxe standard des templates Go pendant la passe d’interpolation. Les templates à l’intérieur des fichiers de Recipe et de FeatureRecipe ne reçoivent PAS .parameters dans leur contexte de template (voir « Boundary with downstream template contexts (Frontière avec les contextes de template en aval) » plus bas pour le contrat par surface).
Texte qui contient ses propres doubles accolades
Comme l’ensemble du texte est un template, les doubles accolades qui appartiennent à une valeur plutôt qu’à un template sont elles aussi lues comme des actions de template. La définition d’une plateforme de flux portée dans les values: d’un composant est le cas courant : n8n entoure de doubles accolades chaque expression des paramètres d’un nœud, comme dans ={{ $json.body.message }}, un prompt Flowise nomme une variable sous la forme {{question}} et un chatflow Flowise écrit {{chatOpenAI_0.data.instance}} pour chaque connexion entre deux nœuds, et un export Langflow porte le code source de ses composants, où les accolades peuvent aussi apparaître. Écrites telles quelles dans un Aggregate, elles arrêtent le build au niveau de l’Aggregate avec E0158, décrit sous « A {{ .parameters.* }} reference cannot be interpolated (Une référence aux paramètres ne peut pas être interpolée) » dans Arrêts fatals ; sa raison nomme la ligne et le premier jeton que le moteur de template n’a pas pu lire — undefined variable "$json" pour une expression n8n. Un commentaire YAML est lui aussi du texte de template, de sorte qu’un {{ écrit dans un commentaire s’arrête de la même façon.
Écrivez chaque {{ d’une telle valeur sous la forme {{"{{"}}. Il s’agit d’une action de template dont le résultat est la chaîne {{, de sorte que l’interpolation remet les deux accolades en place. Un }} fermant ne nécessite rien, car en dehors d’une action c’est du texte simple. L’interpolation s’exécute une seule fois, sur le texte de l’Aggregate, et un template de Recipe écrit ce qu’il lit dans .values en tant que données, de sorte que les accolades restaurées atteignent la sortie rendue telles qu’elles ont été exportées.
# Aggregate fragment — an n8n workflow definition carried as exportedspec: components: automation: type: core/ai-agent/n8n values: workflow_id: support-reply flow_definition: | { "name": "Support reply", "nodes": [ { "name": "Set reply", "type": "n8n-nodes-base.set", "parameters": { "value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}" } } ], "connections": {} }La plateforme reçoit "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}".
Conservez une telle définition dans un scalaire de bloc (|), comme ci-dessus, où les guillemets de l’échappement sont des caractères ordinaires. Le texte de l’Aggregate est aussi lu comme YAML avant d’être interpolé, et à l’intérieur d’une chaîne YAML entre guillemets doubles, le " de l’échappement ferme la chaîne, de sorte que le fichier ne s’analyse plus et que le build s’arrête avec l’erreur YAML.
Le modèle d’accès .parameters.<slot>
Chaque slot de paramètre déclaré est accessible comme un champ de la map .parameters. Un accès correct quant au type correspond au type déclaré :
# Aggregate fragment — parameter declarationsspec: parameters: region: { type: string, enum: [us-east-1, us-west-2] } cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 } enable_debug: { type: boolean, default: false }
components: web: type: core/web-server:1.0.0 values: region: "{{ .parameters.region }}" # string cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer debug: {{ .parameters.enable_debug }} # booleanLa passe d’interpolation produit une évaluation de template Go sur la map .parameters ; le résultat remplace sur place l’expression de template dans le document. Le schéma values: du Component / de la Feature valide ensuite la valeur obtenue lors de la phase de validation de schéma post-interpolation de la résolution.
Les guillemets décident du type remonté
Mettez entre guillemets une référence destinée à une feuille de type chaîne ; laissez-la nue pour tout autre type déclaré. La règle est celle de YAML lui-même, pas une qu’Aggrega ajoute par-dessus : l’interpolation substitue la valeur fournie dans les octets du document et ne fait rien d’autre, de sorte que l’analyse qui suit lit le résultat exactement comme elle lit tout autre scalaire. Un {{ .parameters.cache_ttl_seconds }} nu porte le type propre de la valeur fournie, ce qui permet à un paramètre entier d’atteindre une feuille entière et à un paramètre booléen d’atteindre une feuille booléenne. Un "{{ .parameters.cache_ttl_seconds }}" entre guillemets porte une chaîne, et une feuille déclarée integer ou boolean la refuse : la valeur rédigée échoue au schéma values: de son Component ou de sa Feature sur le type, et le diagnostic nomme la non-concordance de type plutôt qu’une contrainte d’espace de valeurs que la chaîne aurait aussi manquée.
Une référence qui partage son scalaire avec d’autre texte est une chaîne quelle que soit la façon dont elle est écrite, car le document substitué n’a qu’un seul scalaire à lire — image: app:{{ .parameters.tag }} donne app:1.4.0. C’est la forme à employer lorsqu’un paramètre qui n’est pas une chaîne doit aboutir dans une feuille de type chaîne.
Accès aux slots de type objet et de type tableau
Les slots de paramètre de type objet exposent leurs propriétés déclarées comme des champs imbriqués de la map .parameters.<slot>. Les slots de type tableau exposent la sémantique des slices des templates Go (range, index, len).
# Aggregate fragment — object-typed parameterspec: parameters: database_config: type: object properties: host: { type: string, required: true } port: { type: integer, min: 1, max: 65535, default: 5432 } ssl_mode: { type: string, enum: [disable, require, verify-full] }
components: api: type: core/compute/api:1.0.0 values: db_host: "{{ .parameters.database_config.host }}" db_port: {{ .parameters.database_config.port }} db_ssl: "{{ .parameters.database_config.ssl_mode }}"Les slots de paramètre de type tableau prennent en charge l’itération via range :
# Aggregate fragment — array-typed parameterspec: parameters: allowed_hosts: type: array items: { type: string, format: hostname } min: 1
components: ingress: type: core/ingress:1.0.0 values: # Compose a comma-separated list from the parameter array hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"Chaque élément fourni par la Release est vérifié par rapport au contrat items avant l’interpolation, de sorte qu’une valeur qui n’est pas un nom d’hôte — *, par exemple — arrête le build en nommant le paramètre, l’élément et le format. Les noms que format accepte, et ce que chacun vérifie, sont listés dans vocabulary/compact-form-authoring.md.
La bibliothèque de templates Sprig est disponible pendant l’interpolation et fournit des helpers comme join pour des conversions compactes de tableau en chaîne :
hosts: "{{ join `,` .parameters.allowed_hosts }}"Sémantique du remplissage des valeurs par défaut
Un slot de paramètre ayant une déclaration default: reçoit sa valeur par défaut lorsque la Release omet le slot. La valeur par défaut s’applique avant l’exécution de la passe de validation du contrat, de sorte que la validation voit la valeur résolue (fournie par la Release ou par défaut) :
# Aggregatespec: parameters: timeout_seconds: type: integer min: 1 max: 300 default: 30
components: api: type: core/compute/api:1.0.0 values: timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30# Release supplies timeout_seconds: 60 — interpolation uses 60# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)Un slot marqué required: true sans default: déclenche une erreur au moment du build lorsque la Release l’omet (E0165). L’erreur nomme le slot et son emplacement dans le contrat pour que l’auteur le corrige. Un slot n’ayant ni required: true ni default: est facultatif : s’il est omis, chaque référence à celui-ci s’interpole comme vide, et le schéma values: du Component juge ensuite le résultat.
Paramètres à objets imbriqués
Lorsqu’un paramètre déclare type: object avec des properties: dont les enfants portent eux-mêmes des valeurs default:, trois cas de rédaction produisent des résultats distincts. Comprendre la distinction importe lorsque la déclaration du paramètre est un objet structuré — une configuration de base de données, un ensemble de feature flags, une politique de timeout et de retry — plutôt qu’un scalaire unique.
Cas 1 — la Release omet le slot parent. Les valeurs par défaut des enfants du contrat sont appliquées. L’auteur de l’Aggregate qui a déclaré les valeurs par défaut imbriquées obtient le comportement voulu : lorsque les ops ne fournissent pas le slot, la configuration utilise les valeurs par défaut documentées.
# Aggregatespec: parameters: database: type: object properties: host: { type: string, default: "localhost" } port: { type: integer, default: 5432 }
# Release (parent omitted)spec: parameters: {}
# Resolved at template-interpolation timeparameters: database: host: "localhost" port: 5432Cas 2 — la Release rédige le parent sous forme de map vide explicite. Le vide explicite est respecté comme un opt-out délibéré. Les valeurs par défaut des enfants ne sont PAS appliquées ; le slot reste vide. Utilisez cette forme lorsque les ops veulent supprimer les valeurs par défaut imbriquées du contrat sans fournir de surcharges — par exemple, lorsqu’un consommateur en aval attend le slot présent mais vide.
# Release (parent explicit empty)spec: parameters: database: {}
# Resolved at template-interpolation timeparameters: database: {}La distinction avec le Cas 1 est délibérée : les ops peuvent exprimer à la fois « utiliser les valeurs par défaut » (en omettant le slot) et « supprimer les valeurs par défaut » (en rédigeant le slot sous la forme {}). Cela reflète la façon dont Aggrega traite le null explicite dans les annotations — une annotation rédigée sous la forme aggrega.ai/<key>: null est un opt-out délibéré distinct de l’omission complète de l’annotation.
Cas 3 — la Release rédige partiellement le parent. Les enfants que la Release a fournis prennent leurs valeurs rédigées ; les enfants que la Release n’a pas fournis sont remplis à partir des valeurs par défaut.
# Release (partial)spec: parameters: database: host: "db.prod.example.com"
# Resolved at template-interpolation timeparameters: database: host: "db.prod.example.com" # Release-supplied port: 5432 # filled from defaultC’est le cas courant pour les auteurs de Release qui veulent surcharger des champs choisis tout en laissant le reste aux valeurs par défaut du contrat.
Quand utiliser chaque forme
- Omettez le slot lorsque vous voulez que les valeurs par défaut du contrat s’appliquent.
- Rédigez
{}lorsque vous voulez délibérément que le slot soit présent mais vide — lorsque les valeurs par défaut du contrat sont incorrectes pour votre environnement et que vous n’avez pas de surcharges. - Rédigez partiellement lorsque vous voulez certaines surcharges et que le reste utilise les valeurs par défaut du contrat.
Un auteur de Release qui écrit database: {} en attendant « donne-moi les valeurs par défaut » sera surpris — la valeur résolue est vide, et non les valeurs par défaut remplies. Pour obtenir les valeurs par défaut, omettez entièrement le slot.
Le traitement à trois cas s’applique par élément frère à chaque profondeur d’imbrication. Un parent rédigé sous la forme { connection: {}, other_field: "x" } produit un arbre résolu dans lequel connection est vide (Cas 2 à la profondeur 1) et other_field est la valeur fournie par la Release (Cas 3 à la profondeur 0) — les cas s’appliquent indépendamment pour chaque frère, et non comme une décision unique pour l’ensemble du sous-arbre.
Frontière avec les contextes de template en aval
L’octroi asymétrique — les templates de chemin lisent .parameters directement ; les templates de valeur non — est la distinction porteuse à cette frontière. La sémantique de la frontière par surface :
- Un template
values:de composant de l’Aggregate qui écrit{{ .parameters.X }}se résout correctement lors de l’interpolation. Le littéral résolu est écrit sur place dans la chaîne YAML. - Un template
valuesMapping:de la Recipe qui écrit{{ .parameters.X }}est une surface de template de valeur ; le contexte de template ne porte pas.parameters. Les auteurs ayant besoin d’une variation par environnement dansvaluesMapping:l’expriment par le chemin de consommation de.values.<key>résolu — l’Aggregate expose un paramètre, le référence depuis lesvalues:d’un Component, la Release le satisfait, et la valeur post-interpolation parvient jusqu’à la Recipe. - Un template
injectMapping:,provides:oupipeline.with:de la FeatureRecipe est une surface de template de valeur ; commevaluesMapping:de la Recipe..parametersn’est pas dans le contexte de template. - Un template de corps de Workload (contenu
workload:à l’intérieur d’une Recipe) est une surface de template de valeur ; de même. - Un template de chemin (
directory:/subDirectory:d’une frontière de la Release) est l’exception. Le contexte de template de chemin inclut.parameters.<slot>par rapport à l’allowlist fermée ; les références se résolvent lorsque le rendu place la sortie de chaque frontière. Voirpath-template-variables.mdpour la matrice complète des variables de template de chemin.
La frontière de propriété entre les quatre domaines est préservée par la surface qui reçoit les paramètres, et non par le fait que la map des paramètres existe en mémoire à une phase donnée du pipeline. Les templates de chemin sont rédigés par l’opérateur et lui appartiennent ; leur accorder un accès direct aux paramètres maintient les préoccupations de l’opérateur (la disposition des artefacts par environnement) à l’intérieur de la surface de l’opérateur. Les templates de valeur sont rédigés dans le catalogue ; leur refuser un accès direct aux paramètres maintient la rédaction côté catalogue faiblement couplée au contrat de l’Aggregate comme source unique de vérité.
La map de paramètres fusionnée reste lisible jusqu’à ce que chaque phase de rendu soit terminée, et pas au-delà : elle n’est accessible que depuis la compilation pour laquelle elle a été résolue, de sorte que sa durée de vie est bornée par celle du build.
Pont entre piliers
Les paramètres s’interpolent dans les chaînes de valeurs environnantes pendant la résolution. Les valeurs interpolées peuvent aboutir dans n’importe quel pilier que l’Aggregate rédige à son niveau : chaînes values: de composant, chaînes values: de feature, déclarations de transmission parameters: de sous-aggregate (où la valeur du paramètre de l’Aggregate parent se résout puis se propage dans le slot de paramètre de l’Aggregate enfant), et chaînes name: / labels: des métadonnées.
Le pont est unidirectionnel : une valeur de paramètre circule depuis le .parameters.<slot> fourni par la Release (ou par défaut) vers la chaîne YAML à l’emplacement de la référence. Les paramètres ne circulent pas dans l’autre sens — un paramètre ne peut pas lire un champ values:, un champ provides: ni le contenu d’aucun autre pilier. Cette directionnalité fait partie de la garantie du contrat des paramètres de ne valoir qu’à la compilation.
Renvois
- Pour la forme de déclaration des contrats de paramètres typés sur l’Aggregate :
entities/aggregate.md§« Typed parameter contracts (Contrats de paramètres typés) ». - Pour le contexte de template plus large que les Recipes consomment lors du rendu de base (
.values,.infra,.uses,.context.*, etc.) : template-context-contract.md. - Pour la disponibilité par emplacement de template tout au long du pipeline de compilation (quels champs sont présents à quel point d’évaluation) : expansion-matrix.md.
- Pour la liste de contrôle de la remontée des paramètres (les quatre points de contact successifs de la rédaction — déclaration dans l’Aggregate, référence dans values, satisfaction dans la Release, consommation dans la Recipe) :
vocabulary/data-pillars.md§« The parameter-hoisting checklist (La liste de contrôle de la remontée des paramètres) ». - Pour l’ensemble plus large des piliers de données (
values:,infra:,provides:,uses:,features:,locals:,parameters:) :vocabulary/data-pillars.md.