Labels et annotations
Les entités d’Aggrega portent deux mécanismes de métadonnées structurellement similaires — metadata.labels et metadata.annotations — ainsi que des champs porteurs d’annotations répartis entre les surfaces en cascade sur les frontières et les surfaces de rattachement de fonctionnalités. Six surfaces distinctes rédigent ou portent du contenu d’annotations/labels, chacune avec des règles de cascade différentes, des consommateurs différents et des conventions de préfixe différentes. Cette page documente les surfaces en un seul endroit, définit les trois compartiments sémantiques qu’expose le contexte de template à l’exécution, nomme la discipline de préfixes que les auteurs devraient suivre, et documente côte à côte les cinq surfaces de rattachement de Feature afin qu’elles soient visibles à côté du vocabulaire plus large des labels/annotations.
Les six surfaces porteuses d’annotations et de labels
Les auteurs rencontrent des labels et des annotations sur six surfaces distinctes. Chacune a une portée différente, une règle de cascade différente et un consommateur différent.
| # | Surface | Portée | Règle de cascade | Consommateur principal |
|---|---|---|---|---|
| 1 | metadata.labels d’une entité du catalogue | Identité par entité (Component, Feature, Aggregate) | Ne se propage pas en cascade aux instances ; porté sur l’entité du catalogue elle-même | aggrega search -l pour les Components et les Features ; les labels d’un Aggregate sont portés sur son document et aucune commande ne les lit |
| 2 | metadata.labels du Component (intrinsèques) | Propriétés par instance de Component (component.aggrega.ai/type, etc.) | Se propage en cascade dans le .context.labels par nœud de l’IR après les mutations label-transform | Correspondance des sélecteurs (déclarations selector: de usesSchema, portées sous la forme x-aggrega-selector: dans le JSON Schema synthétisé), logique de template de la Recipe |
| 3 | metadata.annotations du Component | Traits par instance de Component rédigés par l’architecte | Se propage en cascade dans le compartiment .context.annotations.catalog par nœud de l’IR | rôles de verdict de la gouvernance (politiques sur les traits intrinsèques), logique de template de la Recipe |
| 4 | annotations: d’Aggregate / de sous-système | Métadonnées cognitives côté Aggregate | Se propage en cascade dans le compartiment .context.annotations.aggregate par nœud de l’IR | valuesMapping: de la Recipe pour le routage cognitif |
| 5 | Frontière de la Release annotations: | Métadonnées physiques côté Ops, y compris les annotations bien connues aggrega.ai/* | Se propage en cascade dans le compartiment .context.annotations.release par nœud de l’IR | Providers (helm lit aggrega.ai/namespace ; compose dérive le nom du réseau de la même clé) ; injectMapping: de la FeatureRecipe pour le routage inter-frontières |
| 6 | Liaisons features.annotations du Manifest | Liaison clé d’annotation → type de Feature avec routage des sous-clés groupé par pilier (maps.infra / maps.values) pour le rattachement de Feature piloté par les annotations | La sous-phase d’expansion des annotations de la résolution parcourt les frontières de la Release (de l’extérieur vers l’intérieur) et les sous-systèmes de l’Aggregate (de l’extérieur vers l’intérieur) ; la surcharge par composant et la désactivation par null sur la valeur entière / par sous-clé s’appliquent ; le contrôle côté contre pilier détermine quel pilier se déclenche pour chaque côté de rédaction | Expansion de Feature pilotée par les annotations (rattachements de Feature synthétiques, enregistrés dans le graphe IR avec origin: annotation) |
Les surfaces 4 et 5 partagent une forme YAML (une map annotations: à la frontière en cascade) mais se propagent dans des compartiments distincts de l’IR — la distinction entre compartiments est la règle porteuse qu’expose l’exécution. La surface 6 est structurellement séparée : elle vit sur l’entité Manifest plutôt que sur le contenu d’Aggregate / de Release, et sa consommation est conditionnée par la passe d’expansion pilotée par les annotations.
La sémantique à trois compartiments de .context.annotations.*
Lorsque le moteur de rendu évalue un template de Recipe, le champ par nœud .context.annotations porte trois compartiments nommés. Chaque compartiment est une map plate string → string indexée par nom d’annotation ; le compartiment détermine qui a rédigé l’annotation et quelle est son intention.
.context.annotations.release— annotations de la frontière de la Release (Surface 5). Elles servent à gouverner les réalités physiques ; les moteurs de rendu les acheminent vers les champsinfra:lorsque c’est approprié. Les annotations bien connuesaggrega.ai/*résident dans ce compartiment..context.annotations.catalog— annotations des métadonnées du Component (Surface 3). Traits intrinsèques immuables rédigés par l’architecte ; consommés principalement par les plugins de policy Wasm..context.annotations.aggregate— annotations des sous-systèmes de l’Aggregate (Surface 4). Métadonnées cognitives ; les moteurs de rendu les acheminent vers les payloadsvalues:lorsque c’est approprié.
La séparation en trois compartiments est un contrat social
Le compilateur n’impose pas les frontières entre les compartiments. Les trois compartiments partagent une forme plate string → string ; le template d’une Recipe peut lire les trois, et rien n’empêche qu’une annotation de frontière de la Release soit interprétée comme un champ de métadonnées cognitives ou qu’une annotation du catalogue soit acheminée vers infra:. La séparation est une discipline de rédaction, pas une garantie du compilateur.
L’objectif de la discipline — ce que les compartiments sont censés exprimer :
- release = « où ce composant s’exécute, gouverné par Ops »
- catalog = « ce qu’est ce composant, rédigé par l’architecte »
- aggregate = « ce que fait ce composant, rédigé par le développeur »
Lorsque les auteurs respectent la séparation, l’outillage en aval peut lire le bon compartiment pour la bonne préoccupation. Lorsque les auteurs l’enfreignent (par ex. en plaçant des métadonnées cognitives dans les annotations release parce que le fichier de Release est pratique), l’exécution fonctionne toujours, mais l’intention du compartiment se brouille.
Socket de linter — signaler les lectures inter-compartiments
Un plugin de linter (signalement hors bande ; voir plugins/plugin-contract.md pour le critère de placement) peut signaler les lectures inter-compartiments où le template d’une Recipe puise dans un compartiment dont l’intention ne correspond pas au champ acheminé. Le critère :
- Lire
.context.annotations.releasepour renseigner un champvalues:— signaler (les métadonnées cognitives devraient provenir du compartimentaggregate). - Lire
.context.annotations.aggregatepour renseigner un champinfra:— signaler (les métadonnées physiques devraient provenir du compartimentrelease). - Lire
.context.annotations.catalogpour renseignervalues:ouinfra:— en général un simple signalement (les annotations du catalogue sont des traits intrinsèques ; les acheminer vers des piliers est inhabituel mais pas toujours faux).
Le linter de publication ne porte aucune règle pour ce critère, et le build ne le vérifie pas ; un plugin de linter à vous peut le faire, via le socket de linter que aggrega lint exécute. La discipline est maintenue par les relecteurs et les auteurs qui suivent la convention d’intention des compartiments.
Discipline des préfixes
Les clés d’annotation et de label suivent une forme uniforme <namespace>/<name>. Les familles de préfixes ci-dessous indiquent qui rédige les clés sous chacune et comment chacune est maintenue — un préfixe est réservé, et un build s’arrête là où une liaison du Manifest ou un label de sortie d’une Recipe revendique une nouvelle clé à l’intérieur ; les autres relèvent de la convention du catalogue, sans rien pour refuser une clé. La différence entre les deux est de savoir si un build s’arrête ; lisez donc la colonne du milieu avant les autres.
| Préfixe | Qui rédige les clés ici | Comment c’est maintenu | Objectif | Exemples |
|---|---|---|---|---|
aggrega.ai/ | Plateforme Aggrega uniquement | Réservé, et imposé. La plateforme définit les clés ici, et vous écrivez celles qu’elle définit — aggrega.ai/namespace sur une frontière de la Release, par exemple. Revendiquer une nouvelle clé à l’intérieur du préfixe provoque un arrêt : une liaison features.annotations du Manifest sous le préfixe nu, et de même une clé de label de sortie d’une Recipe sous celui-ci dans outputLabels: ou outputComponentLabels:. Une annotation écrite sous celui-ci que la plateforme ne définit pas n’est pas refusée : le build la transporte, et là où elle se trouve sur une Release, une cible qui n’agit pas sur elle le signale par un avertissement. Voir errors/fatal-halts.md « A Manifest annotation binding claims the reserved aggrega.ai/ prefix (Une liaison d’annotation du Manifest revendique le préfixe réservé) » et « An output-label key uses a reserved namespace (Une clé d’étiquette de sortie utilise un espace de noms réservé) ». | Annotations natives de la plateforme consommées directement par le fournisseur | aggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment |
feature.aggrega.ai/ | Bibliothèque standard officielle | Convention. Rien ne refuse une clé ici ; le vocabulaire appartient à la bibliothèque standard par accord plutôt que par une vérification. | Raccourcis d’annotation de Feature liés dans features.annotations du Manifest | feature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking |
component.aggrega.ai/ | Bibliothèque standard officielle | Convention. Rien ne refuse une clé ici. | Labels de traits intrinsèques du Component (la clé de sélecteur component.aggrega.ai/type se trouve ici) | component.aggrega.ai/type |
aggregate.aggrega.ai/ | Bibliothèque standard officielle | Convention. Rien ne refuse une clé ici. | Labels d’identité au niveau du module de l’Aggregate | aggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance |
<role>.aggrega.ai/ | Bibliothèque standard officielle, et les entreprises dans leurs propres catalogues | Convention. Rien ne refuse une clé ici. | Labels de capacité — les dimensions comportementales sur lesquelles discrimine un sélecteur usesSchema ou l’appliesTo d’une Feature. Le <role> nomme la préoccupation à laquelle appartient la dimension : soit un rôle de composant, soit une préoccupation transversale que plusieurs rôles partagent. | model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring |
<any-other-domain>/ | Entreprise / communauté | Ouvert. Rédigez sous un domaine que vous contrôlez. | Annotations et labels personnalisés | acme.com/billing-tier, corp/cost-center |
Les auteurs qui écrivent des annotations personnalisées utilisent un domaine qu’ils contrôlent (généralement de style DNS inversé). Rédiger directement sous aggrega.ai/ (sans sous-préfixe) est réservé à la plateforme ; les liaisons features.annotations du Manifest ne peuvent pas non plus lier des clés directement sous aggrega.ai/ — voir entities/manifest.md « aggrega.ai/ Prefix Reservation (Réservation du préfixe aggrega.ai/) ».
Nommer un préfixe de capacité
Une clé de capacité est <role>.aggrega.ai/<dimension>, et le <role> est la partie qui demande du discernement. Trois règles la gouvernent, et la première est celle qui est le plus souvent prise à l’envers.
- Nommez la préoccupation, pas le type de composant qui se trouve la porter en premier. Là où une dimension décrit quelque chose que plusieurs types de composants partagent, le préfixe nomme la préoccupation partagée, afin que le prochain type qui l’acquiert réutilise le vocabulaire au lieu d’en inventer un parallèle.
component.aggrega.ai/hostingest une préoccupation — qui exploite la ressource sous-jacente — et décrit une base de données et une API de modèle avec les mêmes mots ;dataplane.aggrega.ai/*nomme une position sur le chemin du trafic, de sorte qu’un proxy, une passerelle d’entrée et un service mesh se décrivent de la même façon. Une dimension réellement propre à un rôle prend le nom de ce rôle, comme le faitmodel.aggrega.ai/capability. - Un seul mot en minuscules, sans trait d’union, dans le préfixe. Le trait d’union a sa place dans la moitié
<dimension>, où un composé se lit naturellement (request-mirroring,data-class,upstream-licensing). - Une dimension est ajoutée lorsqu’un sélecteur en a besoin, et chaque valeur qu’elle déclare a un composant qui la porte. Chaque mot ici est un mot qu’un auteur de catalogue doit apprendre et qu’un auteur de Feature peut rencontrer, donc une dimension gagne sa place en discriminant quelque chose qu’un
usesSchemaou unappliesTodemande réellement. Une valeur qu’aucun composant ne porte est pire qu’une valeur absente : un sélecteur qui la nomme est analysé, ne correspond à rien et ne signale rien — c’est pourquoi une valeur que le catalogue ne peut pas démontrer reste hors du vocabulaire jusqu’à ce qu’un composant la porte. Une clé dont la valeur est une déclaration d’une organisation sur la manière dont elle utilise ses propres composants, plutôt qu’une propriété du produit, est l’exception, etcompliance.aggrega.ai/data-classest ce cas : la classe des données d’un composant dépend de la manière dont une organisation utilise le composant, donc aucun Component de la bibliothèque standard ne porte l’une de ses valeurs et aucun socket ni aucune Feature de la bibliothèque standard ne sélectionne sur elles. La clé et ses valeurs sont déclarées afin que les propres Components d’une organisation et les policies qu’elle rattache partagent une seule orthographe ; un sélecteur ou une policy qui nomme une valeur ne correspond que dans un catalogue dont les Components la portent. policy-data-class-route montre un tel Component et la policy qui le lit.
Une réservation et une clé définie par la plateforme ne sont pas la même chose
La réservation porte sur la racine aggrega.ai/ nue. Chaque espace de noms <scope>.aggrega.ai/ en dessous est un espace de clés à part entière que la plateforme ne possède pas, ce qui maintient le vocabulaire du catalogue extensible : un catalogue d’entreprise peut rédiger acme.aggrega.ai/team sans rien contester de ce que le build appose.
Quelques clés à l’intérieur de ces espaces de noms ouverts sont néanmoins définies par la plateforme et lues par le build, et cela ne rend pas leur espace de noms réservé :
component.aggrega.ai/typeest obligatoire dans lesmetadata.labelsde chaque Component et prend l’une des valeurs d’un ensemble fixe. Les sélecteurs effectuent la correspondance sur elle ; le compilateur ne bifurque pas selon la valeur qu’elle contient.features.aggrega.ai/requiredType.<label>, rédigée dans lesmetadata.annotationsd’un Component, déclare qu’une Feature du type nommé doit être rattachée. Le build vérifie cette exigence par rapport à l’ensemble final des rattachements de chaque nœud et s’arrête là où rien ne la satisfait — voirerrors/fatal-halts.md« Required feature not attached (Fonctionnalité requise non rattachée) ». Notez le pluriel :features.aggrega.ai/est un espace de noms à part entière, distinct du singulierfeature.aggrega.ai/dans le tableau ci-dessus, qui porte les raccourcis de liaison du Manifest.
Lisez la différence ainsi : un préfixe réservé refuse une clé que vous tentez de définir à l’intérieur, tandis qu’une clé définie par la plateforme est une seule clé nommée que le build connaît, située dans un espace de noms où vous êtes par ailleurs libre de rédiger. Toute autre clé sous component.aggrega.ai/, features.aggrega.ai/ et les autres est une métadonnée que le build transporte sans l’interpréter.
L’une de ces clés dans les metadata.annotations d’un Component est lue par le linter de publication standard plutôt que par le build : observability.aggrega.ai/metrics-credential indique comment les métriques du produit s’authentifient — none, elles sont servies sans identifiant ; target-key, elles exigent la clé que le Component exige de chaque appelant ; separate-token, elles exigent un jeton qui leur est propre. Le build la transporte comme n’importe quelle autre annotation. Le linter la lit pour décider si l’identifiant d’une connexion de scrape est comparé à la clé d’appelant de la cible, et exige qu’elle concorde avec la clé provides metrics_credential_required que le Component déclare — voir « The discipline rules (Les règles de discipline) » dans cli/aggrega-lint.md.
Labels de provenance émis sur la sortie rendue
Au-delà des annotations entrantes que consomment les fournisseurs, Aggrega émet aussi des labels de provenance sur chaque manifeste Kubernetes que rend le fournisseur helm et sur chaque service compose émis, et le fournisseur helm-chart écrit le même ensemble, tel que l’écrit le fournisseur helm, sur chaque artefact qu’il charge avec $import:. L’ensemble de labels permet à l’outillage en aval (tableaux de bord de coûts, piles d’observabilité, contrôleurs GitOps) de faire remonter les ressources d’exécution jusqu’au contenu du catalogue qui les a produites. Les templates propres d’un sous-chart helm-chart sont copiés tels que leur auteur les a écrits, ils portent donc les labels que cet auteur a écrits.
L’ensemble qu’émettent les fournisseurs helm et compose — sur helm, trois des clés sont écrites comme annotations plutôt que comme labels, comme l’indique le tableau :
| Label | Source | Toujours émis ? |
|---|---|---|
app.kubernetes.io/name | Identité du Component — le nom que vous avez écrit, ou, pour un composant qu’apporte un Aggregate importé, son nom qualifié avec le séparateur de module écrit en toutes lettres (voir ci-dessous) ; ou, pour une ressource qu’émet une FeatureRecipe, l’identifiant dérivé pour ce rattachement | Oui sur les manifestes Kubernetes ; non émis sur les services compose (le label standard est spécifique à K8s) |
aggrega.ai/component-id | Identité du Component — le nom que vous avez écrit, ou, pour un composant qu’apporte un Aggregate importé, son nom qualifié avec le séparateur de module écrit en toutes lettres (voir ci-dessous) ; ou, pour une ressource qu’émet une FeatureRecipe, l’identifiant dérivé pour ce rattachement | Oui |
aggrega.ai/recipe-uri | <recipe-name>:<recipe-version> de la Recipe productrice (ou de la FeatureRecipe productrice pour les ressources émises par une FR) | Lorsque l’entité productrice a à la fois un nom et une version définis ; une annotation sur helm |
aggrega.ai/boundary-path | Chemin de frontière vers lequel le composant a été routé | Lorsque le chemin de la frontière n’est pas vide ; une annotation sur helm |
aggrega.ai/aggregate-name | metadata.name de l’Aggregate | Lorsqu’il est défini |
aggrega.ai/compiler-version | Version du compilateur apposée au moment du build | Lorsqu’il est défini |
aggrega.ai/provider | Le fournisseur qui a rendu la ressource (helm, helm-chart, compose) | Oui |
aggrega.ai/provider-version | La version de ce fournisseur | Oui |
aggrega.ai/environment | metadata.environment de la Release | Oui — chaque Release le déclare |
aggrega.ai/sync-wave | Entier syncWave par frontière, l’ordre dans lequel un outil GitOps applique les ressources | Lorsqu’il est non nul ; une annotation sur helm, à côté de argocd.argoproj.io/sync-wave |
Le nom de l’agrégat, l’environnement, la version du compilateur ainsi que le nom et la version du fournisseur sont des chaînes que vous ou le build avez choisies, et aucune d’elles n’est soumise aux règles de Kubernetes sur les valeurs d’étiquette à l’endroit où elle est écrite. Sur helm, chacune de ces étiquettes porte la valeur telle qu’elle est écrite lorsqu’elle est déjà une valeur d’étiquette valide — lettres, chiffres, -, _ et ., une lettre ou un chiffre aux deux extrémités, 63 caractères au plus — et sinon la valeur réécrite en une valeur valide, la valeur d’origine étant ajoutée comme annotation sous la même clé : un Aggregate nommé imported/flow reçoit l’étiquette aggrega.ai/aggregate-name: imported-flow et l’annotation aggrega.ai/aggregate-name: imported/flow. Une valeur déjà conforme n’ajoute aucune annotation. Compose porte la valeur d’origine comme étiquette. La règle de réécriture est énoncée dans providers/well-known-annotations.md « Étiquettes de provenance émises par les fournisseurs ».
Pour les ressources qu’émet une FeatureRecipe, la valeur aggrega.ai/component-id est construite à partir du rattachement plutôt qu’à partir du nom du composant hôte — pour chaque manière dont une FeatureRecipe peut livrer ces ressources, qu’elle synthétise une charge de travail, émette un ensemble d’artefacts autonome ou rende un chart ou un fragment fourni par son auteur. Ainsi, une requête qui sélectionne les ressources d’un rattachement par identité les renvoie toutes, et aucune d’elles n’est indiscernable d’une ressource que le composant hôte a émise lui-même. La manière dont la valeur est construite dépend de l’endroit où la Feature est rattachée ; dans les deux cas, le résultat est une chaîne de label Kubernetes valide.
Pour un composant qu’apporte un Aggregate importé, l’identité est le nom qualifié de ce composant avec le séparateur qui joint le module au composant écrit en toutes lettres — data-layer.main-db est apposé sous la forme data-layer-zdmain-db — parce qu’un point n’est pas un caractère qu’un nom de ressource ou une adresse de cluster peut porter sans risque. Un nom que vous avez écrit sans séparateur est apposé octet pour octet.
L’identité dit à quoi une ressource appartient. C’est une question différente de la manière dont une ressource s’appelle, et pour l’une des livraisons, les deux ont des réponses différentes :
- Là où une FeatureRecipe synthétise une charge de travail, Aggrega construit lui-même ces ressources, il les nomme donc aussi d’après l’identité : l’identité atteint leur
metadata.name, leurs labels de sélecteur et leurs noms de fichiers émis ainsi que leurs labels. C’est un nom à l’intérieur du cluster et pas seulement un label. - Là où une FeatureRecipe livre un chart ou un fragment écrit par son auteur, les noms appartiennent à celui qui l’a écrit. Le nom de release Helm par rapport auquel ces templates sont rendus — et le préfixe des fichiers qu’émet ce rendu — restent ceux du composant hôte. Les charts nomment couramment leurs ressources d’après le nom de release, donc le déplacer renommerait des ressources que le chart lui-même déclare, dans un cluster où elles sont déjà déployées, pour une raison qui n’a rien à voir avec le chart. Les labels portent toujours l’identité propre du rattachement, ce qui permet de retrouver les ressources du rattachement.
- Là où la Feature est rattachée à une frontière, il n’existe pas de composant hôte dont le nom pourrait en tenir lieu, l’identité composée y est donc la base du nommage aussi bien que du label.
Dans les deux cas, la valeur est composée à partir des parties que vous avez écrites, jointes par --, derrière un début fixe qui indique de quel cas il s’agit. Deux débuts sont en usage, et une identité de composant que vous écrivez ne peut commencer par aucun des deux — c’est ce qui empêche qu’un nom que vous avez écrit et un nom composé par Aggrega soient jamais confondus l’un avec l’autre.
Là où la Feature est rattachée à un composant, les parties sont un début fixe cfr, l’identité du composant auquel la Feature est rattachée et la clé sous laquelle elle est rattachée. Une Feature rattachée au composant api sous mon donne cfr--api--mon. Le composant hôte fait partie de la valeur parce qu’un même nom de Feature rattaché à plusieurs composants émet un ensemble de ressources distinct sur chacun, et chaque ensemble a besoin d’une identité propre : rattacher mon à la fois à api et à worker donne cfr--api--mon et cfr--worker--mon plutôt qu’une seule valeur pour les deux. Un rattachement nommé exactement comme le composant qui l’héberge donne une valeur distincte de celle propre à ce composant pour la même raison — mon rattaché à mon donne cfr--mon--mon.
Là où la Feature est rattachée à une frontière — le service passerelle compose-bridge en est l’exemple canonique —, les parties sont un début fixe bfr, puis chaque segment du chemin de la frontière, le plus externe en premier, puis le nom sous lequel la Feature est rattachée. Une Feature nommée gateway sur une frontière à bridge donne bfr--bridge--gateway ; la même Feature sur une frontière à prod/eu donne bfr--prod--eu--gateway.
Un caractère que la valeur ne peut pas porter est écrit en toutes lettres plutôt que remplacé, et comme la valeur est un nom à l’intérieur du cluster en plus d’un label, elle est limitée aux caractères qu’admet tout type de nom de ressource Kubernetes : lettres minuscules, chiffres et trait d’union. Ainsi un trait d’union que vous avez écrit reste un trait d’union, une lettre minuscule ou un chiffre reste tel quel, et tout le reste — y compris une majuscule, qu’une valeur de label admet et qu’un nom de ressource refuse — devient un court échappement : un rattachement nommé my_zone apporte my-zuzone, et un composant myApi avec un rattachement worker donne cfr--my-zx000041pi--worker. Cette valeur échappée est celle par laquelle les ressources du rattachement sont labellisées et sélectionnées sur chaque cible, celle d’après laquelle sont nommés une charge de travail que synthétise le rattachement et ses fichiers, et celle dont est dérivé le nom de release d’un rattachement à une frontière. Une majuscule est le seul caractère que la règle des noms de ressource ajoute à ce qu’un label seul aurait écrit en toutes lettres, donc une valeur composée dont les parties n’en contiennent aucune — cfr--api--mon, bfr--prod--eu--gateway — est la valeur qu’un label seul porterait. Deux rattachements que vous pouvez distinguer donnent donc deux valeurs — quel que soit le nom que vous leur avez donné, et quelle que soit la profondeur de la frontière — parce que -- est une séquence qu’aucune partie écrite ne peut contenir, de sorte que déplacer la division entre les parties change la valeur au lieu d’entrer en collision avec elle.
La longueur que peut avoir une valeur composée est la réponse de la cible plutôt qu’un nombre que détient Aggrega : la cible pour laquelle les ressources sont rendues est interrogée, et la valeur est raccourcie jusqu’à ce que cette cible l’accepte. Une valeur de label Kubernetes porte au plus 63 caractères, et un nom de release Helm dérivé de la même identité est borné plus étroitement encore, de sorte que le même rattachement peut aboutir à une valeur plus courte sous une cible que sous une autre. Une valeur qui tient est émise exactement telle que composée, ce qui est le cas ordinaire et le cas de chaque rattachement du catalogue de la bibliothèque standard. Une valeur qui ne tient pas est raccourcie : chaque partie garde son commencement, et un condensé de dix caractères de l’identité entière est ajouté derrière un marqueur qu’aucun nom que vous pouvez écrire ne produit — ainsi une valeur raccourcie est reconnaissable comme telle et ne peut jamais être lue comme une valeur qui tenait. Un rattachement gateway profondément imbriqué peut donc être rendu sous la forme bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e. Il est très peu probable que deux valeurs raccourcies se rencontrent, et si cela arrive, un build s’arrête plutôt que de laisser deux d’entre elles partager un nom.
Voir errors/fatal-halts.md « The same name is derived more than once inside the output (Le même nom est dérivé plus d’une fois à l’intérieur de la sortie) » pour savoir quelles paires provoquent un arrêt et comment les séparer.
La valeur aggrega.ai/recipe-uri d’une ressource émise par une FR correspond au name:version propre de la FeatureRecipe, et non à l’identité de la Recipe consommatrice — ainsi l’outillage en aval qui lit recipe-uri pour identifier l’entité productrice obtient la provenance correcte à la fois pour la sortie émise par les composants et pour celle émise par les FR.
Pour les détails de l’émission propres à chaque fournisseur (où les labels atterrissent sur la sortie rendue, et comment chaque fournisseur les sérialise), voir providers/well-known-annotations.md « Provenance labels emitted by providers (Labels de provenance émis par les fournisseurs) ».
Labels de sortie déclarés par la Recipe
En plus de l’ensemble de provenance détenu par le compilateur, l’auteur d’une Recipe peut déclarer ses propres labels à apposer sur la sortie rendue de la Recipe, via Recipe.spec.outputLabels:. Ceux-ci empruntent le même rail d’émission que les labels de provenance — ils sont fusionnés dans le même ensemble de labels et atterrissent partout où atterrit la provenance — mais ils appartiennent à l’auteur plutôt qu’au compilateur. L’usage prévu est un trait de réalisation : une propriété de la manière dont une Recipe donnée réalise un composant (par exemple hosting: managed par opposition à hosting: self-hosted pour une Recipe de service géré par opposition à une Recipe de chart auto-hébergé du même type de composant), exposée sur la sortie afin que l’outillage de coûts, de policy et d’inventaire puisse l’interroger.
Les espaces de noms aggrega.ai/ et app.kubernetes.io/ sont réservés à l’ensemble de provenance ; une clé sous l’un ou l’autre de ces préfixes est refusée au chargement — dans outputLabels: et dans outputComponentLabels:, le bloc compagnon qui nomme une clé de label du composant et appose la valeur que le composant lui-même déclare. Un ensemble de labels de sortie validé est donc toujours disjoint des clés de provenance, de sorte que les deux n’entrent jamais en collision sur la sortie fusionnée. Le critère est la racine nue : une clé à portée comme component.aggrega.ai/hosting se trouve dans un espace de noms à part entière et peut être écrite littéralement ou promue. L’exposition par fournisseur (objet helm et pod-template lors de la synthèse ; objet lors du rendu à partir de sources et pour les artefacts ; labels des services compose ; tags terraform par ressource sur les corps d’artefacts .tf.json) correspond au placement de la provenance, et est documentée en entier sur la page de l’entité Recipe sous « The outputLabels: field (Le champ outputLabels:) » et « The outputComponentLabels: field (Le champ outputComponentLabels:) ».
Rattachement de Feature — cinq surfaces
Les Features se rattachent aux Components par cinq surfaces de rédaction distinctes, chacune avec une portée, un utilisateur visé et une priorité d’ordonnancement différents au sein du modèle en oignon à 5 niveaux. L’ordonnancement complet des rattachements et le modèle en oignon lui-même sont documentés dans architecture/10-compilation-pipeline.md ; le tableau ci-dessous énumère les cinq surfaces côte à côte.
| Niveau | Surface | Rédigé par | Portée | Règle de cascade |
|---|---|---|---|---|
| 1 | Bloc features: d’un composant de l’Aggregate | Développeur | Par instance de composant (granulaire) | Aucune — directement par l’auteur |
| 2 | Bloc features: d’un sous-système de l’Aggregate | Développeur | Portée du sous-système (transversale au sein de l’Aggregate) | Se propage en cascade à chaque composant du sous-système |
| 3 | components.<id>.features de la frontière de la Release | Ops | Par instance de composant (granulaire, côté Ops) | Aucune — directement par l’auteur |
| 4 | Bloc features: de la frontière de la Release | Ops | Portée de la frontière (transversale au sein de la frontière) | Se propage en cascade à chaque composant de la frontière |
| 5 | Expansion de features.annotations du Manifest | Opérateur de plateforme | Piloté par les annotations (rattachement synthétique) | Se propage en cascade à travers l’arbre des frontières (côté Release) ou l’arbre des sous-systèmes (côté Aggregate) ; la surcharge par composant et la désactivation par sous-clé via null s’appliquent |
Les cinq surfaces se cumulent ; un rattachement présent sur n’importe quelle surface contribue à l’ensemble de fonctionnalités résolu du Component. Lorsque le même nom d’instance de Feature apparaît sur plus d’une surface, les contributions fusionnent en un seul rattachement au lieu de se remplacer mutuellement, et une incompatibilité de type entre elles arrête le build avec une erreur feature-merge-conflict.
Les cinq surfaces sont délibérées, conformément à la séparation des préoccupations de l’architecture — développeur (niveaux 1-2), Ops (niveaux 3-4), opérateur de plateforme (niveau 5) — plutôt que redondantes. Les auteurs choisissent la surface qui correspond à qui possède le rattachement et à quelle portée.
Quels labels décident si une Feature s’applique
Une Feature déclare où elle peut se rattacher avec spec.appliesTo et spec.appliesToAnyOf, et le build juge cette déclaration par rapport aux labels finalisés du nœud sur lequel le rattachement aboutit. Rattacher une Feature à un nœud que ces labels ne satisfont pas arrête le build ; une Feature qui ne déclare aucune des deux surfaces n’énonce aucune exigence et s’applique partout.
L’ensemble de labels finalisé est assemblé en deux étapes, et aucune d’elles n’est celle que les auteurs supposent le plus souvent.
- Un nœud tire ses labels de l’entité de catalogue Component que nomme son
type:. Ils sont une propriété du type de composant, pas de l’instance : l’Aggregate ne peut pas labelliser une instance de composant, et la Release non plus. Les propresmetadata.labelsd’un Aggregate décrivent l’Aggregate comme un module réutilisable et ne se propagent pas en cascade aux composants qu’il contient. Ainsi deux instances d’un même type portent des labels identiques, et changer les labels d’un nœud signifie changer le type vers lequel il pointe — ou changer l’entité de ce type. - Un rattachement
label-transformpeut ensuite les réécrire. Là où la configuration de l’espace de travail rattache un plugin de gouvernance dans le rôlelabel-transform, celui-ci s’exécute lors de la construction de la topologie et peut ajouter, modifier ou supprimer des labels de nœud avant que quoi que ce soit ne soit jugé par rapport à eux. Il ne peut toucher à rien d’autre, de sorte que les labels sont la seule partie d’un nœud qu’il peut déplacer — et ils sont exactement la partie dont dépend l’applicabilité.
Une proposition faite à partir des labels que déclare un seul document est donc une approximation, pas une prédiction. Lire les metadata.labels d’une entité Component vous dit avec quoi commence un nœud de ce type, ce qui est la bonne réponse assez souvent pour être utile et fausse de deux manières précises : un document qui partage simplement le nom d’un nœud est un sujet différent avec des labels différents, et un rattachement label-transform peut déplacer l’ensemble sous n’importe quel document. Les outils qui proposent des suggestions de rattachement à partir des seules sources travaillent sur cette approximation ; le jugement que rend un build porte sur l’ensemble finalisé.
Priorité des attachements
Lorsque deux contributions fournissent le même champ du même rattachement, quatre règles décident laquelle porte la sortie rendue. Elles sont appliquées dans cet ordre, et c’est l’ordre qui rend le résultat prévisible :
- Origine. Une contribution rédigée explicitement l’emporte sur une contribution pilotée par une annotation, quelle que soit la portée à laquelle l’une ou l’autre a été déclarée. Écrire un champ dans un bloc
features:est la manière dont un auteur surcharge ce qu’une annotation aurait apporté, et une annotation ne déplace jamais silencieusement quelque chose écrit à la main. Le compilateur enregistre l’annotation supprimée à côté de la valeur gagnante et la signale comme un avis, de sorte que la surcharge est visible plutôt que mystérieuse. - Propriété des piliers. Chaque domaine remplit son propre pilier : les surfaces de l’Aggregate apportent
values, les surfaces de la Release apportentinfra. Comme les deux côtés n’écrivent jamais le même pilier, une contribution du développeur et une contribution de l’opérateur ne peuvent pas se disputer le même champ — il n’y a aucune question de priorité entre développeur et opérateur à trancher. - Autorité de la composition. Une déclaration dans l’Aggregate que vous déployez l’emporte sur une déclaration à l’intérieur d’un Aggregate qu’il compose, même lorsque l’Aggregate composé a déclaré à la portée la plus étroite. La composition reste prépondérante : un module ne peut pas l’emporter sur l’Aggregate qui le consomme simplement en choisissant une portée plus étroite.
- Spécificité. Au sein d’un même niveau de rédaction et d’un même pilier, la portée la plus étroite affine la plus large, champ par champ. Un rattachement à portée de composant surcharge un rattachement à l’échelle d’un sous-système ou d’une frontière portant le même nom d’instance — mais uniquement pour les champs qu’il mentionne effectivement. Les champs que la portée plus étroite omet conservent les valeurs de la portée plus large, de sorte qu’un rattachement partagé peut fournir la configuration commune pendant qu’un seul composant en ajuste un champ. Deux contributions à la même portée se résolvent selon l’ordre de rédaction, la plus tardive l’emportant, ce qui permet à un sous-système interne d’affiner un sous-système externe et à une frontière plus profonde d’affiner une frontière moins profonde.
La priorité gouverne les valeurs des champs. Elle ne réordonne pas l’évaluation : la séquence dans laquelle le compilateur replie les surfaces, et dans laquelle il exécute l’injectMapping pré-rendu de chaque rattachement, est la séquence fixe à cinq niveaux documentée dans architecture/10-compilation-pipeline.md. Le bloc inject rédigé d’un rattachement suit cette séquence d’évaluation plutôt que le classement des portées ci-dessus, de sorte qu’un rattachement ne porte jamais deux ordonnancements concurrents.
Quels types portent metadata.labels et metadata.annotations
metadata.labels se trouve sur Component, Feature, Aggregate et les quatre types de bibliothèque ; metadata.annotations sur les mêmes types sauf Aggregate. Manifest, Release, Recipe, FeatureRecipe et Plugin ne portent ni l’un ni l’autre.
Récapitulatif des cascades
Les règles de cascade à travers les six surfaces, telles que les évalue le compilateur :
- Les labels des entités de catalogue (Surface 1) restent sur l’entité de catalogue. Ils ne descendent pas vers les instances ; les consommateurs les lisent en inspectant directement le contenu du catalogue.
- Les
metadata.labelsdu Component (Surface 2) alimentent le.context.labelspar nœud après la passe facultativelabel-transformlors de la construction de la topologie. - Les
metadata.annotationsdu Component (Surface 3) alimentent le compartiment par nœud.context.annotations.catalog. - Les
annotations:de l’Aggregate / du sous-système (Surface 4) se propagent en cascade à travers la hiérarchie des sous-systèmes, en s’accumulant des sous-systèmes externes vers l’intérieur, dans le compartiment par nœud.context.annotations.aggregate. - Les
annotations:de la frontière de la Release (Surface 5) se propagent en cascade à travers la hiérarchie des frontières, des frontières externes vers l’intérieur, dans le compartiment par nœud.context.annotations.release. - Les
features.annotationsdu Manifest (Surface 6) ne se propagent pas directement en cascade vers les données IR par nœud ; la sous-phase d’expansion pilotée par les annotations de la résolution consomme les liaisons pour synthétiser des rattachements de Feature par nœud, que le graphe IR (--ir-graph) enregistre avecorigin: annotation. Les rattachements synthétiques sont structurellement indiscernables des rattachements explicites en aval de la résolution, sauf par cette provenance — voirproviders/well-known-annotations.mdpour l’exposé complet de l’expansion etarchitecture/13-catalog-and-registry.md§« Annotation-driven Feature expansion (expansion des Feature pilotée par les annotations) » pour les mécanismes au chargement du catalogue et à l’inspection.
Pour la conception canonique des annotations en cascade, voir architecture/06-data-taxonomy-and-composition.md §2 (Flux 5).
Références croisées
templates/template-context-contract.md— vue d’exécution de.context.labelset des trois compartiments.context.annotations.*.providers/well-known-annotations.md— matrice des annotations de frontière par fournisseur et asymétrie de l’émission des labels de provenance.entities/manifest.md— la surface de liaisonfeatures.annotationsdu Manifest (Surface 6).vocabulary/publishing-surface.md— vocabulaire de métadonnées uniforme qui complète les labels/annotations du côté de la publication.plugins/plugin-contract.md— le critère de placement du socket de linter pour les vérifications consultatives sur les lectures inter-compartiments.architecture/06-data-taxonomy-and-composition.md— conception canonique des annotations en cascade.architecture/10-compilation-pipeline.md— modèle en oignon à 5 niveaux qui ordonne le rattachement de Feature.