Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Piliers de données

Le cadrage conceptuel des cinq mots-clés structurels du DSL — parameters, values, uses, infra, inject — se trouve dans architecture/06-data-taxonomy-and-composition.md. Cette page couvre la liste canonique des piliers de données, la sémantique de rédaction par pilier, les mécanismes inter-piliers et le vocabulaire des valeurs par défaut que les auteurs rencontrent d’un pilier à l’autre. La triade topologique complémentaire (provides, inject, uses — mots-clés qui câblent les arêtes du graphe) est documentée dans topology-triad.md ; le vocabulaire des métadonnées distinct des piliers de données (labels, annotations, champs de la surface de publication) se trouve dans labels-and-annotations.md et publishing-surface.md.

Liste canonique des piliers

Les entités Aggrega portent sept piliers de données nommés. Cinq participent au flux de données de l’IR comme état vivant tout au long du rendu ; deux sont transitoires ou privés et n’existent qu’à des étapes précises de la compilation.

PilierSe trouve surCycle de vieRôle
valuesInstances de composant / de rattachement de l’AggregateVivant tout au long du renduPayload cognitif rédigé par le développeur
infraEntrées de composant, de rattachement et de connexion de la ReleaseVivant tout au long du renduDimensionnement physique rédigé par l’opérateur
providesBloc provides: de la RecipeVivant tout au long du rendu (pilier dérivé — voir ci-dessous)Chaînes de sortie publiques calculées par la Recipe, que consomme le pipe topologique
usesInstances de composant / de fonctionnalité de l’AggregateVivant tout au long du renduArêtes topologiques vers d’autres composants / fonctionnalités
featuresInstances de composant de l’Aggregate + de la Release ; slots déclarés dans le featuresSchema d’une entité du catalogue — voir « Features pillar (Pilier Features) » ci-dessousVivant tout au long du renduPilier des rattachements — une seule forme pour chaque famille de rattachements
parametersRacines de l’Aggregate + de la ReleaseLisible jusqu’à la fin du pipeline, jusqu’à ce que chaque phase de rendu soit terminée ; accessible aux templates de chemin pendant le rendu via l’octroi asymétrique ; les contextes de template de valeur consomment les littéraux post-interpolation plutôt que .parameters directementSlots par environnement remplis par la Release
localsBloc locals: de la RecipePrivé à la Recipe — visible uniquement à l’intérieur des templates propres à la RecipeÉtat de chaîne calculé que les Recipes dérivent dans le préambule des locals

values / infra / provides / uses / features sont les cinq piliers vivants que le contexte de template à l’exécution expose respectivement via .values, .infra, .provides, .context.uses et .features. parameters et locals sont hors de la liste des piliers vivants — parameters parce qu’il ne survit pas à la résolution ; locals parce qu’il est privé à la Recipe et ne franchit jamais les frontières des entités.

Les piliers sont des panneaux indicateurs, pas des murs : le moteur de templates permet les lectures inter-piliers à chaque site, sauf interdiction explicite par les règles d’autosuffisance (un bloc provides: de Recipe et un bloc source: de Recipe lisant .context.inject / .context.uses ; documenté dans templates/expansion-matrix.md). Les frontières des piliers relèvent de la discipline de rédaction, non d’une contrainte imposée par le langage.

Frontières des piliers et discipline de rédaction

Les lectures inter-piliers depuis un template de Recipe ne sont pas restreintes à chaque site qui autorise le contexte de template complet. La discipline de rédaction attend des auteurs qu’ils :

  • Lisent .values pour le payload cognitif (intention rédigée par le développeur).
  • Lisent .infra pour le dimensionnement physique (dimensionnement rédigé par l’opérateur).
  • Lisent .context.uses[].provides.<key> pour les chaînes de pointeurs inter-composants (le flux de données de la triade topologique).
  • Lisent .context.inject pour le pipe de livraison post-hydratation (assemblé à partir des sources d’inject dans component.inject, uses[].inject et les interceptions injectMapping de FeatureRecipe).

La discipline est faite de panneaux indicateurs, pas de murs. Un template de Recipe qui lit .infra.replicas pour piloter un champ values: fonctionne ; le moteur de templates ne bloque pas la lecture. Le cadrage de l’architecture est que les frontières des piliers décrivent l’intention de rédaction — à qui appartiennent les données — plutôt qu’une restriction à l’exécution. Les conventions correspondent à la répartition en quatre domaines : les valeurs rédigées par le développeur proviennent de .values ; le dimensionnement rédigé par l’opérateur provient de .infra ; les coordonnées inter-composants proviennent du pipe topologique.

Lorsqu’un pont inter-piliers délibéré est nécessaire — par ex. le schema: d’un Component expose un réglage destiné au développeur que le template valuesMapping: de la Recipe achemine vers une sortie en forme d’infra: côté Ops, selon vocabulary/inheritance-and-interface.md — l’architecture traite le pont comme une exception signalée. Voir « Cross-pillar mechanics (Mécanismes inter-piliers) » ci-dessous.

Values

Le pilier values: porte le payload cognitif rédigé par le développeur — les paramètres de forme de l’application que le développeur dicte pour chaque instance de composant. Le schema: du Component déclare la forme des valeurs ; l’Aggregate du développeur renseigne des valeurs concrètes pour chaque instance. C’est le domaine du développeur.

Rédigé dans :

  • Aggregate components.<id>.values: — payload cognitif par instance de composant.
  • Aggregate subsystems.<name>.components.<id>.values: — idem, à l’intérieur de composants regroupés en sous-systèmes.
  • Aggregate components.<id>.features.<name>.values: et features.<name>.values: d’un sous-système — payload des valeurs du rattachement, quelle que soit la famille à laquelle appartient la Feature rattachée (les paramètres de requête au vault d’un rattachement d’identifiants sont rédigés ici comme les autres).

