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

La taxonomie des entités

L’architecture d’Aggrega est organisée en quatre domaines, chacun appartenant à un persona différent et abritant des types d’entités spécifiques, plus une couche de bibliothèques de niveau 3 — le troisième niveau du modèle de niveaux des entités de la référence du langage — qui contient du contenu réutilisable de schéma, de mapping, de workload et d’artefact. La vue d’ensemble ci-dessous montre comment les quatre domaines et les bibliothèques de niveau 3 sont liés les uns aux autres ; chaque section qui suit s’ouvre sur un diagramme de ses propres entités, où une entité d’un autre domaine est dessinée avec un contour en pointillés. Les surfaces de rédaction détaillées (champs, schémas, exemples) de chaque entité se trouvent dans le catalogue des entités de la référence du langage.

graph TD
    Intent["<b>Domain 1: Developer Intent</b><br/><i>Developer</i>"]
    Catalog["<b>Domain 2: Platform Catalog</b><br/><i>Platform Architect</i>"]
    Routing["<b>Domain 4: Routing & Policy</b><br/><i>Platform Operator / DevOps</i>"]
    Infra["<b>Domain 3: Infrastructure Base</b><br/><i>Infrastructure Engineer / Ops</i>"]
    Libs["<b>Tier 3: Libraries</b>"]

    Intent -->|"requests, attaches"| Catalog
    Intent -->|"binds via"| Routing
    Routing -->|"attaches"| Catalog
    Catalog -->|"resolved to"| Infra
    Routing -->|"resolves, renders via"| Infra
    Catalog -.->|"$ref"| Libs
    Infra -.->|"$import"| Libs

Le corpus couvre quatre domaines plus la couche de bibliothèques de niveau 3 :

#EntitéDomaineRôle
1AggregateDomaine 1 — Intention du développeurPlan de la topologie applicative
2ComponentDomaine 2 — Platform CatalogInterface abstraite de nœud de calcul
3FeatureDomaine 2 — Platform CatalogTrait opérationnel (y compris les Features d’identifiants)
4RecipeDomaine 3 — Base d’infrastructureImplémentation d’un Component, par fournisseur
5FeatureRecipeDomaine 3 — Base d’infrastructureImplémentation d’une Feature, par fournisseur
6PluginDomaine 3 — Base d’infrastructurePlugin WebAssembly adressé par contenu (rendu des fournisseurs, étapes de pipeline, linting)
7ManifestDomaine 4 — Routage et politiquesFichier de verrouillage des dépendances qui associe les interfaces aux Recipes
8ReleaseDomaine 4 — Routage et politiquesRouteur de déploiement qui lie l’Aggregate au Manifest
9SchemaLibraryNiveau 3 — BibliothèquesDéfinitions JSON Schema 2020-12 réutilisables
10MappingLibraryNiveau 3 — BibliothèquesFragments de templates Go réutilisables
11WorkloadLibraryNiveau 3 — BibliothèquesFragments de templates de Workload réutilisables
12ArtifactLibraryNiveau 3 — BibliothèquesLots d’artefacts nommés réutilisables

Ce tableau constitue l’ensemble complet des types d’entités de rédaction, c’est-à-dire les types qu’un auteur déclare dans un champ kind:. Le type Workload est un contenu appartenant à la plateforme, intégré dans l’entrée synthétisée d’une Recipe plutôt qu’une entité de catalogue autonome (voir le chapitre 16) ; il est donc délibérément absent du tableau ci-dessus.

