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

extends et implements

Héritage via extends

Les entités du catalogue (Component, Feature) prennent en charge l’héritage simple via le mot-clé extends, qui permet aux architectes de plateforme de construire des entités spécialisées sur une base partagée. La fusion profonde de l’enveloppe YAML est commune aux deux types : les métadonnées, les labels et les tables structurelles déclaratives de l’entité qui étend écrasent les clés correspondantes de la base, et les maps imbriquées sont fusionnées récursivement. Les deux types se séparent sur les piliers de données.

Cette page couvre les types du catalogue, et ce ne sont pas les seuls types qui déclarent extends. Une Release et un Manifest le déclarent aussi, et tous deux sont des documents côté déploiement rédigés l’un à côté de l’autre plutôt que des entités indexées dans le catalogue — leurs références nomment donc des fichiers, pas des entités de catalogue, et ce qui est fusionné est une surface de rédaction plutôt qu’un schéma. Pour ceux-ci, voir entities/release.md et entities/manifest.md.

L’extends d’un Component compose la structure et hérite des piliers en entier

Pour un Component, extends compose metadata.labels, metadata.annotations, spec.featuresSchema (slots de rattachement), spec.usesSchema (sockets de topologie) et spec.inject (la liste d’autorisation du self-inject, dont les entrées se concatènent base en premier, sans doublons). Les trois piliers de données — values, infra, provides — ne sont pas composés. Un Component qui étend ne rédige aucun contenu de pilier : il écrit le marqueur littéral schema: inherited et reçoit le bloc schema: de la base exactement tel que la base l’a rédigé, à chaque profondeur d’une chaîne.

Le schéma Component publié rend ce marqueur à la fois obligatoire et exclusif, et rejette chaque écart par rapport à lui au chargement du document, avec un diagnostic propre à chacun : du contenu de pilier rédigé sous schema: sur un Component qui déclare extends: ; schema: entièrement omis dans ce cas ; et schema: inherited sur un Component qui ne déclare aucun extends:.

Deux conséquences en découlent, et elles tirent dans des directions opposées :

  • L’ensemble des clés est fixé par la base. Un Component qui étend ne déclare aucune clé de pilier, il ne peut donc ni masquer, ni supprimer, ni retyper une clé que la base déclare, et n’en ajoute aucune de son cru. Une instance de la base et une instance de tout ce qui l’étend sont validées par rapport au même contrat de pilier.
  • Le resserrement passe par assertions:. Une spécialisation qui doit admettre moins que les piliers hérités l’exprime comme un prédicat sur elle-même, et non comme une feuille de schéma restreinte. Si une base core/base-server déclare tls_enabled: { type: boolean, default: true }, une spécialisation qui exige TLS sans condition écrit :
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/tls-only-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
extends: core/base-server
schema: inherited # values, infra and provides are the base's, verbatim
assertions:
tls-is-mandatory: |
{{- if not .values.tls_enabled -}}
{{- fail "this component requires tls_enabled: true" -}}
{{- end -}}

La règle rejette une valeur que le bloc de pilier hérité accepte, ce qui est exactement ce que resserrer signifie ici. La direction inverse n’a aucune expression : une spécialisation ne peut pas assouplir une contrainte héritée, car elle ne peut pas reformuler la feuille qui la porte. Voir entities/component.md « Catalog Authoring: Extending Base Components (Rédaction du catalogue : étendre des Components de base) » pour le tableau de composition complet et la paire base-extension détaillée.

L’extends d’une Feature compose ses piliers

Pour une Feature, le schema: de l’enfant se compose avec celui de la base selon la sémantique de composition de JSON Schema 2020-12, produisant un schéma fusionné unique par rapport auquel une instance rédigée est validée. Les Features d’identifiants — celles qui portent le label feature.aggrega.ai/kind: secret — s’en servent pour s’appuyer sur une base partagée : une Feature d’identifiants enfant étend un parent pour hériter de son schéma de requête au vault tout en resserrant les contraintes.

Le compilateur ne prend pas position sur le sens de ce changement. La composition est structurelle, donc une contrainte de l’enfant qui élargit celle de la base se compose sans arrêter le build et apparaît comme un signalement. Rien ne la rejette : la contrainte d’une base de Feature est une attente partagée que les auteurs du catalogue font respecter par la relecture, et non un contrat que la plateforme fait appliquer.

Liaison d’interface via implements