Interdit dans :

  • Entité Release (le schéma de la Release interdit un bloc values: à tous les niveaux d’imbrication — le Parameter Hoisting est la voie prise en charge pour la variation par environnement ; voir Parameters ci-dessous).

Validé par : le bloc values: du schema du Component (et le bloc values: du schema de la Feature pour les rattachements de Feature), résolu en JSON Schema 2020-12 au chargement du Component / de la Feature selon vocabulary/validation-surface.md, couche 2.

Consommé par : les templates valuesMapping: de la Recipe via .values. Le contexte de template complet expose le dictionnaire des valeurs résolues à chaque site de template du rendu de base.

Infra

Le pilier infra: porte le dimensionnement physique rédigé par l’opérateur — réplicas, demandes de ressources, limites d’IOPS, épinglage de région, classe de machine. Il exprime le où et quelle taille, en complément du quoi et comment cela se comporte des values. C’est le domaine de l’opérateur.

Quatre surfaces de rédaction

Les auteurs rencontrent infra: sur quatre surfaces distinctes, chacune avec une portée différente et un comportement de cascade différent :

#SurfacePortéePriorité de fusion
1Frontière de la Release components.<id>.infra: (spec.components.<id>.infra: dans une Release sans frontières)Une instance de composantLe dimensionnement propre du composant ; aucune autre surface ne l’écrit
2Frontière de la Release features.<name>.infra:Un rattachement de portée frontière, sur chaque composant de la frontièreLa plus basse pour ce rattachement — la surface 3 la remplace champ par champ
3Frontière de la Release components.<id>.features.<name>.infra:Un rattachement sur un composantRemplace la surface 2 pour ce rattachement, champ par champ
4Release components.<id>.uses.<socket>.<alias>.infra:Une connexionValidé par rapport à l’infraSchema du socket ; n’atteint que le rendu du composant consommateur

La surface 1 est la plus rédigée : un opérateur dimensionne chaque composant que la Release place. Une frontière ne porte aucun infra: propre — le schéma de la Release le refuse — donc un dimensionnement que partagent plusieurs composants s’écrit sur chacun, ou s’hérite d’une Release parente via extends: (ci-dessous). Les surfaces 2 et 3 couvrent le dimensionnement des rattachements de Feature — les Features portent leur propre payload infra que la FeatureRecipe consomme lorsqu’elle synthétise des sidecars ou des ressources par Feature : un rattachement de portée frontière est dimensionné une fois, et un composant en ajuste un seul champ.

« Infra principalement localisé » — la règle avec exceptions

La cible architecturale pour infra: est locale au composant : le dimensionnement d’un composant s’applique à cette instance de composant et ne déborde pas sur les autres composants. C’est le mécanisme qui permet à Ops d’augmenter les IOPS de la base de données sans affecter la demande de CPU du serveur d’API.

La règle : infra: est principalement localisé sur la surface qui l’a rédigé. Des exceptions de cascade existent à dessein :

  • Cascade des annotations de frontière. Les annotations: d’une frontière se propagent en cascade à travers les frontières imbriquées jusqu’aux composants internes (surface 5 de la matrice des annotations dans labels-and-annotations.md). Les annotations que les Recipes consomment comme entrée de routage deviennent une portée indirecte d’infra — l’annotation au niveau de la frontière passe par .context.annotations.release dans la sortie rendue de la Recipe par nœud.
  • Héritage de Release via extends:. Une Release qui fait extends: d’une Release parente hérite des déclarations infra du parent sur chaque surface qui les porte, sauf si l’enfant les remplace clé par clé. La valeur de l’enfant l’emporte clé par clé, jusqu’à la première valeur indivisible — un scalaire, une liste, un template — qui est remplacée en entier, et une clé que l’enfant écrit à null est supprimée plutôt que mise à rien. L’héritage franchit délibérément la frontière propre à chaque Release ; pour la règle de fusion complète et ce qui voyage avec elle, voir entities/release.md.
  • Acheminement inter-piliers par pont de schéma. Le schema: d’un Component peut exposer un réglage values: destiné au développeur que le template valuesMapping: de la Recipe achemine vers la sortie du fournisseur en forme d’infra: (voir « Cross-pillar mechanics — Schema-bridge cross-pillar piping (Mécanismes inter-piliers — Acheminement inter-piliers par pont de schéma) » ci-dessous). À strictement parler, la valeur naît dans values: et passe dans la sortie rendue ; la cascade est interne à l’instance mais inter-piliers.

La localisation est l’intention de conception, pas un mur que le moteur impose : les cascades ci-dessus sont des exceptions délibérées, chacune documentée sur la surface qui la porte.

Partition entre côté et pilier pour l’expansion de Feature pilotée par les annotations. L’invariant de l’Aggregate comme surface de rédaction se prolonge jusqu’au chemin d’expansion de Feature piloté par les annotations : les annotations côté Aggregate (portée de sous-système et d’instance de composant) ne peuvent déclencher que des sous-clés maps.values ; les annotations côté Release (portée de frontière et d’instance de composant) ne peuvent déclencher que des sous-clés maps.infra. Un binding de Manifest peut déclarer des chemins dans les deux piliers ; chaque côté ne déclenche que son sous-ensemble compatible, et la composition entre côtés fusionne les contributions champ par champ au moment du build de l’IR. La partition préserve la séparation de rédaction values-développeur / infra-opérateur sur la surface des annotations — la même séparation que values: et infra: imposent sur les surfaces de rattachement explicite. Voir providers/well-known-annotations.md §« Side-vs-pillar partition per subkey (Partition entre côté et pilier par sous-clé) » pour l’explication par sous-clé et le motif de composition entre côtés.

