Release
Le rôle conceptuel de l’entité Release (Domaine 4 — le routeur de déploiement qui lie un Aggregate à un Manifest et répartit les composants dans des frontières physiques) est décrit dans architecture/04-entity-taxonomy.md. Le mécanisme de séquencement temporel (syncWave par frontière), le Dynamic Addressing Polyfill et le patron Parameter Hoisting sont décrits dans architecture/12-day-two-lifecycles.md. Cette page couvre la surface de rédaction de la Release.
Le rôle de la Release
La Release lie un aggregate à un manifest et répartit les composants dans des frontières physiques de déploiement (par ex. aws-eks-production). C’est le point d’entrée unique de la compilation : aggrega build --release release.yaml.
La Release remplit le contrat abstrait de l’agrégat en injectant les réalités physiques strictement dans le bloc parameters, et injecte le dimensionnement physique (comme les CPU ou les ports) via l’espace de noms parallèle infra.
Chaque Release déclare un champ manifest: qui nomme son Manifest (sauf si la Release utilise extends:, qui hérite du pointeur de manifeste du parent). La CLI aggrega build lit directement ce champ ; aucune option CLI --manifest n’existe, de sorte que la spécification des dépendances reste commitée dans Git à côté de la Release elle-même, ce qui rend l’historique des déploiements auditable via l’historique Git propre à la Release.
Les champs aggregate: et manifest: sont résolus par identité ou par fichier à chemin relatif, de la même manière que le reste du langage résout les références — jamais comme un radical de nom de fichier relatif à la Release. Une valeur ./ ou ../ est un fichier local explicite, lu directement relativement à la Release. Un jeton nu est une identité — le metadata.name de l’entité référencée. Une identité manifest: est résolue en parcourant le répertoire propre à la Release (un Manifest est une configuration d’opérateur côté déploiement, il n’a donc pas de niveau catalogue ni registre). Une identité aggregate: se résout à travers la cascade complète — le répertoire de la Release, puis le catalogue, puis le registre — de sorte qu’une Release peut nommer un Aggregate publié par son identité et que le même module publié se résout, qu’il soit le spec.aggregate de premier niveau d’une Release ou un sous-agrégat au sein d’un autre Aggregate. Ce modèle identité-ou-chemin permet à un Aggregate partagé de servir de base à de nombreuses variantes de Release sans coupler la référence à un nom de fichier, et à un Aggregate publié d’être déployé directement par son nom.
Un chemin reste à l’intérieur de l’espace de travail. Une valeur ./ ou ../ désigne un fichier que contient l’espace de travail, et il en va de même de tout autre chemin qu’écrit une Release — son extends: et un $import: de paramètres, ci-dessous. Un chemin qui sort de l’espace de travail tel qu’il est écrit, ou qu’un lien symbolique sur le trajet en fait sortir, est refusé avant que quoi que ce soit ne soit lu dans le fichier qu’il désigne. Pour déployer un Aggregate conservé hors de l’espace de travail, nommez-le par son identité et indiquez le répertoire qui le contient comme répertoire de catalogue dans la configuration de l’espace de travail ; un Manifest, une Release que nomme un extends: et un fichier de paramètres sont lus à côté de la Release et jamais recherchés par nom, ils sont donc conservés dans l’espace de travail. Une Release que vous nommez sur la ligne de commande, ou que la configuration de l’espace de travail nomme, hors de l’espace de travail est une racine à part entière : chaque chemin qu’elle écrit — et chaque chemin qu’écrit une Release à laquelle mène sa chaîne extends: — doit mener à un fichier situé dans le répertoire qui contient cette Release, et un chemin qui sort de ce répertoire, ou qu’un lien en fait sortir, est refusé de la même manière. Conservez ce qu’une telle Release nomme à côté d’elle, ou construisez-la dans l’espace de travail qui contient les deux. Voir errors/fatal-halts.md §« A reference to another file leads out of the directory it must stay inside (Une référence à un autre fichier sort du répertoire à l’intérieur duquel elle doit rester) ».
La Release fixe la destination des artefacts compilés ; l’aiguillage vers les fournisseurs relève du Manifest vers lequel pointe la Release (voir Manifest et Release : séparation des responsabilités pour la répartition des rôles).
Métadonnées d’environnement
Chaque bloc de métadonnées d’une Release accepte un champ environment: — une chaîne libre identifiant l’environnement dans lequel la Release est déployée (valeurs typiques : production, staging, dev). Le champ est informatif : il ne porte aucune énumération, aucun motif au niveau du schéma et aucune validation inter-entités au-delà de type: string. Le compilateur émet sa valeur sous forme de label aggrega.ai/environment sur chaque manifeste Kubernetes que rend le fournisseur helm, aux côtés du reste de la suite de labels de provenance d’Aggrega — telle qu’elle est écrite lorsqu’il s’agit d’une valeur de label Kubernetes valide, et sinon réécrite en une valeur valide, la valeur exacte étant portée par l’annotation aggrega.ai/environment (ainsi eu/prod reçoit le label eu-prod) ; le fournisseur helm-chart ajoute les mêmes labels à chaque artefact chargé via $import: qu’il place dans un sous-chart, tandis que les templates propres du sous-chart portent ce que leur auteur a écrit. Le fournisseur compose porte la même valeur sous forme de label aggrega.ai/environment sur chaque service qu’il émet.
Cinq usages pratiques guident la rédaction de environment: :
-
Attribution des coûts OTel/FinOps. Les tableaux de bord de coûts cloud (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) filtrent les pods Kubernetes par environnement au moyen de tags. Le label
aggrega.ai/environment: productionest propagé dans les labels des pods via l’injection de labels du fournisseur Helm ; les rapports de coûts regroupent les dépenses paraggrega.ai/environmentsans tagging manuel ressource par ressource. -
Filtrage des traces et des logs OTel. Les tableaux de bord d’observabilité (Datadog, New Relic, Honeycomb, Grafana Tempo) filtrent la télémétrie par label d’environnement.
aggrega.ai/environment: stagingpermet aux opérateurs de limiter les requêtes de logs et les recherches de traces au staging sans filtrer sur des conventions de namespace ou des noms de charts — un label canonique unique sur toute la surface rendue. -
Ciblage par les opérateurs Kubernetes. Les contrôleurs GitOps (ArgoCD, Flux) et les opérateurs de politiques (Kyverno, OPA Gatekeeper) filtrent parfois les ressources par label d’environnement pour des politiques propres à un environnement (par exemple, « les ressources réservées à la production exigent un label approved-image-source »). Le label
aggrega.ai/environmentfournit un sélecteur stable, distinct des conventions de namespace ou des schémas de nommage. -
Différenciation de la production multirégion. Une équipe qui exécute une Release
production-us-eastà côté d’une Releaseproduction-eu-west— toutes deux avecmetadata.environment: production— obtient le même labelaggrega.ai/environment: productiondans toutes les régions. Combiné à un label de région distinct, cela permet le regroupement des coûts entre régions (« dépenses totales de production ») et l’analyse détaillée par région. -
Délimitation de la conformité. La collecte de preuves SOC 2, PCI et HIPAA se délimite par environnement (audit de la production uniquement, etc.). Le label
aggrega.ai/environmentest exploité par les outils de collecte de preuves de conformité (Vanta, Drata) pour filtrer les ressources selon le périmètre d’audit.
Le schéma exige environment: sur chaque Release ; la valeur est informative, et le compilateur ne la lit que pour écrire le label aggrega.ai/environment.
Contraintes au niveau du schéma
Deux garanties structurelles protègent l’Aggregate en tant que source unique de vérité :
values:est interdit. Pour protéger l’Aggregate en tant que source unique de vérité, le schéma de la Release interdit mécaniquement un blocvalues:— l’opérateur ne peut déclarer devaluessur aucun Component ni aucune Feature depuis une Release. L’interdiction s’étend aux arêtesuses: une entréeusespar arête d’une Release porteinfraet les rattachements qu’elle écrit sur la connexion, et ceux-ci portent aussiinfra— jamaisvalues(les valeurs par arête destinées au développeur, et les valeurs d’un rattachement sur une connexion, restent dans l’Aggregate). La variation par environnement des valeurs destinées au développeur passe par le Parameter Hoisting : le développeur expose un champ typéparameters.*dans l’Aggregate, le templatevaluesdu Component y fait référence et la Release renseigne le paramètre pour son environnement. Voir architecture/06-data-taxonomy-and-composition.md §8 Contrainte 4 pour l’interdiction au niveau du schéma énoncée explicitement. La surface d’arêtesusesde la Release — ce qu’elle peut configurer et câbler — est documentée dans Configuration de connexion par arête ci-dessous.extends+aggregate:est rejeté. Pour empêcher des Releases intraçables qui « modifient l’aggregate », lorsqu’une Release utiliseextends, la déclaration d’un pointeuraggregateest rejetée par le schéma de la Release. La release enfant doit correspondre exactement à la même intention du développeur que sa release parente. Lemanifest, en revanche, devient facultatif, ce qui débloque la « liaison tardive » — l’opérateur peut hériter de toute la topologie physique tout en remplaçant de façon chirurgicale le Manifest.
Le bloc parameters:
Une Release remplit le contrat de paramètres typé que l’Aggregate déclare. spec.parameters: est la surface de rédaction — un mappage YAML dont les clés correspondent aux déclarations parameters.* de l’Aggregate et dont les valeurs fournissent ce que chaque environnement renseigne.
# Aggregate declares the typed contractapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: my-app version: 1.0.0spec: parameters: db_size: { type: string, required: true } timeout_seconds: { type: integer, default: 30 } region: { type: string, enum: [us-east-1, eu-west-1], required: true }# Release fulfills the contract for this environmentapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: my-app manifest: prod-manifest parameters: db_size: "100Gi" timeout_seconds: 60 region: "us-east-1"Chaque valeur passe la vérification du schéma déclaré par l’Aggregate au niveau du contrat de paramètres, et le build s’arrête lorsqu’une Release omet un paramètre obligatoire (E0165, parameter-missing) ou fournit une valeur que le contrat de son slot refuse (E0164, parameter-contract-violation). Les paramètres déclarés avec un default: reçoivent la valeur par défaut lorsque la Release omet le slot ; le contrat typé est le seul vocabulaire de rédaction.
Deux modes de rédaction — choix selon la forme du contenu. parameters: accepte soit un mappage YAML inline (mode 1, présenté ci-dessus), soit une seule clé $import: pointant vers un fichier local (mode 2) :
spec: aggregate: my-app manifest: prod-manifest parameters: $import: ./prod-parameters.yamlUn chemin $import: relatif est résolu à partir du répertoire qui contient la Release qui l’écrit, d’où que la commande soit lancée, de sorte que la ligne de commande et l’éditeur lisent le même fichier ; un chemin absolu désigne son propre emplacement, et l’un comme l’autre doit mener à un fichier situé dans l’espace de travail — ou, pour une Release désignée hors de l’espace de travail, dans le répertoire qui la contient. Les deux modes sont mutuellement exclusifs à cet endroit, et un seul fichier peut être importé. La superposition de paramètres sur plusieurs fichiers relève des chaînes extends: de Release : la Release parente fournit un ensemble de base de paramètres et l’enfant étend et remplace par environnement. Voir Release composite / héritage extends: plus bas pour ce modèle.
Démarcation entre paramètres et infra. Les paramètres portent l’intention cognitive du développeur, exprimée sous forme de slots typés que l’Aggregate déclare ; la Release les remplit. infra: sur la Release porte le dimensionnement physique de l’opérateur (nombre de réplicas, limites CPU/mémoire, classes de stockage) rattaché à des composants précis ou à des rattachements de Feature. Les paramètres alimentent les templates values: de l’Aggregate via .parameters.X ; infra: alimente le template valuesMapping: de la Recipe via .infra.X. Voir architecture/06-data-taxonomy-and-composition.md §3 pour la taxonomie des piliers de données et templates/parameters-context.md pour le cycle de vie des paramètres dans le pipeline.
Frontières et portée par défaut
Une Release regroupe les composants en frontières — des unités physiques de déploiement, chacune avec son propre répertoire de sortie et sa propre cascade d’annotations. Le cas à frontière unique est le plus courant ; il ne demande donc aucune cérémonie.
Portée unique (le cas par défaut). Rédigez les composants directement sous spec.components: et omettez le bloc 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 fournisseur, via la valeur par défaut sûre de subDirectory décrite plus bas : dist/compose/, dist/helm/, …), sans segment portant le nom de la frontière dans le chemin. C’est le déploiement le plus simple : aggrega build sur une cible Compose plate ou à cluster unique, sans nommer de frontières.
spec: aggregate: aggregate manifest: manifest components: db: infra: engine_version: "11.4" web: infra: port: 8080Portées multiples. Lorsqu’une Release couvre plus d’un regroupement physique — clusters, régions ou sync waves distincts — déclarez des frontières nommées sous boundaries:. Chaque frontière porte son propre directory:, sa propre cascade d’annotations et son propre syncWave:, et les composants sont adressés au sein de leur frontière.
Exclusivité mutuelle. spec.components: et spec.boundaries: sont mutuellement exclusifs à la racine de la Release — une Release rédige 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. La surface components de niveau supérieur porte la même forme par composant, côté opérateur, que les components d’une frontière (infra:, annotations:, uses:).
Une frontière déclarée nommée default. La sortie plate est une propriété de la frontière par défaut synthétisée, pas du nom. Une frontière nommée default qu’une Release déclare explicitement sous boundaries: est une frontière nommée ordinaire : sa sortie suit son directory: (par défaut dist/boundaries/default/), exactement comme toute autre frontière déclarée.
Voir architecture/06-data-taxonomy-and-composition.md §7 pour le modèle de la portée par défaut.
Ségrégation spatiale et chemins de sortie
Chaque frontière déclare un directory de sortie physique pour ses artefacts compilés ; les composants d’une frontière peuvent le remplacer via un subDirectory par composant. Le compilateur calcule le chemin final de l’artefact en les joignant, sous forme séparée par des barres obliques sur toutes les plateformes : Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).
- Un répertoire, une graphie. Le chemin évalué est nettoyé une seule fois, de sorte que
out/a,out//a,./out/aetout/a/sont un seul et même répertoire. Les frontières dont les chemins se nettoient vers le même répertoire et dont le rendu passe par le même fournisseur sont assemblées ensemble, exactement comme le sont des frontières écrites avec des chemins identiques. - Le chemin reste sous la racine de sortie. Un chemin qui remonte hors de la racine de sortie (
..,../escape,a/../..), un chemin absolu, ou un chemin qui ne désigne aucun répertoire — vide, ou se réduisant après nettoyage à la racine de sortie elle-même — arrête le build avant que quoi que ce soit ne soit écrit. Le message nomme la Release, la frontière, le champ en cause (directory:ousubDirectory:) et la valeur à laquelle il s’est évalué, car cette valeur est souvent le résultat d’un template. - Valeur par défaut sûre. Si
subDirectoryest omis ou vide, le compilateur applique automatiquementsubDirectory: "{{ .capability }}"— les artefacts de chaque capacité de rendu (Helm, Helm-chart, Compose, Terraform, CloudFormation) se retrouvent dans leur propre sous-dossier, ce qui évite les collisions d’artefacts mélangés dans les outils CI/CD en aval. UnsubDirectory: ""écrit explicitement est lu exactement comme s’il était omis ; il reçoit donc lui aussi cette valeur par défaut. - Remplacement à plat. Pour désactiver entièrement les sous-répertoires (tous les artefacts directement sous
directory), définissezsubDirectory: ".". Un templatesubDirectoryqui s’évalue en chaîne vide —"{{ .parameters.sub }}"avecsubdéfini à"", par exemple — les désactive également. - Variables de template.
directorys’évalue avec{{ .capability }},{{ .boundary_name }},{{ .parameters.X }},{{ .manifest.recipe_name }}et{{ .parent_boundary.* }}pour les données en cascade d’une frontière englobante.subDirectorys’évalue avec le même ensemble plus{{ .component_id }}(remplacements par composant uniquement). Le compilateur évalue les templates de chemin avecmissingkey=error— référencer une variable non déclarée arrête le build avec un diagnostic précis. Voir variables des templates de chemin pour la matrice par contexte et les règles de cascade depuis la frontière parente.
Les annotations de frontière descendent en cascade vers chaque composant contenu ; infra reste strictement local au composant qui le cible. Le mappage récursif boundaries permet une imbrication arbitraire (frontière dans une frontière dans une frontière), tandis que les invariants de la cascade d’annotations et de l’infra local tiennent à chaque niveau.
Exemple détaillé :
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: spatial-release version: 1.0.0 environment: productionspec: aggregate: spatial-app manifest: prod-manifest boundaries: eu-prod: directory: "deploy/eu-prod" # Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`. annotations: "aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations components: api-server: infra: { replicas: 5 } # Strictly local aws-rds: # Scenario B: Bespoke Enterprise Naming. subDirectory: provisioning postgres-db: # Scenario C: The Flat Directory Override. subDirectory: "." # not "", which takes the defaultLes annotations propagées en cascade par ce mécanisme apparaissent dans les templates de Recipe en aval via .context.annotations.release ; voir Rédaction d’une Recipe et la matrice d’expansion des templates pour la façon dont les moteurs de rendu les consomment.
Valeurs d’annotation structurées. Lorsqu’un binding de Manifest déclare plusieurs chemins de routage du pilier infra pour une même clé d’annotation, la valeur d’annotation côté Release peut être un objet structuré portant des valeurs pour plusieurs champs du schéma d’une Feature en une seule déclaration :
boundaries: prod: annotations: feature.myco/db-pool: pool_size: 20 max_connections: 100 components: api: annotations: feature.myco/db-pool: max_connections: 200 # closer-level override # pool_size not listed → inherits 20 from boundaryLes valeurs structurées descendent en cascade avec une fusion profonde par sous-clé ; les sous-clés du niveau le plus proche remplacent celles du parent. Un null par sous-clé désactive une sous-clé tandis que les sous-clés sœurs demeurent. Le côté Release n’applique que les sous-clés dont le pilier dans la table de binding est infra ; les sous-clés routées vers values relèvent des annotations côté Aggregate. Pour l’explication complète des valeurs structurées — composition entre les deux côtés, validation de type par sous-clé, la discipline des valeurs par défaut assouplies — voir providers/well-known-annotations.md §« Valeurs d’annotation structurées ».
Annotations connues. Au-delà des clés ad hoc, la bibliothèque standard d’Aggrega définit un ensemble d’annotations connues sous les espaces de noms aggrega.ai/ et feature.aggrega.ai/, regroupées en catégories placement, réseau, sécurité et observabilité. Les auteurs qui ajoutent des annotations à une frontière de Release devraient consulter providers/well-known-annotations.md pour la matrice complète ainsi que les règles de consommation par fournisseur — la page documente quels fournisseurs appliquent chaque clé connue et quel comportement ils produisent lorsque la clé est présente.
Configuration de connexion par arête
Un composant de frontière peut porter un bloc uses: qui configure ou câble les arêtes de la topologie au sein des sockets que déclare le usesSchema de catalogue du Component. C’est la surface par connexion de l’opérateur, bornée afin que le développeur garde la maîtrise de l’architecture qu’il a rédigée :
- Configurer une arête existante. Définissez
infrapar arête sur une arête que le développeur a déjà déclarée. L’entrée nomme l’alias du développeur et fournitinfra; soit elle nomme la même cible que celle câblée par le développeur, soit elle omet la cible. L’infraest validé par rapport à l’infraSchemadu socket. - Câbler un socket non lié. Créez une arête vers un socket que le
usesSchemadu Component déclare mais que le développeur a laissé non câblé, pointant vers un composant existant. L’arête créée peut aussi porterinfrapar arête. - Rattacher sur une connexion. Placez des rattachements sous
features:de l’entrée, indexés par un slot que le socket déclare dans sonfeaturesSchema— les mêmes slots que remplit l’entrée de connexion du développeur. Chacun portetype, unedescriptionfacultative etinfra, et jamaisvalues. Sous un slot que le développeur a déjà rempli sur la même connexion, l’entrée dimensionne ce rattachement : n’écrivez queinfra, puisque le type et les valeurs viennent de l’Aggregate (untypeécrit ici doit concorder avec celui de l’Aggregate, sinon le build s’arrête à cette entrée en nommant les deux). Sous un slot que le développeur a laissé vide, le rattachement appartient à la Release ettypeest obligatoire. Dans les deux cas, le remplissage est soumis auselectordu slot et compte pour un slotrequired, exactement comme celui du développeur.
La surface est créer-sans-recibler : une Release peut ajouter une arête vers un socket non lié, mais elle ne peut pas rediriger une arête que le développeur a déjà déclarée. Une entrée par arête qui nomme une cible différente de celle de l’arête du développeur arrête le build ; une entrée qui nomme la même cible (ou l’omet) configure cette arête. La Release ne peut pas non plus déclarer de values sur une arête ou sur un rattachement qu’elle y écrit (les valeurs destinées au développeur restent dans l’Aggregate), lier un socket que le usesSchema ne déclare pas, ni faire pointer une arête vers un composant qui n’existe pas — chacun de ces cas est un arrêt fatal. Il en va de même d’une entrée qui définit infra ou features sur une connexion qui n’existe pas une fois toutes les arêtes tracées, sauf si le composant consommateur est désactivé avec active: false. Voir errors/fatal-halts.md §« Lors de la construction de la topologie ».
Trois autres arrêts maintiennent les rattachements d’une connexion sur leur connexion :
- Un nom pour lequel le socket ne déclare aucun slot provoque un arrêt, exactement comme sur l’entrée de connexion de l’Aggregate, à cette entrée de la Release, en nommant les slots que le socket déclare et ceux dont le nom n’est qu’à une modification près.
- Un rattachement que seule la Release effectue, écrit sans
type, provoque un arrêt à l’entrée de connexion, en nommant le slot. Un rattachement effectué par la Release ne porte pas devalues, il convient donc à une Feature dont lesvaluesn’exigent rien ; celle dont le schéma exige une valeur provoque un arrêt pour la valeur manquante à la même entrée. Les Features d’identifiants de la bibliothèque standard qui portent le localisateur d’un appelant n’en exigent aucun dansvalues: chacune l’accepte aussi dansinfra(voir ci-dessous). - Le nom composé écrit ailleurs que sur la connexion provoque un arrêt. Un rattachement de connexion devient un rattachement du composant consommateur nommé
<alias>.<slot>(voir l’entrée de connexion de l’Aggregate), et les clésfeatures:propres à une entrée de composant comme celles d’une frontière admettent un point. Une entrée de composant qui écrit ce nom, ou une frontière qui l’écrit de sorte qu’il atteigne un composant dont la connexion le porte — un composant placé dans cette frontière ou dans une frontière imbriquée en elle, y compris ceux d’un sous-module routé — provoque un arrêt en nommant les deux graphies, une fois pour chaque composant atteint. Le slot d’un socket se remplit sur chaque connexion et jamais par un rattachement descendant en cascade d’une portée plus large.
spec: components: router: uses: models: # Size the attachment the Aggregate declared on the "gpt" connection: infra only. gpt: features: credential: infra: { rotation: hourly } # Attach on a connection the developer left without one: the type is required. plain: features: credential: type: core/generated-secretUn identifiant sur une connexion que la Release câble nomme son secret dans infra. Une connexion que la Release câble n’a pas d’entrée dans l’Aggregate, donc rien n’y écrit les values de l’identifiant, et la Release n’écrit values nulle part. Chaque Feature d’identifiants de la bibliothèque standard qui porte le localisateur d’un appelant — core/referenced-secret, core/referenced-secret-set, core/secret-value et core/secret-provided — l’accepte donc dans infra aussi bien que dans values : origin, ou entries pour core/referenced-secret-set, avec la même forme et la même déclaration sensitive: true dans les deux piliers. Chaque réalisation lit le pilier qui le porte.
spec: components: router: uses: models: gpt: target: gpt # wire the socket the developer left unbound features: credential: type: core/referenced-secret infra: origin: openai-team-a # the secret the operator namesLe localisateur s’écrit dans exactement un pilier par rattachement. Un rattachement qui le porte dans les deux — les values de l’Aggregate et l’infra de la Release pour le même slot — ou dans aucun s’arrête sur l’assertion propre de la Feature (E0033), en nommant la Feature, le rattachement et le composant, et en indiquant lequel des deux cas s’est produit. La règle appartient aux entités de catalogue de ces Features, pas au compilateur, qui évalue leur assertion comme il évalue celle de toute Feature. Les champs autres que le localisateur gardent leur pilier : key reste une feuille de values, de sorte qu’un rattachement que seule la Release effectue lit la clé de données par défaut de la Feature, value. L’interdiction de values: est inchangée — le localisateur de l’opérateur est infra.
core/secret-provided est celle qui ne convient pas à une connexion : elle publie sa valeur pour que le bloc inject: propre au rattachement la livre, et le rattachement d’une connexion ne porte de bloc inject: dans aucun des deux documents, si bien que sur une connexion aucun bloc inject: ne la livre. Utilisez plutôt core/referenced-secret ou core/secret-value à cet endroit.
spec: aggregate: spatial-app manifest: prod-manifest boundaries: eu-prod: components: api-server: uses: databases: # Configure the developer-declared edge "primary": add per-edge infra. # The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget. primary: infra: { storage_class: fast-ssd } caches: # Wire an edge into the declared-but-unbound "caches" socket to an existing component. main: target: redis-prod infra: { storage_class: standard }L’infra par arête résolu alimente le contexte de rendu du composant consommateur à .context.uses.<alias>.infra.<key> ; il n’apparaît jamais dans le contexte du composant cible, de sorte que la sortie rendue d’une cible est invariante vis-à-vis des consommateurs qui configurent des arêtes vers elle. Un rattachement sur une connexion arrive lui aussi sur le composant consommateur, comme l’un de ses rattachements : son infra fusionne avec les values de l’Aggregate pour le même slot, et sa FeatureRecipe effectue le rendu à partir des deux. La Recipe du composant consommateur le lit sous sa connexion, à .context.uses.<alias>.features.<slot>, et son Workload le livre en nommant la connexion à côté du slot — voir Livrer un identifiant porté par une connexion.
Le champ aggregates: — router les sous-modules imbriqués vers les frontières
Lorsque l’Aggregate déclare des sous-modules imbriqués via spec.aggregates:, la Release décide dans quelle frontière atterrissent les composants de chaque sous-module en déclarant aggregates: à côté de components: à l’intérieur de la frontière cible :
# Aggregate declares two sub-aggregatesapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: platform version: 1.0.0spec: aggregates: finance: type: finance-module:1.2.0 analytics: type: analytics-module:2.0.0 components: gateway: type: core/ingress---# Release routes each sub-aggregate into a specific boundaryapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: platform manifest: prod-manifest boundaries: eu-prod: directory: "deploy/eu-prod" aggregates: finance: {} components: gateway: {} us-prod: directory: "deploy/us-prod" aggregates: analytics: {}Placez chaque sous-agrégat listé sous Aggregate.spec.aggregates: dans exactement une frontière.
Le routage place des composants. Chaque composant d’un sous-module routé atterrit dans la frontière qui le route et prend les directory, subDirectory, syncWave et la cascade d’annotations de cette frontière — le même contexte que reçoit un composant nommé directement sous components:, y compris la provenance aggrega.ai/boundary-path apposée sur les artefacts émis. Router un sous-module et adresser chacun de ses composants par son chemin pointé qualifié avec un corps vide produisent donc des artefacts identiques ; le routage est la manière la plus courte de le dire, et la seule de le dire sans connaître le contenu du sous-module.
Un composant appartient à exactement une frontière, et le build s’arrête lorsqu’un document en place un deux fois — le même sous-module routé vers deux frontières, un sous-module routé vers une frontière alors que l’un de ses composants est nommé dans une autre, ou un composant nommé à la fois directement et via une entrée de routage. Le diagnostic nomme les deux emplacements, car le choix de celui à conserver revient à l’auteur. Router un sous-module vers une frontière et nommer l’un de ses composants sous cette même frontière n’est pas un conflit : le routage place le composant et l’entrée nommée le configure.
Un sous-agrégat que la Release ne place nulle part arrête le build. Le placement est lu à travers les deux écritures, si bien que le build ne s’arrête que lorsque aucune n’atteint le sous-module : aucune frontière ne le route sous aggregates:, et aucune frontière ne nomme l’un de ses composants sous components: par chemin pointé qualifié. Chacune des écritures suffit à elle seule à le placer, et un sous-module dont tous les composants sont nommés individuellement n’a besoin d’aucune entrée de routage. La correction se fait dans le bloc aggregates: de l’Aggregate qui a importé le sous-module — l’Aggregate que la Release déploie, pour un sous-module qu’il importe directement, et le document propre du sous-module importateur, pour un sous-module imbriqué. Le diagnostic nomme cette entrée par la clé avec laquelle le document importateur l’écrit, de sorte que pour un sous-module imbriqué elle se lit comme le nom local plutôt que comme le chemin pointé.
Deux cas, délibérément, n’arrêtent pas le build. Un sous-module qui n’apporte aucun composant n’a rien à placer. Un sous-module dont l’interrupteur active: se résout en false n’a jamais été composé, de sorte qu’aucun de ses composants n’existe pour être placé.
Un placement partiel ne déclenche pas cette règle : un sous-module est placé dès que l’un quelconque de ses composants atteint une frontière, donc en nommer un satisfait le sous-module. Il ne s’ensuit pas que les autres puissent être omis. Chaque composant que la frontière n’a pas nommé n’est alors placé par rien, et la règle sur les composants ci-dessous le signale à sa propre clé — un sous-module placé en partie arrête donc le build une fois par composant laissé de côté, et non au niveau du sous-module. Les deux écritures qui placent un sous-module entier en une ligne sont l’entrée de routage et le fait de nommer chaque composant ; tout ce qui se situe entre les deux place ce qu’il nomme, et rien de plus.
Un composant que la Release ne place nulle part arrête lui aussi le build, un niveau plus bas. La règle ci-dessus demande si un sous-module a atteint une frontière ; celle-ci pose la même question pour chaque composant que contient la composition. Un composant atteint une frontière en étant nommé sous les components: de cette frontière, ou en se trouvant dans un sous-module qu’une frontière route vers elle. Un composant qui n’atteint ni l’un ni l’autre est rendu en dehors de toute frontière déclarée par la Release, et ne tient ses directory, subDirectory, syncWave, sa cascade d’annotations et son infra: par composant de nulle part — le build s’arrête donc et nomme le composant plutôt que d’émettre des artefacts que la configuration des frontières n’a jamais atteints.
Les deux règles se partagent le terrain en s’interrogeant sur le sous-module du composant, et pas seulement sur le fait qu’il en ait un. Un composant d’un sous-module que la Release n’a placé nulle part relève de la règle sur les sous-modules, qui signale cette unique erreur d’écriture une seule fois à l’entrée aggregates: plutôt qu’une fois par composant que contient le module. Un composant d’un sous-module que la Release a placé en partie relève de cette règle-ci, car la règle sur les sous-modules lit un tel module comme placé et n’en dit rien — chaque composant que la frontière n’a pas nommé est donc signalé ici, à sa propre clé à l’intérieur du document qui le déclare. Placer un sous-module en partie nomme donc exactement ce que vous vouliez nommer, et vous signale chaque composant que vous n’avez pas nommé.
Et une entrée de frontière qui nomme un composant que l’Aggregate déployé ne contient pas arrête le build. Les deux règles ci-dessus lisent le placement du côté du composant — quelque chose l’a-t-il placé ? Celle-ci le lit du côté de la Release : le nom se résout-il ? Une entrée qui ne se résout en rien ne place rien, de sorte que son subDirectory, ses annotations, son infra: par composant et ses uses: configurent un composant qui n’existe pas, et le build s’arrête plutôt que d’émettre un déploiement que l’entrée n’a jamais atteint. Les deux écritures sont vérifiées : un nom sous les components: d’une frontière est lu comme l’identifiant que porte le composant une fois la composition terminée, et un nom sous les components: d’une entrée de routage est lu comme le nom local qu’il porte à l’intérieur de ce sous-module. Le diagnostic indique l’identifiant que l’entrée a adressé, qui, dans l’écriture routée, n’est pas le nom présent dans le fichier — le fichier écrit la moitié locale et le sous-module fournit son préfixe.
Un nom est refusé parce qu’il ne se résout en rien, jamais pour sa forme : un nom pointé est ordinaire, car un composant situé un module plus bas porte le préfixe de ce module. Un composant dont l’interrupteur active: se résout en false reste nommable — désactiver un composant n’exige pas de modifier la Release qui le configure.
Un sous-système n’ajoute rien au chemin qualifié, de sorte qu’une frontière adresse un composant par son nom nu, quelle que soit la façon dont l’Aggregate le regroupe. Seule la composition de sous-modules qualifie un identifiant. Un composant de l’Aggregate déployé est store, que l’auteur l’ait écrit au niveau supérieur ou à l’intérieur d’un sous-système nommé data ; un composant situé un module plus bas est data.store, et le data y est le préfixe du module et non celui d’un sous-système. Ainsi, une entrée de frontière écrite data.store pour un composant situé dans un sous-système nommé data n’adresse rien : l’entrée elle-même arrête le build en vertu de la règle ci-dessus, et le composant auquel elle était destinée n’atteint pas non plus de frontière. Corriger l’entrée en store résout les deux.
Placer un sous-module exige donc boundaries:. La forme à portée unique n’a pas de surface de routage — aggregates: est une clé d’une frontière, pas de spec: — et la map components: de premier niveau n’accepte que des noms non qualifiés, de sorte qu’une Release qui déploie un Aggregate important des sous-modules déclare boundaries:.
Routage récursif. aggregates: est récursif — chaque entrée sous les aggregates: d’une frontière peut elle-même déclarer une map aggregates: imbriquée pour une composition de modules profondément imbriqués.
Bloc de routage par agrégat. Une entrée de routage accepte exactement deux clés et rien d’autre : components:, pour configurer des composants individuels de ce sous-module, et un aggregates: imbriqué pour les modules imbriqués plus profondément. annotations: appartient à la frontière, et l’infra: par composant appartient à une entrée sous les propres components: de l’entrée de routage.
Dans une entrée de routage, un composant a pour clé le nom qu’il porte à l’intérieur de son sous-module — consumer, et non data.consumer — car c’est le seul nom qu’il y possède. Le chemin pointé qualifié est la façon dont la map components: d’une frontière adresse le même composant ; les deux écritures ne sont pas interchangeables, et une entrée de routage rejette une clé pointée.
boundaries: eu-prod: directory: "deploy/eu-prod" annotations: aggrega.ai/namespace: "finance-zone" aggregates: finance: components: ledger: # the component's name inside the finance module infra: replicas: 3 aggregates: reporting: {} # a module nested inside financeLes composants et les Features propres au sous-agrégat ne sont pas redéclarés dans la Release — la Release les route plutôt que de les répéter, et n’en nomme un que pour le configurer.
Séquencement temporel — syncWave par frontière
Chaque frontière de la Release déclare facultativement un champ entier syncWave:, qui donne à l’opérateur un contrôle explicite sur l’ordre de déploiement sans toucher à l’Aggregate du développeur. Le numéro de vague est une propriété de la frontière elle-même ; chaque composant contenu dans le sous-arbre de la frontière hérite de la valeur de vague de sa frontière lorsque les artefacts sont émis.
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: my-app manifest: prod-manifest boundaries: infra: directory: "deploy/infra" syncWave: 0 components: core-vpc: {} postgres-db: {} migrations: directory: "deploy/migrations" syncWave: 1 components: db-migration-task: {} apps: directory: "deploy/apps" syncWave: 2 components: web-server: {} ai-agent: {}Sémantique de la valeur de vague. syncWave: est un entier signé (positif, nul ou négatif). La valeur par défaut lorsque le champ est omis est 0. Les valeurs de vague ne sont pas héritées d’une frontière parente — chaque frontière qui souhaite une vague autre que celle par défaut en déclare une explicitement. Les Components ne peuvent pas remplacer la vague de leur frontière (la vague est une propriété de l’unité spatiale, pas des composants individuels).
Émission par fournisseur. Le compilateur émet la valeur de vague de la frontière dans la sortie rendue, sous la forme native du fournisseur. Trois de ces formes sont détaillées ci-dessous ; ce que fait la vague sur chaque fournisseur de la bibliothèque standard, terraform compris, est présenté sous forme de tableau dans providers/reference-matrix.md « Ce que fait la syncWave d’une frontière sur chaque fournisseur ».
- Kubernetes (fournisseur helm / helm-chart). Lorsque la vague n’est pas
0, chaque ressource Kubernetes que le fournisseur helm rend pour la frontière porte l’annotation standard de GitOpsargocd.argoproj.io/sync-wave: "<N>"; les hooks Helm portent en outre l’annotationhelm.sh/hook-weight: "<N>", afin que la même valeur de vague pilote l’ordonnancement pre/post-install propre à Helm. ArgoCD lit l’annotation sync-wave et Helm lit le poids d’un hook, et chacun ordonne l’application des ressources en conséquence. Le fournisseur helm-chart copie les templates d’un chart source tels que leur auteur les a écrits, de sorte que les ressources propres d’un sous-chart ne portent la vague que là où ces templates l’écrivent ; un artefact chargé par$import:qu’il ajoute porteargocd.argoproj.io/sync-waveet aucunhelm.sh/hook-weight(voirproviders/helm-chart.md). - Compose. Chaque service du fichier compose dans lequel une frontière est rendue attend, via
depends_on, les services de la vague immédiatement précédente qui ont contribué au même fichier — selon l’état de santé de la cible lorsque la cible déclare unhealthcheck, et selon son démarrage lorsqu’elle n’en déclare pas. La vague ordonne donc les services d’un fichier et rien en dehors : les frontières rendues dans des fichiersdocker-compose.yamldistincts sont des projets compose distincts, et leur séquencement relève de l’opérateur. Les arêtesuses:continuent d’exprimer un ordonnancement par arête à côté de la vague. Voirproviders/compose.md. - CloudFormation. Chaque ressource du template de stack assemblé dépend, via
DependsOn, des ressources de la vague immédiatement précédente qui ont contribué au même stack — la vague fixe donc l’ordre dans lequel les ressources sont créées et, à l’inverse, l’ordre dans lequel elles sont supprimées. Il ne s’agit pas d’un ordonnancement par disponibilité : un template de stack n’a aucune notion d’une ressource prête à servir. LeDependsOnpropre à un fragment est étendu plutôt que remplacé. Les Components qui s’assemblent dans un autre stack sont hors de portée, et le séquencement de deux stacks relève de l’opérateur. Voirproviders/cloudformation.md.
Unité d’écriture des vagues vs unité déployable. La frontière est l’unité dans laquelle on écrit les vagues. L’unité déployable est le chemin d’assemblage dans lequel les composants sont émis — par défaut 1:1 avec la frontière, mais deux frontières sœurs qui partagent un directory: fusionnent en une seule sortie assemblée (un Chart.yaml, un docker-compose.yaml). Dans ce cas, la sortie assemblée peut contenir des ressources de plusieurs vagues ; une Application ArgoCD qui la lit ordonne, au sein de l’Application, chaque ressource selon l’annotation sync-wave que porte cette ressource — sur helm, chaque ressource rendue pour une vague non nulle, et sur helm-chart, uniquement un artefact chargé par $import:, les templates propres d’un sous-chart portant ce que leur auteur a écrit. Le séquencement entre Applications à travers les chemins relève de la CI de l’opérateur.
Cas d’usage. L’ordonnancement par vagues compte chaque fois que le démarrage d’une frontière dépend de l’achèvement préalable d’une autre. Schéma canonique : une frontière infra en vague 0 (VPC + base de données), une frontière migrations en vague 1 (job de migration de schéma) et une frontière apps en vague 2 (l’application qui consomme le schéma migré). Sans vagues explicites, les trois se déploient simultanément et l’application plante et redémarre en boucle en attendant la fin de la migration.
Pour le cadrage architectural complet — le modèle d’exécution en DAG, la justification du placement du séquencement temporel sur la Release plutôt que sur l’Aggregate, et la distinction entre unité d’écriture des vagues et unité déployable — voir architecture/12-day-two-lifecycles.md §1.
Rattachement de Feature
La Release peut rattacher des Features à la fois au niveau d’une frontière (politique large) et au niveau d’un composant précis (ciblage précis), l’exécution suivant le modèle en oignon à 5 niveaux défini dans architecture/10-compilation-pipeline.md. Les Features déclarées dans la Release apportent type, infra et uses ; elles ne peuvent pas déclarer values (voir Contraintes au niveau du schéma ci-dessus).
Une Feature rattachée à une frontière a pour clé un nom d’instance que vous choisissez, et ce nom ne peut être ni . ni ... Sur un fournisseur qui donne à chaque contributeur un répertoire qui lui est propre — terraform, sous modules/, et helm-chart, sous charts/ —, les fichiers d’une Feature au niveau de la frontière sont écrits dans un répertoire nommé d’après la seule instance, et aucun de ces deux noms n’est un répertoire à part entière : le build s’arrête, en nommant la Release, la frontière et l’instance. Un nom qui contient simplement des points, comme audit.v2, est un nom ordinaire.
features: est la seule surface de rattachement de la Release, aux deux niveaux — comme c’est le cas pour l’Aggregate. Un identifiant d’accès est une Feature portant le label feature.aggrega.ai/kind: secret, de sorte qu’un identifiant d’accès rattaché par l’opérateur est rattaché sous features: comme n’importe quelle autre Feature, et nomme son secret dans infra exactement comme le fait un identifiant sur une connexion (voir Configuration de connexion par arête) — sur un composant que l’Aggregate a laissé sans identifiant, ou comme dimensionnement d’un rattachement que l’Aggregate a déclaré sans nommer de secret. Il n’existe de second mot-clé de rattachement à aucun niveau ; un document qui en déclare un est rejeté au chargement avec une erreur d’enveloppe nommant la propriété inattendue.
Une fonctionnalité rattachée à l’échelle d’une frontière peut porter un bloc uses:, et ce bloc se projette sur chaque composant routé vers la frontière : chaque composant obtient une arête de dépendance vers les cibles nommées par la fonctionnalité et reçoit par injection les provides de ces cibles. Cela exprime une dépendance partagée une seule fois au niveau de la frontière — « chaque composant de cette frontière communique avec le cache / le collecteur / le bus de messages partagé » — plutôt que de répéter la même arête uses: sur chaque composant. Un rattachement de Feature au niveau d’un sous-système dans l’Aggregate projette ses uses: de la même manière sur les composants du sous-système. uses est une déclaration de câblage de la topologie, pas une valeur ; elle est donc autorisée dans la Release. La projection est indépendante de la portée d’exécution de la Feature rattachée : une Feature dont la FeatureRecipe est rendue une fois par frontière projette néanmoins ses uses: par composant, tandis que la ressource partagée elle-même est rendue une fois.
Une fonctionnalité rattachée à un seul composant porte le même bloc uses: et câble la même arête à partir de ce seul composant : le composant obtient une arête de dépendance vers chaque cible nommée, reçoit par injection les provides de ces cibles, et l’arête enregistre le rattachement comme son origine exactement comme le fait la forme à l’échelle de la frontière. Les deux sont une seule déclaration à deux largeurs — rattacher à la frontière pour câbler chacun de ses composants, rattacher sur un composant pour câbler celui-là — et le choix entre les deux est une question de portée, jamais de ce que fait le câblage. Aucune des deux ne crée de ressources de calcul : la cible doit déjà nommer un composant que l’Aggregate a déclaré, et une cible qui ne le fait pas arrête le build. Une connexion tracée par une Feature ne porte aucun rattachement propre : son entrée accepte target et inject, et une clé features: à cet endroit est refusée au chargement de la Release.
boundaries: cluster: directory: ./dist/cluster components: api: features: shared_backend: type: core/shared-backend uses: backend: primary: target: db # a component of the assembled graph inject: env: - in: DB_HOST from: host # db's `host` provides reaches api as DB_HOST db: {}Comment s’écrit une cible. Une cible d’arête nomme un composant du graphe assemblé ; elle s’écrit donc avec le chemin pointé qualifié — data.store, et non store — chaque fois que la cible appartient à un sous-module routé. Cela vaut même lorsque le rattachement lui-même se trouve sous une entrée de routage, dont les clés components: sont locales au module : la clé indique sur quel composant se trouve le rattachement et la cible indique quel composant l’arête atteint, et seule la seconde est un nom valable dans tout le graphe. Une cible écrite avec un nom local au module ne correspond à aucun composant et arrête le build avec le même diagnostic que produit toute arête pendante.
Release composite et héritage par extends:
Une Release peut déclarer spec.extends: pointant vers une Release de base dont elle hérite la surface de rédaction.
La référence est un chemin vers un fichier situé à côté de la Release qui la déclare — ./base-release.yaml, ou ../shared/base-release.yaml. Une Release relève du côté déploiement et n’est pas indexée dans le catalogue, de sorte qu’une référence extends: ne se résout jamais via le catalogue. Le chemin relatif est la seule forme qu’elle accepte : une référence écrite comme une coordonnée de registre est refusée, de même qu’un nom nu, chacune avec la forme en chemin relatif indiquée dans le diagnostic. L’extends: d’un Manifest est le proche voisin qui se lit différemment — il accepte un chemin relatif ou le metadata.name nu d’un Manifest situé à côté de la Release —, de sorte que les deux formes ne sont pas interchangeables, et un nom nu qui se résoudrait sur un Manifest ne se résout pas ici. Chaque maillon d’une chaîne se lit de la même façon : une Release parente conservée dans un autre répertoire nomme sa propre parente par un chemin situé à côté d’elle-même, où que se trouve la Release que vous avez nommée, exactement comme son $import: de paramètres est résolu à côté d’elle. Le chemin doit mener à une Release à l’intérieur du workspace, comme tout chemin qu’écrit une Release — ou, pour une Release nommée hors du workspace, à l’intérieur du répertoire qui contient cette Release, auquel chaque maillon de sa chaîne est tenu : un chemin qui en sort en remontant, ou qu’un maillon fait sortir, est refusé avant que le fichier qu’il nomme ne soit lu.
Le compilateur suit la chaîne au chargement de la Release — en refusant une chaîne qui revient à un fichier qui s’y trouve déjà, une chaîne qui dépasse la limite de profondeur et une référence qui ne nomme rien — puis réduit la chaîne à une seule Release résolue.
Ce dont vous héritez, vous pouvez le remplacer clé par clé. Votre valeur l’emporte, jusqu’en bas, jusqu’à ce que vous atteigniez une valeur qui forme un tout indivisible — un scalaire, une liste, un template — que vous prenez ou remplacez en entier. Vous supprimez un élément hérité en l’écrivant null. C’est la même règle que suivent un Component, une Feature et un Manifest qui étendent, de sorte qu’un auteur qui en a rencontré un les a tous rencontrés.
Appliqué à une Release : les boundaries se composent par nom de frontière et une frontière par clé, les components par nom de composant, infra en profondeur, les features par nom d’instance puis par pilier ; les uses d’un composant par socket puis par connexion, où un target écrit par l’enfant remplace celui hérité, l’infra de la connexion se compose clé par clé, et ses features se composent par slot puis par pilier selon la même règle que suivent les features propres d’un composant ; directory, subDirectory, syncWave et les pointeurs vers l’Aggregate et le Manifest sont des scalaires qui remplacent.
Deux choses ne se transmettent pas :
- Identité et provenance. Aucun champ
metadatan’est hérité.metadata.environmentest celui à connaître : il est requis pour chaque Release et propre à chaque Release par nature, de sorte qu’un enfant effectue le rendu avec son propre environnement dans ses labels de provenance plutôt qu’avec celui de son parent. - Le pointeur vers l’Aggregate est hérité plutôt que redéfinissable. L’enfant ne peut pas déclarer
aggregate:— le schéma refuseextends:etaggregate:dans un même document — de sorte qu’un enfant déploie la même intention du développeur que sa base.
L’enfant peut omettre manifest:, héritant de celui de sa base, ou le redéfinir pour le Late Binding.
Une seule forme de routage tout au long de la chaîne. boundaries: et components: s’excluent mutuellement au sein d’une même Release, et cela vaut aussi tout au long d’une chaîne : une base qui déclare des frontières nommées associée à un enfant qui déclare des composants de premier niveau est refusée, et le diagnostic nomme les deux fichiers et les deux clés. Choisissez une forme de routage et utilisez-la jusqu’en bas.
Le modèle de passerelle pour le développement local. Le cas d’usage canonique est celui d’un développeur qui exécute localement l’Aggregate de production de son équipe sans forker l’Aggregate ni dupliquer la topologie des frontières. L’équipe publie une Release de production ; une Release locale l’étend par extends: et redéfinit uniquement le pointeur vers le Manifest, en remplaçant les Recipes ciblant le cloud par des équivalents locaux :
# production Release (committed; the source of truth for prod deployments)apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release environment: production version: "1.0.0"spec: aggregate: my-app manifest: prod-manifest parameters: region: us-east-1 db_size: 100Gi out_dir: prod boundaries: prod: # A directory is a TEMPLATE, not a fixed path. Writing it against a # parameter is what lets a child render somewhere else without # restating the boundary topology. directory: deploy/{{ .parameters.out_dir }} components: api: { infra: { replicas: 5 } } db: {}
---# Local Release (developer-side; inherits everything, swaps the Manifest)apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: local-release environment: local version: "1.0.0"spec: extends: ./prod-release.yaml manifest: local-manifest # surgically overrides for local parameters: region: dev-local db_size: 1Gi out_dir: local # the inherited directory resolves here insteadlocal-release hérite de sa base la topologie des frontières, les rattachements de Feature et les redéfinitions de composants ; le développeur conserve un seul local-release.yaml et exécute aggrega build --release local-release.yaml sans dupliquer aucune configuration de production.
Écrivez directory: en fonction d’un paramètre. Comme un répertoire s’hérite comme n’importe quel autre scalaire, un enfant qui hérite d’un répertoire ne contenant aucune variable de template effectue le rendu dans le même chemin que sa base, et aucune option de ligne de commande ne le redirige. C’est légitime quand c’est ce que vous vouliez — échanger uniquement les Recipes pour comparer leur sortie, par exemple — de sorte que le build le signale et continue plutôt que de refuser. Écrire le répertoire en fonction d’un paramètre, comme ci-dessus, garde la topologie en un seul endroit tout en envoyant la sortie de chaque Release vers un emplacement qui lui est propre.
Superposition de paramètres sur plusieurs fichiers. L’héritage de Release est le lieu de la superposition de paramètres sur plusieurs fichiers. Une Release de base fournit l’ensemble commun de paramètres ; les enfants par environnement étendent la base par extends: et redéfinissent les slots qui diffèrent :
# base-release.yaml — common parametersspec: aggregate: my-app parameters: timeout_seconds: 30 feature_flags: { dark_mode: true }
---# prod-release.yamlspec: extends: ./base-release.yaml manifest: prod-manifest parameters: feature_flags: { dark_mode: false } # override one nested key
---# staging-release.yamlspec: extends: ./base-release.yaml manifest: staging-manifestChaque enfant voit les paramètres hérités de sa base fusionnés avec les siens. Les paramètres à valeur de map fusionnent en profondeur, la clé de l’enfant l’emportant ; les paramètres à valeur scalaire sont remplacés par l’enfant ; une clé qu’un enfant écrit null est supprimée plutôt que définie à rien.
Une base peut importer ses paramètres et un enfant peut tout de même redéfinir des clés individuelles. Les deux modes de rédaction décrits plus haut sous parameters: — en ligne, ou un unique $import: — sont une règle portant sur un document, et non sur une chaîne : chaque Release de la chaîne déclare l’un ou l’autre mode, et l’import de chacune est résolu par rapport au répertoire qui contient cette Release avant que la chaîne ne soit réduite. Ainsi, une base qui importe un fichier partagé et un enfant qui écrit quelques clés en ligne se composent clé par clé, exactement comme le feraient deux blocs en ligne :
# base-release.yaml — parameters arrive from a shared file beside itspec: aggregate: my-app parameters: $import: ./shared-params.yaml # tier: prod, region: eu
---# local-release.yaml — overrides one key, inherits the restspec: extends: ./base-release.yaml manifest: local-manifest parameters: tier: local # region stays eu, from the imported fileModes d’erreur. Les chaînes extends: cycliques, les pointeurs parents manquants et les déclarations aggregate: côté enfant interrompent tous le chargement du workspace avec des diagnostics explicites nommant la Release fautive et la violation au niveau du schéma. Voir errors/fatal-halts.md pour la forme des messages de chaque erreur.