Annotations bien connues
Les Providers lisent des annotations spécifiques pour configurer un contexte propre à la plateforme — définies sur la frontière d’une Release ou sur l’entrée d’un composant dans une Release, ou déclarées dans l’Aggregate sur un sous-système ou une instance de composant. Le compilateur lui-même est agnostique vis-à-vis des valeurs de ces annotations — il les transmet comme des chaînes opaques. Chaque fournisseur déclare quelles annotations il lit, à quelle portée, et quelle valeur par défaut s’applique lorsque l’annotation est absente. Cette déclaration se trouve dans spec.provider.wellKnownAnnotations d’un Plugin de rendu de fournisseur, et elle est délibérément étroite : un fournisseur ne liste une clé que là où il la lit. Un fournisseur qui n’en lit aucune déclare spec.provider.readsNoWellKnownAnnotations: true à la place.
La matrice de prise en charge de ce chapitre est générée à partir de ces déclarations, à la granularité que porte la déclaration — par fournisseur par type d’entrée, car un fournisseur peut lire une clé lorsqu’il synthétise une unité de déploiement et n’avoir aucun moyen de la lire lorsqu’il rend un artefact copié localement. Rédigez en vous appuyant sur la matrice d’ici : une cellule dit ce que ce fournisseur lit sur ce chemin, car une cellule ne peut rien dire que le fournisseur n’ait pas déclaré. Une déclaration qui nomme un type d’entrée que le propre contrat de comportement de rendu du fournisseur ne rend pas est refusée lorsque l’entité Plugin est lue, de sorte que les deux affirmations ne peuvent pas diverger.
Le vocabulaire réservé est l’ensemble plus large, et il se trouve plutôt à deux endroits — ce chapitre, qui nomme chaque clé réservée, y compris celles qu’aucun fournisseur ne lit, et l’ensemble des préfixes réservés que vérifie le lint de publication.
Les invariants
- Le compilateur n’interprète ni ne valide jamais la valeur d’une annotation bien connue de fournisseur : il transporte la clé et sa valeur à travers la cascade, et avertit là où une cible n’agit pas sur la clé.
- Chaque fournisseur documente quelles annotations il lit et quelles valeurs par défaut il applique.
- Les annotations s’appliquent uniformément au sein d’une frontière. Si une valeur varie selon le composant, elle a sa place dans des annotations au niveau du composant (qui remplacent les annotations de frontière) ou dans
infradu composant. - Les annotations bien connues des Provider ne dupliquent jamais les labels des composants. Les labels de Component décrivent ce qu’est un composant. Les annotations de frontière décrivent où un composant est déployé.
- Les Recipes ne traitent pas les annotations bien connues de fournisseur. Le fournisseur applique automatiquement le contexte de placement (espace de noms, préfixe de registre, compte de service) après que la Recipe a produit son contenu.
- Le préfixe
aggrega.ai/est réservé à la bibliothèque standard. Les annotations d’entreprise personnalisées utilisent leur propre préfixe. - Les annotations au niveau Component dans la Release remplacent les annotations au niveau de la frontière (fusion profonde, le composant l’emporte). Lorsqu’un fournisseur assemble la sortie de plusieurs frontières en un seul artefact, il peut exiger qu’une annotation se résolve uniformément entre elles — le fournisseur
helm-charttire le nom du chart parapluie deaggrega.ai/chart-name, et lorsque plus d’une frontière contribue au même chart et qu’elles résolvent cette annotation en valeurs différentes, le build s’arrête en nommant les frontières en désaccord, car un chart ne peut pas porter deux noms. - Les annotations que déclare l’Aggregate atteignent les mêmes clés en dessous de celles de la Release. Une clé déclarée sur un sous-système ou sur une instance de composant — dans l’Aggregate lui-même, ou dans un module qu’il importe, où elle atteint les composants propres du module — s’applique au composant partout où la Release ne définit aucune valeur pour cette clé ; là où la Release en définit une, sur la frontière ou sur l’entrée du composant, c’est la valeur de la Release qui s’applique. Les annotations propres d’une entité de catalogue n’en définissent jamais.
aggrega.ai/chart-nameest l’exception à la portée de l’Aggregate : elle nomme un assemblage plutôt qu’un composant, et elle est lue depuis les frontières de Release qui y contribuent.
La matrice complète des annotations
Comment lire cette matrice
Les six tableaux par catégorie ci-dessous nomment chaque annotation du vocabulaire réservé aggrega.ai/, ce qu’elle contrôle et ce que fait le fournisseur lorsqu’elle est absente. Savoir si un fournisseur donné applique une clé donnée est une question plus fine, car un fournisseur rend plus d’un type d’entrée — un artefact copié localement (sourced), un Workload que le fournisseur synthétise lui-même (synthesized), ou les artifacts: d’une Recipe comme sortie entière d’un nœud (artifacts-only) — et une clé peut être lue sur l’un de ces chemins tout en étant inaccessible sur un autre. Quel fournisseur rend quel type d’entrée est indiqué dans ../../architecture/16-recipe-input-composition.md ; ce que chacun applique est Prise en charge par fournisseur et type d’entrée ci-dessous, qui est l’énoncé faisant autorité de cette page.
Chaque cellule de cette grille porte l’un de trois niveaux :
- Appliquée — le fournisseur applique la clé sur ce type d’entrée, et la sortie rendue change en conséquence de manière déterministe.
- Appliquée sous condition — le compilateur émet une surcharge additive à côté de l’artefact cible au lieu de modifier l’artefact, donc le fait que la valeur prenne effet dépend de ce que cet artefact expose une clé correspondante qui lui soit propre. Efficace en pratique, jamais une garantie. Aucun fournisseur n’implémente de cellule conditionnelle, et la surface de déclaration n’offre aucun moyen d’en exprimer une, donc la grille générée ci-dessous n’émet que les deux autres niveaux. Le niveau est nommé parce que la voie existe réellement pour un artefact copié localement, et un vocabulaire à deux niveaux forcerait la matrice soit à revendiquer une garantie qu’elle ne peut pas donner, soit à nier que la voie existe tout court.
- Non appliquée — aucun fournisseur n’applique la clé sur ce chemin : la cible n’y a aucun emplacement de rendu pour elle, donc le mécanisme de placement ne contribue en rien à ce qui est rendu, et la colonne Par défaut du tableau de catégorie indique ce que vous obtenez à la place. La valeur traverse quand même le build comme une chaîne opaque, intacte. Le niveau est nommé d’après le mécanisme plutôt que d’après le sort de la valeur, car ce sont des questions différentes et seule la première est une question à laquelle une cellule peut répondre : ce qu’un fournisseur applique est une propriété des emplacements de rendu de cette cible, ce qui est exactement ce qu’énonce la déclaration derrière chaque cellule.
Deux portées, et une seule d’entre elles fait du type d’entrée un axe pertinent :
- À portée de nœud —
aggrega.ai/namespace,aggrega.ai/image-registry,aggrega.ai/image-pull-secret,aggrega.ai/service-accountetaggrega.ai/kubernetes-versionfaçonnent la sortie rendue propre d’un composant, que produit le chemin sélectionné par son type d’entrée. Ce sont les colonnes de la grille. - À portée d’assemblage et de référence —
aggrega.ai/chart-nameest résolue une seule fois lorsqu’un chart parapluie est assemblé, et les trois clésaggrega.ai/aws-*sont résolues lorsqu’une référence franchit une frontière. Le type d’entrée n’est un axe pour aucune des deux : la valeur est lue à l’assemblage ou à la référence, quelle que soit la façon dont chaque nœud contributeur a été rendu. Elles ont leur propre tableau dans Clés résolues par assemblage et par référence.
Catégorie 1 — Placement
| Annotation | Appliquée par | Objectif | Par défaut |
|---|---|---|---|
aggrega.ai/namespace | helm (avec source, synthétisé) ; compose (avec source, synthétisé) | Espace de noms Kubernetes (helm) ; nom du réseau Docker (compose) | Non injecté si absent (helm) ; un réseau nommé d’après le chemin du fichier compose, partagé par chaque nœud de ce fichier dépourvu de l’annotation (compose) |
aggrega.ai/project-name | réservée ; aucun fournisseur ne la lit | Réservée à un nom de projet Docker Compose | — |
aggrega.ai/region | réservée ; aucun fournisseur ne la lit | Réservée à une région cloud à la portée du placement | — |
aggrega.ai/account-id | réservée ; aucun fournisseur ne la lit | Réservée à un identifiant de compte cloud à la portée du placement | — |
aggrega.ai/kubernetes-version | helm (avec source) | Version de Kubernetes du cluster sur lequel le composant est déployé, qu’un chart rendu depuis la source lit comme .Capabilities.KubeVersion | La version pour laquelle rend le helm template standard de la même release helm : celle de la bibliothèque cliente Kubernetes avec laquelle le fournisseur est construit |
aggrega.ai/namespace a un double usage par conception. Il exprime la même intention d’isolation logique — « les ressources de cette frontière vivent dans leur propre portée adressable » — sous la forme native de chaque cible : un metadata.namespace Kubernetes pour helm, un nom de réseau Docker pour compose. Les auteurs de Recipe définissent une seule annotation ; chaque fournisseur la matérialise de manière appropriée pour la cible. Dans le cas de compose, le nom du réseau est résolu par nœud à partir de l’annotation de ce nœud, en se rabattant sur le chemin du fichier compose lorsque le nœud ne porte aucune annotation — de sorte que des frontières sans annotation qui partagent un fichier compose partagent un réseau, et c’est aggrega.ai/namespace qui les sépare. Quel que soit celui des deux qui fournit l’identité, celle-ci est ensuite écrite dans les caractères qu’accepte un nom de réseau compose — tout autre caractère est écrit sous forme de séquence d’échappement plutôt que remplacé, de sorte que deux identités qui diffèrent si peu que ce soit restent sur deux réseaux, et la casse de l’identité est conservée telle que rédigée. La référence du fournisseur compose documente la dérivation en entier, y compris comment lire un nom encodé et ce que coûte un renommage.
aggrega.ai/kubernetes-version énonce une propriété du cluster sur lequel un composant est déployé plutôt que l’endroit où le composant y aboutit : les templates de chart choisissent une version d’API, un champ ou un mécanisme entier selon la version pour laquelle ils sont rendus, et le build n’a aucun cluster à interroger. Le fournisseur helm lit la valeur de la même façon que helm template --kube-version lit son option, et arrête le build sur une valeur qui n’est pas une version ; lorsqu’aucune n’est nommée, un chart est rendu pour la version pour laquelle rend helm template de la même release helm. La référence du fournisseur helm documente les formes acceptées et la valeur par défaut.
Catégorie 2 — Registre
| Annotation | Appliquée par | Objectif | Par défaut |
|---|---|---|---|
aggrega.ai/image-registry | helm, compose — synthétisé uniquement | Préfixe de registre pour les images de conteneur, appliqué à chaque référence d’image de conteneur synthétisée | Aucun préfixe |
aggrega.ai/image-pull-secret | helm — synthétisé uniquement | Nom imagePullSecrets de Kubernetes, fusionné avec les entrées existantes du pod synthétisé | Aucun |
Catégorie 3 — Réseau
| Annotation | Appliquée par | Objectif | Par défaut |
|---|---|---|---|
aggrega.ai/cluster-domain | réservée ; aucun fournisseur ne la lit | Réservée à un suffixe DNS pour la découverte de services entre espaces de noms | — |
aggrega.ai/ingress-class | réservée ; aucun fournisseur ne la lit | Réservée à une IngressClass Kubernetes sur les ressources Ingress | — |
aggrega.ai/service-mesh | réservée ; aucun fournisseur ne la lit | Réservée aux annotations d’injection de sidecar du maillage | — |
Catégorie 4 — Sécurité
| Annotation | Appliquée par | Objectif | Par défaut |
|---|---|---|---|
aggrega.ai/service-account | helm — synthétisé uniquement | ServiceAccount Kubernetes pour les Pods synthétisés ; remplace le workload.serviceAccount de la Recipe lorsque les deux sont définis | Le workload.serviceAccount de la Recipe, ou non défini lorsque la Recipe n’en déclare aucun |
aggrega.ai/pod-security-standard | réservée ; aucun fournisseur ne la lit | Réservée à un niveau des Pod Security Standards | — |
aggrega.ai/iam-role | réservée ; aucun fournisseur ne la lit | Réservée à un rôle d’identité cloud lié à une charge de travail | — |
Catégorie 5 — Empaquetage
| Annotation | Appliquée par | Objectif | Par défaut |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart — par assemblage | Nom du chart parapluie | Nom de l’Aggregate et chemin d’assemblage du parapluie, joints — voir Résolution du nom de chart |
aggrega.ai/chart-version | réservée ; aucun fournisseur ne la lit | Réservée à une version de chart Helm | — |
aggrega.ai/stack-name | réservée ; aucun fournisseur ne la lit | Réservée à une stack nommée explicitement | — |
aggrega.ai/tf-backend | réservée ; aucun fournisseur ne la lit | Réservée à un identifiant de backend d’état Terraform | — |
Catégorie 6 — Cible cloud
| Annotation | Appliquée par | Objectif | Par défaut |
|---|---|---|---|
aggrega.ai/aws-account | cloudformation — par référence entre frontières | Compte AWS dans lequel la stack (frontière) est déployée | Même compte — une référence entre stacks se résout par l’import d’un export de stack dans le même compte |
aggrega.ai/aws-region | cloudformation — par référence entre frontières | Région AWS dans laquelle la stack (frontière) est déployée | Même région — une référence entre stacks se résout par l’import d’un export de stack dans la même région |
aggrega.ai/aws-assume-role-arn | cloudformation — par référence entre frontières | ARN du rôle IAM qu’assume une lecture de stack entre comptes pour atteindre les valeurs exportées d’une stack homologue | Aucun rôle n’est fourni sur une référence entre comptes |
Chaque frontière CloudFormation est rendue dans une seule stack. Lorsqu’une arête uses passe d’une frontière à une autre, le fournisseur cloudformation doit savoir où se trouve la stack homologue pour façonner la référence : deux stacks dans le même compte et la même région échangent des valeurs par un export et un import de stack ; une homologue dans un compte ou une région différents nécessite une lecture des sorties de stack entre comptes, éventuellement sous un rôle assumé. Ces annotations portent ce contexte de placement. Chacune est lue au moment où le fournisseur façonne une telle référence, et résolue à ce moment-là par la cascade d’annotations ordinaire — une valeur définie sur le composant l’emporte sur une valeur définie sur la frontière, et une valeur que définit la Release l’emporte sur une valeur que déclare l’Aggregate. Une valeur au niveau de la frontière est donc la manière courante de les exprimer, pas la seule. Ce sont des chaînes pointeurs scalaires opaques — le fournisseur les achemine dans la référence qu’il construit et ne les résout jamais par rapport à l’état AWS réel ; le compte, la région et le rôle sont fournis par la Release ou déclarés dans l’Aggregate, et l’environnement d’exécution résout la lecture physique finale. Lorsque toutes les annotations sont absentes, le fournisseur traite l’homologue comme étant dans le même compte et la même région et ne fournit aucun rôle.
Prise en charge par fournisseur et type d’entrée
Les clés à portée de nœud, par fournisseur et par type d’entrée. Les en-têtes de colonne omettent le préfixe aggrega.ai/ que porte chaque clé. applied et — portent les niveaux définis ci-dessus, — signifiant non appliquée ; n/a signifie que le fournisseur ne rend pas du tout ce type d’entrée, de sorte qu’il n’existe là aucun chemin sur lequel la clé pourrait être appliquée ou manquée.
| Provider | Type d’entrée | namespace | image-registry | image-pull-secret | service-account | kubernetes-version |
|---|---|---|---|---|---|---|
helm | sourced | applied | — | — | — | applied |
helm | synthesized | applied | applied | applied | applied | — |
helm | artifacts-only | — | — | — | — | — |
compose | sourced | applied | — | — | — | — |
compose | synthesized | applied | applied | — | — | — |
compose | artifacts-only | — | — | — | — | — |
helm-chart | sourced | — | — | — | — | — |
helm-chart | synthesized | n/a | n/a | n/a | n/a | n/a |
helm-chart | artifacts-only | n/a | n/a | n/a | n/a | n/a |
terraform | sourced | — | — | — | — | — |
terraform | synthesized | n/a | n/a | n/a | n/a | n/a |
terraform | artifacts-only | — | — | — | — | — |
cloudformation | sourced | — | — | — | — | — |
cloudformation | synthesized | n/a | n/a | n/a | n/a | n/a |
cloudformation | artifacts-only | — | — | — | — | — |
Chaque fournisseur distribué avec le compilateur a des lignes ici, y compris un fournisseur qui ne lit aucune annotation de placement — un ensemble de lignes vide serait impossible à distinguer d’un fournisseur que personne n’a encore décrit. Un fournisseur fourni séparément déclare ce qu’il lit de la même manière et n’est pas listé ici, car une page publiée ne peut pas énumérer des fournisseurs qu’elle n’a jamais vus.
Une Recipe peut déclarer plus d’un type d’entrée à la fois — un workload: avec des artifacts: à côté, par exemple. Lisez la grille par type : la sortie synthétisée d’un tel nœud correspond à la ligne synthesized, et ses fichiers d’artefacts au cas des artefacts. La ligne artifacts-only est le type d’entrée où une Recipe déclare artifacts: et rien d’autre.
Vous n’avez pas besoin de consulter la grille pour le savoir. Définir une clé que la cible de l’un de vos rendus ne lit sur aucun des types d’entrée de ce rendu produit un avertissement nommant la clé, la cible et chaque type d’entrée que ce rendu déclare, de sorte qu’une cellule dans laquelle vous êtes tombé par accident se signale au moment où vous lancez le build plutôt que d’attendre que vous pensiez à regarder ici :
warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored itSur un rendu déclarant plus d’un type d’entrée, l’avertissement porte sur ce rendu dans son ensemble, pas sur l’une de ses moitiés. Comme les types se composent par addition, une cible qui lit la clé sur l’un quelconque d’entre eux l’applique bel et bien, et la sortie de ce rendu porte le résultat — aucun avertissement n’est donc émis. Un avertissement n’apparaît que lorsque chaque type que déclare ce rendu manque la clé, et il les nomme tous :
warning: node "backend" (provider "helm"): target "helm" does not support annotation aggrega.ai/cluster-domain on sourced or synthesized input and ignored itAinsi, un workload: à côté d’un source: suffit pour que aggrega.ai/service-account prenne effet sur ce nœud, et le build reste silencieux à ce sujet — ce qui est le compte rendu honnête, car la valeur atteint la moitié synthétisée et apparaît dans les manifestes émis.
Lisez la grille par rendu, pas par composant. Une fonctionnalité rattachée à un nœud génère ses ressources par la cible que nomme sa propre FeatureRecipe, aux types d’entrée que déclare cette FeatureRecipe — elle aboutit donc dans sa propre ligne de cette grille, qui n’est pas forcément la ligne où aboutit son composant hôte. Un composant qui synthétise son Workload pendant qu’une fonctionnalité rattachée apporte des artifacts: à côté lit la ligne synthesized pour les manifestes propres du composant et la ligne artifacts-only pour les fichiers du rattachement, et une clé appliquée sur la première peut être manquée sur la seconde. L’avertissement suit la même séparation et vous informe de chacune séparément, car ce sont des fichiers différents. Une fonctionnalité rattachée à une frontière plutôt qu’à un composant nommé lit la grille de la même manière.
La valeur passe quand même intacte — le build ne s’arrête pas, car une frontière couvrant des composants sur des cibles hétérogènes aura toujours un rendu qui ne peut pas agir sur une clé donnée, et c’est une Release ordinaire plutôt qu’une erreur. Une annotation de frontière se propage en cascade, de sorte qu’une ligne rédigée produit un avertissement par rendu qui ne peut pas agir sur elle, ce qui vous permet de voir quelles parties de votre sortie sont concernées. Il appartient à la classe unsupported-field et se désactive avec l’option de cette classe ; Avertissements donne le détail. Deux limites à connaître : seules les clés au préfixe aggrega.ai/ nu sont vérifiées, car une clé à sous-préfixe relève de votre propre vocabulaire, et un fournisseur qui ne déclare aucune affirmation de prise en charge ne produit aucun avertissement, car il n’y a rien à quoi comparer ce que vous avez rédigé. Un fournisseur qui déclare ne lire aucune de ces clés n’est pas silencieux de cette manière : readsNoWellKnownAnnotations: true sur son entité Plugin est une affirmation ne couvrant aucune clé, de sorte que chaque clé au préfixe nu qui atteint l’un de ses rendus déclenche l’avertissement. Le fournisseur terraform le déclare.
Pourquoi un artefact copié localement applique moins de clés. Une annotation à portée de nœud est appliquée là où le fournisseur dispose d’un emplacement de rendu pour elle. Lorsque le fournisseur synthétise lui-même l’unité de déploiement, il possède chaque champ du résultat, de sorte qu’un préfixe de registre, un secret de pull et un compte de service ont tous un endroit où atterrir. Un artefact copié localement — un chart Helm, un fichier compose, un module Terraform — porte à la place sa propre interface de configuration, et le compilateur ne lit pas cette interface, il ne peut donc pas savoir à laquelle des clés propres de l’artefact correspondrait un préfixe de registre ou un compte de service. Le placement que contrôle l’appel de rendu environnant s’applique toujours, c’est pourquoi aggrega.ai/namespace est appliquée à un chart rendu depuis la source. Le placement qui reviendrait à décider où, à l’intérieur de l’artefact de quelqu’un d’autre, une valeur a sa place ne s’applique pas, et un auteur le fournit par les valeurs propres de cet artefact. C’est pourquoi les lignes avec source sont clairsemées là où les lignes synthétisées sont pleines, et c’est la forme à attendre de toute clé ajoutée plus tard.
Clés résolues par assemblage et par référence
Quatre des clés livrées ne sont pas à portée de nœud, elles se trouvent donc en dehors de la grille ci-dessus plutôt que d’y être intégrées : le type d’entrée n’est pas un axe pertinent pour elles, et donner à chacune une ligne par type d’entrée répéterait une seule cellule trois fois et suggérerait une distinction qui n’existe pas. Chacune déclare la portée de frontière, et le tableau ci-dessous est généré à partir de ces déclarations.
| Annotation | Appliquée par | Objectif | Par défaut |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart | Nom du chart Helm parapluie assemblé. | Le nom de l’Aggregate et le chemin d’assemblage du parapluie — son répertoire de sortie sous dist/, tel que boundaries/data/helm-chart — sont utilisés, chacun encodé, puis joints. |
aggrega.ai/aws-account | cloudformation | Le compte AWS dans lequel la stack (frontière) est déployée. Une référence entre frontières le lit pour décider si une stack homologue se trouve dans le même compte. | L’homologue est traitée comme étant dans le même compte, et une référence entre stacks se résout par l’import d’un export de stack dans le même compte plutôt que par une lecture des sorties de stack entre comptes. |
aggrega.ai/aws-region | cloudformation | La région AWS dans laquelle la stack (frontière) est déployée. Une référence entre frontières la lit pour décider si une stack homologue se trouve dans la même région. | L’homologue est traitée comme étant dans la même région, et une référence entre stacks se résout par l’import d’un export de stack dans la même région. |
aggrega.ai/aws-assume-role-arn | cloudformation | L’ARN du rôle IAM qu’assume une lecture de stack entre comptes pour atteindre les valeurs exportées d’une stack homologue. | Aucun rôle n’est fourni, et une référence entre comptes ne porte aucun assume-role. |
Quand chacune est résolue, ce que la déclaration elle-même ne porte pas. aggrega.ai/chart-name est résolue une seule fois par assemblage de chart parapluie, à partir de la cascade d’annotations de la frontière ; chaque contributeur à un même assemblage doit la résoudre en la même valeur, et un désaccord arrête le build en nommant les frontières. Les trois clés aggrega.ai/aws-* sont résolues par référence entre frontières selon la priorité du composant sur la frontière, de sorte qu’une valeur de composant l’emporte sur une valeur de frontière ; la catégorie 6 ci-dessus décrit la référence que façonne chacune d’elles.
Noms réservés qu’aucun fournisseur ne lit
Onze clés de la matrice ci-dessus sont marquées réservée ; aucun fournisseur ne la lit : aggrega.ai/project-name, aggrega.ai/region, aggrega.ai/account-id, aggrega.ai/cluster-domain, aggrega.ai/ingress-class, aggrega.ai/service-mesh, aggrega.ai/pod-security-standard, aggrega.ai/iam-role, aggrega.ai/chart-version, aggrega.ai/stack-name et aggrega.ai/tf-backend.
Définir l’une d’elles sur une Release ou dans un Aggregate n’a aucun effet sur la sortie rendue. Aucun fournisseur ne les lit, et aucune valeur par défaut n’est appliquée à leur place — en particulier, aucun suffixe DNS n’est appliqué pour aggrega.ai/cluster-domain, de sorte qu’une Recipe qui a besoin d’un domaine de cluster doit le fournir comme valeur ordinaire plutôt que de compter sur cette annotation. Un auteur de Recipe qui a besoin de l’un de ces comportements l’exprime comme une valeur de Recipe ou un champ infra de composant.
Aucun fournisseur ne déclare ces onze. Le wellKnownAnnotations d’un fournisseur ne liste que ce qu’il lit, de sorte qu’aucune des onze n’y apparaît — un lecteur qui ouvre le Plugin helm, helm-chart, compose ou cloudformation voit les clés qui fonctionnent et rien d’autre. C’est tout l’intérêt de la déclaration étroite : une clé déclarée est une clé qui fonctionne, et la portée à côté d’elle indique sur quel chemin.
Deux des noms réservés sont proches de clés actives et ne sont pas interchangeables avec elles. aggrega.ai/region et aggrega.ai/account-id nomment une région et un compte à la portée du placement et n’atteignent aucun fournisseur ; les clés que lit le fournisseur cloudformation sont aggrega.ai/aws-region et aggrega.ai/aws-account, dans l’espace de noms du cloud, en catégorie 6. Lorsque vous voulez dire le contexte de placement entre stacks de CloudFormation, rédigez la forme aws- — la paire sans préfixe est retenue pour éviter les collisions, et n’est reliée à rien. Deux autres noms réservés sont couverts par d’autres surfaces plutôt que par une annotation : aggrega.ai/stack-name est réservé, tandis que le nom de la stack dans laquelle une frontière cloudformation est rendue est dérivé de manière déterministe de l’identité de la release et de la frontière ; et le rôle d’identité cloud d’une charge de travail est fourni comme un champ ordinaire défini par l’opérateur sur la Feature qui émet la liaison, et non par aggrega.ai/iam-role.
Les noms restent réservés, et restent listés ici, parce que le préfixe aggrega.ai/ est réservé : un catalogue d’entreprise ne doit pas réutiliser l’une de ces clés pour un sens qui lui est propre, car la plateforme détient la clé pour un sens qui lui est propre. Cette matrice et l’ensemble des préfixes réservés que vérifie le lint de publication constituent ensemble le registre des réservations, et les deux sont tenus au même ensemble de noms par une vérification qui lit les deux et échoue lorsqu’ils divergent. Rédiger l’une des onze ne fait donc ni échouer la validation ni déclencher la règle « ne pas utiliser le préfixe aggrega.ai/ nu » — elle n’a simplement aucun effet.
La version du chart parapluie qu’émet une frontière helm-chart est toujours 0.1.0 ; c’est une valeur fixe plutôt qu’une valeur par défaut de aggrega.ai/chart-version.
Remarque : les liaisons
features.annotationsdu Manifest utilisant le préfixeaggrega.ai/sont rejetées au chargement ; le préfixe est réservé exclusivement aux annotations bien connues de fournisseur documentées dans ce chapitre. Les auteurs de liaisons de Feature pilotées par annotation utilisentfeature.aggrega.ai/pour les raccourcis de la bibliothèque standard ou un domaine personnalisé pour les raccourcis d’entreprise.Remarque : un
nullexplicite sur une annotation de Release retire la liaison héritée de la frontière ou du composant qui remplace (désactivation de Feature pilotée par annotation). Les composants frères de la même frontière qui ne s’en sont pas retirés conservent la liaison héritée ; les clés absentes continuent d’hériter de la cascade parente comme d’habitude.
Annotations rédigées dans le catalogue que lit le compilateur
Tout ce qui précède est une annotation de fournisseur : rédigée sur la Release ou déclarée dans l’Aggregate, transmise par le compilateur comme une chaîne opaque, lue par un fournisseur. Un second vocabulaire, bien plus petit, fonctionne dans l’autre sens — rédigé par l’Architecte sur les metadata.annotations propres à une entité de catalogue, lu par le compilateur, et jamais vu par un fournisseur. L’invariant 1 ci-dessus porte sur le vocabulaire des fournisseurs et ne s’étend pas à celles-ci ; le compilateur lit exactement les clés listées ici et aucune autre.
Ces clés se situent sous un sous-préfixe <scope>.aggrega.ai/, et non sous le préfixe aggrega.ai/ nu, elles sont donc en dehors du registre des réservations que porte la matrice ci-dessus et en dehors de la règle des préfixes réservés que le lint de publication applique aux clés à préfixe nu.
| Annotation | Rédigée sur | Lue par | Objectif |
|---|---|---|---|
features.aggrega.ai/requiredType.<label> | metadata.annotations du Component | le compilateur, sur le graphe finalisé | Déclare un mandat de présence : chaque instance de ce Component doit porter au moins un rattachement dont le type est égal à la valeur de l’annotation. <label> est un suffixe choisi par l’auteur qui nomme l’exigence dans le diagnostic ; ce n’est pas un nom d’emplacement et rien ne le déréférence. Répétez la clé avec des labels différents pour déclarer plusieurs mandats. |
Le mandat est satisfait par un rattachement à n’importe quelle portée — un bloc features: au niveau du composant ou du sous-système, un bloc de Release au niveau de la frontière ou du composant, ou une expansion pilotée par annotation — car il teste l’ensemble final des rattachements de l’instance plutôt que l’origine de chaque rattachement. Un mandat non satisfait arrête le build en nommant le label et le type requis ; une valeur qui n’est pas un URI de type de Feature, ou une clé sans label après le préfixe, arrête le build avec un diagnostic distinct de déclaration mal formée. Le traitement complet de la rédaction, et la différence entre un mandat et un emplacement featuresSchema, se trouvent dans entities/component.md « Obligations de présence ».
Labels de provenance émis par les fournisseurs
Les annotations ci-dessus entrent dans le build — la Release ou l’Aggregate les rédige, les fournisseurs les consomment. Les Providers émettent aussi un ensemble parallèle de labels en sortie du build, en les attachant à la sortie rendue afin que l’outillage en aval puisse rattacher les ressources d’exécution au contenu du catalogue qui les a produites. Ces labels de provenance ne sont pas rédigés dans la Release ; ils sont dérivés de l’état propre du build (identité de la Recipe, chemin de frontière, nom de l’agrégat, environnement, sync wave, version du compilateur) et émis par le fournisseur au moment du rendu.
L’ensemble qu’émettent les fournisseurs, attaché à chaque manifeste Kubernetes que rend le fournisseur helm, à chaque artefact chargé via $import: que le fournisseur helm-chart ajoute à un sous-chart, et à chaque service émis par compose — les templates propres d’un sous-chart helm-chart sont copiés tels que leur auteur les a écrits, ils portent donc tout ce que cet auteur a écrit :
| Label | Source | Émission |
|---|---|---|
app.kubernetes.io/name | ID du nœud (ou, pour une ressource qu’émet une FeatureRecipe, l’identifiant dérivé pour ce rattachement — voir ci-dessous) | helm et helm-chart uniquement — label standard de Kubernetes, non émis sur les services compose |
aggrega.ai/component-id | ID du nœud (ou, pour une ressource qu’émet une FeatureRecipe, l’identifiant dérivé pour ce rattachement — voir ci-dessous) | Les trois fournisseurs |
aggrega.ai/recipe-uri | <recipe-name>:<recipe-version> de la Recipe productrice (ou de la FeatureRecipe productrice pour les ressources émises par une FR) | Les trois fournisseurs, lorsque l’entité productrice a à la fois un nom et une version définis ; une annotation sur helm et helm-chart |
aggrega.ai/boundary-path | Chemin de frontière vers lequel le composant a été routé | Les trois fournisseurs, lorsque le chemin de frontière n’est pas vide ; une annotation sur helm et helm-chart |
aggrega.ai/aggregate-name | metadata.name de l’Aggregate | Les trois fournisseurs, lorsqu’il est défini |
aggrega.ai/compiler-version | Version du compilateur apposée au moment du build | Les trois fournisseurs, lorsqu’il est défini |
aggrega.ai/provider | Le fournisseur qui a rendu la ressource | Les trois fournisseurs |
aggrega.ai/provider-version | La version de ce fournisseur | Les trois fournisseurs |
aggrega.ai/environment | metadata.environment de la Release | Les trois fournisseurs — chaque Release le déclare |
aggrega.ai/sync-wave | Entier syncWave par frontière | Les trois fournisseurs, lorsqu’il est non nul ; une annotation sur helm et helm-chart |
Les valeurs de aggrega.ai/aggregate-name, aggrega.ai/environment, aggrega.ai/compiler-version, aggrega.ai/provider et aggrega.ai/provider-version proviennent de chaînes que le build ne soumet pas aux règles de Kubernetes sur les valeurs de label — un Aggregate nommé imported/flow, un environnement nommé eu/prod, la version (devel) d’un build de développement. Sur helm et helm-chart, chacun de ces labels porte sa valeur telle qu’elle est écrite lorsque la valeur est déjà une valeur de label valide : lettres, chiffres, -, _ et ., une lettre ou un chiffre aux deux extrémités, 63 caractères au plus. Sinon, le label porte la valeur réécrite sous cette forme — tout autre caractère devient -, les suites de - se réduisent à un seul, les extrémités sont rognées jusqu’à une lettre ou un chiffre, et le résultat est tronqué à 63 caractères au plus — et la valeur littérale est ajoutée comme annotation sous la même clé. Un Aggregate nommé imported/flow reçoit donc le label aggrega.ai/aggregate-name: imported-flow et l’annotation aggrega.ai/aggregate-name: imported/flow ; une valeur dépourvue de tout caractère qu’un label conserve est portée par la seule annotation. Un sélecteur compare la valeur du label telle qu’elle apparaît dans la sortie rendue, et l’outillage qui a besoin du nom exact lit l’annotation lorsqu’elle est présente. Compose, dont les valeurs de label ne sont pas contraintes, porte la valeur littérale comme label.
Notes d’émission par fournisseur
helm— les labels arrivent dansmetadata.labelssur chaque ressource Kubernetes rendue (Deployment, Service, PVC, etc.), et les clés qu’une valeur de label ne peut pas porter —aggrega.ai/recipe-uri,aggrega.ai/boundary-path,aggrega.ai/sync-wave, ainsi que la valeur littérale de tout label réécrit comme décrit ci-dessus — dansmetadata.annotations. Les chemins du mode avec source (rendu via le SDK Helm avec injection des labels post-rendu), du mode synthétisé (synthèse de la charge de travail) et deartifacts:produisent le même ensemble.helm-chart— les mêmes labels et annotations arrivent sur chaque artefact chargé via$import:que le fournisseur ajoute auxtemplates/d’un sous-chart. Les templates propres du chart source, ainsi qu’un artefact à contenu inline placé à la racine du sous-chart, n’en portent aucun — voir helm-chart.md.compose— les labels arrivent dansservices.<name>.labelssur chaque service compose émis. Le mode avec source (injection des labels après fusion sur le document fusionné base + valuesMapping) et le mode synthétisé (synthèse de la charge de travail définissant directement le bloc de labels du service) produisent tous deux le même ensemble. Le labelapp.kubernetes.io/name, propre à Kubernetes, est omis de la sortie compose.
Pour les ressources qu’émet une FeatureRecipe, la valeur de aggrega.ai/component-id est construite à partir du rattachement plutôt qu’à partir du nom du composant hôte — pour chacune des façons dont une FeatureRecipe peut livrer ces ressources, de sorte que les ressources d’un rattachement ne sont jamais indiscernables par label de celles du composant hôte lui-même. Que cette identité soit aussi ce d’après quoi ces ressources sont nommées dépend de la livraison : une charge de travail qu’Aggrega synthétise est nommée d’après l’identité, tandis qu’un chart ou un fragment fourni par l’auteur du rattachement conserve le nom de release Helm et le préfixe de fichier de sortie du composant hôte, car les templates propres de l’auteur sont rendus avec ce nom. La façon dont la valeur est composée — les deux débuts possibles, les parties et leur jonction par --, la manière dont un caractère qu’un label ne peut pas porter est écrit en toutes lettres, la manière dont une valeur trop longue pour sa cible est raccourcie, et les noms dont elle est et n’est pas la base — ne dépend pas du fournisseur ; elle est donc énoncée une seule fois dans vocabulary/labels-and-annotations.md « Labels de provenance émis sur la sortie rendue » plutôt que répétée ici. Cette page couvre l’autre moitié : l’endroit où les labels arrivent sur la sortie rendue de chaque fournisseur.
La clé aggrega.ai/recipe-uri se résout vers le name:version propre de la FeatureRecipe, et non vers l’identité de la Recipe consommatrice — l’outillage en aval qui lit le label pour identifier l’entité productrice obtient la provenance correcte aussi bien pour la sortie émise par les composants que pour celle émise par les FR.
Annotations sync-wave
La clé aggrega.ai/sync-wave ci-dessus est couplée à une annotation sync-wave que l’outillage en aval lit pour ordonner ce qu’il applique. Sur compose, la clé est un label, qui expose la valeur de la vague aux requêtes par sélecteur ; sur helm et helm-chart, c’est une annotation, et l’annotation couplée fait apparaître la valeur là où chaque outil la lit par convention.
| Annotation | Émission | Consommée par |
|---|---|---|
argocd.argoproj.io/sync-wave | helm, sur chaque ressource Kubernetes qu’il rend, et helm-chart, sur chaque artefact chargé via $import: — lorsque syncWave est non nul sur la frontière contributrice | Ordonnancement sync-wave d’ArgoCD |
helm.sh/hook-weight | helm uniquement, sur les manifestes issus des templates du chart qui portent déjà une annotation helm.sh/hook lorsque syncWave est non nul | Ordonnancement par hook-weight de Helm au sein d’une phase de hook |
L’émission de helm.sh/hook-weight dépend du chemin
Une subtilité à signaler aux auteurs de charts : helm.sh/hook-weight n’est émise que sur les manifestes rendus par le chemin de templating du chart — le répertoire templates/ du chart rendu via le SDK Helm. Les Manifests produits par le chemin des artefacts — sur le fournisseur helm, chaque entrée du bloc artifacts: de la Recipe, à contenu inline ou chargée via $import:, et sur helm-chart une entrée chargée via $import: — portent l’annotation argocd.argoproj.io/sync-wave et l’ensemble complet des labels de provenance, mais ils ne reçoivent pas helm.sh/hook-weight — même lorsque l’artefact porte une annotation helm.sh/hook.
La distinction est structurelle : helm.sh/hook et helm.sh/hook-weight sont des primitives d’ordonnancement du runtime Helm qui s’appliquent aux ressources de hook issues des templates du chart. Les artefacts de l’auteur de la Recipe sont des ressources supplémentaires déclarées au niveau de la Recipe ; par défaut, ils ne participent pas au cycle de vie des hooks de Helm.
Si vous avez besoin de l’ordonnancement par hook-weight de Helm sur une ressource de hook, rédigez la ressource comme template de chart sous le répertoire source: d’une Recipe que rend le fournisseur helm, plutôt que comme entrée artifacts: ; les templates d’un sous-chart helm-chart sont copiés tels qu’ils sont écrits et ne reçoivent aucune des deux annotations. Le template de chart recevra à la fois argocd.argoproj.io/sync-wave et helm.sh/hook-weight, correspondant à la valeur syncWave de la frontière contributrice.
Exemples de rédaction
Placement et configuration du registre au niveau de la frontière :
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east aggrega.ai/image-registry: registry.corp.com aggrega.ai/image-pull-secret: corp-registry-creds components: api: {} worker: {}Surcharge par composant (le composant l’emporte sur la frontière pour une même clé d’annotation) :
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east components: api: {} legacy-thing: annotations: aggrega.ai/namespace: legacy-east # override — this component deploys elsewhereCascade des annotations côté Aggregate
Les annotations se trouvent aussi sur la surface de rédaction de l’Aggregate — à la portée du sous-système (spec.subsystems.<name>.annotations) et à la portée de l’instance de composant (spec.subsystems.<name>.components.<name>.annotations ou spec.components.<name>.annotations pour les composants de premier niveau). La cascade côté Aggregate fait descendre les annotations rédigées par le développeur le long de l’arbre des sous-systèmes jusqu’aux composants contenus.
La règle de cascade
Une annotation au niveau d’un sous-système se propage à chaque sous-système imbriqué et à chaque composant contenu dans le sous-arbre du sous-système. Les annotations d’un niveau plus proche remplacent celles d’un niveau plus externe avec une granularité par clé : une annotation au niveau du composant remplace toute annotation héritée au niveau du sous-système pour la même clé, sans affecter les clés voisines ni les composants frères.
Une clé d’annotation à une portée donnée se trouve dans l’un de trois états :
- Clé absente — la portée ne déclare aucune valeur pour cette annotation. Les sous-systèmes imbriqués et les composants contenus héritent de tout binding d’une portée ancêtre.
- Une valeur chaîne — la portée déclare une valeur. Les sous-systèmes imbriqués et les composants contenus héritent de cette valeur, sauf s’ils déclarent leur propre valeur ou y renoncent.
nullYAML explicite — la portée supprime de son sous-arbre toute liaison héritée pour cette clé. Les composants frères et les sous-systèmes frères conservent leur héritage indépendant ; seul le sous-arbre de la portée qui renonce perd la liaison.
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # propagates to api and worker components: api: # inherits feature.myco/db-pool: "shared-pool" worker: annotations: feature.myco/db-pool: null # opts out for this component only special: annotations: feature.myco/db-pool: "vip-pool" # closer-level overrideAnnotations des Provider déclarées dans l’Aggregate
Les clés de la matrice ci-dessus descendent elles aussi en cascade à travers l’Aggregate, et un fournisseur applique ce que la cascade laisse sur chaque composant. L’aggrega.ai/namespace d’un sous-système place chaque composant situé en dessous ; la valeur propre d’une instance de composant place plutôt ce composant. Un module que l’Aggregate importe porte sa propre cascade : ses sous-systèmes et ses instances de composant atteignent les composants propres du module, et rien de ce que déclare l’Aggregate importateur n’atteint l’intérieur d’un module.
La Release se situe au-dessus de l’Aggregate pour chaque clé. Là où la Release définit une clé pour un composant — sur sa frontière ou sur l’entrée propre du composant —, c’est la valeur de la Release qui s’applique ; là où elle n’en définit aucune, c’est celle de l’Aggregate. Les deux côtés se superposent clé par clé, de sorte qu’une Release qui ne définit que aggrega.ai/namespace laisse en vigueur un aggrega.ai/image-registry que l’Aggregate a déclaré.
Un null explicite dans la Release ne retire que la valeur propre de la Release. Une entrée de composant qui écrit aggrega.ai/namespace: null supprime l’espace de noms que la frontière de sa Release lui aurait transmis, et le composant prend alors la valeur que déclare son Aggregate — ou aucune, là où l’Aggregate n’en déclare pas non plus. Une Release ne peut pas supprimer une valeur que l’Aggregate déclare ; elle peut seulement en définir une qui lui est propre par-dessus.
# Aggregatespec: subsystems: billing: annotations: aggrega.ai/namespace: billing # api and worker render into billing components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0 annotations: aggrega.ai/namespace: billing-batch # worker renders into billing-batch# Releasespec: boundaries: production: components: api: annotations: aggrega.ai/namespace: prod-billing # the Release's value wins: api renders into prod-billing worker: {}aggrega.ai/chart-name est la seule clé hors de cette portée : elle nomme un chart parapluie assemblé à partir de plusieurs composants, elle est donc lue depuis les frontières de Release qui contribuent à ce chart, jamais depuis les annotations d’un composant.
Un template de Recipe ou de FeatureRecipe lit les compartiments d’annotations par nom — .context.annotations.aggregate, .context.annotations.release et .context.annotations.catalog contiennent chacun ce que ce côté a écrit —, de sorte qu’un template qui lit une clé de placement dans un compartiment ne voit que la valeur de ce côté.
La partition entre côté et pilier
L’invariant de l’Aggregate comme surface de rédaction restreint les annotations côté Aggregate au pilier des valeurs. Une liaison d’annotation de Manifest déclare des chemins de routage soit sous maps.infra (routage côté Release), soit sous maps.values (routage côté Aggregate) ; une annotation côté Aggregate dont la liaison ne déclare que des chemins sous maps.infra arrête le build avec un diagnostic clair qui nomme la clé d’annotation, le pilier routé et le côté de rédaction. La règle symétrique s’applique au côté Release : les annotations côté Release ne peuvent router que par maps.infra ; une annotation côté Release contre une liaison réservée aux valeurs déclenche l’erreur parallèle. Chaque diagnostic est classé dans le domaine du document où la valeur de l’annotation a été rédigée — [DEVELOPER_ERROR] depuis un Aggregate, [OPS_ERROR] depuis une Release —, de sorte que l’en-tête nomme la surface à ouvrir.
Les liaisons qui déclarent des chemins dans les deux piliers routent à chaque passe le sous-ensemble compatible avec le côté : une annotation côté Aggregate ne déclenche que les chemins du pilier des valeurs, et une annotation côté Release ne déclenche que les chemins du pilier infra. La composition entre côtés — values depuis l’Aggregate, infra depuis la Release — produit un rattachement de Feature par paire (Component, Feature), avec les deux piliers renseignés et une provenance par feuille qui enregistre quel côté a fourni chaque feuille.
Exemple de rédaction — une annotation de sous-système est routée vers values
# Manifest bindingspec: mappings: features: type: core/db-pool: db-pool-helm:1.0.0 annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - pool # routes to values.pool# Aggregatespec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0Après l’expansion des annotations, api et worker portent tous deux un rattachement synthétique de la Feature feature.myco/db-pool dont le champ values.pool vaut "shared-pool". Le graphe du build (aggrega validate --release <release> --ir-graph) enregistre chaque feuille avec origin: annotation, side: aggregate et annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool.
Valeurs d’annotation structurées
Une Feature comportant plusieurs champs configurables appelle une seule clé d’annotation qui porte des valeurs pour plusieurs d’entre eux à la fois. La forme d’annotation structurée permet à une clé de router vers plusieurs chemins de liaison en une seule déclaration :
# Aggregate Subsystem — Developer's intent for db-pool (values-pillar subkeys)subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5# Release Boundary — Operator's sizing for db-pool (infra-pillar subkeys)boundaries: prod: annotations: feature.myco/db-pool: pool_size: 20 max_connections: 100La liaison du Manifest déclare le routage des quatre sous-clés dans des listes maps: regroupées par pilier :
# Manifestspec: mappings: features: annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - db_name - read_replicas infra: - pool_size - max_connectionsLa forme de la valeur de l’annotation est l’une de trois :
- Chaîne scalaire — une valeur unique. La liaison doit déclarer exactement un chemin au total ; le scalaire est routé vers ce chemin.
- Objet structuré — une table associant sous-clé et sous-valeur. Le chemin de chaque sous-clé doit figurer dans la liste
maps.infraoumaps.valuesde la liaison ; la sous-valeur est routée vers le champ du schéma de la Feature nommé, dans le pilier déclaré. nullYAML explicite — renonce en bloc à la liaison héritée pour cette portée de la cascade.
Chaque sous-clé d’une valeur structurée se résout indépendamment par rapport à la liste maps de la liaison. Une sous-clé absente à la fois de maps.infra et de maps.values arrête le build avec une erreur claire qui nomme la sous-clé fautive et les chemins déclarés.
Fusion en cascade des valeurs structurées
Les annotations structurées descendent en cascade avec une fusion profonde par sous-clé. L’annotation d’une portée enfant de la cascade fusionne sous-clé par sous-clé avec l’annotation du parent ; le niveau le plus proche remplace le parent avec une granularité par sous-clé :
subsystems: data: annotations: feature.myco/db-pool: db_name: "data-default" read_replicas: 3 components: api: annotations: feature.myco/db-pool: db_name: "api-override" # overrides parent at this subkey only # read_replicas not listed → inherits 3 from parent analytics: annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-out: removes inherited subkey # db_name not listed → inherits "data-default" from parentAnnotations effectives après la cascade :
- Component
api:{ db_name: "api-override", read_replicas: 3 } - Component
analytics:{ db_name: "data-default" }— renonciation àread_replicasà cette portée
Un niveau enfant de la cascade dont la valeur est un scalaire (face à un parent structuré) remplace en bloc au lieu de fusionner. Les incohérences de forme entre niveaux de la cascade se résolvent en faveur de la valeur du niveau le plus proche ; le compilateur n’avertit pas en cas d’incohérence de forme.
null sur la valeur entière et null par sous-clé
La cascade offre deux mécanismes de renonciation à des granularités différentes :
# Whole-value null — opts out wholesale at this scopecomponents: api: annotations: feature.myco/db-pool: nullLa liaison de l’annotation entière est supprimée sur ce composant ; aucun rattachement de Feature synthétique n’est synthétisé à partir de cette clé d’annotation à cette portée. Les composants frères conservent leur liaison héritée.
# Per-subkey null — opts out just one subkeycomponents: api: annotations: feature.myco/db-pool: db_name: "api-db" read_replicas: nullL’annotation continue de contribuer à cette portée, mais la sous-clé read_replicas est supprimée. Les autres sous-clés (déclarées à cette portée ou héritées des niveaux parents de la cascade) restent en place.
Conseil de rédaction : utilisez null sur la valeur entière pour désactiver à une portée un rattachement de Feature piloté par annotation. Utilisez null par sous-clé lorsque vous voulez conserver l’essentiel de la contribution d’une annotation tout en supprimant un ou plusieurs champs précis.
Partition entre côté et pilier par sous-clé
L’invariant de l’Aggregate comme surface de rédaction s’applique par sous-clé lorsque la valeur d’une annotation est structurée. Le pilier de chaque sous-clé (selon la déclaration maps de la liaison) doit être compatible avec le côté de rédaction :
- Une annotation côté Aggregate ne peut porter que des sous-clés routées vers
maps.values. - Une annotation côté Release ne peut porter que des sous-clés routées vers
maps.infra.
Une sous-clé routée vers un pilier incompatible arrête le build avec une erreur claire qui cite la sous-clé et le pilier concernés. La chaîne d’erreurs rassemble toutes les sous-clés incompatibles par annotation avant de s’arrêter — les opérateurs voient chaque problème en un seul cycle de build au lieu d’enchaîner corrections et reconstructions.
Validation du type par sous-clé
La valeur d’exécution de chaque sous-clé est validée par rapport au type déclaré dans le spec.schema de la Feature cible, dans le pilier routé. Les types déclarés pris en charge sont string, integer, number, boolean, object, array, null. Une sous-valeur dont le type YAML ne correspond pas au type déclaré du schéma arrête le build avec une erreur claire qui nomme la sous-clé, le type réel et le type déclaré.
La correspondance des types est stricte — aucune coercition. Une chaîne "20" face à un champ de schéma de type entier arrête le build ; les auteurs déclarent correctement les types dans le schéma de la Feature ou utilisent des annotations scalaires qui sont transmises comme chaînes.
Levier de rédaction pour une validation stricte. Les propriétés sans type déclaré dans le spec.schema de la Feature acceptent n’importe quelle forme de valeur d’exécution, y compris des tables imbriquées. Lorsque le schéma ne déclare pas de contrainte, le build n’en invente pas. Les auteurs qui veulent une validation stricte du type par sous-clé déclarent type sur chaque propriété de spec.schema. La couche de rendu de la FeatureRecipe en aval traite toute forme que porte la contribution de l’annotation.
Composition entre côtés
Lorsqu’une annotation côté Aggregate (sous-clés values) et une annotation côté Release (sous-clés infra) ciblent toutes deux le même rattachement de Feature sur le même Component, le build fusionne les contributions en un seul rattachement de Feature avec les deux piliers renseignés. La provenance par feuille enregistre la source de chaque sous-clé — le rattachement synthétisé porte values.db_name attribué au site de rédaction de l’Aggregate et infra.pool_size attribué au site de rédaction de la Release.
Le modèle de composition entre côtés est la forme de rédaction canonique pour les Features dont les champs mêlent intention du développeur et dimensionnement par l’opérateur : l’Aggregate déclare les choix cognitifs (quelle base de données, combien de réplicas au niveau de l’application) ; la Release déclare le dimensionnement physique (quelle taille de pool, combien de connexions au niveau de l’infrastructure). Une seule liaison de Manifest les relie avec un seul ensemble de déclarations maps.
Références associées
- Architecture des Provider — l’architecture à plugins des fournisseurs et le rôle du Plugin de rendu de fournisseur.
- ../entities/release.md — la surface de rédaction de la Release où se trouvent les annotations de frontière et de composant.
- ../entities/aggregate.md — la surface de rédaction de l’Aggregate où se trouvent les annotations au niveau du sous-système et du composant.
- ../entities/manifest.md — la table
mappings.features.annotationsdu Manifest, où les liaisons d’annotation déclarent leur routagemaps:. - ../../architecture/11-governance-and-compliance.md — la façon dont la provenance est apposée à la compilation, en complément des annotations contrôlées par l’auteur.