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

Aggregate

Le rôle conceptuel de l’entité Aggregate (Domaine 1 — le plan déclaratif de topologie du développeur) est décrit dans architecture/04-entity-taxonomy.md. Les modèles de composition (sous-systèmes, agrégats imbriqués, convention Zero-Port, Parameter Hoisting) sont décrits dans architecture/06-data-taxonomy-and-composition.md. Cette page couvre la surface de rédaction du catalogue pour l’Aggregate — plus précisément, la rédaction de modules Aggregate réutilisables destinés à être distribués par le catalogue.

Portée Component : le sous-système par défaut

Un Aggregate organise les composants en sous-systèmes — des regroupements nommés pour des préoccupations transversales (un niveau données, un niveau edge) qui portent leur propre cascade d’annotations. La plupart des Aggregates ont un seul regroupement, qui ne demande donc aucune cérémonie.

Portée unique (par défaut). Rédigez les composants directement sous spec.components: et omettez le bloc subsystems: :

spec:
components:
api:
type: core/server:1.0.0
worker:
type: core/worker:1.0.0

Le compilateur les regroupe dans un sous-système default synthétisé. L’identité des nœuds est inchangée — api reste api, jamais default.api — de sorte qu’un Aggregate rédigé ainsi est interchangeable avec la forme explicite à sous-système unique, et son adressage (dans les cibles uses:, dans les diagnostics) utilise le chemin simple spec.components.<name>. La portée synthétisée est consignée fidèlement dans l’IR exportée (avec un marqueur de sous-système synthétisé), mais n’apparaît jamais dans les chemins qu’un auteur écrit ou lit.

Portées multiples. Lorsque les composants se répartissent en groupes transversaux distincts, déclarez des sous-systèmes nommés sous subsystems:. Chaque sous-système porte ses propres composants et sa propre cascade d’annotations, et peut imbriquer d’autres sous-systèmes.

Exclusivité mutuelle. spec.components: et spec.subsystems: sont mutuellement exclusifs à la racine de l’Aggregate — rédigez l’un ou l’autre, jamais les deux. Un document qui déclare les deux s’arrête au chargement avec une erreur d’enveloppe. (Un sous-système qu’un développeur nomme explicitement default est un sous-système déclaré ordinaire, adressé par son chemin qualifié spec.subsystems.default.components.<name> — l’élision de la portée synthétisée dépend de la provenance, pas du nom.)

Modules Aggregate réutilisables

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 qu’à travers cette interface : une cible uses: est le nom du module, un point et l’un de ses alias exportés, et le compilateur relie l’arête au composant interne que nomme l’alias. Une cible qui pénètre dans un module par tout autre nom — le nom du composant à l’intérieur du module, ou un chemin vers un module imbriqué en son sein — arrête la build, en nommant le module et les alias qu’il exporte ; voir A uses target names a module’s component the module does not export (Une cible nomme un composant d’un module que le module n’exporte pas).

Pourquoi une liste exportedComponents: explicite. Les auteurs d’un module décident lesquels de ses composants forment l’interface publique et lesquels restent des détails d’implémentation. Comme un parent ne peut nommer que ce que la liste publie, l’intérieur du module peut être refactorisé — un composant renommé, un composant scindé en deux, un worker remplacé par un service géré — sans casser aucun parent, tant que chaque nom publié pointe toujours vers un composant. La liste coûte une entrée par composant publié, et un composant peut être publié sous son propre nom (store: store) lorsque c’est le nom que les importateurs doivent utiliser. La même règle vaut à l’intérieur d’une composition : un module atteint un module qu’il importe à travers les alias exportés de ce module. Une Release peut relier entre eux deux composants d’un même module, puisque cette connexion ne traverse l’interface d’aucun module.

Réexporter l’interface d’un module imbriqué. Une entrée exportedComponents: peut pointer vers l’alias exporté d’un sous-agrégat imbriqué plutôt que vers un composant déclaré directement — un module qui republie une partie d’un module qu’il importe, sous son propre nom d’interface et éventuellement sous un nouveau nom. Une arête uses: qui cible un tel alias réexporté se résout de manière transitive le long de la chaîne jusqu’au nœud interne concret, de sorte qu’un module compose des modules plus profonds dans sa propre interface publique sans exposer leur organisation interne, et qu’un consommateur n’a jamais besoin de savoir à quelle profondeur la cible est imbriquée. La discipline de l’interface stable vaut à chaque étape : chaque module ne réexporte que ce qu’il choisit de publier. Une cible réexportée qui ne se résout en aucun nœud interne arrête la build de manière explicite, tout comme une cible directe pendante, et une chaîne de réexportation qui se referme sur elle-même est rejetée au lieu d’être suivie indéfiniment.