Provides

Le pilier provides: est dérivé — une Recipe le déclare, mais contrairement à values / infra, le développeur ne le rédige pas directement. Les Recipes calculent les chaînes de sortie publiques que le pipe topologique consommera.

Le bloc provides: d’une Recipe est une map de paires <key>: <template>. Chaque template est évalué par rapport à la surface autosuffisante propre à la Recipe (.values, .infra, .context.instance_id, .context.rendered_name là où le fournisseur du nœud en signale un, et les .locals résolus du nœud) pendant l’évaluation des provides. Les chaînes résultantes sont exposées via .provides et consommées par les blocs uses[].inject des appelants via des références from: "<key>". .locals est disponible parce que les locals du nœud se résolvent dans le préambule de cette étape, avant ses provides (voir Locals ci-dessous) ; nommer une clé que le bloc locals ne déclare pas provoque un arrêt.

Invariant d’autosuffisance. Les templates provides: d’une Recipe ne doivent pas référencer .context.inject ni .context.uses. L’évaluation des provides exécute ces templates dans n’importe quel ordre — ils ne se referment que sur les données propres du nœud, donc l’ordre n’a pas d’importance. Des références entre nœuds lieraient cette évaluation à l’ordre d’itération topologique, ce que la conception évite délibérément. Voir templates/expansion-matrix.md, ligne 6, pour la règle et sa justification.

Pourquoi provides: est un pilier. Les chaînes de sortie sont la surface publique canonique de chaque Recipe ; les consommateurs en aval (uses[].inject de l’appelant, blocs injectMapping de FeatureRecipe lisant les provides résolus de la cible via .context.uses) traitent le dictionnaire comme un contrat typé. Nommer provides: comme pilier reconnaît son statut de premier ordre aux côtés de values / infra / uses / features. Le traiter comme « un simple détail interne de la Recipe » sous-estime son rôle de source de données principale du pipe topologique.

Uses

Le pilier uses: est la déclaration des arêtes topologiques. Le bloc uses: d’une instance de composant nomme les arêtes auxquelles le composant participe — les sockets par lesquels il consomme des cibles. La grammaire complète est documentée dans topology-triad.md ; cette section nomme uses: comme pilier par souci d’exhaustivité.

uses: se trouve sur les instances de composant de l’Aggregate + les rattachements de fonctionnalité ; le contexte de template à l’exécution expose une entrée par connexion sortante, indexée par son alias, sous .context.uses. La projection porte les métadonnées résolues de la cible de chaque arête (les provides de la cible, les labels, les annotations), de sorte que les Recipes des appelants peuvent lire les chaînes de pointeurs inter-composants lors de l’évaluation des templates du rendu de base, ainsi que les rattachements écrits sur cette connexion, à .context.uses.<alias>.features.<slot>.

Pilier Features

features: est le pilier des rattachements : un mot-clé, une forme, chaque rattachement. Une Feature opérationnelle, une Feature d’identifiants et une Feature d’identité sont toutes déclarées ici sous le nom d’instance que choisit l’auteur. Le contexte de template à l’exécution expose les rattachements du nœud sous la forme .features.<name>, chacun portant type, values, infra et les provides résolus du rattachement. Un rattachement écrit sur l’une des connexions du composant est exposé dans cette même forme sous la connexion, à .context.uses.<alias>.features.<slot>, et jamais sous .features — ainsi une Recipe qui parcourt .features ne rencontre que les rattachements propres au composant (voir le contrat du contexte de template).

Un rattachement dont le nom d’instance correspond à un slot que l’entité déclare dans featuresSchema remplit ce slot ; tout autre nom d’instance est un rattachement libre. Remplir un slot est ce qui relie les quatre surfaces que parcourt un identifiant fondé sur un slot :

SurfaceLieu de rédactionRôle
Component / Feature featuresSchema:entité du catalogueDéclare les slots que l’entité attend ; par slot, encadre la liste d’autorisation de livraison (env / file / blackbox) et, éventuellement, un sélecteur de labels que le remplissage doit satisfaire
Aggregate components.<id>.features.<slot>:Instance de composant de l’AggregateRemplit le slot avec un rattachement ; fournit les values: propres au rattachement et, pour un slot transparent, son mappage inject:
Workload containers.<name>.attachments.<KEY>.from/as:Corps de Workload de la RecipeRéférence un slot déclaré — ou, à côté de connection: <alias>, un slot que déclare le socket de cette connexion — et dicte la livraison par conteneur de ce qui l’a rempli
FeatureRecipe (source / workload / artifacts / valuesMapping, injectMapping, pipeline:)la FeatureRecipe liéeProduit la sortie du rattachement — une ressource émise, une réécriture de la livraison, ou les deux

Le nom du slot est l’identifiant porteur sur les quatre : la surface 1 le déclare, les surfaces 2–4 le référencent, et le flux de données va dans un seul sens (déclarer → remplir → référencer → produire).

Pour la liste de contrôle de rédaction, voir examples/04-secrets.md « The secret-delivery checklist (La liste de contrôle de la livraison des secrets) ».

Locals

Le pilier locals: est l’état privé de la Recipe. Le bloc entier se résout dans le préambule des locals, avant le provides: de ce nœud ; les chaînes résultantes sont visibles par chacun des templates ultérieurs propres à la Recipe — provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, pipeline[].with. Un template provides: qui nomme une clé que le bloc ne déclare pas provoque un arrêt.

