Taxonomie des données et composition
La taxonomie unifiée des données et les règles de composition
Pour établir un schéma prévisible et éliminer la friction cognitive, la plateforme utilise exactement cinq mots-clés universellement compris et une structure YAML strictement fondée sur des maps (dictionnaires), avec des maps plutôt que des tableaux imbriqués à la racine de la structure.
1. Le standard de map à 5 mots-clés et la symétrie totale des schémas
Le vocabulaire structurel direct : une règle fondamentale de la conception des schémas veut que les structures de données racines soient des mots-clés uniques et structurels. Si l’emploi d’expressions anglaises familières (comme depends_on ou runs_within) peut rendre un DSL YAML plus naturel à lire pour un développeur, il introduit une complexité structurelle lorsqu’il faut mapper ces clés dans des templates Go programmatiques. Pour conserver une correspondance directe 1:1 des variables et éviter la fragmentation du langage dédié (DSL), les schémas JSON des entités centrales du catalogue (Component, Feature) présentent une symétrie structurelle quasi totale, portée par le même ensemble central de mots-clés structurels utilisé dans tous les emplacements d’instance rédigés. Les Features d’identifiants (avec le label feature.aggrega.ai/kind: secret) partagent exactement ce paradigme — il n’existe pas de schéma distinct pour les secrets.
parameters(le contrat d’environnement global)- Portée : définis à la racine de l’
Aggregate; fournis par laRelease(CI/CD) en ligne sousparameters:ou viaparameters: { $import: <path> }pointant vers un fichier de paramètres externe. - Signification : des arguments externes qui modifient dynamiquement l’état cognitif ou logique de l’application d’un environnement à l’autre (p. ex. passer de
workers: 2àworkers: 10). Prend en charge un contrat typé (voir data-pillars pour la syntaxe complète du contrat typé) validé avant l’interpolation. Pour les workflows GitOps qui conservent les valeurs de paramètres dans un fichier séparé, la Release utilise la forme$import:; le compilateur charge le contenu du fichier et remplace la map en ligneparameters:. La superposition de plusieurs fichiers s’exprime par des chaînesextends:de Release.
- Portée : définis à la racine de l’
values(l’intention cognitive - appartient au développeur)- Portée : utilisées de manière uniforme dans les
componentset leurs rattachementsfeaturesau sein de l’Aggregate, Features d’identifiants comprises. - Signification : l’état cognitif central, la logique métier et la configuration opérationnelle. Opaques pour le compilateur Go, mais strictement validées par la déclaration
schema:unifiée du catalogue (forme compacte ou JSON Schema 2020-12).
- Portée : utilisées de manière uniforme dans les
uses(la topologie structurelle - état déclaratif)- Portée : utilisées de manière uniforme dans les
componentset leurs rattachementsfeaturesau sein de l’Aggregate, Features d’identifiants comprises. - Signification : un énoncé déclaratif de fait qui définit les arêtes réseau et les dépendances (p. ex. « Cet agent utilise cette base de données »). Analysé nativement par le compilateur Go pour tracer le graphe de la représentation intermédiaire (IR). Validé par la déclaration
usesSchemaunifiée du catalogue pour imposer la sûreté des types entre nœuds.
- Portée : utilisées de manière uniforme dans les
infra(la réalité physique - appartient à Ops)- Portée : utilisé de manière uniforme dans les
componentsd’une frontière et leurs rattachementsfeaturesau sein de laRelease. - Signification : l’empreinte physique et le dimensionnement mécanique injectés lors du Late Binding (p. ex.
cpu_limit: "4",port: 5432). Les instances de composant de l’Aggregate et leurs rattachementsfeaturesne comportent pas de champinfraet, combinées àadditionalProperties: false, rejettentinfralors de la validation du schéma. Validé par la déclarationschema:unifiée du catalogue.
- Portée : utilisé de manière uniforme dans les
inject(le contrat de livraison - commande impérative)- Portée : utilisé sur une instance de composant, dans des définitions de cible explicites au sein de
useset sur lesfeaturesrattachées, Features d’identifiants comprises. - Signification : une commande explicite et impérative qui dicte l’intention de la livraison (p. ex. « Compilateur, injecte cette valeur mappée comme variable d’environnement »). Elle établit le contrat abstrait (
env,file,argou des mécanismes personnalisés) pour une sortie physique, un endpoint résolu ou un identifiant récupéré, tandis que la mécanique physique décrivant comment exactement ce montage est exécuté est entièrement déléguée à la Recipe Ops sous-jacente. Chaque mécanisme est une liste d’entrées ([{ in: API_HOST, from: "host" }]), chacune nommant son identifiant local avecin:et portant exactement l’un defrom:ouvalue:.
- Portée : utilisé sur une instance de composant, dans des définitions de cible explicites au sein de
.context(le pipe de métadonnées générique)- Portée : injecté silencieusement par le compilateur dans les templates de la
RecipeOps. - Signification : porte ce que le compilateur a assemblé pour le nœud à partir du reste du graphe (comme
.context.uses), transmis directement au moteur de templates d’Ops.
- Portée : injecté silencieusement par le compilateur dans les templates de la
La réalité de la correspondance 1:1
En remplaçant les prépositions familières par des mots-clés d’infrastructure stricts, on obtient une correspondance 1:1 directe. L’ingénieur Ops n’a pas à traduire de la grammaire ; il fait simplement référence aux clés exactes que le développeur a écrites.
Formes structurelles : des maps à la racine, des tableaux dans les payloads. Les blocs de topologie racines — components, features, aggregates, subsystems, boundaries — sont des maps YAML dont les clés, rédigées par l’utilisateur, servent d’identifiants d’instance stables. Les tableaux ne sont pas valides à ces positions ; la clé de map est l’identité que le compilateur utilise pour les références croisées (target: my-db), la construction des nœuds du graphe et la résolution du Manifest. Dans les blocs de payload opaques (values, infra, parameters), les tableaux sont pleinement autorisés — les développeurs peuvent écrire tools_allowed: ["sql", "web"] ou hostnames: ["stripe.com", "twilio.com"] dans les values d’un Component. Le schéma de l’Aggregate déclare ces blocs de payload comme additionalProperties: true, de sorte qu’ils sont opaques pour le compilateur Go et entièrement validés par la déclaration schema: intégrée au catalogue. La volatilité des frameworks (nouvelles formes d’API d’IA, nouveaux formats de payload cloud-native) se trouve ainsi placée dans le domaine du catalogue, où elle peut évoluer indépendamment, tandis que le compilateur Go reste limité aux clés adressables à la racine structurelle.
2. Les flux d’information : qui, quand et pour quoi ?
Pour éviter les collisions d’espaces de noms dans les templates et la fuite involontaire de configurations d’infrastructure physique dans la logique cognitive de l’application, l’architecture sépare explicitement les données en six flux distincts :
- Flux 1 : l’injection environnementale (
parameters) : le pipeline CI/CD injecte les réalités du déploiement. Le compilateur valide chaque valeur fournie par la Release par rapport au contrat typéparameters:, puis interpole les variables de template Go résolues avant d’exécuter la validation du schémavalues:en aval.- Usage recommandé : les
parameterssont réservés à la logique cognitive de l’application qui varie d’un environnement à l’autre (p. ex.LOG_LEVEL=debug,ENABLE_BETA=true). Le dimensionnement opérationnel et les questions d’infrastructure physique — réplicas, limites de CPU, ARN AWS, noms d’hôte d’ingress — passent par le blocinfrade laReleaseet les overlays de frontière, ce qui garde l’Aggregatedu développeur centré sur l’intention applicative. - Porte de sortie pragmatique : pour les petites équipes, le prototypage rapide ou les intégrations CI/CD héritées où une séparation stricte n’est pas praticable, les
parameterspeuvent transporter des configurations d’environnement globales à travers la pile. Le compilateur accepte tout ce qui passe la validation du schéma ; la recommandation ci-dessus est un contrat social, pas une règle du compilateur.
- Usage recommandé : les
- Flux 2 : l’intention applicative cognitive (
valuesdans les Components) : définit la logique intrinsèque de l’application. La déclarationschema:du Component (forme compacte ou JSON Schema 2020-12) fournit une vérification de types et une validation strictes pour ce payload, offrant aux développeurs un retour « Shift-Left » immédiat et garantissant que les configurations demandées correspondent à l’API d’infrastructure sous-jacente. - Flux 3 : l’intention opérationnelle de Feature (
valuesdans les Features) : dans l’Aggregate, le développeur demande les capacités d’infrastructure dont le comportement relève de l’intention applicative et interroge des identifiants strictement typés, sans modifier le code interne. Une Feature dont toutes les entrées sont opérationnelles ne porte pas devaluesdu développeur : les opérations la rattachent dans la Release, avec soninfra(flux 4). - Flux 4 : le dimensionnement de l’infrastructure physique (
infra) : en contournant entièrement le développeur, le dimensionnement physiqueinfraest projeté explicitement depuis laReleasepropre à l’environnement directement sur les Components à portée locale et leurs Features rattachées, Features d’identifiants comprises. Pour éviter les collisions de validation de schémas fermés dues à la diffusion telle quelle de dictionnaires, le dimensionnementinfraest strictement localisé au composant explicite qui le cible. Cela maintient les limites de calcul, les réplicas et les exigences mécaniques en ressources dans le domaine Ops. - Flux 5 : les annotations en cascade (métadonnées contextuelles) : les données contextuelles larges (comme les domaines opérationnels, les namespaces ou les codes de facturation) sont gérées par des annotations en cascade, ce qui évite la pollution par diffusion de
infra. Elles sont séparées en compartiments selon leur origine, et l’usage prévu de chaque compartiment ci-dessous est un contrat social : un template de Recipe peut lire les trois, et le compilateur n’impose pas la séparation (voir labels-and-annotations) :.context.annotations.release(frontières du domaine 4) : utilisées exclusivement pour régir les réalités physiques. Ops achemine explicitement ces annotations vers des champsinfralocaux stricts via des templates Go (p. ex. en mappant un namespace régional sur un composant de calcul)..context.annotations.aggregate(sous-systèmes du domaine 1) : utilisées exclusivement pour régir la logique cognitive et opérationnelle. Ces annotations sont acheminées explicitement dans les payloadsvaluesdu composant (p. ex. en propageant en cascade le code de facturation d’une équipe jusqu’à une configuration de l’application)..context.annotations.catalog(catalogue du domaine 2) : traits intrinsèques immuables rédigés par l’architecte, utilisés principalement pour l’évaluation programmatique des politiques Wasm.
- Flux 6 : le pipe de métadonnées (
.context) : applique les exigences globales de l’entreprise (tags SOC2) directement aux templates de l’infrastructure physique.
3. Abstraction réseau : la convention « Zero-Port »
- La bonne pratique : les développeurs devraient omettre les ports de l’
Aggregate. La Recipe Ops gère dynamiquement le routage interne. - La porte de sortie : si le code interne d’une application ne peut pas être modifié, l’architecte de plateforme expose explicitement un champ
portdans la déclarationschema:. Note d’architecture : la convention « Zero-Port » est l’exemple le plus marquant de la séparation des responsabilités plus large de la plateforme. Exactement la même philosophie — éloigner la mécanique physique du développeur — s’applique aux demandes de CPU, aux limites de mémoire, aux domaines opérationnels et au dimensionnement des disques. Chaque fois qu’une contrainte d’infrastructure physique doit fuir dans le payload applicatif du développeur (en raison de code hérité ou d’exigences matérielles strictes), elle doit toujours être régie par une « porte de sortie » explicite dans la déclarationschema:de l’architecte, la déclaration par rapport à laquelle le payload du développeur est validé.
Le nom « Zero-Port » désigne cette convention ; le principe se généralise à toute contrainte d’infrastructure physique qu’une application héritée code en dur. Le schéma ci-dessous utilise tcp_keepalive_seconds comme exemple détaillé — un délai noyau/réseau que l’application attend au niveau des sockets — parce qu’il se situe clairement sur l’axe de la fuite d’infra.
Le schéma (domaine 2) :
values: image: { type: string, required: true } # The architect explicitly allows the developer to declare a hardcoded constraint tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }Le YAML du développeur (domaine 1) :
components: legacy-payment-engine: type: core/java-tomcat:1.0.0 values: image: "corp/payments:v4" tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versaComportement du compilateur : le compilateur Go transmet tcp_keepalive_seconds: 120 dans le graphe de l’IR. La Recipe Ops lit ensuite {{ .values.tcp_keepalive_seconds }} pour configurer la spécification du pod Kubernetes ou le délai d’inactivité du répartiteur de charge du fournisseur cloud, comblant ainsi l’écart avec l’existant sans enfreindre le schéma.
4. Le contrat d’injection et la map pré-résolue
Parmi les cinq mots-clés structurels, inject a une forme différente des autres. parameters, values, uses et infra sont des états déclaratifs — le développeur écrit des faits sur ce qu’est l’application et ce dont elle dépend. inject est une commande impérative — le développeur dicte comment une valeur doit être livrée au conteneur en cours d’exécution, en mappant des sources de données abstraites (les clés provides d’une cible, les valeurs propres du composant, la réponse du coffre d’une Feature d’identifiants) sur des mécanismes de livraison concrets (env, file, arg ou un mécanisme personnalisé que le Component déclare).
Ce découplage est structurel. L’Aggregate du développeur dit « injecte l’hôte de la base de données comme variable d’environnement DB_HOST » sans nommer l’adresse physique de la base de données, le chemin du coffre dans le magasin de secrets ni le format de nom d’hôte du fournisseur cloud. La Recipe Ops reçoit la chaîne résolue via .context.inject et la consomme sans avoir à rédiger la chaîne de recherche.
La map pré-résolue. Pendant le rendu, le compilateur résout chaque source d’injection — les littéraux d’auto-injection et les références from: vers les provides du composant lui-même, les références entre composants via uses[].inject, les interceptions injectMapping de la FeatureRecipe — en un unique dictionnaire aplati dans .context.inject. Au moment où le template valuesMapping de la Recipe de base s’exécute, chaque clé d’injection porte sa valeur de chaîne finale. Les Recipes parcourent directement la map ({{ range $k, $v := .context.inject.env }}) sans parcourir la chaîne de résolution.
Les noms que le développeur donne aux valeurs propres du composant. Là où le Component déclare spec.inject, le bloc inject: propre au développeur choisit les noms sous lesquels les valeurs propres et les provides du composant atteignent le canal de livraison. Le compilateur indique à la Recipe, dans .context.self_inject, l’unique valeur propre que lit le template de chaque entrée — par mécanisme, chaque nom associé à provides.<key>, à values.<key> pour un template qui lit exactement une valeur propre et rien d’autre, ou à une chaîne vide — sous la forme que prennent les noms d’une connexion dans .context.uses.<alias>.inject. La convention du catalogue de la bibliothèque standard pour une Recipe qui exécute l’image du développeur consiste à traiter comme des valeurs par défaut les noms qu’elle choisirait sinon pour les valeurs propres du composant, en ne fournissant une valeur propre sous son nom par défaut que lorsqu’aucune entrée ne lui est déjà associée. Il s’agit d’une convention du catalogue, et non d’une règle du compilateur : un catalogue d’entreprise peut fournir les valeurs propres de ses composants comme il l’entend. Le compilateur lit la table à partir du texte écrit par le développeur et n’attache aucune signification aux noms.
La spécification complète du contrat d’injection — sémantique du contexte à double état, règles de collision de clés, modèle d’interception de la FeatureRecipe et exemples détaillés — se trouve dans topology-triad.
5. Le moteur de templates (DX d’Ops)
Les ingénieurs Platform Ops rédigent les templates de traduction et ont besoin de toute la puissance du templating d’infrastructure standard, sans langage de templates propriétaire. Les templates d’Aggrega sont des Go text/template :
- Pas de chaînes « magiques » : le compilateur préserve les clés de map exactes du développeur. Ops accède aux features en toute sécurité via l’indexation standard des maps Go :
{{ (index .features "public-route").infra.hostname }}. - La bibliothèque Sprig : le compilateur enregistre nativement la bibliothèque Sprig, standard de Helm, qui donne un accès immédiat à des pipelines comme
| default,| quoteet| toYaml. - Fragments de MappingLibrary : un fragment de mapping que plusieurs Recipes réutilisent réside dans une MappingLibrary et est importé dans chaque Recipe avec
$import:. Les helpers de templates de charts de Helm (include,tpl,required,warn) ne sont pas enregistrés ; sprig-functions liste ceux qui le sont.
6. Règles de composition : Aggregates, sous-systèmes et Components
- Regroupement logique (le tableau
subsystems) : les développeurs peuvent appliquer des métadonnées logiques (propriété d’équipe, labels de conformité) et des features transversales à des dizaines de composants simultanément à l’aide desubsystems. Les sous-systèmes agissent comme des dossiers récursifs sur le plan logique/de l’intention, propageant lesannotationsvers le bas dans le compartiment.context.annotations.aggregateet rattachant des features à tous les composants contenus sans imposer de frontières physiques. Les features de niveau sous-système suivent le même schéma que les features de niveau composant (avec prise en charge detype,values,uses,inject), car elles relèvent du domaine 1 (intention du développeur). Lors de la finalisation du graphe, le compilateur aplatit les features du sous-système dans la liste de features de chaque composant contenu, en les plaçant après les features propres du composant et avant toute feature rattachée par la Release dans l’ordre d’exécution.
subsystems: finance-module: annotations: "billing.corp.com/team": "payments" features: audit-logging: type: core/audit-logger:1.0.0 values: { log_level: "verbose" } components: ledger-api: type: core/python-worker:1.0.0 ledger-db: type: core/postgres:1.0.0- Les Aggregates composites sont PRIS EN CHARGE (le modèle des modules) : les Aggregates servent à la fois d’Aggregate racine que construit une Release et de modules réutilisables. Un Aggregate parent peut déclarer un Aggregate enfant exactement comme un composant, en lui transmettant des
parameters. Pour éviter un couplage fort, les Aggregates enfants exposent un contratexportedComponents:, qui établit un nom d’interface publique stable. Le parent n’atteint les composants du module que par cette interface : une cibleuses:nomme le module et l’un de ses alias exportés, et le compilateur relie l’arête au composant interne que nomme l’alias, tandis qu’une cible qui pénètre dans un module par tout autre nom arrête la build en nommant le module et les alias qu’il exporte. Un module peut lui-même réexporter le composant exporté d’un module imbriqué sous son propre nom d’interface — éventuellement en le renommant — et le compilateur résout une telle chaîne de réexportation de manière transitive jusqu’au nœud interne sous-jacent, de sorte que les modules se composent à n’importe quelle profondeur sans qu’un parent ait besoin de savoir à quelle profondeur la cible est imbriquée. Une cible qui ne se résout en aucun nœud interne arrête toujours la build de manière explicite, et une chaîne de réexportation qui se referme sur elle-même est rejetée au lieu d’être suivie indéfiniment.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: components: internal-pg-primary: type: core/postgres:1.0.0
exportedComponents: # The Public Contract (Written once by the module author) primary_db: "internal-pg-primary"apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: my-catalog/child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_db-
Les Components ne peuvent pas contenir de sous-composants : les Components sont des briques atomiques. La composition se fait au niveau de l’Aggregate, par les sous-systèmes et les sous-agrégats. Si une application nécessite plusieurs conteneurs physiques (comme une API + un sidecar), cette imbrication physique se trouve dans le template de la Recipe Ops, pas dans la définition du Component.
-
Un service cohérent par Component — la frontière de la charge de travail unique : un Component modélise un service cohérent — un seul service exposé, ou la ou les charges de travail d’un service avec ses charges de travail auxiliaires purement internes. Son label
component.aggrega.ai/typenomme la forme opérationnelle de ce service unique. Plusieurs charges de travail physiques au sein d’un même Component conviennent lorsqu’elles forment un produit cohérent sans éléments utilisables indépendamment : un service dont le chart exécute un contrôleur plus un webhook plus un injecteur reste un seul Component. Le critère n’est pas la présence de plusieurs charges de travail ; c’est l’utilisabilité indépendante.La frontière se trace là où un bundle contient quelque chose qu’un autre composant pourrait utilement utiliser (
use) seul — en particulier une infrastructure étrangère comme une base de données, un cache ou un broker de messages qu’Aggrega modélise déjà comme un Component à part entière. Un tel bundle n’est pas un seul Component ; c’est un module sous-agrégat — le modèlespec.aggregates+exportedComponentsprésenté plus haut — qui compose un Component par service, de sorte que chaque service soit un nœud adressable avec son propre type, ses propres arêtes et sa propre surface de politiques et de mise à l’échelle.L’heuristique, formulée comme une règle nette : le chart contient-il quelque chose qu’un autre composant pourrait utilement utiliser seul, ou pour lequel Aggrega dispose déjà d’un Component ? Si oui, modélisez-le comme une pile — un module sous-agrégat composant des Components par service. S’il ne sert jamais que ce seul service, modélisez-le comme un seul Component.
Envelopper un produit multiservice entier dans un seul Component opaque est un antipattern documenté. Le compilateur est sans parti pris et l’acceptera — il rend tout ce qui passe la validation du schéma — mais la bibliothèque standard compose plutôt des Components par service dans un module, car un emballage monolithique masque les services modélisables indépendamment à la topologie, au sélecteur ainsi qu’aux politiques et à la mise à l’échelle par service. Cette discipline de granularité est un contrat social — voir
../language-reference/vocabulary/social-contracts.md(granularité du Component).
7. La portée par défaut — divulgation progressive du regroupement
subsystems (dans l’Aggregate) et boundaries (dans la Release) sont les constructions de regroupement, mais un développeur n’a pas à les déclarer d’emblée. Chaque entité propose deux formes d’écriture, et elles sont mutuellement exclusives : écrire les composants regroupés sous des portées nommées, ou écrire les composants directement au niveau supérieur — jamais les deux à la fois. Un document qui déclare à la fois des components de niveau supérieur et des portées nommées s’arrête au chargement avec une erreur d’enveloppe.
Pour la forme plate (components de niveau supérieur), le compilateur synthétise une véritable portée default au chargement et y replie les composants de niveau supérieur, de sorte que chaque passe en aval voit une structure uniforme porteuse de portées. La portée synthétisée n’est pas un conteneur caché : c’est un véritable nœud de l’IR, marqué de sa provenance, distinguable d’une portée qu’un développeur nomme explicitement default. Elle n’est masquée que là où l’auteur lit des chemins — les diagnostics et l’adressage affichent le chemin en forme de racine .spec.components[…] que le développeur a réellement écrit.
- Aggregate plat (composants de niveau supérieur) : les composants s’écrivent sous
spec.components, sanssubsystems. Le compilateur les replie dans un sous-systèmedefaultsynthétisé au chargement. Les annotations de portée de sous-système et les fonctionnalités de niveau sous-système ne s’appliquent qu’aux sous-systèmes déclarés ; la forme plate n’en porte aucune. - Release plate (composants de niveau supérieur) : les composants s’écrivent sous
spec.components, sansboundaries. Le compilateur les replie dans une frontièredefaultsynthétisée dont la sortie est plate — les artefacts arrivent directement sousdist/(par provider :dist/compose/,dist/helm/, …), sans segment portant le nom de la frontière. C’est le cas le plus simple :aggrega buildsur une cible Compose plate ou à cluster unique, sans nommer de frontières. (Une frontière qu’un développeur déclare et nommedefaultest une frontière nommée ordinaire et, sansdirectory:qui lui soit propre, émet versdist/boundaries/default/comme n’importe quelle autre.) - Le chemin d’évolution : lorsqu’une architecture plate grandit au point d’avoir besoin de regroupement (espaces de noms différents, regroupements logiques séparés, déploiement sur plusieurs frontières), le développeur déplace les composants de niveau supérieur dans des
subsystemsexplicites, ou Ops introduit desboundariesexplicites. Comme les deux formes sont mutuellement exclusives, il s’agit d’un passage de la forme plate à la forme à portées — et non d’un mélange des deux — et l’identité des nœuds est préservée pendant la transition.
La raison est la divulgation progressive : exiger un regroupement obligatoire pour des cas d’usage triviaux (une démo à un seul service, un prototype local rapide) crée une friction inutile. Le test d’intégration « de zéro à fonctionnel en 10 minutes » exige qu’un développeur puisse écrire un Aggregate minimal avec un composant, un Manifest et une Release, et obtenir une sortie fonctionnelle sans avoir d’abord à comprendre les sous-systèmes ou les frontières. La portée par défaut est la rampe d’accès ; les portées déclarées sont là où va une architecture à mesure qu’elle grandit.
8. Contraintes architecturales et modèles recommandés
Les entrées ci-dessous sont un modèle recommandé et cinq contraintes. Les schémas imposent les contraintes 4 et 5 — la Release n’a pas de bloc values, et l’instance de composant d’un Aggregate n’a pas de clé labels ; les autres sont des conventions que le compilateur ne vérifie pas.
-
Modèle recommandé : remontée des paramètres via des chaînes de template
- Exemple : le développeur écrit
workers: {{ .parameters.env_workers }}dans son blocvalues, sans guillemets, afin que la valeur arrive sous la forme de l’entier qu’elle a été déclarée être. - Pourquoi : si l’Aggregate déclare
env_workerscomme paramètre typé (type: integer), le compilateur valide d’abord la valeur fournie par la Release par rapport au contrat. La validation du contrat des paramètres a lieu avant l’interpolation ; l’interpolation a lieu avant la validation du schémavalues:englobant. Cela préserve la réutilisabilité de l’Aggregate : Ops fournit l’entier via lesparameters:de laRelease, le compilateur le valide par rapport à la déclaration typéeparameters:, substitue la valeur résolue dans le document, et la déclarationschema:du Component valide avec succès l’entier obtenu.
- Exemple : le développeur écrit
-
Contrainte 1 : les identifiants sont des attachements, pas des valeurs
- Modèle déconseillé : le développeur écrit
values: { password: "123" }sur un composant. - Pourquoi : la convention de la bibliothèque standard veut qu’un identifiant soit demandé comme attachement sous
features:, en nommant untypede Feature d’identifiant (un type étiquetéfeature.aggrega.ai/kind: secret) et en utilisant lesvaluespropres à cet attachement pour décrire la requête adressée à un magasin de secrets. Il s’agit d’une convention, pas d’une vérification du compilateur — le compilateur n’interprète pas ce que signifie une feuille devalueset transporte tel quel un littéral en ligne. C’est la surface d’attachement qui rend la forme bien écrite disponible et typée.
- Modèle déconseillé : le développeur écrit
-
Contrainte 2 : Components agnostiques vis-à-vis des capacités
- Modèle non pris en charge : l’architecte écrit
aws_instance_type: stringdans la déclarationschema:du Component. - Pourquoi : par convention, les Components sont agnostiques vis-à-vis des capacités. Les cibles matérielles physiques se trouvent dans les Recipes d’Ops ou dans des annotations
.contextgénériques, et non dans la logique applicative cognitive de base.
- Modèle non pris en charge : l’architecte écrit
-
Contrainte 3 : logique conditionnelle sur les métadonnées
- Modèle non pris en charge : Ops écrit
{{ if eq .context.labels.gpu "true" }}dans uneRecipepour changer fondamentalement la stratégie de déploiement. - Pourquoi : le canal
.contextcontourne la validationschema:de chaque pilier. S’appuyer sur des étiquettes non validées pour la logique d’infrastructure de base rend la plateforme fragile. L’objet.contexttransporte un étiquetage de métadonnées (par ex. facturation, SOC2) ; le routage structurel relève des piliers validés par schéma.
- Modèle non pris en charge : Ops écrit
-
Contrainte 4 : la Release ne peut pas remplacer les valeurs du développeur
- Modèle non pris en charge : Ops tente de remplacer la logique cognitive d’un développeur (par ex. en changeant
workers: 4enworkers: 10) depuis laRelease. - Pourquoi : l’
Aggregateest la source unique de vérité pour l’intention du développeur. Si une valeur est codée en dur dans l’Aggregate, elle est immuable d’un environnement à l’autre. Si une valeur doit changer selon l’environnement, le développeur utilise la remontée des paramètres. Le schéma de laReleasel’impose en interdisant les blocsvalues, limitant Ops à remplir le contratparameterset à définir l’infraphysique.
- Modèle non pris en charge : Ops tente de remplacer la logique cognitive d’un développeur (par ex. en changeant
-
Contrainte 5 : étiquettes au niveau de l’instance dans l’Aggregate
- Modèle non pris en charge : le développeur écrit
labels: {}sur une instance de composant dans l’Aggregate. - Pourquoi : les étiquettes sont des caractéristiques immuables de niveau catalogue, écrites par l’architecte de la plateforme — l’identité sémantique que lisent les moteurs de politiques et les sélecteurs. La Release achemine les composants vers les frontières par un ciblage explicite par ID fondé sur des maps (
components: { "my-agent": {} }), ce qui préserve la possibilité d’imbriquerinfraet des surcharges de fonctionnalités par composant sans mêler la paternité des étiquettes à l’Aggregate du développeur.
- Modèle non pris en charge : le développeur écrit
9. Le périmètre de sécurité & les garde-fous explicites sur l’egress (destinations hors périmètre)
Aucune application n’existe dans le vide. Une architecture Aggrega compilée représente un graphe strictement cartographié. Pourtant, les systèmes d’IA modernes interagissent constamment avec des entités extérieures à ce périmètre compilé — comme les LLM SaaS publics (Anthropic, OpenAI), les API publiques génériques (Stripe, Twilio) ou les bases de données brownfield héritées (Oracle sur site).
Pour intégrer ces systèmes externes en toute sécurité, Aggrega sépare strictement la frontière de sécurité de la mécanique d’exécution. La frontière de sécurité est régie par la règle universelle du Component et le garde-fou explicite sur l’egress.
1. La règle universelle du Component
Si une application interagit avec une entité — qu’il s’agisse d’une base de données locale, d’une ressource cloud gérée, d’un LLM SaaS ou d’un point de terminaison d’API publique générique —, cette entité DOIT être déclarée comme un Component distinct dans l’Aggregate. Cette règle est une convention : le compilateur ne peut pas voir un appel que fait l’application, donc rien ne la vérifie.
En traitant les API SaaS externes et les bases de données héritées comme des nœuds de premier ordre dans le graphe de la représentation intermédiaire (IR), les développeurs peuvent attacher des configurations de proxy Zero-Trust directement à l’appel sortant. Par exemple, en modélisant l’API Stripe comme un nœud distinct, un développeur peut lui attacher une fonctionnalité header-injector, garantissant que la configuration générée empêche l’agent appelant de détenir le jeton brut de l’API dans sa propre mémoire.
2. Le garde-fou explicite sur l’egress (conformité de l’infrastructure)
Plutôt que de s’appuyer sur une logique codée en dur dans le compilateur pour régir l’egress réseau, Aggrega délègue entièrement la sécurité du périmètre aux moteurs de politiques agnostiques de l’entreprise et aux plugins de rendu Wasm. Cela garantit que les configurations générées se conforment strictement aux approbations explicites d’egress.
- Le point d’ancrage du catalogue (domaine 2) : lorsqu’un architecte définit un composant SaaS public (par ex.
core/external-service), il y attache une étiquette d’entreprise immuable (par ex.security.enterprise.com/zone: "untrusted-external"). - Le garde-fou de politique (à la compilation) : avant que la moindre configuration soit générée, le moteur de politiques OPA ou Kyverno évalue le graphe. L’entreprise écrit une règle simple : « Si un nœud interne se connecte à un nœud étiqueté
untrusted-external, l’ID de ce nœud cible doit figurer explicitement dans le tableauparameters.approved_egressde l’environnement. » Si un développeur tente d’acheminer des données vers une destination externe non approuvée, le moteur de politiques arrête la compilation. - La génération de la configuration (au moment du rendu) : si la politique est satisfaite, la règle d’egress est rendue à partir de ce que l’opérateur a rattaché. La Feature
core/egress-allowlist, rattachée au composant appelant dans la Release, rend surhelmuneNetworkPolicyKubernetes par workload que ce composant rend, n’autorisant l’egress que vers ses propres pods, vers les pods des cibles de ses arêtesusessur les ports que ces pods déclarent, vers le DNS du cluster et vers les plages d’adresses que le rattachement liste pour une cible que le cluster n’exécute pas, comme une API SaaS publique. La build s’arrête à moins que la Release n’affirme, avecinfra.control_plane_present: true, que le plugin réseau du cluster applique les network policies, et s’arrête en nommant toute connexion externe de ce type pour laquelle aucune plage d’adresses n’est listée ; surcompose, qui n’a pas de network policy, le rattachement arrête la build. Le développeur n’écrit jamais de règle de pare-feu.
Cela garantit — au moyen d’un rôle de verdict de gouvernance qui évalue la topologie déclarée — que l’infrastructure explicitement déclarée est conforme à la politique d’egress sans que le compilateur Go de base ait besoin de comprendre ce que signifie « externe ». (Remarque : un véritable egress zero-trust suppose que le cluster cible exécute une CNI Default Deny à l’exécution ; les configurations générées se contentent de cartographier les exceptions autorisées).
Un Component par service externe
Chaque service externe est déclaré comme un composant distinct, et non regroupé dans un tableau à cibles multiples. Si une application appelle cinq API tierces différentes, le développeur déclare cinq composants core/external-service distincts. C’est cette déclaration par service qui permet aux moteurs de politiques et aux plugins Wasm de cibler individuellement chaque destination sortante — en attachant à chaque dépendance externe des politiques d’egress différentes, des fonctionnalités de proxy différentes ou des points d’ancrage d’observabilité différents.
Découpler la sécurité de l’exécution (le scénario « brownfield »)
Il est essentiel de noter que l’étiquette sémantique (par ex. untrusted-external) détermine la politique de sécurité réseau, et non l’exécution. Elle est indépendante du fait qu’Aggrega rende ou non des artefacts qui provisionnent la ressource.
- Scénario A (API SaaS publique) : étiquetée
untrusted-externaldans le catalogue (déclenche les garde-fous d’egress de la politique). Réalisée par un workload de référence (aucune ressource de calcul provisionnée ; voir §10). - Scénario B (base de données héritée interne) : étiquetée
internal-trusted(contourne les garde-fous d’egress, reste dans le VPC). Réalisée par un workload de référence (aucune ressource de calcul provisionnée ; voir §10). - Scénario C (base de données auto-hébergée) : étiquetée
internal-trusted. Exécutée via le plugin de rendu Helm (provisionnée physiquement sous forme de StatefulSet Kubernetes).
10. Services que la build ne provisionne pas : Workloads de référence
Lorsqu’une application interagit avec une base de données héritée sur site ou une API SaaS publique (comme Stripe), la règle universelle du Component impose que ces entités externes soient déclarées comme des composants distincts dans l’Aggregate. Cependant, Aggrega ne doit pas tenter de générer pour elles un artefact physique de Pod Kubernetes ou d’instance AWS RDS.
La Recipe qui réalise un tel composant déclare un Workload de form: reference : un endpoint — un hôte ou une URL —, éventuellement un port, et aucun conteneur. Le compilateur les transmet tous deux comme chaînes de pointeurs déterministes et ne les résout jamais. Ce qu’un provider rend pour un Workload de référence lui appartient : helm émet un Service ExternalName portant l’hôte de l’endpoint, afin que les workloads du cluster puissent atteindre un service dont l’endpoint est un nom DNS sous un nom stable interne au cluster ; compose ne rend rien pour lui. Kubernetes traite un externalName comme un nom DNS, de sorte qu’un endpoint écrit sous forme d’adresse IP est atteint à l’adresse que reçoit un consommateur plutôt qu’à travers le Service.
Sur les deux providers, les provides: de la Recipe atteignent chaque consommateur via .context.uses et le contrat inject exactement comme ceux d’un composant provisionné. Le câblage d’un consommateur ne change donc pas lorsque sa cible passe de provisionnée à référencée : seule change la Recipe à laquelle le Manifest associe la cible.
Le pipeline d’exécution étape par étape
1. Domaine 1 (l’Aggregate) : l’intention du développeur Le développeur demande une base de données Oracle héritée. Peu lui importe où elle se trouve ; il indique seulement que son agent appelant attend que la chaîne de connexion lui soit fournie sous forme de variable d’environnement. Comme l’IP est statique et connue à l’avance, il la transmet via des paramètres.
components: legacy-oracle: type: core/legacy-database:1.0.0 values: host: "{{ .parameters.legacy_oracle_ip }}" sid: "PROD_DB"
my-agent: type: core/python-worker:1.0.0 values: {} uses: databases: legacy_db: target: legacy-oracle inject: env: - in: ORACLE_DSN # Local env var from: "primary_endpoint" # Target provides key2. Domaine 4 (le Manifest) : le routage Ops associe le type de base de données héritée à la Recipe qui formate sa chaîne de connexion. Le Manifest nomme une Recipe et rien de plus ; la Recipe qu’il nomme déclare un Workload de form: reference, et c’est cette forme qui empêche le nœud de provisionner des ressources de calcul. Le routage reste parfaitement plat et prévisible, car la map a exactement une forme, quelle que soit la cible.
spec: mappings: components: type: "core/legacy-database": "oracle-dsn-formatter:1.0.0"3. Domaine 3 (la Recipe de référence) : structurer le passage de relais L’ingénieur Ops écrit la Recipe. Elle construit la chaîne de connexion primary_endpoint à partir des values du développeur dans son bloc locals, la publie sous provides et déclare un Workload de référence pointant vers l’hôte de la base de données.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: oracle-dsn-formatter version: 1.0.0spec: capability: helm implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values locals: primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads provides: primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: reference endpoint: "{{ .values.host }}" port: 15214. Exécution par le compilateur au rendu (le passage de relais)
- Le compilateur évalue la Recipe de
legacy-oracle. Pour une Release qui fournitlegacy_oracle_ip: "10.0.4.55", sonprimary_endpointvautoracle://10.0.4.55:1521/PROD_DB. - Sur
helm, le Workload de référence rend un Service ExternalName,legacy-oracle, avecexternalName: 10.0.4.55et le port1521; surcompose, il ne rend rien. - Le compilateur rend ensuite la Recipe de
my-agent. Son canal.context.usesporte lesprovidesdu nœud Oracle, et le contrat d’injection a déjà résoluORACLE_DSNà partir d’eux.
5. Domaine 3 (la Recipe appelante) : remplir le contrat La recette Helm standard du worker Python lit la map d’injection qu’elle a reçue, exactement comme elle le ferait pour une base de données que la build provisionne.
# Inside python-worker-helm (The calling agent's recipe)env: # The compiler pre-resolved the target's provides into the inject map {{- range $key, $value := .context.inject.env }} - name: {{ $key }} # Renders: ORACLE_DSN value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB {{- end }}11. Acheminement entre piliers par schema-bridge : relier l’intention à l’infrastructure
Voir inheritance-and-interface pour le modèle schema-bridge qui expose en toute sécurité des réglages d’infrastructure spécialisés au travers de composants enfants — un champ values: destiné au développeur, déclaré dans le schema: du Component, que le template valuesMapping: de la Recipe achemine vers la sortie rendue de forme infra:.
12. Provisionnement greenfield (« Aggregates de plateforme »)
Un piège récurrent du platform engineering consiste à forcer le routeur (le fichier Release) à gérer le lourd provisionnement de clusters du jour 0 (par ex. créer un nouveau cluster AWS EKS avant d’y déployer l’application). Cela produit des fichiers de routage longs et difficiles à lire.
Aggrega traite ce problème grâce au principe « des tortues jusqu’en bas ». Le schéma de la Release ne comporte aucun bloc pour installer de l’infrastructure ; le provisionnement de clusters se modélise avec des Aggregates de plateforme.
Puisqu’un cluster AWS EKS, un plan de contrôle Istio et un VPC AWS ne sont en définitive que des ressources cloud physiques, ils sont modélisés exactement comme des composants applicatifs.
- L’Aggregate de plateforme : l’équipe Infrastructure écrit un
Aggregate.yamlstandard dont les composants sontcore/aws-vpc,core/eks-clusteretcore/istio-base. - La Release de plateforme : l’équipe déploie cet agrégat. Le moteur de rendu associé à ces composants de plateforme produit les artefacts nécessaires pour mettre en place l’infrastructure de base.
- La Release applicative : lorsque le développeur de l’application est prêt à déployer son agent d’IA, l’équipe Ops se contente de cibler le cluster nouvellement créé avec une frontière dans le propre fichier
Releasede l’application.