Les déclarations d’un module sont vérifiées comme celles de l’Aggregate. Le document d’un module n’est lu que lorsque la composition qui l’importe est construite, et ses déclarations sont vérifiées à partir de ce moment, à toute profondeur d’imbrication. Le bloc inject: propre à un composant du module est soumis à la liste d’autorisation spec.inject de son type, ainsi qu’aux règles qui interdisent de revendiquer deux fois une même clé de livraison et de lire une clé que le type ne publie pas. Un rattachement écrit sur l’un des sous-systèmes propres du module ne peut nommer qu’un socket que sa Feature déclare, et il en va de même pour un rattachement que la Release écrit sur un composant apporté par un module.

Les rattachements aux sous-systèmes d’un module atteignent ses composants. Une Feature qu’un module rattache à l’un de ses propres sous-systèmes se propage en cascade sur chaque composant que le module déclare sous ce sous-système, sous-systèmes imbriqués compris, exactement comme le fait un rattachement de sous-système dans l’Aggregate — et sur ces composants seulement, jamais sur le composant d’un Aggregate importateur situé sous un sous-système du même nom. Elle est évaluée juste après les rattachements propres du composant, les sous-systèmes extérieurs avant les intérieurs. Sur un champ que les deux écrivent, le rattachement propre du composant portant le même nom l’emporte, et les champs qu’il omet conservent les valeurs du sous-système. Chaque composant qu’elle atteint la soumet à l’appliesTo de la Feature. Un constat portant sur les déclarations propres d’un module nomme le module et la clé dans son document — .spec.subsystems.<subsystem>.features.<attachment>, par exemple — de sorte que la modification se fait dans le module, là où se trouve la déclaration, plutôt que dans l’Aggregate qui l’importe.

Emplacement dans le catalogue

Un module Aggregate réutilisable se trouve sous le répertoire de type aggregate/, au chemin que son metadata.name énonce, segment par segment, avec un répertoire de version comme feuille :

aggrega-catalog/
└── aggregate/
└── {module-name}/ # the module's metadata.name, segment for segment
└── {version}/ # the module's metadata.version
└── aggregate.yaml # The module definition

Un nom de module peut porter un segment initial {publisher} désignant le fournisseur ou l’auteur — core pour la bibliothèque standard, acme pour une entreprise — et les modules publiés de la bibliothèque standard sont nommés ainsi : core/agenta se trouve à aggregate/core/agenta/1.0.0/aggregate.yaml. Un nom constitué d’un seul jeton se trouve un niveau moins profond, à aggregate/{module-name}/{version}/aggregate.yaml. Les deux formes sont bien formées ; le nom est ce que l’auteur écrit, et le répertoire le reflète. Ce reflet est une convention du catalogue et non quelque chose que vérifie le compilateur — un module est trouvé par le nom qu’il déclare, et non par l’emplacement de son fichier.

URI OCI : hub.aggrega.ai/aggregate/{module-name}:{version}, en minuscules — ainsi un module nommé core/agenta est publié vers hub.aggrega.ai/aggregate/core/agenta:1.0.0, et un module nommé db-module vers hub.aggrega.ai/aggregate/db-module:1.0.0.

Le modèle des modules

Module enfant (aggregate/child-database-module/1.0.0/aggregate.yaml, publié sous hub.aggrega.ai/aggregate/child-database-module:1.0.0) :

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"

Aggregate parent :

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
aggregates:
finance-db-subsystem:
type: child-database-module:1.0.0
components:
billing-api:
type: core/python-worker:1.0.0
uses:
databases:
- finance-db-subsystem.primary_db

Labels des modules

Lorsqu’un Aggregate est publié dans le catalogue comme module réutilisable, il peut porter des metadata.labels sur son enveloppe YAML — par exemple aggregate.aggrega.ai/tier: infrastructure ou aggregate.aggrega.ai/compliance: pci-dss. Ces labels décrivent l’identité du module et sont portés sur le document du module tel que publié ; aucune commande ne les lit encore. La recherche dans le catalogue n’indexe pas les Aggregates, et le graphe de build ne porte ni les labels d’un module ni son nom de catalogue, de sorte qu’une politique de gouvernance ne peut pas sélectionner les composants d’un module d’après le module dont ils proviennent.