Rédigé dans : bloc spec.locals: de la Recipe — une map de paires <key>: <template> évaluées par rapport à une surface autosuffisante locale au nœud : .context.instance_id, .values, .infra et les entrées du même bloc déjà résolues. Rien d’autre n’y figure : .provides, .metadata et le reste de .context.* n’y sont pas, et une référence à l’un d’eux provoque un arrêt.

L’ordre est porteur. Les entrées se résolvent dans l’ordre d’écriture et une entrée peut lire une entrée sœur définie au-dessus d’elle, en recevant sa valeur résolue. Le chaînage ne va que vers le bas — là où une entrée en lit une autre, déplacer la définition sous son lecteur est refusé, et le compilateur ne réordonne jamais le bloc pour que la référence se résolve. Une référence à une entrée ultérieure provoque un arrêt qui nomme le défaut d’ordre ; une référence à une clé non déclarée provoque un arrêt qui nomme la clé. Sur une Recipe dont le source: est un bloc structuré, les deux défauts sont aussi refusés pendant que l’artefact qu’il nomme est épinglé, de sorte que aggrega pull les signale avant qu’un build ne rende de sortie. La vérification lit le chemin vers lequel une référence se résout plutôt que les frappes, elle atteint donc de la même façon la forme directe, un bloc with .locals, une variable liée à .locals et le bloc entre parenthèses, (.locals).<key> ou ($.locals).<key>. Une écriture qu’elle ne couvre pas : une clé atteinte via une fonction, comme index .locals ou (default dict .locals).<key>. Une clé absente atteinte ainsi ne provoque pas d’arrêt, et elle rend le texte littéral <no value> plutôt que rien du tout — sauf via index lui-même, qui provoque un arrêt en nommant la clé sur chaque surface de template lorsque la map qu’il lit ne la contient pas.

Visibilité : privé à la Recipe. Il n’existe pas de champ .context.uses[].locals — un appelant ne peut pas lire les locals de sa cible à travers l’arête. Ce qu’un appelant peut lire, c’est le provides: de la cible.

Cas d’usage :

  • Calculer des chaînes de pointeurs internes à la Recipe (par ex. secret_target_admin_password: "redis-auth", le suffixe du nom d’un Secret) que consomment à la fois le valuesMapping: et le provides: de la Recipe, et qu’une FeatureRecipe d’identifiants rattachée au même composant lit sous la forme .locals.secret_target_admin_password — les templates d’un rattachement voient les locals résolus de la Recipe hôte fusionnés avec ceux du rattachement. Sur la cible helm, chacun d’eux écrit le nom complet sous la forme {{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }} : le nom rendu est le nom du composant écrit avec les caractères qu’autorise un nom Kubernetes, et un local ne peut pas le lire, donc le local porte le suffixe et chaque lecteur joint les deux.
  • Factoriser (DRY) des valeurs calculées répétées au sein d’une Recipe (un nom d’hôte calculé une fois, référencé depuis plusieurs champs valuesMapping:).
  • Valeurs intermédiaires pour une logique de template complexe qui serait illisible en ligne.

provides: et locals: — face publique et face privée

Les deux piliers côté Recipe portent une séparation délibérée de la visibilité que les auteurs devraient garder à l’esprit :

  • provides: est la face publique. Chaque clé est la surface canonique du pipe topologique — les blocs uses[].inject des appelants en aval les consomment via des références from: "<key>". Le dictionnaire provides: est un contrat typé dont dépendent les appelants ; renommer ou supprimer une clé est un changement cassant pour chaque Recipe dont les déclarations uses[].inject la référencent.
  • locals: est la face privée. Chaque clé est un état interne à la Recipe, visible uniquement à l’intérieur des templates ultérieurs propres à la Recipe. Aucun appelant ne peut lire les locals d’une Recipe ; les noms dans locals: ne font partie d’aucune interface publiée et les renommer est une refactorisation interne à la Recipe sans effet en aval.

Les deux sont aussi ordonnés : locals: se résout en premier, donc provides: peut lire .locals mais locals: ne peut pas lire .provides. Publier la valeur d’un local via provides: signifie donc ajouter une entrée provides qui lit le local — l’expression reste à un seul endroit.

La séparation est délibérée, conformément à la séparation architecturale entre les internes de la Recipe (privés) et l’interface de la Recipe (publique). Les auteurs qui traitent provides: et locals: comme un seul espace de noms perdent la distinction de visibilité et risquent d’exposer un état interne à travers le pipe topologique — chaque clé déclarée dans provides: devient partie de la surface contractuelle de la Recipe, que l’auteur l’ait voulu ou non. L’objectif de la discipline : déclarer d’abord une clé dans locals: ; la promouvoir vers provides: uniquement lorsqu’un appelant en aval en a réellement besoin.

La visibilité est fixée par le pilier dans lequel une clé est déclarée : il n’existe pas de marqueur de visibilité par clé, donc une valeur à la fois privée et publiée est une entrée locals: plus une entrée provides: qui la lit.

Parameters

Les schémas Aggregate et Release portent tous deux un dictionnaire parameters à leur racine. Les développeurs déclarent les clés qu’attend l’Aggregate ; Ops renseigne les valeurs à partir de fichiers de Release propres à chaque environnement. Ce découplage est le mécanisme de la promotion GitOps : un unique Aggregate.yaml immuable traverse les environnements Dev, Staging et Production, la Release de chaque environnement fournissant ses propres valeurs de paramètres.