Le Plugin est une entité d’authoring à part entière — avec son propre kind, son propre JSON Schema et son propre répertoire de catalogue — détenue par Platform Ops dans le domaine 3. Un Plugin est une référence adressée par contenu à un artefact WebAssembly, qui déclare l’unique type de socket qu’il implémente. La taxonomie compte sept membres : provider (rend les nœuds de l’IR en artefacts natifs du provider), linter (émet des diagnostics sur le contenu rédigé), pipeline-step (une étape d’une feature-recipe-pipeline), governance (remplit un rôle de gouvernance — transformer des labels ou des annotations, ou rendre un verdict d’acceptation ou de rejet sur le graphe de l’IR ou sur les artefacts rendus), cli (apporte une sous-commande aggrega qu’un opérateur invoque en ligne de commande), parser (transforme un texte source étranger en arbre structuré canonique) et importer (transforme une source étrangère d’infrastructure ou de définition d’agents en brouillons de fichiers d’authoring Aggrega). Un Plugin de rendu de provider (pluginType: provider) est l’unité qui assure le rendu de provider : il déclare dans spec.provider.capabilities le ou les noms de provider qu’il rend et porte le reste des métadonnées de son socket de provider dans ce même bloc spec.provider. Le compilateur épingle et route la référence ; le runtime WebAssembly exécute les octets ; le compilateur n’interprète pas ce que fait le plugin — le plugin est le vecteur de l’intelligence propre au domaine qui vit dans WebAssembly. Sa surface d’authoring et de métadonnées est documentée dans language-reference/entities/plugin.md.

Domaine 1 : intention du développeur (le « quoi »)

graph LR
    classDef ext stroke-dasharray:5 4;

    A["Aggregate<br/>The 'What'"]
    CC["Component"]:::ext
    CapC["Feature"]:::ext
    EB["Release"]:::ext

    A -.->|"Requests"| CC
    A -.->|"Attaches"| CapC
    A -->|"Binds via"| EB
  • Rôle : le développeur. Il se concentre uniquement sur l’architecture IA, les boucles cognitives et les exigences de survie de l’application. Il n’a besoin de connaître ni CEL, ni OPA, ni les ports physiques.
  • 1. Aggregate : le plan déclaratif, fondé sur des maps, de la topologie applicative. Qu’il serve d’Aggregate racine que construit une Release ou de module paramétré et réutilisable, il définit des components logiques et attache, sous features, les Features dont le comportement relève de l’intention applicative, avec leurs values ; une Feature dont toutes les entrées sont opérationnelles est au contraire attachée par l’opérateur dans la Release (voir le domaine 4). Un identifiant se demande sur cette même surface de rattachement features, au moyen d’une Feature d’identifiants : il n’existe pas de bloc distinct pour cela. Il définit des exigences de capacité abstraites via parameters (des contrats typés rédigés dans le vocabulaire de la forme compacte) et l’état de la charge utile via values. Les instances de Component prennent en charge un champ description facultatif pour la documentation et l’affichage dans Studio. Il promeut la convention « Zero-Port » (abstraire les ports réseau sauf s’ils sont explicitement exigés par du code existant), sans plateforme cible ni namespace codés en dur.

Domaine 2 : Platform Catalog (les « interfaces et l’intelligence »)

graph TD
    classDef ext stroke-dasharray:5 4;

    A["Aggregate"]:::ext
    EB["Release"]:::ext
    CC["Component<br/>The Compute Interface"]
    CapC["Feature<br/>The Operational Trait"]
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext

    A -.->|"Requests"| CC
    A -.->|"Attaches"| CapC
    EB -.->|"Attaches"| CapC
    CC -.->|"Resolved to"| CD
    CapC -.->|"Resolved to"| CapD
  • Rôle : le Platform Architect. Le « programmeur » de la plateforme. Il place chaque composant dans l’ontologie opérationnelle, rédige les politiques programmables (mutateurs et validateurs Wasm) et établit les labels sémantiques de duck typing.
  • 2. Component : l’interface abstraite d’un nœud de calcul. Il déclare sa forme de base via l’ontologie cloud opérationnelle (par ex. component.aggrega.ai/type: server) et superpose son identité cognitive via des labels de duck typing (par ex. model.aggrega.ai/capability: generative). Il déclare des emplacements d’identifiants via featuresSchema (obligatoires/facultatifs, boîte noire/transparents) et utilise schema: (JSON Schema 2020-12, généralement rédigé avec la notation abrégée de la forme compacte) pour valider strictement le bloc values opaque du développeur.
  • 3. Feature : un trait opérationnel modulaire (par ex. masquage des données, routage DNS, gestion des secrets). Elle utilise des sélecteurs de labels appliesTo pour se lier dynamiquement à des labels sémantiques précis. Comme les Components, elle déclare des emplacements d’identifiants via featuresSchema pour imposer le provisionnement des clés d’API. Point essentiel, elle utilise metadata.annotations pour marquer explicitement les éléments du graphe IR plat, ce qui indique aux validateurs de politiques Wasm et aux plugins de rendu en aval comment traiter la charge utile de configuration de la Feature.
    • Features d’identifiants : la plateforme unifie la gestion des identifiants dans l’entité Feature : une Feature portant le label feature.aggrega.ai/kind: secret est une feature d’identifiants, qui définit une interface de requête vers un magasin de secrets (par ex. AWS Secrets Manager, HashiCorp Vault). Elle s’attache sous features: comme toute autre Feature, sur la même surface et sous la même forme ; le label est une métadonnée que porte le catalogue pour décrire ce que produit le rattachement, et aucune branche du compilateur ne le lit. Il n’existe pas de kind distinct pour le magasin de secrets ou la recipe de secrets : une FeatureRecipe d’identifiants a la même forme que toute autre FeatureRecipe, le pipeline de récupération puis de livraison est le même pour les deux, et le contrat de livraison inject (env, file, arg) est partagé. Une entité, un mot-clé de rattachement, un chemin d’exécution des modificateurs à travers le rendu ; et les identifiants s’associent sous features.type dans le Manifest.