La distinction essentielle. Les labels d’un Aggregate décrivent l’identité du module réutilisable dans le catalogue. Ils ne se propagent pas en cascade aux nœuds composants enfants. Les labels des composants proviennent exclusivement de l’entité de catalogue Component du Domaine 2. Si un développeur importe un module étiqueté aggregate.aggrega.ai/tier: infrastructure, les composants individuels de ce module ne conservent que leurs propres labels définis dans le catalogue (par ex. component.aggrega.ai/type: stateful-server). Le label de l’Aggregate n’est jamais injecté dans le dictionnaire labels du nœud IR.

Voir architecture/06-data-taxonomy-and-composition.md §6 pour la discussion complète sur les Aggregates composites / le modèle des modules (y compris la règle d’absence de sous-composants pour les Components), ainsi que pour le mécanisme de regroupement transversal subsystems. Voir vocabulary/data-pillars pour la surface de rédaction du contrat typé parameters.

Contrats de paramètres typés

Le bloc spec.parameters: de l’Aggregate déclare le contrat typé des paramètres que la Release renseigne. Chaque slot de paramètre porte un type déclaré, une description facultative, un default facultatif, des contraintes facultatives sur l’espace des valeurs et (pour les slots de type objet) une structure imbriquée. Le compilateur valide chaque valeur fournie par la Release par rapport au contrat pendant la résolution, avant l’exécution de l’interpolation des paramètres.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: web-app
version: 1.0.0
spec:
parameters:
region:
type: string
description: Cloud region the deployment targets
enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1]
default_locale:
type: string
description: Default UI locale presented to end users
enum: [en-US, en-GB, fr-FR, ja-JP]
default: en-US
enable_debug:
type: boolean
description: Toggle verbose request logging
default: false
feature_flags:
type: object
description: Per-feature enablement map
valuesType: { type: boolean }
default: {}
allowed_hosts:
type: array
description: Hostnames the ingress accepts
items: { type: string, format: hostname }
min: 1
default: ["web-app.example.com"]
components:
web:
type: core/web-server:1.0.0
values:
default_locale: "{{ .parameters.default_locale }}"
region: "{{ .parameters.region }}"
debug: {{ .parameters.enable_debug }}

Les guillemets sur chaque référence sont délibérés : ce sont eux qui déterminent le type avec lequel arrive la valeur remontée. Voir templates/parameters-context.md.

Vocabulaire des slots de paramètre

Le bloc typé parameters: accepte le vocabulaire de la forme compacte : type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate et validateMessage (une vérification personnalisée et le message qu’elle signale), items (pour les tableaux), properties (pour les objets), valuesType (pour les maps de valeurs typées) et required: true (marqueur par slot). Trois de ces mots-clés prennent comme valeur un contrat plutôt qu’un simple réglage — items, valuesType et chaque entrée sous properties — et, sur un slot de paramètre, ce contrat imbriqué s’écrit sous la même forme typée que le slot qui l’entoure : valuesType: { type: boolean }, et non valuesType: boolean. Avant l’interpolation, le compilateur vérifie directement la map de paramètres fusionnée par rapport à ces déclarations : un paramètre qu’aucun slot ne déclare est rejeté, un slot marqué required: true que ni la Release ne renseigne ni un default ne fournit arrête le build, et chaque valeur fournie est vérifiée par rapport au type déclaré de son slot, à l’appartenance à son enum, aux bornes minLength et maxLength, à l’expression régulière pattern et au format sur un slot de chaîne, ainsi qu’aux bornes min et max — la valeur d’un slot numérique, la longueur d’un slot de chaîne et le nombre d’éléments d’un slot de tableau. Les slots d’objet et de tableau sont récursifs : chaque entrée sous properties et chaque élément par rapport à items sont vérifiés de la même façon, un contrat valuesType régit les clés que properties ne nomme pas, et une clé imbriquée qu’aucune déclaration ne nomme est rejetée. Voir vocabulary/compact-form-authoring.md pour le vocabulaire complet des mots-clés, y compris les cas où un pilier schema: écrit ces mots-clés différemment.

