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

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 la Release (CI/CD) en ligne sous parameters: ou via parameters: { $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 ligne parameters:. La superposition de plusieurs fichiers s’exprime par des chaînes extends: de Release.
  • values (l’intention cognitive - appartient au développeur)
    • Portée : utilisées de manière uniforme dans les components et leurs rattachements features au 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).
  • uses (la topologie structurelle - état déclaratif)
    • Portée : utilisées de manière uniforme dans les components et leurs rattachements features au 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 usesSchema unifiée du catalogue pour imposer la sûreté des types entre nœuds.
  • infra (la réalité physique - appartient à Ops)
    • Portée : utilisé de manière uniforme dans les components d’une frontière et leurs rattachements features au sein de la Release.
    • 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 rattachements features ne comportent pas de champ infra et, combinées à additionalProperties: false, rejettent infra lors de la validation du schéma. Validé par la déclaration schema: unifiée du catalogue.
  • 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 uses et sur les features rattaché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, arg ou 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 avec in: et portant exactement l’un de from: ou value:.
  • .context (le pipe de métadonnées générique)
    • Portée : injecté silencieusement par le compilateur dans les templates de la Recipe Ops.
    • 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.

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éma values: en aval.
    • Usage recommandé : les parameters sont 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 bloc infra de la Release et les overlays de frontière, ce qui garde l’Aggregate du 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 parameters peuvent 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.
  • Flux 2 : l’intention applicative cognitive (values dans les Components) : définit la logique intrinsèque de l’application. La déclaration schema: 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 (values dans 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 de values du développeur : les opérations la rattachent dans la Release, avec son infra (flux 4).
  • Flux 4 : le dimensionnement de l’infrastructure physique (infra) : en contournant entièrement le développeur, le dimensionnement physique infra est projeté explicitement depuis la Release propre à 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 dimensionnement infra est 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 champs infra locaux 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 payloads values du 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 port dans la déclaration schema:. 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éclaration schema: 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 versa

Comportement 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, | quote et | 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 de subsystems. Les sous-systèmes agissent comme des dossiers récursifs sur le plan logique/de l’intention, propageant les annotations vers le bas dans le compartiment .context.annotations.aggregate et 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 de type, 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.
aggregate.yaml
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 contrat exportedComponents:, qui établit un nom d’interface publique stable. Le parent n’atteint les composants du module que par cette interface : une cible uses: 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.
child-database-module.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
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"
parent-app.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
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/type nomme 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èle spec.aggregates + exportedComponents pré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, sans subsystems. Le compilateur les replie dans un sous-système default synthé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, sans boundaries. Le compilateur les replie dans une frontière default synthétisée dont la sortie est plate — les artefacts arrivent directement sous dist/ (par provider : dist/compose/, dist/helm/, …), sans segment portant le nom de la frontière. C’est le cas le plus simple : aggrega build sur une cible Compose plate ou à cluster unique, sans nommer de frontières. (Une frontière qu’un développeur déclare et nomme default est une frontière nommée ordinaire et, sans directory: qui lui soit propre, émet vers dist/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 subsystems explicites, ou Ops introduit des boundaries explicites. 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.

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 bloc values, 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_workers comme 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éma values: englobant. Cela préserve la réutilisabilité de l’Aggregate : Ops fournit l’entier via les parameters: de la Release, le compilateur le valide par rapport à la déclaration typée parameters:, substitue la valeur résolue dans le document, et la déclaration schema: du Component valide avec succès l’entier obtenu.
  • 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 un type de Feature d’identifiant (un type étiqueté feature.aggrega.ai/kind: secret) et en utilisant les values propres à 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 de values et transporte tel quel un littéral en ligne. C’est la surface d’attachement qui rend la forme bien écrite disponible et typée.
  • Contrainte 2 : Components agnostiques vis-à-vis des capacités

    • Modèle non pris en charge : l’architecte écrit aws_instance_type: string dans la déclaration schema: 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 .context génériques, et non dans la logique applicative cognitive de base.
  • Contrainte 3 : logique conditionnelle sur les métadonnées

    • Modèle non pris en charge : Ops écrit {{ if eq .context.labels.gpu "true" }} dans une Recipe pour changer fondamentalement la stratégie de déploiement.
    • Pourquoi : le canal .context contourne la validation schema: de chaque pilier. S’appuyer sur des étiquettes non validées pour la logique d’infrastructure de base rend la plateforme fragile. L’objet .context transporte un étiquetage de métadonnées (par ex. facturation, SOC2) ; le routage structurel relève des piliers validés par schéma.
  • 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: 4 en workers: 10) depuis la Release.
    • Pourquoi : l’Aggregate est 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 la Release l’impose en interdisant les blocs values, limitant Ops à remplir le contrat parameters et à définir l’infra physique.
  • 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’imbriquer infra et des surcharges de fonctionnalités par composant sans mêler la paternité des étiquettes à l’Aggregate du développeur.

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 tableau parameters.approved_egress de 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 sur helm une NetworkPolicy Kubernetes par workload que ce composant rend, n’autorisant l’egress que vers ses propres pods, vers les pods des cibles de ses arêtes uses sur 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, avec infra.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 ; sur compose, 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-external dans 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 key

2. 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/v1beta1
kind: Recipe
metadata:
name: oracle-dsn-formatter
version: 1.0.0
spec:
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: 1521

4. Exécution par le compilateur au rendu (le passage de relais)

  1. Le compilateur évalue la Recipe de legacy-oracle. Pour une Release qui fournit legacy_oracle_ip: "10.0.4.55", son primary_endpoint vaut oracle://10.0.4.55:1521/PROD_DB.
  2. Sur helm, le Workload de référence rend un Service ExternalName, legacy-oracle, avec externalName: 10.0.4.55 et le port 1521 ; sur compose, il ne rend rien.
  3. Le compilateur rend ensuite la Recipe de my-agent. Son canal .context.uses porte les provides du nœud Oracle, et le contrat d’injection a déjà résolu ORACLE_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.

  1. L’Aggregate de plateforme : l’équipe Infrastructure écrit un Aggregate.yaml standard dont les composants sont core/aws-vpc, core/eks-cluster et core/istio-base.
  2. 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.
  3. 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 Release de l’application.