L’ontologie comme label. L’ontologie cloud opérationnelle est déclarée dans metadata.labels["component.aggrega.ai/type"] plutôt que sous la forme d’un champ spec.type de premier niveau. Ce choix permet au moteur de sélecteurs de labels du compilateur de cibler directement les valeurs de l’ontologie : une Feature déclare appliesTo: "component.aggrega.ai/type in (server, worker)" pour s’attacher dynamiquement à chaque composant server ou worker sans aucune nouvelle logique Go dans le compilateur central. Le même mécanisme de sélecteurs s’applique à chaque label Aggrega, de sorte qu’une Feature, un sélecteur de socket ou un mappage de frontière d’une Release lit la clé de label propre à un catalogue exactement comme il lit celle-ci.

component.aggrega.ai/type est la clé d’Aggrega, et son ensemble de valeurs est fermé : le schéma publié du Component énumère les primitives, et un document qui porte toute autre valeur est refusé au chargement, E0215 nommant le label et listant ce qu’il accepte. Un catalogue qui a besoin d’une classification qu’Aggrega ne définit pas ajoute sa propre clé de label à côté (le schéma du Component accepte toute clé de label supplémentaire avec une valeur de type chaîne), de sorte qu’un nouvel axe coûte une clé à vous et aucune nouvelle version du compilateur, tandis que la clé réservée garde un sens unique partout. C’est ce qui permet à une Feature écrite pour component.aggrega.ai/type in (stateful-server) de fonctionner avec des Components d’auteurs qui ne se sont jamais rencontrés.

Domaine 3 : base d’infrastructure (les « implémentations »)