Les mots-clés ci-dessous sont aussi vérifiés sur la déclaration elle-même, avant la lecture de toute valeur de la Release, de sorte qu’un slot qui ne pourrait rien contraindre arrête le build même quand aucune Release ne le fournit :

  • Les bornes de longueur sont supérieures ou égales à zéro. Un minLength ou un maxLength négatif sur la déclaration propre d’un paramètre est refusé par le schéma de l’Aggregate au chargement de l’Aggregate, avec le nom du paramètre et de la clé. Dans un contrat imbriqué — sous items, properties ou valuesType — une borne de longueur est lue telle qu’elle est écrite et n’est pas soumise à ce plancher au chargement de l’Aggregate ; écrivez-la donc là aussi avec une valeur supérieure ou égale à zéro : un minLength négatif n’impose rien, et un maxLength négatif refuse toute valeur.
  • min et max doivent borner quelque chose. Sur un slot booléen ou objet, la paire ne borne rien ; un min ou un max écrit à cet endroit est donc refusé au chargement de l’Aggregate, avec le nom du paramètre et de la clé.
  • Un pattern doit compiler. Chaque pattern est compilé comme expression régulière à la lecture du contrat de paramètres — sur le slot lui-même et dans tout contrat imbriqué, à n’importe quelle profondeur — et un pattern qui ne compile pas est refusé avec le nom du paramètre, le pattern et la raison. Le contrat est lu pour chaque build, chaque pull et chaque validation de Release qui atteint l’Aggregate, qu’il s’agisse de l’Aggregate propre de la Release ou d’un module que cet Aggregate importe. La vérification des valeurs compare ensuite chaque valeur fournie à cette même expression compilée.
  • Un format doit être l’un de ceux que le compilateur vérifie. format désigne l’un de email, uri, hostname, ipv4, ipv6, uuid, date-time et date, orthographiés comme JSON Schema les orthographie. Tout autre nom — une faute de frappe comme emial, ou un nom que JSON Schema ne définit pas, comme password — est refusé au chargement de l’Aggregate, avec le nom du paramètre et la liste des noms pris en charge : sur le slot lui-même par le schéma de l’Aggregate, et dans un contrat imbriqué, à n’importe quelle profondeur, à la lecture du contrat de paramètres. Une chaîne fournie qui n’a pas le format désigné est ensuite refusée avec le nom du paramètre, la valeur et le format. Ce que vérifie chaque nom est décrit dans vocabulary/compact-form-authoring.md.

Paramètres de type objet et de type tableau

Les slots de paramètre acceptent tout type que la forme compacte prend en charge, y compris les objets imbriqués et les tableaux d’éléments typés :

spec:
parameters:
database_config:
type: object
description: Database connection configuration
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full], default: require }
pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels:
type: array
description: Custom Prometheus labels to attach to scraped metrics
items:
type: object
properties:
name: { type: string, required: true }
value: { type: string, required: true }

La Release renseigne les paramètres de type objet avec du YAML structuré ; le compilateur valide la structure par rapport au schéma déclaré avant l’interpolation. Les templates qui font référence aux champs de l’objet utilisent la syntaxe standard des templates Go : {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }}, etc.

Validation du contrat de paramètres