aggregate.yaml
spec:
parameters:
corp_db_name:
type: string
required: true
env_workers:
type: integer
required: true
region:
type: string
required: true
enable_debug:
type: boolean
required: true
components:
my-backend:
type: core/python-worker:1.0.0
values:
workers: {{ .parameters.env_workers }}
region: "{{ .parameters.region }}"
# release-prod.yaml — inline parameter values
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
corp_db_name: "enterprise_data"
env_workers: 10
region: "eu-west-1"
enable_debug: false

Pour les flux CI/CD qui conservent les valeurs des paramètres dans un fichier séparé (par ex. un .yaml par environnement versionné à côté de la Release), la Release utilise la forme $import: : parameters: { $import: ./prod-values.yaml }. Le contenu du fichier remplace la map en ligne à la surface de la Release. Le chemin se résout depuis le répertoire qui contient la Release, quel que soit l’endroit d’où une commande est lancée, et doit mener à un fichier à l’intérieur de l’espace de travail — ou, pour une Release désignée hors de l’espace de travail, à l’intérieur du répertoire qui la contient. La superposition de plusieurs fichiers (combiner un fichier de base avec un overlay propre à un environnement) s’exprime par des chaînes extends: de Release — la Release parente fournit les paramètres de base ; la Release enfant étend et remplace clé par clé.

Cycle de vie des paramètres. Le compilateur résout les paramètres en trois phases. (1) Remplissage par défaut — les slots qui définissent default: et n’ont aucune valeur de Release reçoivent leur valeur par défaut. (2) Validation du contrat des paramètres — le contrat typé parameters: valide chaque valeur par rapport à ses contraintes déclarées type / enum / min / max / pattern, valeur par défaut remplie comprise, de sorte qu’une valeur par défaut qui enfreint son propre contrat arrête le build. (3) Interpolation — le compilateur évalue tout le texte de l’Aggregate comme un template et remplace chaque référence {{ .parameters.<slot> }} par la valeur résolue. La map fusionnée reste ensuite lisible pendant le rendu, de sorte que les templates de chemin (frontière de la Release directory: / subDirectory:) puissent lire .parameters.<slot> directement, par rapport à la liste d’autorisation fermée documentée dans ../path-template-variables.md. Les surfaces de template de valeur (Recipe valuesMapping, FeatureRecipe injectMapping / provides / pipeline.with, corps de Workload) ne reçoivent PAS .parameters dans leur contexte de template — elles consomment les valeurs résolues écrites dans les chaînes values: environnantes par l’interpolation de la phase 3.

La liste de contrôle de la remontée des paramètres

Chaque valeur qui varie d’un environnement à l’autre passe successivement par quatre points de contact de rédaction. Le modèle mental que portent les auteurs : pour toute valeur qui varie entre Dev / Staging / Production, attendez-vous à toucher l’Aggregate (déclarer), le template des values (référencer), la Release (remplir) et le template de la Recipe (consommer).

ÉtapeSurfaceAction
1Aggregate spec.parameters.<name>Déclarez le paramètre dans le cadre du contrat de rédaction typé de l’Aggregate. Chaque slot de paramètre porte un type déclaré (string, integer, number, boolean, array, object), une description facultative, un default facultatif, des contraintes facultatives sur l’espace des valeurs (enum, min, max, pattern, minLength, maxLength) et une structure imbriquée facultative pour les slots de type objet. Le contrat valide chaque valeur fournie par la Release avant l’interpolation.
2Template values: du Component à l’intérieur du même AggregateRéférencez le paramètre via {{ .parameters.<name> }} depuis l’intérieur du bloc values: de tout composant (ou fonctionnalité, ou sous-agrégat) qui le consomme. La référence est une expression de template Go — le compilateur l’évalue pendant la phase d’interpolation de la résolution.
3Release spec.parameters.<name> (en ligne ou parameters: { $import: ./path.yaml })Remplissez le paramètre avec la valeur propre à l’environnement à la surface de la Release. Des fichiers de Release par environnement fournissent des valeurs différentes pour la même clé de paramètre sans modifier l’Aggregate.
4Template valuesMapping: de la RecipeConsommez la valeur résolue via {{ .values.<key> }} — la Recipe est une surface de template de valeur ; son contexte de template ne porte pas .parameters directement. La variation par environnement atteint la Recipe à travers le dictionnaire values: post-interpolation qu’écrit la phase d’interpolation ci-dessus. (Les templates de chemin sur les frontières de la Release constituent l’exception : ils lisent .parameters.<slot> directement pendant le rendu, selon l’octroi asymétrique.)

Les quatre points de contact sont séquentiels et porteurs : omettre la déclaration dans l’Aggregate laisse la Release sans slot à remplir ; omettre la référence dans les values laisse la Recipe sans valeur à consommer ; omettre le remplissage dans la Release laisse le paramètre vide. Le compilateur valide la chaîne pendant la résolution (validation du contrat des paramètres par rapport à la déclaration typée parameters:, puis interpolation dans les chaînes values: environnantes, puis validation JSON Schema du dictionnaire values: résultant par rapport au schema: du Component ou de la Feature) ; les écarts apparaissent soit comme une violation du contrat des paramètres (détectée par rapport à la déclaration typée parameters:), soit comme une erreur de template non rempli (détectée à l’interpolation), soit comme une violation de contrainte JSON Schema par rapport au schéma values: (détectée à la validation du schéma).

Le motif est le mécanisme canonique de la promotion GitOps : un unique Aggregate immuable traverse les environnements, la Release de chaque environnement fournissant ses propres valeurs de paramètres. Toute valeur par environnement qu’un auteur veut faire varier a sa place dans la chaîne des paramètres plutôt qu’intégrée directement dans l’Aggregate.

Sémantique de fusion d’extends: par pilier