graph LR
    classDef ext stroke-dasharray:5 4;

    CC["Component"]:::ext
    CapC["Feature"]:::ext
    ENV["Manifest"]:::ext
    EB["Release"]:::ext
    CD["Recipe<br/>The Implementation"]
    CapD["FeatureRecipe<br/>The Binding"]
    T["Plugin<br/>The Wasm Plugin"]

    CC -.->|"Resolved to"| CD
    CapC -.->|"Resolved to"| CapD
    ENV -->|"Resolves Interfaces to"| CD
    ENV -->|"Resolves Interfaces to"| CapD
    EB -->|"Renders via"| T
  • Rôle : l’ingénieur d’infrastructure / Ops. Il est responsable de la réalité physique, de l’attribution des ports réseau et de la logique de templating.
  • 4. Recipe : le template de traduction multi-fournisseur (par ex. Helm ou Docker Compose). Elle établit un contrat d’API strict 1:1 avec le composant du catalogue via le mot-clé implements. La Recipe associe les .values du développeur au format physique. Elle code en dur les ports réseau physiques (par ex. 5432) et lit les provides de la cible par le pipe .context.uses, satisfaisant ainsi le contrat d’injection sans coder en dur les noms de bases de données.
  • 5. FeatureRecipe : associe explicitement une Feature à une implémentation d’infrastructure concrète via le mot-clé implements. Elle impose une capacité du fournisseur cible dans capability (par ex. helm, compose). Comme la plateforme unifie la gestion des identifiants dans l’entité Feature, les FeatureRecipes traitent à la fois les fonctionnalités opérationnelles (masquage des données, routage DNS, injection de sidecars) et les fonctionnalités d’identifiants (génération de CRD de coffre-fort, montage de volumes de secrets). Pour couvrir tout ce spectre, elle prend en charge trois blocs d’exécution distincts :
    1. pipeline : un tableau séquentiel de plugins WebAssembly (Wasm) pour la mutation du Workload après le rendu (par ex. injecter un sidecar Envoy via JSONPatch, ou monter un volume de secrets).
    2. source et valuesMapping, workload, artifacts : les trois mêmes types d’entrée que porte une Recipe, utilisés pour la génération de ressources ; ils permettent aux Ops d’assurer nativement le rendu de templates statiques (par ex. générer une nouvelle CRD HTTPRoute ou une CRD ExternalSecret) à côté du composant de base.
    3. injectMapping (interception avant le rendu) : un bloc de template Go natif exécuté avant le rendu de la Recipe de base. Il produit un dictionnaire JSON que le compilateur fusionne nativement en profondeur par-dessus le pipe mémoire .context.inject de l’appelant, ce qui permet une mutation des variables d’environnement et des chaînes de connexion côté appelant, sans Wasm.
    • Le modèle de FeatureRecipe d’identifiants : lorsqu’une FeatureRecipe implémente une Feature d’identifiants (portant le label feature.aggrega.ai/kind: secret), le principe standard du Plugin en deux parties s’applique : le pipeline enchaîne un plugin Fetcher (qui génère la CRD propre au coffre-fort) suivi d’un plugin Injector (qui monte le secret dans le conteneur cible). La séparation Fetcher/Injector maximise la réutilisabilité : passer d’AWS Secrets Manager à HashiCorp Vault ne nécessite que de remplacer le plugin Fetcher ; l’Injector reste identique.
  • 6. Plugin : le plugin WebAssembly adressé par contenu. Un Plugin de rendu de fournisseur (pluginType: provider) est l’unité qui transforme les types d’entrée d’une Recipe en format de fichier final sérialisé en chaîne : il déclare dans spec.provider.capabilities le ou les noms de fournisseurs qu’il sert (par ex. helm), expose un export render_node vers lequel le compilateur répartit les appels, et porte le reste des métadonnées de son socket de fournisseur (workloadSchema, wellKnownAnnotations) dans ce même bloc spec.provider. Les autres types de socket qu’un Plugin peut déclarer sont pipeline-step, linter, governance, cli, parser et importer. Le compilateur route la référence épinglée ; le runtime WebAssembly exécute les octets.

Domaine 4 : routage et politiques (la « colle »)