Le contrat lui-même est vérifié en premier, à sa lecture — les vérifications des bornes de longueur et des patterns décrites plus haut sous « Vocabulaire des slots de paramètre ». Le compilateur exécute ensuite trois sous-étapes pendant le traitement des paramètres :

  1. Remplissage des valeurs par défaut — les slots qui définissent un default: et pour lesquels la Release ne fournit aucune valeur reçoivent leur valeur par défaut. Les paramètres à objet imbriqué suivent une sémantique d’écriture à trois cas pour les slots parents omis, explicitement vides et partiellement écrits : omettre le parent remplit les valeurs par défaut des enfants, écrire le parent sous la forme {} préserve le vide explicite (supprime les valeurs par défaut des enfants), et écrire le parent sous la forme d’une map non vide ne remplit que les enfants que la Release n’a pas fournis. Voir templates/parameters-context.md pour les exemples YAML et le guide de décision « quand utiliser chaque forme ».
  2. Validation du contrat — chaque valeur de la map fusionnée, qu’elle ait été fournie par la Release ou remplie par un default:, est validée par rapport aux contraintes déclarées type / enum / min / max / pattern / structure imbriquée. Les échecs de validation arrêtent le build avec une erreur claire qui nomme le slot fautif, la valeur fournie et la contrainte violée. Les paramètres obligatoires manquants sans default: produisent un arrêt similaire avec le nom du slot.
  3. Interpolation — le compilateur évalue tout le texte de l’Aggregate comme un template, avant de le lire comme YAML, et remplace chaque référence {{ .parameters.<slot> }} — en général dans des chaînes values: de composants / fonctionnalités / sous-agrégats — par la valeur résolue ; tout autre {{ dans le texte est lui aussi lu comme syntaxe de template, de sorte qu’une valeur portant ses propres doubles accolades — la définition exportée d’une plateforme de flux, par exemple — écrit chaque {{ sous la forme {{"{{"}}, comme le décrit Texte qui porte ses propres doubles accolades. Après cette passe, les surfaces de templates de valeurs consomment des littéraux déjà interpolés et ne reçoivent pas .parameters dans leur contexte de template.

La map de paramètres fusionnée reste active pendant le rendu afin de prendre en charge l’évaluation des templates de chemin. Les templates directory: et subDirectory: écrits par l’opérateur sur les frontières de la Release lisent .parameters.<slot> directement au moment du rendu, par rapport à une liste fermée de valeurs autorisées ; l’émission des chemins a besoin d’un vocabulaire de région / d’environnement pour la disposition des artefacts par environnement, et l’autorisation asymétrique garde cette préoccupation de l’opérateur à l’intérieur de la surface de l’opérateur, sans passer par les values de l’Aggregate. La map reste lisible jusqu’à la fin de toutes les phases de rendu et n’est accessible que depuis la compilation pour laquelle elle a été résolue ; les recettes qui consomment des values: écrites par le développeur voient les chaînes post-interpolation, tandis que les templates de chemin voient des données .parameters actives pendant le rendu. Voir templates/expansion-matrix.md ligne 3 pour la matrice de disponibilité des templates de chemin et path-template-variables.md pour la liste des variables autorisées dans les templates de chemin.

Pour la liste de contrôle plus large du parameter hoisting (déclaration dans l’Aggregate → référence dans les values → renseignement dans la Release → consommation dans la Recipe) et pour la mécanique transversale aux piliers, voir vocabulary/data-pillars.md §« Paramètres » et §« La liste de contrôle du parameter hoisting ». Pour les champs du contexte de template exposés pendant l’interpolation et l’exception des templates de chemin, voir templates/parameters-context.md.

Une arête uses est un appel que l’Aggregate déclare

Une arête uses est l’énoncé, par l’Aggregate, qu’un composant en appelle un autre. Le compilateur achemine vers l’appelant les valeurs que la cible publie et ne restreint rien : à elle seule, une arête n’admet pas l’appelant et ne refuse personne d’autre, et une charge de travail qui atteint l’adresse de la cible sans arête l’atteint tout de même.

Restreindre qui peut appeler un composant, et ce qu’il peut appeler, est la décision de l’opérateur, prise par environnement dans la Release. Lorsqu’une Release rattache à un composant la Feature core/caller-allowlist du catalogue de la bibliothèque standard, le build écrit une network policy qui admet exactement les composants dont les arêtes uses pointent vers lui, les pods propres de ce composant et les sources que le rattachement nomme. Son pendant sortant, core/egress-allowlist, ne laisse le composant auquel elle est rattachée atteindre que les composants vers lesquels pointent ses propres arêtes uses, ses propres pods, le DNS du cluster et les plages d’adresses que la Release énumère. Un appel que l’Aggregate ne déclare pas comme arête peut alors être refusé par le cluster à l’une ou l’autre extrémité, partout où son plugin réseau applique les network policies. Écrivez donc une arête pour chaque appel que vos composants effectuent, y compris un appel qui n’injecte aucune valeur : une arête manquante est un appel qu’un composant cloisonné peut refuser. model-server-caller-allowlist montre un serveur de modèle joignable uniquement par la passerelle placée devant lui.

Les rattachements propres d’une connexion : features sur une entrée uses

Une connexion qu’un composant établit dans sa forme détaillée uses: est une entrée à part entière, et, à côté de target, inject et values, elle peut porter des rattachements, sous features:. Chacun est indexé par un slot que le socket déclare : le Component consommateur énumère, dans le featuresSchema du socket, les slots que chaque connexion câblée par ce socket peut remplir (voir Sockets de topologie). C’est ainsi qu’un composant détient un identifiant différent pour chaque composant qu’il atteint — une passerelle qui appelle deux modèles avec deux clés, ou un agent qui présente sa propre clé à un modèle.

spec:
parameters:
openai_key_secret: { type: string }
components:
router:
type: core/gateway/litellm # its `models` socket declares a `credential` slot
values: { model: gpt } # the alias it publishes as its model
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
values:
origin: "{{ .parameters.openai_key_secret }}"
key: api-key
plain:
target: plain # this connection carries no attachment
gpt:
type: core/ai-model/openai
values: { model: gpt-4o-mini }
plain:
type: core/ai-model/ollama
values: { model: llama3.1 }

Un rattachement sur une connexion porte type (obligatoire), une description facultative et des values pour la Feature. Il ne porte ni uses ni inject : un rattachement sur une connexion ne s’imbrique pas, et la façon dont son contenu atteint le consommateur relève de la Recipe du composant consommateur plutôt que d’un bloc inject. Un document qui écrit l’une ou l’autre de ces clés est refusé à son chargement, avec le nom de la clé.

Seulement les slots que le socket déclare. Un rattachement sous un nom que le featuresSchema du socket ne liste pas arrête le build au chargement, en nommant la connexion, le socket, le composant et les slots que le socket déclare — et, lorsque le nom est à une modification de l’un d’eux, ce slot, comme orthographe probablement voulue. Un slot rempli est ensuite soumis à la déclaration propre du slot sur chaque connexion : un selector que les labels de la Feature ne satisfont pas arrête le build à cette entrée, et un slot required laissé vide sur une connexion quelconque l’arrête en nommant cette connexion. Un socket qui ne déclare aucun slot n’admet aucun rattachement sur ses connexions, pas plus qu’un socket ad hoc — un socket que l’Aggregate câble sans que le Component le déclare —, puisqu’il ne déclare aucun slot. Un composant qu’apporte un sous-module est soumis à la même règle, et le constat pointe vers le document propre du sous-module. Voir A connection carries an attachment under a name its socket declares no slot for (Une connexion porte un rattachement sous un nom pour lequel son socket ne déclare aucun slot).

Une connexion établie par une Feature n’en porte aucun. Le bloc uses: propre d’une Feature rattachée — sur un composant ou sur un sous-système — s’écrit sous la même forme mais refuse features: au chargement du document. Un identifiant dont une telle connexion a besoin remplit un slot que la Feature déclare dans son propre featuresSchema, rattaché à côté de la Feature ; voir L’identifiant propre d’une Feature.

Le nom que prend le rattachement. Chaque rattachement de connexion devient un rattachement du composant consommateur, nommé <alias>.<slot> — l’alias sous lequel la connexion est écrite, un point et le slot : gpt.credential ci-dessus. Le point est le séparateur réservé aux noms que le compilateur compose, qu’aucun alias, slot ou nom de rattachement d’un Aggregate ne peut contenir, de sorte que le nom composé n’est jamais égal à un nom écrit dans le bloc features: propre du composant ; une Release qui l’écrit sur un composant ou une frontière est refusée (voir Configuration des connexions par arête). C’est le nom sous lequel le niveau par instance du Manifest indexe le rattachement (voir Mappage d’URI plat), le nom sous lequel les diagnostics et le graphe IR le signalent, et la valeur que la FeatureRecipe du rattachement lit sous .attachment_name (voir Noms dérivés du rattachement d’une connexion).

À partir de là, il se résout comme tout rattachement : le Manifest lie son type de Feature à une FeatureRecipe, ses values sont validées par rapport au schéma de la Feature — un échec est signalé à l’entrée de connexion qui les a écrites — et sa FeatureRecipe effectue le rendu à partir des values et de l’infra propres au rattachement. Deux choses le distinguent des rattachements propres du composant :

  • Il ne figure pas dans .features de la Recipe consommatrice. Ce pilier ne porte que les rattachements écrits dans le bloc propre du composant, de sorte qu’une Recipe qui parcourt .features à la recherche de ses propres rattachements par type ne reçoit jamais l’identifiant d’une connexion. Une Recipe lit le rattachement d’une connexion depuis la connexion elle-même, sous .context.uses.<alias>.features.<slot>, dans la forme que porte .features — ses provides résolus compris (voir Les rattachements d’une connexion).
  • Il n’aboutit qu’au consommateur. La sortie rendue d’une cible est la même, quoi que portent les connexions qui l’atteignent.

La copie du bloc écrit dans le graphe. Le graphe IR conserve le bloc uses: de chaque composant tel qu’il a été écrit, et un rattachement de connexion y garde son type et sa description et aucune de ses values. Les valeurs apparaissent une seule fois, sur le rattachement que porte le consommateur, où une valeur que la Feature déclare sensible est masquée.

Une Release peut dimensionner avec infra un rattachement déclaré ici, ou en rattacher un qui lui est propre sur une connexion qu’elle atteint — voir Configuration des connexions par arête.

Désactiver un composant ou un module : active:

Une instance de composant et un module sous-agrégat acceptent chacun une bascule active: qui décide si cette entité fait partie ou non de la topologie compilée. Si vous l’omettez, l’entité est présente ; c’est le comportement par défaut et le cas ordinaire.

spec:
parameters:
enable_cache:
type: boolean
default: false
components:
api:
type: core/server:1.0.0
redis:
type: core/redis:1.0.0
active: "{{ .parameters.enable_cache }}"
aggregates:
reporting:
type: my-catalog/reporting-module:1.0.0
active: false

Écrivez directement un booléen, ou un template sur .parameters qui se résout en booléen. La forme template est la raison d’être de la bascule : elle permet à une Release de décider de la présence d’une entité en renseignant un paramètre, de sorte qu’un seul Aggregate couvre des environnements qui diffèrent par les éléments qu’ils déploient — sans que la Release déclare quoi que ce soit que l’Aggregate n’a pas déclaré.

Ce qu’une bascule à faux supprime. L’entité est élaguée avant la construction du graphe, et l’élagage se propage en cascade : un composant emporte ses propres arêtes uses: et ses Features rattachées, et un module emporte tout ce qu’il a apporté — ses composants, leurs arêtes, leurs rattachements. Rien de ce que l’entité élaguée a apporté n’est rendu. Ce que l’élagage n’atteint pas, c’est une référence à cette entité depuis un endroit qui a survécu, objet du paragraphe suivant.

Un composant restant qui pointe encore vers un composant élagué arrête le build. Si api déclare une arête uses: vers redis et que redis est désactivé, le build s’arrête plutôt que de laisser disparaître l’arête, ce qui laisserait les valeurs injectées de api silencieusement vides au moment du déploiement. Décidez lequel des deux a sa place dans cet environnement : réactivez la cible, conditionnez le consommateur au même paramètre pour que la paire parte ensemble, ou retirez l’arête du bloc uses: du consommateur.

Une bascule écrite doit se résoudre en booléen, et une valeur vide n’en est pas un. La bascule est lue strictement une fois son template résolu, et un littéral qui ne s’analyse pas comme booléen arrête le build au lieu de prendre une valeur par défaut. Le cas à surveiller est une bascule qui lit un paramètre sans valeur : elle se résout en rien, et lire ce rien comme « présent » déploierait précisément l’entité que vous avez conditionnée à ce paramètre. Écrire active: sans rien derrière n’est donc pas la même chose qu’omettre la clé — seule une bascule que personne n’a écrite vaut « présent » par défaut. Donnez au paramètre un default: dans spec.parameters pour que chaque environnement ait une réponse, ou renseignez-le dans la Release. Pour rendre une entité présente sans condition, supprimez la clé active: plutôt que de la vider. L’arrêt est décrit sous « An active: toggle does not resolve to true or false (Une bascule ne se résout ni en true ni en false) » dans la référence des conditions d’arrêt.

Un composant désactivé reste nommable depuis une Release. Une Release peut encore le nommer dans une frontière, et c’est délibéré : désactiver un composant est un acte d’écriture, et l’on n’attend pas de la Release qui le configure qu’elle soit réécrite dans la même modification.

Annotations sur les sous-systèmes et les composants

Les sous-systèmes et les instances de composant portent tous deux un champ annotations:. Les annotations rédigées par le développeur sur la surface de l’Aggregate pilotent la cascade d’annotations côté Aggregate — une annotation de sous-système se propage à chaque sous-système imbriqué et à chaque composant contenu, les niveaux les plus proches prenant le dessus clé par clé. La map mappings.features.annotations du Manifest déclare les bindings qui traduisent les clés d’annotation en rattachements synthétiques de Feature au moment du build. L’invariant de l’Aggregate comme surface de rédaction restreint ces annotations à un routage par les chemins maps.values du binding ; un binding qui ne déclare que des chemins maps.infra se déclenche du côté de la Release, et non du côté de l’Aggregate.

Formes des valeurs

Chaque clé d’annotation prend l’une de quatre formes, distinguant « je me tais » de « je déclare une valeur » — un scalaire ou un objet structuré — et de « je me retire » :

  • Clé absente — la portée ne déclare aucune valeur pour cette annotation. Les sous-systèmes imbriqués et les composants contenus héritent de tout binding d’une portée ancêtre.
  • Une chaîne scalaire — une valeur unique. Le binding du Manifest doit déclarer exactement un chemin au total ; le scalaire est routé vers ce chemin.
  • Un objet structuré — une map de sous-clé vers sous-valeur. Chaque sous-clé de l’objet est routée, via les maps du binding du Manifest, vers le champ correspondant du schéma de la Feature dans le pilier déclaré.
  • null YAML explicite — la portée retire de son sous-arbre tout binding hérité pour cette clé. Les composants et sous-systèmes frères conservent leur héritage ; seule la portée qui se retire perd le binding.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker
components:
api:
type: core/server:1.0.0
# inherits feature.myco/db-pool: "shared-pool"
worker:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Valeurs structurées pour les Features à plusieurs champs

Une Feature dotée de plusieurs champs configurables se prête à une valeur d’annotation structurée : une seule clé d’annotation portant des valeurs pour plusieurs champs du schéma de la Feature en une seule déclaration. Le côté Aggregate ne déclenche que les sous-clés dont le pilier dans la map du binding est values ; les sous-clés routées vers infra relèvent des annotations côté Release.

spec:
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
components:
api:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
db_name: "api-override" # closer-level override at subkey granularity
# read_replicas not listed → inherits 5 from parent
analytics:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out

Les valeurs structurées se propagent en cascade avec une fusion profonde par sous-clé : les sous-clés des niveaux les plus proches remplacent celles du parent ; un null explicite sur une sous-clé supprime la sous-clé héritée pour cette portée, tandis que les sous-clés sœurs demeurent. Pour l’exposé complet sur les valeurs structurées — composition entre les deux côtés avec les sous-clés infra côté Release, validation de type par sous-clé, la discipline de valeur par défaut assouplie pour les champs de schéma sans type déclaré — voir providers/well-known-annotations.md §« Valeurs d’annotation structurées ».

Indépendance par clé

Chaque clé d’annotation hérite, remplace et se retire de façon indépendante. Un composant qui déclare annotations.feature.myco/db-pool: null se retire uniquement de cette clé ; les autres clés héritées du sous-système englobant continuent de se propager à ce composant. Les composants frères d’un même sous-système conservent indépendamment leurs propres maps d’annotations — le retrait d’un composant n’affecte pas ses frères.

Annotations des composants de premier niveau

Les composants de premier niveau (déclarés directement sous spec.components plutôt qu’à l’intérieur d’un sous-système) ne portent aucune cascade héritée. Leur champ annotations: déclare les valeurs directement sur la portée du composant ; l’expansion synthétise des rattachements de Feature à partir de chaque annotation déclarée pour laquelle le Manifest porte un binding correspondant.

Pour la règle de cascade côté Aggregate appliquée aux bindings, la répartition entre côté et pilier, et un exemple complet montrant les bindings qui traduisent les annotations en rattachements synthétiques de Feature, voir providers/well-known-annotations.md §« Cascade d’annotations côté Aggregate ».

Motifs d’ancres YAML (bloc defs:)

Le schéma de l’Aggregate accepte un bloc defs: facultatif au niveau racine — une liste de chaînes YAML utilisée uniquement comme support pour les ancres YAML standard (&anchor) et les références (*anchor). Le contenu du bloc n’est jamais lu par le compilateur ; il existe pour que les auteurs puissent déclarer les définitions d’ancres en un seul endroit et y faire référence dans le reste de l’Aggregate, en gardant les valeurs répétées DRY sans perdre le dictionnaire plat en O(1) que le compilateur parcourt. Le mécanisme reprend le bloc defs: équivalent de l’entité Manifest.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: anchored-app
version: 1.0.0
defs:
- &default_log_level "info"
spec:
components:
primary:
type: core/compute/api-server:1.0.0
values:
log_level: *default_log_level
secondary:
type: core/compute/python:1.0.0
values:
log_level: *default_log_level

Les ancres sont résolues au moment de l’analyse YAML, de sorte que *default_log_level est la chaîne "info" au moment où le compilateur lit le bloc des valeurs. Le bloc defs: est l’emplacement conventionnel des définitions d’ancres ; YAML permet de déclarer des ancres n’importe où, mais les regrouper garde le reste de l’Aggregate lisible. Le bloc est facultatif — les Aggregates qui n’ont pas besoin d’ancres l’omettent entièrement.