Lorsqu’une entité du catalogue déclare extends: et que le compilateur parcourt la chaîne d’héritage, le contenu de chaque pilier fusionne selon des règles propres au pilier. La sémantique diffère d’un pilier à l’autre ; le tableau ci-dessous est la référence canonique par pilier.

PilierComportement de fusion sur une chaîne extends:
values (JSON Schema 2020-12)Sur une chaîne de Feature, les schémas se composent via la composition JSON Schema 2020-12. Un Component qui étend ne rédige aucun contenu de pilier et reçoit le bloc de sa base exactement tel que la base l’a rédigé, à chaque profondeur d’une chaîne.
infra (fragment JSON Schema 2020-12)Comme values — composé sur une chaîne de Feature, hérité en entier par un Component qui étend.
provides (map de templates de la Recipe)Remplacement superficiel au premier niveau : la clé enfant remplace entièrement la clé parente de même nom ; les clés sœurs sont conservées du parent. Les templates ne sont pas composés ; le template de l’enfant possède entièrement son slot.
uses (usesSchema)Superposition de l’entrée entière par socket, par nom de socket. Un enfant ajoute des sockets que sa base ne déclare pas, et un socket qu’il redéclare sous un nom existant remplace entièrement cette entrée — ses schémas de valeur et d’infra et son selector ensemble. Les entrées de socket ne sont pas composées, et rien ne compare un selector redéclaré à celui de la base.
features (schéma par slot de featuresSchema)Superposition de l’entrée entière par slot, par nom de slot, aux mêmes conditions que usesSchema. Un enfant ajoute librement des slots ; un slot qu’il redéclare remplace entièrement l’entrée de la base au lieu de se composer avec elle.
locals (map de templates de la Recipe)Remplacement superficiel au premier niveau — comme provides.
parameters (map racine de l’Aggregate)Un Aggregate n’a pas de champ extends:, donc aucune chaîne d’Aggregate ne fusionne de paramètres. Sur une chaîne extends: de Release, un paramètre à valeur de map fusionne en profondeur avec priorité à la clé enfant, un paramètre à valeur scalaire est remplacé par l’enfant, et une clé que l’enfant écrit à null est supprimée.

Le motif général dépend du type et de la surface. Les piliers validés par schéma d’une Feature se composent selon JSON Schema 2020-12. Les piliers d’un Component qui étend sont hérités en entier — il n’en rédige aucun, donc son contrat est exactement celui de sa base, et une contrainte de la base ne peut donc pas être assouplie, par construction. Les surfaces à forme fixe — usesSchema et featuresSchema — se superposent par nom pour les deux types : un enfant ajoute des entrées, et une entrée qu’il redéclare remplace entièrement celle de la base. Les piliers rédigés comme templates utilisent un remplacement superficiel par clé, ce qui donne à l’enfant la pleine propriété de tout slot de template qu’il déclare.

Un Component qui étend resserre une contrainte via assertions: plutôt que via un pilier — un prédicat qu’il ajoute, évalué à côté de ceux dont il hérite. Voir inheritance-and-interface.md pour ce mécanisme.

Pour le mécanisme d’héritage lui-même, voir inheritance-and-interface.md « Inheritance via extends (Héritage via extends) », qui couvre les types du catalogue. Une Release n’est pas une entité du catalogue et se combine selon sa propre règle ; cette règle se trouve dans entities/release.md « Composite Release and extends: inheritance (Release composite et héritage par extends:) ».

Mécanismes inter-piliers

Le cadrage en panneaux indicateurs permet les lectures inter-piliers partout, sauf sur les surfaces d’autosuffisance documentées. Les motifs ci-dessous formalisent des mécanismes inter-piliers courants ; un symptôme de rédaction problématique est documenté afin que les auteurs reconnaissent le compromis.

Acheminement inter-piliers par pont de schéma — signalé, pas cloisonné

Les frontières des piliers relèvent de la discipline de rédaction : l’architecture signale ce qui va où (values: pour l’intention cognitive du développeur, infra: pour le dimensionnement physique d’Ops, provides: pour les chaînes émises par la Recipe, etc.) et le relecteur du catalogue fait respecter la convention. Le moteur de templates lui-même permet les lectures inter-piliers, sauf si les règles d’autosuffisance documentées les interdisent (le provides: d’une Recipe ne voit pas .context.inject ; le provides: de portée frontière d’une FeatureRecipe ne voit pas les champs propres à chaque consommateur). Les murs des piliers sont des panneaux indicateurs, pas une contrainte imposée.

Une exception signalée canonique : le schema: d’un Component peut déclarer un réglage values: destiné au développeur que le template valuesMapping: de la Recipe achemine vers la sortie rendue en forme d’infra:. Le développeur dicte l’intention via un champ values: typé ; le template de la Recipe achemine la valeur résultante vers la couche d’infrastructure du fournisseur sans que le développeur rédige de code d’infrastructure. Un exemple détaillé :

# Component schema declares a developer-facing dial in values
spec:
schema:
values:
required_iops: { type: integer, min: 100 }
# Recipe valuesMapping pipes the developer's intent into the provider's infra-side knob
valuesMapping:
iops_limit: "{{ .values.required_iops }}"

Le pont est documenté dans inheritance-and-interface.md avec des exemples détaillés. L’intention architecturale (un réglage inter-piliers déclaré que la Recipe achemine) va dans une seule direction — des values: côté développeur qui passent dans la sortie rendue côté Ops — et se concrétise dans les templates de mapping de la Recipe, pas dans le schéma du Component lui-même. La frontière des piliers reste signalée : le développeur voit values:, la Recipe voit à la fois values: et infra:, la sortie rendue les combine.

Accumulateur inject inter-piliers