Les Recipes et les FeatureRecipes se lient à une interface de Component ou de Feature via le mot-clé implements: en tête de leur spec. La liaison déclare de quelle interface du catalogue cette Recipe / FeatureRecipe est l’implémentation concrète, et prend en charge trois formes de correspondance des versions :

  • Exacte — implements: core/api-server:1.0.0 — correspond à une version précise du type de Component.
  • Plage compatible avec la version majeure — implements: core/api-server:^1.0.0 — correspond à toute version satisfaisant >=1.0.0, <2.0.0 (compatible avec la version majeure selon SemVer). Utilisée lorsqu’une Recipe prend en charge une plage compatible plutôt qu’une seule version épinglée.
  • Sans version — implements: core/api-server — correspond à toute version du type de Component. Utilisée lorsqu’une Recipe sert toutes les versions du type.

implements: ne sélectionne jamais une Recipe : c’est le mapping du Manifest qui le fait. Ce que la déclaration pilote, c’est le contrôle de cohérence sur chaque entrée de mapping — la version du type mappé doit satisfaire l’implements: de la Recipe mappée sous l’une des trois formes, ou la Recipe doit implémenter une base que ce type étend — ainsi que la liste de candidats que proposent le diagnostic d’absence de mapping et la complétion de l’éditeur. Une entrée de mapping dont la Recipe a un implements: qui ne correspond ni au type mappé ni à aucune de ses bases arrête le build, en nommant le mapping, la Recipe et sa valeur implements:. Lorsqu’une clé components.type atteint une instance de composant à une version que la clé ne nomme pas — toutes les instances, pour une clé écrite sans version —, le contrôle est refait avec le type propre de cette instance, à la version sous laquelle le build la compile, et une Recipe qui ne le satisfait pas arrête le build de la même façon, en nommant l’instance.

La liaison implements: est le mécanisme qui fait fonctionner « le même type de Component, des Recipes différentes pour des fournisseurs différents » : un Component core/postgres peut avoir une Recipe qui l’implémente pour le fournisseur helm et une autre Recipe qui l’implémente pour le fournisseur compose. Chaque Recipe déclare la même valeur implements:, et le Manifest avec lequel une Release effectue son build mappe le type vers celle qu’elle veut.

Une Recipe écrite pour une base sert tout ce qui l’étend

implements: nomme une base, et une Recipe qui en nomme une est l’implémentation concrète pour chaque Component qui étend cette base, à n’importe quelle profondeur de la chaîne. Ainsi, une spécialisation construite avec extends n’a besoin d’aucune Recipe propre — c’est ce qui rend un wrapper publié peu coûteux à consommer : l’équipe qui le publie rédige un Component, et les équipes qui le déploient réutilisent les Recipes de la base sur chaque cible.

Deux faits valent ici en même temps, et ils sont distincts. Un lecteur qui les réduit à « la spécialisation n’a besoin de rien » écrit un Manifest qui échoue, pour une raison qu’il cherchera dans le mauvais fichier :

  • La Recipe correspond. Le contrôle de cohérence entre la clé de type d’un mapping du Manifest et l’implements: de la Recipe mappée accepte le mapping lorsque la Recipe implémente le type mappé lui-même ou n’importe quelle base que ce type étend. Les trois formes de version ci-dessus s’appliquent à une base exactement comme au type lui-même : une Recipe qui déclare implements: core/base-server:^1.0.0 satisfait une spécialisation dont la base est en version 1.4.0, et ne satisfait pas une spécialisation dont la base est en 2.0.0.
  • Le Manifest mappe toujours le type propre de la spécialisation. La sélection de la Recipe se fait par clé de mapping exacte. Une instance de enterprise/labelled-server a besoin de sa propre entrée mappings.components.type ; elle n’hérite pas de l’entrée écrite pour core/base-server. Une spécialisation sans entrée propre s’arrête avec le diagnostic d’instance non mappée même lorsque sa base est mappée.

Le coût de rédaction d’une spécialisation est donc une ligne de Manifest et aucune nouvelle Recipe :

# The wrapper extends core/base-server and authors no pillars.
# core/helm/base-server declares: implements: core/base-server
spec:
mappings:
components:
type:
enterprise/labelled-server:1.0.0: core/helm/base-server:1.0.0