graph TD
    classDef ext stroke-dasharray:5 4;

    A["Aggregate"]:::ext
    EB["Release<br/>The Deployment Router"]
    ENV["Manifest<br/>The Dependency Lockfile"]
    CapC["Feature"]:::ext
    T["Plugin"]:::ext
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext

    A -->|"Binds via"| EB
    EB -.->|"Attaches"| CapC
    EB -->|"Uses"| ENV
    EB -->|"Renders via"| T
    ENV -->|"Resolves Interfaces to"| CD
    ENV -->|"Resolves Interfaces to"| CapD
  • Rôle : le Platform Operator / DevOps.
  • 7. Manifest : le fichier de verrouillage des dépendances. Il utilise un mappage d’URI plat : un dictionnaire components.type associe les types de composants du catalogue à des URI de Recipe, et un dictionnaire features.type associe les types de Feature à des URI de FeatureRecipe. La résolution est une recherche directe d’URI dans le fichier de verrouillage et le catalogue ; la détermination des capacités découle du champ spec.capability de chaque Recipe résolue, au moment du build. Après la résolution, chaque entité doit avoir un mappage, sinon le compilateur s’arrête. Pour maintenir un écosystème DRY, les Manifests prennent en charge un modèle de composition à la Kustomize via le mot-clé extends, ce qui permet aux manifestes propres à un environnement (comme local ou staging) d’hériter proprement d’un manifeste de base global et de ne déclarer que leurs surcharges spécifiques.
  • 8. Release : le routeur. Elle lie un aggregate à un manifest et associe les composants à des frontières physiques (par ex. aws-eks-production). Pour maintenir un flux de travail DRY, les Releases prennent en charge l’héritage via le mot-clé extends, ce qui permet aux releases propres à un environnement d’hériter proprement d’une release de base globale. Elle remplit le contrat abstrait de l’aggregate en injectant les réalités physiques strictement dans le bloc parameters, et injecte le dimensionnement physique (comme les CPU ou les ports) via l’espace de noms parallèle infra. Pour protéger l’Aggregate en tant que source unique de vérité, le schéma de la Release interdit mécaniquement un bloc values: : les Ops ne peuvent déclarer de values sur aucun Component ni aucune Feature depuis une Release. La variation par environnement des valeurs destinées au développeur passe par le Parameter Hoisting : le développeur expose un champ typé parameters.* dans l’Aggregate, le template values du Component y fait référence et la Release renseigne le paramètre pour son environnement. Les valeurs rendues diffèrent selon les environnements, tandis que l’Aggregate, la surface de rédaction qui détermine quelles valeurs existent et comment elles circulent, reste la source unique de vérité. Voir la contrainte 4, « La Release ne peut pas surcharger les valeurs du développeur », dans Contraintes architecturales et modèles recommandés pour l’interdiction au niveau du schéma énoncée explicitement. Point essentiel, pour empêcher des Releases intraçables qui « modifient l’aggregate », lorsqu’une Release utilise extends, la déclaration d’un aggregate est rejetée par le schéma de la Release (la contrainte du schéma interdit de déclarer aggregate lorsque extends est utilisé). La release enfant doit correspondre exactement à la même intention du développeur que sa release parente. Le manifest, en revanche, devient facultatif, ce qui débloque la « liaison tardive » : les Ops peuvent hériter de toute la topologie physique tout en remplaçant de façon chirurgicale le fichier de verrouillage des dépendances.
    • Rattachement des Feature : la Release rattache elle aussi des Features, sous features sur une frontière ou sur un seul composant. Une Feature dont toutes les entrées sont opérationnelles, elle la rattache directement, avec son type et son infra ; une Feature que l’Aggregate a rattachée, elle la dimensionne, en écrivant l’infra de ce rattachement sous le même nom.

Pourquoi séparer le Manifest de la Release. Séparer le fichier de verrouillage logiciel (Manifest) du routeur de déploiement (Release) permet une forme qu’aucune des deux entités ne pourrait produire seule : DevOps déploie une seule application sur plusieurs routeurs de déploiement régionaux (différentes Releases ciblant différentes régions cloud, toutes faisant référence au même Manifest) sans dupliquer les liaisons de Recipe d’un environnement à l’autre. Chaque Release régionale porte la disposition de ses frontières et ses paramètres propres à l’environnement tout en consommant le même fichier de verrouillage logiciel que fournit le Manifest. La mise à l’échelle multirégion découle de la séparation des domaines, et non de la duplication du Manifest.

Niveau 3 : bibliothèques (réutilisation du catalogue)