Le pipe .context.inject est le point de fusion de trois sources qui traversent les piliers :

  1. Self-inject au niveau du Component (component.inject) — tire ses chaînes des values et des provides propres au composant.
  2. Uses-inject (uses[].inject) — tire ses chaînes des provides de la cible.
  3. Interceptions injectMapping: de la FeatureRecipe — tirent leurs chaînes de n’importe laquelle des sources ci-dessus, plus le payload infra: propre à la FeatureRecipe.

Au moment où le rendu de base s’exécute, .context.inject.<mechanism>.<key> a accumulé des entrées provenant des trois sources. L’accumulateur est inter-piliers par construction — des entrées issues de values, provides et infra passent toutes dans la même map .context.inject. Les Recipes qui consomment .context.inject voient l’état après fusion sans avoir besoin de savoir quel pilier a fourni quelle entrée.

Pour la grammaire d’inject et les règles de collision, voir topology-triad.md.

Duplication des contraintes inter-piliers

Un champ qui vit dans deux piliers avec des couches de validation différentes peut porter des contraintes en double. L’exemple canonique : un numéro de port déclaré dans l’usesSchema d’un Component (validé par JSON Schema, plage min: 1, max: 65535) et le même numéro de port consommé dans le champ services.<name>.ports.<port> d’un Workload, pour lequel le spec.provider.workloadSchema du plugin de rendu du fournisseur peut ajouter une règle min: 1024 pour les ports non privilégiés. Le spec.provider.workloadSchema d’un Plugin de rendu du fournisseur documente la façon dont le fournisseur traduit un Workload et indique que le fournisseur est capable d’en synthétiser un ; il ne valide rien. Tout corps de Workload est validé par rapport au schéma Workload de la plateforme, quel que soit le fournisseur, donc une contrainte écrite uniquement dans un workloadSchema — une règle de port min: 1024, par exemple — n’est pas appliquée ; pour refuser une telle valeur, placez la contrainte dans le schéma du Component ou dans une assertion.

Rattachement de Feature / isolation des piliers du Component

Un rattachement de Feature n’écrit pas dans les piliers du Component parent. Chaque Feature rattachée porte son propre payload de pilier (son propre bloc values: et son propre bloc infra:). La FeatureRecipe qui synthétise les ressources de la Feature lit son propre payload de pilier indépendamment de celui du Component. L’isolation porte sur les entrées : ce qu’un rattachement lit lui appartient, quel que soit le sort de ce qu’il écrit. Là où le fournisseur de la cible écrit des documents distincts, la sortie rendue du rattachement se trouve à côté de celle du Component, dans un répertoire qui lui est propre ; là où le fournisseur regroupe les contributeurs d’une frontière en un seul document, le rattachement contribue à ce document comme le fait le Component, et chaque ressource porte toujours l’identité propre du rattachement, de sorte que la provenance de chaque élément reste lisible.

Deux conséquences pour les auteurs :

  • Une définition values: sur un rattachement de Feature n’apparaît pas dans le .values du template valuesMapping: du Component. Le Component ne voit que ses propres valeurs.
  • Le payload infra: d’une Feature ne passe pas dans l’infra: du Component. Chaque Feature rattachée a son propre dimensionnement physique, limité aux ressources de la Feature.

L’isolation est explicite selon la séparation des responsabilités de l’architecture : les Features sont des contributeurs indépendants superposés aux Components via le modèle en oignon à 5 niveaux. Pour les surfaces de rattachement et leur ordre, voir labels-and-annotations.md « Feature attachment — five surfaces (Rattachement de Feature — cinq surfaces) ».

Le même nom de propriété dans les deux piliers

Un Component ou une Feature dont le spec.schema.values: et le spec.schema.infra: déclarent le même nom de propriété — à la racine, à n’importe quelle profondeur d’imbrication, ou les deux — est un symptôme fréquent de rédaction problématique. Les deux piliers sont des espaces de noms séparés à dessein (le compilateur accepte le chevauchement), donc le schéma est validé et la sortie rendue est bien formée. Le symptôme est cognitif : lecteurs et auteurs de templates se heurtent à la friction « quel pilier contient le foo que je lis ? » chaque fois qu’ils parcourent le schéma ou écrivent un template qui s’appuie dessus.

# Smell — both pillars declare `mode`. A reader of the schema or a
# template against the Feature has to disambiguate every reference.
spec:
schema:
values:
mode: { type: string }
infra:
mode: { type: string }

Les auteurs dont le chevauchement est intentionnel ont une vraie raison de garder les deux — par ex., un mode qui signifie « mode opérationnel de l’application » sous values ("debug" / "production") et « mode de topologie du déploiement » sous infra ("standalone" / "clustered") porte des sémantiques distinctes, et les noms se trouvent coïncider. Les auteurs dont le chevauchement est accidentel (le cas le plus courant) renomment l’une des entrées.

Une deuxième forme intentionnelle est une donnée unique que l’un ou l’autre auteur peut fournir. Les Features d’identifiants de la bibliothèque standard qui portent le localisateur d’un appelant — core/referenced-secret, core/referenced-secret-set, core/secret-value et core/secret-provided — la déclarent dans les deux piliers sous un même nom et une même forme, de sorte que le développeur l’écrit dans values ou l’opérateur dans infra, et l’assertion propre à chaque Feature refuse un rattachement qui l’écrit dans les deux ou dans aucun. Le signalement décrit ci-dessous nomme ces quatre à chaque chargement qui les atteint ; pour elles, il rapporte le contrat, pas une erreur.