Lorsque la chaîne extends du type mappé ne peut pas être parcourue — elle forme une boucle, ou une base qu’elle nomme est absente du catalogue —, le build s’arrête sur ce défaut de chaîne plutôt que sur le mapping, car un mapping ne peut pas être jugé tant que la chaîne dont il dépend n’est pas résolue. Le contrôle ne parcourt la chaîne qu’à travers les Components déjà présents sur cette machine — ceux d’un répertoire de catalogue, et ceux que le cache local d’artefacts conserve sous un épinglage du lockfile — et n’interroge jamais un registre, de sorte qu’une base détenue uniquement par un registre compte ici comme absente. La récupérer est le rôle de aggrega pull : une base est une dépendance de tout ce qui l’étend, donc un pull suit chaque chaîne extends: qu’atteint la Release, récupère chaque base qu’aucun répertoire de catalogue ne contient et l’épingle dans le lockfile, où le build suivant la trouve. Le Manifest n’a besoin d’aucune ligne pour la base elle-même, sauf si un Aggregate déclare aussi une instance de la base.

Les suggestions de Recipe restent plus étroites que cette règle de correspondance. La liste de candidats qu’affiche un diagnostic d’absence de mapping, et l’ordre que la complétion de l’éditeur applique à une valeur de mapping, nomment les recettes qui implémentent le type demandé lui-même ; elles ne s’élargissent pas aux recettes qui implémentent l’une de ses bases.

Pour une présentation de bout en bout exécutable — un wrapper publié dans le catalogue, l’unique ligne de Manifest qui le consomme, la Recipe de la base qui façonne sa sortie rendue, et l’arrêt que produit une instance du wrapper sans mapping propre —, voir l’exemple détaillé examples/extends-wrapper/.

Consommation des versions entre entités

Chaque type d’entité d’Aggrega — Component, Feature, Aggregate, Recipe, FeatureRecipe, Manifest, Release, Plugin, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary — porte un champ obligatoire metadata.version validé par rapport à la même regex SemVer (MAJOR.MINOR.PATCH selon architecture/02-ecosystem-philosophy.md). Les versions sont uniformes dans leur forme ; la consommation des versions varie selon le type d’entité. Certaines versions participent activement à la résolution ; d’autres sont une provenance descriptive par rapport à laquelle le compilateur n’effectue aucune correspondance. Le tableau ci-dessous couvre les types qui ne sont pas des bibliothèques, en indiquant ce que le compilateur fait du champ de version de chaque entité et en utilisant la taxonomie de statut à quatre labels de 10-status.md pour classer chaque régime de consommation. Les quatre types de bibliothèque sont hors du tableau parce que leur régime est uniforme et différent : un consommateur référence une bibliothèque par son nom nu, peut affirmer un plancher de version minimale facultatif :<version>, et le lockfile propre à chaque Release détient la version résolue et son digest de contenu.

EntitéRégime de consommationStatut
ComponentRésolution des références de type ; correspondance implements: de la Recipeavailable — formes exacte, à plage caret (^MAJOR.MINOR.PATCH) et sans version dans les deux cas (voir Résolution des versions et État du langage → Correspondance des versions)
FeatureRésolution des références de rattachement ; correspondance implements: de la FeatureRecipeComme pour Component
RecipeRésolution des niveaux de mapping du Manifestavailable — formes exacte, à plage caret et sans version dans une valeur de mapping, chacune sélectionnant la version la plus élevée qui la satisfait
FeatureRecipeRésolution des niveaux de mapping du ManifestComme pour Recipe
AggregateRésolution de la référence aggregates[].type parenteavailable — formes exacte, à plage caret et sans version, chacune sélectionnant la version la plus élevée qui la satisfait (voir Résolution des versions)
PluginAiguillage vers le Provider via recipe.spec.capability → spec.provider.capabilitiesavailable — la capacité nue sélectionne le fournisseur, et un épinglage sur elle (helm:<version>, helm:^<version>) sélectionne la version de ce plugin qui effectue le rendu ; l’identité du plugin est la référence oci://<repository> sans digest plus metadata.version, et le digest de contenu est enregistré dans le lockfile de la release par rapport auquel le build vérifie les octets récupérés
ManifestProvenance du graphe IR (manifest_version)available (lu uniquement pour la provenance ; aucun rôle dans l’aiguillage de la résolution)
ReleaseProvenance du graphe IR (release_version) + métadonnées de template (.metadata.release_version)Comme pour Manifest