graph LR
    classDef ext stroke-dasharray:5 4;

    CC["Component"]:::ext
    CapC["Feature"]:::ext
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext
    SL["SchemaLibrary<br/>JSON Schema definitions"]
    ML["MappingLibrary<br/>Go template fragments"]
    WL["WorkloadLibrary<br/>Workload template fragments"]
    AL["ArtifactLibrary<br/>Named artifact bundles"]

    CC -.->|"$ref"| SL
    CapC -.->|"$ref"| SL
    CD -.->|"valuesMapping $import"| ML
    CapD -.->|"$import"| ML
    CD -.->|"workload $import"| WL
    CD -.->|"artifacts $import"| AL
    CapD -.->|"$import"| AL
  • Rôle : le Platform Architect (le même persona que dans le domaine 2), mais ce rôle n’intervient que lorsque le contenu du catalogue devient assez volumineux pour tirer parti de la réutilisation des schémas d’un Component à l’autre ou de la réutilisation d’une Recipe à l’autre de templates, de formes de workload ou de lots d’artefacts. Les auteurs isolés et les petits catalogues se passent de toute entité de niveau 3.
  • 9. SchemaLibrary : des définitions JSON Schema 2020-12 réutilisables. Une bibliothèque déclare des schémas nommés sous spec.schemas: et des assistants paramétrés facultatifs sous spec.templates: (avec des déclarations $params: et des références $instantiate: pour la réutilisation paramétrique). Les entités du catalogue consomment les entrées de la bibliothèque via le mot-clé JSON Schema standard $ref:, qui pointe vers l’entrée de la bibliothèque par son identité, sous la forme sans hôte <library>#/schemas/<name> (la version provient du fichier de verrouillage, et non de la référence). Nommage en PascalCase, distribution via OCI, épinglage dans le fichier de verrouillage. Facultative, pour les catalogues qui ont besoin de réutiliser des schémas d’un Component à l’autre : des formes communes comme PodResources, PersistenceSpec, NodePool, MetricsServiceMonitor reviennent dans chaque Component de datastore et chaque Component de workload, et les entrées d’une SchemaLibrary sortent cette répétition de la rédaction de chaque Component.
  • 10. MappingLibrary : des fragments de templates Go réutilisables. Une bibliothèque déclare des templates nommés sous spec.mappings:. Les Recipes et les FeatureRecipes consomment les entrées de la bibliothèque par identité via valuesMapping: { $import: <library>#/mappings/<name> }. Un mode de rédaction unique (templates Go uniquement) ; aucun chemin de rédaction parallèle en Jsonnet. Facultative, pour les catalogues qui ont besoin de réutiliser des mappings d’une Recipe à l’autre : des modèles communs comme la logique des helpers des charts Bitnami ou des modèles partagés de templates de pod reviennent dans chaque Recipe de datastore ciblant le même fournisseur, et les entrées d’une MappingLibrary sortent cette répétition de la rédaction de chaque Recipe.
  • 11. WorkloadLibrary : des fragments de templates de Workload réutilisables. Une bibliothèque déclare des entrées de workload nommées sous spec.workloads:. Une Recipe consomme une entrée par identité via workload: { $import: <library>#/workloads/<entry> }, et le corps importé est validé par rapport au schéma de Workload appartenant à la plateforme exactement comme un bloc workload: en ligne ; un workload importé depuis une bibliothèque produit donc un rendu identique à son équivalent en ligne. Un mode de rédaction unique (templates Go uniquement). Facultative, pour les catalogues qui ont besoin de réutiliser des workloads d’une Recipe à l’autre, lorsque plusieurs Recipes partagent une même forme de déploiement et ne diffèrent que par leurs valeurs.
  • 12. ArtifactLibrary : des lots d’artefacts nommés réutilisables. Une bibliothèque déclare des lots nommés sous spec.artifacts:, chaque lot regroupant les fichiers de sortie qui vont ensemble (par exemple une CRD, son RBAC et une ConfigMap) et étant importé comme une seule unité. Les Recipes et les FeatureRecipes consomment un lot par identité via artifacts.<name>: { $import: <library>#/artifacts/<name> }. Un mode de rédaction unique (templates Go uniquement). Facultative, pour les catalogues qui ont besoin de réutiliser des artefacts d’une Recipe à l’autre, lorsque le même ensemble de ressources auxiliaires accompagne de nombreuses Recipes.

Chaque bibliothèque est publiée via OCI, épinglée dans le fichier de verrouillage (les sections schema_libraries:, mapping_libraries:, workload_libraries: et artifact_libraries:) et apparaît dans l’interface du Hub avec la connaissance de ses consommateurs (quels Components font référence à quelles entrées de bibliothèque ; quelles Recipes consomment quelles entrées de bibliothèque).