Le chargement du catalogue émet un signalement notice: LINT: <kind> "<name>" at <path> declares property "<property>" in both values: and infra: pillars (path: <dotted-path>) pour chaque propriété homonyme dont le chevauchement aboutit à une feuille terminale d’au moins un côté. Les propriétés homonymes qui existent comme espaces de noms d’organisation partagés (les deux piliers portent un objet nommé ingress avec des sous-propriétés disjointes) ne déclenchent pas d’avertissement ; seul le chevauchement des feuilles est signalé. L’avertissement est un signalement — le build se poursuit.

Niveaux de validation des piliers

Les piliers portent la validation sur trois niveaux. Chaque niveau couvre une préoccupation différente ; le même champ peut être validé par plus d’un niveau (voir « Cross-pillar constraint duplication (Duplication des contraintes inter-piliers) » ci-dessus).

NiveauCe qu’il valideOù il s’exécute
1 — Enveloppe JSON SchemaForme structurelle (quelles clés sont présentes, si les types correspondent aux déclarations des champs)Résolution, à chaque chargement de fichier
2 — Schéma par pilier (schema / featuresSchema / usesSchema)Contenu typé par pilier, validé comme JSON Schema 2020-12Résolution, une fois l’enveloppe validée
3 — contrôle des capacités du fournisseurContenu du Workload conditionné par la capacité de mode synthétisé du fournisseur lié, documentée par le spec.provider.workloadSchema du plugin de rendu du fournisseurRendu de base, après la résolution de valuesMapping

Pour le tableau des formes d’erreur à quatre couches et les préfixes d’erreur par couche, voir validation-surface.md.

Mécanismes de valeur par défaut

Les valeurs par défaut apparaissent dans le corpus à travers plusieurs mécanismes distincts. Les auteurs rencontrent le mot « default » dans plus de cinq contextes ; le tableau ci-dessous est la référence canonique pour savoir quel mécanisme produit une valeur lorsque l’auteur laisse un champ vide.

#MécanismeLieu de rédactionDéclencheur
1default: de JSON Schema (forme compacte { default: <value> })schema: de Component / Feature, parameters: de l’AggregateLe champ est validé avec la valeur par défaut lorsque le développeur omet la clé. Pour les paramètres de l’Aggregate, la fusion des paramètres renseigne la valeur par défaut déclarée avant l’exécution de la validation du contrat (voir templates/parameters-context.md).
2Template Go optional .X `Y` <fallback>valuesMapping: de la Recipe, corps du Workload, templates de FeatureRecipe, l’évaluateur d’assertionsValeur de repli sensible à la présence — renvoie <fallback> uniquement lorsque la clé est absente de la map ; un zéro / vide / false rédigé à la clé renvoie cette valeur rédigée. La forme canonique, côté Aggrega, du repli pour champ absent. Voir templates/sprig-functions.md.
3Template Go | default <expr>valuesMapping: de la Recipe, corps du Workload, templates de FeatureRecipePipeline en ligne qui se déclenche sur « vide » (le test de vacuité de Sprig — zéro, chaîne vide, false, nil). Confond l’absence de la map avec la présence d’une valeur zéro/vide/false. Adapté à une sémantique de surcharge propre à chaque site d’appel (le repli du binding diffère de la valeur par défaut du champ au niveau du schéma) lorsque cette confusion est acceptable. Pas adapté au repli pour champ absent lorsqu’un zéro / vide / false rédigé est une intention légitime — utilisez optional (mécanisme 2) dans ce cas.
4Fonction default de Sprig ({{ default <expr> .field }})Comme 3Forme fonctionnelle du mécanisme 3, avec la même confusion liée à la vacuité.
5Repli dans locals: de la RecipeTemplate locals: de la RecipeUne entrée de locals calcule une chaîne porteuse d’une valeur par défaut que le reste de la Recipe consomme

Recommandations de placement. Lorsqu’une valeur par défaut fait véritablement partie du contrat du type (par ex., « ce port vaut 5432 par défaut sauf si le développeur le remplace »), le default: de JSON Schema (mécanisme 1) est canonique — l’autocomplétion de l’IDE affiche la valeur par défaut ; les outils de validation la respectent ; le contrat accompagne l’entité de catalogue Component / Feature OU la déclaration du paramètre de l’Aggregate. Lorsqu’un template de Recipe a besoin d’un repli pour une clé de map facultative, l’assistant optional (mécanisme 2) est la forme canonique du repli pour champ absent — il distingue un zéro / vide / false rédigé de l’absence. Le | default du template Go (mécanisme 3) est réservé au cas de surcharge propre à chaque site d’appel, où la confusion entre valeurs absentes et falsy est acceptable ; n’y recourez que lorsque la sémantique de surcharge est l’intention explicite.

Références croisées

  • inheritance-and-interface.md — mécanisme extends:, liaison d’interface implements:, acheminement inter-piliers par pont de schéma.
  • topology-triad.md — mécanismes topologiques provides, inject, uses.
  • labels-and-annotations.md — vocabulaire de métadonnées côté contenu, distinct des piliers de données (la liste canonique des piliers ci-dessus n’inclut pas les labels / annotations / champs de publication — ceux-ci relèvent du vocabulaire de métadonnées).
  • publishing-surface.md — vocabulaire de métadonnées côté publication, distinct des piliers de données.
  • validation-surface.md — quatre couches de validation de schéma, dont les trois niveaux de validation des piliers ci-dessus.
  • templates/expansion-matrix.md — disponibilité, par site de template, des lectures inter-piliers + règles d’autosuffisance pour provides: et source: de la Recipe.
  • examples/04-secrets.md — la liste de contrôle de la livraison des secrets en six points de contact.
  • architecture/06-data-taxonomy-and-composition.md — cadrage conceptuel canonique des cinq mots-clés structurels du DSL.