Régimes de résolution du catalogue (Component, Feature, Aggregate, Plugin). Une référence à l’un de ces types — le type d’un composant, le type d’un rattachement de fonctionnalité, l’aggregates[].type d’une importation de sous-agrégat, le plugin d’une étape de pipeline — se résout selon la règle qu’enseigne Résolution des versions : une référence exacte, à plage caret ou sans version sélectionne la version la plus élevée qui la satisfait parmi celles que contient le catalogue, et le pull, le build, une validation, l’éditeur et les outils destinés à l’assistant appliquent tous cette seule et même règle. Pour un Component ou une Feature, la correspondance implements: lit les trois mêmes formes dans l’autre sens — une version concrète du type par rapport à la forme que déclare une Recipe ou une FeatureRecipe — comme le contrôle de cohérence décrit ci-dessous, et non comme une sélection. L’aiguillage vers le plugin de rendu du Provider utilise une forme plus simple : il recherche par nom la recipe.spec.capability nue parmi les spec.provider.capabilities du plugin de rendu du fournisseur, et un épinglage de version écrit sur la capacité sélectionne la version de ce plugin qui effectue le rendu, en s’arrêtant lorsqu’aucune version ne le satisfait.

Résolution des niveaux de mapping du Manifest. Le mécanisme de résolution plat mappings.{components,features} du Manifest (avec les niveaux name et type, le nom l’emportant sur le type, et le type versionné l’emportant sur le type non versionné) est documenté dans entities/manifest.md. Le résolveur consomme ces mappings : la sélection de la Recipe et de la FeatureRecipe est une recherche directe de la valeur de mapping dans le lockfile et le catalogue, et un composant ou un rattachement dont le type n’a aucun mapping arrête le build. spec.implements ne sélectionne pas une Recipe — c’est le contrôle de cohérence au chargement sur un mapping que l’auteur a déjà écrit, et la source de la liste de candidats que proposent le diagnostic d’absence de mapping et la complétion de l’éditeur. L’aiguillage des capacités découle ensuite du champ spec.capability de la Recipe résolue, et non de la forme structurelle du Manifest.

Régimes de provenance descriptive (Manifest, Release). Le metadata.version du Manifest et le metadata.version de la Release sont lus lorsque le compilateur renseigne la provenance, et apparaissent dans le bloc de provenance du graphe IR sous la forme manifest_version et release_version ; aucun label sur la sortie rendue ne porte l’un ou l’autre. Les templates voient également la version de la Release exposée sous la forme .metadata.release_version. Aucune des deux versions n’est comparée à la version d’une autre entité pour l’aiguillage de la résolution ; il s’agit de provenance pure.

Lire le tableau. La classification à quatre labels distingue « le champ de version est accepté par le schéma et existe sur l’entité » (toujours vrai — regex SemVer uniforme) de « le compilateur effectue une correspondance avec cette version pendant la résolution » (varie selon l’entité).

Acheminement inter-piliers par pont de schéma : relier l’intention à l’infrastructure

Aggrega exprime une forte séparation des responsabilités entre le Domaine 1 et le Domaine 4 : le développeur écrit la logique cognitive dans le bloc values, tandis que l’opérateur dicte le dimensionnement physique dans le bloc infra. Le schéma Aggregate.yaml impose un corollaire concret : le mot-clé infra est absent des instances de composant de l’Aggregate et de leurs rattachements features et, combiné avec additionalProperties: false, il est rejeté par la validation du schéma. Les développeurs ne devraient pas dicter le dimensionnement physique dans l’intention du développeur ; lorsqu’une valeur précise convient au cas de l’application (par ex., un port codé en dur ou un nombre précis de CPU), l’architecte peut l’exposer explicitement dans la déclaration schema: du Component, et la valeur passe par values.

Pour les cas où une contrainte d’infrastructure précise fait partie intrinsèque du contrat d’un composant — une base de données de trading à haut débit qui doit disposer de 10 000 IOPS provisionnées, une charge de travail de ML qui doit s’exécuter sur exactement 4 GPU —, les architectes de plateforme exposent la contrainte via un Component conçu à cet effet, en utilisant le motif d’acheminement inter-piliers par pont de schéma.

Le motif du pont de schéma pour les composants conscients de l’infrastructure. Le Component expose le réglage d’infrastructure précis dans le bloc values du développeur via sa déclaration schema:, et le template valuesMapping: de la Recipe liée achemine la valeur vers la sortie rendue en forme d’infra:. Le résultat est un pont typé entre l’intention cognitive et le dimensionnement physique : le développeur dicte la contrainte matérielle via un champ validé, et la contrainte parvient à Ops sans qu’aucune des deux parties n’écrive de code d’infrastructure brut. Le réglage est une clé de pilier, il est donc déclaré sur le Component dont le contrat le possède — un Component qui fait extends: d’une base ne déclare aucune clé de pilier et ne peut donc pas en introduire une.

# Domain 2: The Platform Catalog (the schema-bridge Component)
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/high-perf-postgres
version: 1.0.0
labels:
component.aggrega.ai/type: "stateful-server"
spec:
schema:
values:
# Expose the dial safely to the Developer with a typed contract.
required_iops: { type: integer, min: 1000, max: 100000, required: true }
infra:
# Operator-owned sizing the Recipe below reads alongside the dial.
storage: { size: { type: string, default: 100Gi } }
compute: { instance_class: { type: string, default: db.m5.large } }
# Domain 2: The Platform Catalog (the Recipe pipes the dial into provider infra)
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: aws-rds-high-perf-postgres
version: 1.0.0
spec:
implements: core/high-perf-postgres:^1.0.0
capability: terraform
source: ./modules/rds
valuesMapping: |
# The Recipe pipes the developer's values.required_iops into the provider's infra-side knob.
iops: {{ .values.required_iops }}
allocated_storage: "{{ .infra.storage.size }}"
instance_class: "{{ .infra.compute.instance_class }}"
# Domain 1: The Developer Intent (remains capability-agnostic)
components:
trading-db:
type: core/high-perf-postgres:1.0.0
values:
required_iops: 10000 # Developer dictates the hardware constraint safely

Mise à l’échelle multi-environnement (l’exigence de remontée des paramètres). Pour faire évoluer cette contrainte matérielle entre les environnements GitOps (Dev vs. Prod) sans modifier l’Aggregate.yaml du développeur, le développeur remonte la valeur dans le contrat typé parameters. Ops remplit l’exigence d’IOPS précise via des fichiers Release propres à chaque environnement. L’ordre d’exécution du compilateur protège le flux : la validation du contrat des paramètres s’exécute à la résolution ; l’interpolation résout le paramètre dans la chaîne values: environnante ; le template valuesMapping: de la Recipe achemine la valeur résolue vers la sortie rendue.

1. L’intention du développeur (abstraire le réglage). Le développeur sait qu’il doit contrôler les IOPS, mais il abstrait le nombre explicite au niveau de l’environnement via le contrat typé parameters.

spec:
parameters:
env_iops:
type: integer
min: 1000
max: 100000
description: Provisioned IOPS for the trading-db instance
components:
trading-db:
type: core/high-perf-postgres:1.0.0
values:
required_iops: {{ .parameters.env_iops }} # Hoisted to the environment

2. Les Releases GitOps (remplissage par Ops). Ops remplit le contrat parameters dans des fichiers Release propres à chaque environnement. Le contrat typé valide chaque valeur fournie par la Release avant l’exécution de l’interpolation.

  • Environnement Dev (release-dev.yaml) : env_iops: 1000
  • Environnement Prod (release-prod.yaml) : env_iops: 25000

L’ordre de compilation. Ce mécanisme est protégé par l’ordre d’exécution strict du compilateur à la résolution :

  1. Validation du contrat des paramètres. Chaque valeur de paramètre fournie par la Release est validée par rapport à la déclaration typée parameters: de l’Aggregate. Une valeur Prod de 25000 est valide (dans min: 1000, max: 100000) ; une valeur de 500 provoquerait un arrêt avec une erreur claire.
  2. Interpolation. Le compilateur lit les valeurs de paramètres de la Release Prod et interpole 25000 dans la chaîne YAML de l’Aggregate à values.required_iops. La map de paramètres fusionnée reste vivante pendant le rendu, de sorte que les surfaces de template de chemin puissent lire .parameters.<slot> directement ; les surfaces de template de valeur consomment le littéral post-interpolation déjà écrit dans le bloc values: de l’Aggregate. La map reste lisible jusqu’à ce que chaque phase de rendu soit terminée, et n’est accessible que depuis la compilation pour laquelle elle a été résolue.
  3. Validation du schéma. La déclaration schema: du Component valide le dictionnaire values: résultant ; values.required_iops: 25000 satisfait le min: 1000, max: 100000 du schéma.
  4. Rendu du valuesMapping de la Recipe. Le template valuesMapping: de la Recipe liée achemine values.required_iops vers la sortie en forme d’infra du fournisseur (iops: 25000). Le plugin Wasm du fournisseur génère la configuration physique correcte de la base de données. Le développeur obtient son contrôle matériel explicite, Ops obtient sa mise à l’échelle propre à chaque environnement, et l’Aggregate reste agnostique vis-à-vis des capacités.