Schéma de la Release d’Aggrega
Référence générée. Ne pas modifier à la main — régénérer à partir du JSON Schema publié.
Identifiant du schéma : https://aggrega.ai/schemas/release-v1beta1.schema.json
Consultez la référence de rédaction de la Release pour des conseils rédigés sur l’écriture des entités Release ; cette page documente le schéma structurel que décrit cette référence.
Type de premier niveau : object
Propriétés
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | oui | Constante : "aggrega.ai/v1beta1" |
kind | const “Release” | oui | Constante : "Release" |
metadata | object | oui | |
spec | object | oui | Ce que la Release lie et route : l’Aggregate et le Manifest qu’elle déploie (ou une base extends), le renseignement des paramètres propre à l’environnement, et les frontières vers lesquelles ses composants sont routés. |
Les propriétés supplémentaires ne sont pas autorisées.
release.metadata
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
name | string | oui | Au moins 1 caractère. |
environment | string | oui | |
version | string | oui | Versionnage sémantique strict de la release (par ex. 1.0.0). Motif : ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
description | string | non | Ce qu’est cette entité et à quoi elle sert, écrit pour quelqu’un qui décide s’il va l’utiliser. Commencez par une phrase qui nomme la chose, puis ajoutez ce dont un lecteur a besoin pour la choisir et l’utiliser correctement — ce qu’elle attend de la plateforme sur laquelle elle déploie, et tout ce que son comportement a de surprenant. Un court paragraphe est la longueur habituelle. |
maintainers | object[] | non | Liste des mainteneurs responsables de cette entité. |
license | string | non | Identifiant SPDX de la licence du logiciel que décrit cette entité, par exemple MIT ou AGPL-3.0. Il consigne les conditions de ce logiciel, pas celles de ce fichier. |
repository | string | non | L’URL du dépôt Git où se trouvent les fichiers source. |
home | string | non | L’URL de la page d’accueil, du wiki ou de la documentation de cette entité. |
keywords | string[] | non | Une liste de mots-clés descriptifs pour la découvrabilité dans l’interface utilisateur. |
Les propriétés supplémentaires ne sont pas autorisées.
release.metadata.maintainers[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
name | string | oui | |
email | string | non | |
url | string | non |
Les propriétés supplémentaires ne sont pas autorisées.
release.spec
Ce que la Release lie et route : l’Aggregate et le Manifest qu’elle déploie (ou une base extends), le renseignement des paramètres propre à l’environnement, et les frontières vers lesquelles ses composants sont routés.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
aggregate | string | non | Référence à l’Aggregate (intention du développeur) que cette release déploie. Un jeton nu se résout par identité — le metadata.name de l’Aggregate référencé, recherché dans le répertoire propre à la Release puis dans le catalogue. Une valeur commençant par ’./’ ou ’../’ est un fichier local explicite résolu relativement à la Release (par ex. ’../shared/app.yaml’ pour partager un même Aggregate entre des variantes de release dans un sous-répertoire). |
manifest | string | non | Référence au Manifest qui résout les interfaces abstraites par rapport auxquelles cette release déploie. Un jeton nu se résout par identité — le metadata.name du Manifest référencé, recherché dans le répertoire propre à la Release. Une valeur commençant par ’./’ ou ’../’ est un fichier local explicite résolu relativement à la Release. Un Manifest se situe côté déploiement et n’est pas indexé dans le catalogue ; il ne se résout donc qu’à partir du répertoire de la Release ou d’un chemin explicite. |
extends | string | non | Référence à une Release de base, dont cette Release hérite la surface de rédaction — son arbre de frontières avec l’infra par composant et les rattachements de Feature qui s’y trouvent, ses paramètres, ses annotations et son pointeur vers le Manifest. La valeur est un chemin vers un fichier situé à côté de cette Release, commençant par ’./’ ou ’../’ ; un nom nu et une coordonnée de registre sont tous deux refusés, car une Release se situe côté déploiement et n’est pas indexée dans le catalogue. Ce qui est hérité peut être remplacé clé par clé, jusqu’à la première valeur indivisible — un scalaire, une liste, un template — qui est remplacée en entier ; une clé écrite comme null retire ce qui a été hérité. Aucun champ de métadonnées n’est transmis, de sorte qu’un enfant porte son propre nom, sa propre version et son propre environnement. Déclarer ‘aggregate’ à côté de ‘extends’ est refusé par ce schéma, de sorte qu’un enfant déploie la même intention du développeur que sa base ; ‘manifest’ reste facultatif et peut être surchargé pour remplacer le fichier de verrouillage des dépendances. |
parameters | object | non | Contrat de renseignement des variables propre à l’environnement, avec deux modes de rédaction par aiguillage selon la forme du contenu. Mode 1 (inline) : une map YAML portant directement des valeurs de paramètres imbriquées et structurées. Mode 2 (import de fichier) : une map YAML d’exactement une clé, $import: ./relative/path.yaml, pointant vers un seul fichier local qui fournit les valeurs des paramètres. Une seule source à cet endroit — la superposition sur plusieurs fichiers relève des chaînes extends: de Release (la Release parente fournit les paramètres de base ; l’enfant étend + surcharge). |
boundaries | map de boundary | non | Les boîtes logiques racines dans lesquelles les composants de l’Aggregate sont routés. Clés : une ou plusieurs lettres, chiffres, traits de soulignement ou traits d’union. Un point n’est pas autorisé. Motif : ^[a-zA-Z0-9_-]+$. |
components | map de boundary_component | non | Instances de composant de premier niveau portant l’infra par composant de l’opérateur, pour une Release à portée unique sans frontières nommées. Mutuellement exclusif avec boundaries : déclarez components pour une Release plate ou boundaries pour un routage vers plusieurs cibles, jamais les deux. Lorsque components est utilisé, le compilateur synthétise une frontière default qui les contient et émet leurs artefacts à plat dans dist/. Clés : une ou plusieurs lettres, chiffres, traits de soulignement ou traits d’union. Un point n’est pas autorisé. Motif : ^[a-zA-Z0-9_-]+$. |
Les propriétés supplémentaires ne sont pas autorisées.
Définitions
boundary_component
Une instance de composant routée dans une frontière, avec un dimensionnement physique et des rattachements de fonctionnalités facultatifs.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
description | string | non | Documentation facultative décrivant le rôle de ce composant dans cette frontière de la Release. |
subDirectory | string | non | Surcharge du sous-chemin au niveau Component, ajoutée au répertoire de la frontière parente. S’il est omis ou vide à la fois sur la frontière et sur le composant, il vaut par défaut ’{{ .capability }}’ ; une chaîne vide écrite ici est lue comme omise. Définissez-le sur ’.’, ou sur un template qui s’évalue en une chaîne vide, pour désactiver la génération de sous-répertoires. |
annotations | map de string ou object ou null | non | Annotations de l’Opérateur propres au Component qui remplacent, pour ce composant, les annotations au niveau de la frontière. Fusionnées en profondeur par-dessus les annotations de la frontière (le composant l’emporte en cas de collision de clés ; les valeurs structurées fusionnent sous-clé par sous-clé avec des parents structurés). Les valeurs sont des chaînes, des objets structurés ou null. Utilisées pour les surcharges, par composant, des annotations bien connues du fournisseur (par ex. aggrega.ai/namespace sur le fournisseur helm). Un null explicite sur une clé héritée de la frontière parente retire de ce composant la liaison héritée (renonciation à une Feature pilotée par annotation) ; les composants frères conservent la liaison héritée. |
infra | object | non | Dimensionnement physique strictement local à ce composant (par ex. réplicas, IOPS du disque). |
features | map de object | non | Les Features rattachées à ce composant via la Release. Pour les fonctionnalités également déclarées dans l’Aggregate, seul infra est fourni (les values proviennent de l’Aggregate). Pour les fonctionnalités propres à la Release (injectées par l’Opérateur), type est obligatoire. Les clés sont des noms d’instance de fonctionnalité et peuvent porter l’URI complet du type de fonctionnalité (points et barres obliques autorisés). La Release NE DOIT PAS fournir de values pour les fonctionnalités — c’est le domaine du Développeur. Clés : une ou plusieurs lettres, chiffres, traits de soulignement, points, barres obliques ou traits d’union. Motif : ^[a-zA-Z0-9_./-]+$. |
uses | release_uses_block | non | Surface d’arêtes de l’Opérateur. Dans les sockets déclarés par l’Architecte, la Release peut câbler un socket déclaré mais non lié vers un composant existant (target) et/ou fournir une infra par arête. Pas de values (l’interdiction de values: de la Release s’applique) et aucune création de ressources de calcul ; recibler une arête déclarée par le développeur provoque un arrêt au build. |
Les propriétés supplémentaires ne sont pas autorisées.
release_uses_block
Surface uses par arête rédigée dans la Release, indexée par socket puis par alias (reflétant la forme de la topologie uses de l’Aggregate). Chaque connexion peut définir target (pour créer une arête vers un socket déclaré mais non lié, pointant vers un composant existant), infra (configuration de l’opérateur par arête, validée par rapport à l’infraSchema du socket lorsque la Release est résolue) et features (rattachements qui remplissent les emplacements que le socket déclare), dans n’importe quelle combinaison. values est interdit (l’interdiction de values: de la Release) ; recibler une arête déclarée par le développeur est un garde-fou bien visible au build.
Clés : une ou plusieurs lettres, chiffres, traits de soulignement ou traits d’union. Un point n’est pas autorisé. Motif : ^[a-zA-Z0-9_-]+$.
Les valeurs sont map of object.
Aucune autre clé n’est autorisée.
release_connection_attachment
Un rattachement que porte une entrée de connexion d’une Release : la Feature qui remplit un emplacement déclaré par le socket de la connexion, avec le dimensionnement de l’opérateur pour celle-ci.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
type | string | non | L’URI de la Feature. Obligatoire pour un rattachement que seule la Release effectue. Doit correspondre au type de l’Aggregate si les deux le déclarent. |
description | string | non | Documentation facultative expliquant pourquoi l’Opérateur a rattaché cette fonctionnalité à la connexion. |
infra | object | non | Dimensionnement opérationnel pour ce rattachement, validé par la déclaration de schéma de la Feature. |
Les propriétés supplémentaires ne sont pas autorisées.
aggregate_routing
Route dans cette frontière les composants internes d’un sous-module Aggregate imbriqué. Reflète la structure component/aggregate de la frontière pour la composition récursive.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
components | map de boundary_component | non | Instances de Component au sein de l’agrégat imbriqué à router dans cette frontière. Les clés sont le nom local que chaque composant porte à l’intérieur de ce sous-module — ‘main-db’ pour le composant que la map components propre à une frontière désigne comme ‘data.main-db’ — car c’est le seul nom qu’il y porte. Clés : une ou plusieurs lettres, chiffres, traits de soulignement ou traits d’union. Un point n’est pas autorisé. Motif : ^[a-zA-Z0-9_-]+$. |
aggregates | map de aggregate_routing | non | Autres agrégats imbriqués au sein de ce sous-agrégat (pour une composition de modules profondément imbriqués). Clés : une ou plusieurs lettres, chiffres, traits de soulignement ou traits d’union. Un point n’est pas autorisé. Motif : ^[a-zA-Z0-9_-]+$. |
Les propriétés supplémentaires ne sont pas autorisées.
boundary
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
description | string | non | Documentation facultative décrivant l’objectif et la cible physique de cette frontière (par ex. ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’). |
directory | string | non | Chemin de sortie physique pour la génération des artefacts GitOps. Prend en charge les variables de template Go ({{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}). Combiné à subDirectory par une jonction de chemins pour produire le chemin final de l’artefact. |
subDirectory | string | non | Sous-chemin au niveau de la frontière, ajouté à directory. S’il est omis ou vide à la fois sur la frontière et sur le composant, il vaut par défaut ’{{ .capability }}’ pour le partitionnement automatique CI/CD ; une chaîne vide écrite ici est lue comme omise. Définissez-le sur ’.’, ou sur un template qui s’évalue en une chaîne vide, pour le désactiver. |
syncWave | integer | non | Vague de déploiement facultative par frontière (entier signé, 0 par défaut). Chaque composant de cette frontière hérite de la vague de la frontière dans son nœud. Les valeurs négatives sont autorisées (exécutées avant tout le reste) ; les valeurs plus grandes s’exécutent après les plus petites. Sur K8s et Helm, la vague est ce qui ordonne le déploiement : elle devient une annotation argocd.argoproj.io/sync-wave, et sur une ressource que le chart marque déjà comme hook Helm, elle devient aussi le helm.sh/hook-weight de ce hook. Sur compose, la vague est à la fois consignée comme label de service et utilisée pour ordonner les services du fichier dans lequel elle est rendue, au moyen de depends_on entre eux — elle atteint donc chaque service de ce seul fichier et rien en dehors. Sur cloudformation, la vague ordonne le provisionnement de la pile dans laquelle la frontière est assemblée : chaque ressource d’une vague est déclarée dépendante des ressources de la vague précédente, ce qui fixe l’ordre dans lequel elles sont créées et, à l’inverse, l’ordre dans lequel elles sont supprimées. Il s’agit uniquement de l’ordre de création et de suppression — un template de pile n’exprime aucune notion de ressource prête, de sorte que rien n’attend qu’une ressource devienne opérationnelle. Sur terraform, la vague ordonne les blocs module de la configuration racine dans laquelle la frontière est assemblée : chaque module d’une vague est déclaré dépendant des modules de la vague précédente, ce qui fixe l’ordre dans lequel le moteur effectue ses actions. Il s’agit uniquement de l’ordre des actions — une configuration n’exprime aucune notion de ressource prête, de sorte que rien n’attend qu’une ressource devienne opérationnelle — et la valeur est aussi consignée avec la provenance de build du nœud. Le compilateur reporte la même valeur sur chaque nœud de la frontière sous la forme du sync_wave de ce nœud, où le comportement par cible est décrit à nouveau du point de vue du nœud. Les frontières imbriquées n’héritent pas implicitement — chacune déclare sa propre vague. |
annotations | map de string ou object ou null | non | Annotations de l’Opérateur à l’échelle de la frontière, se propageant en cascade jusqu’au compartiment .context.annotations.release. Les valeurs sont des chaînes, des objets structurés ou null. Une valeur structurée porte une configuration par sous-clé qui fusionne en profondeur avec les parents structurés (par sous-clé, l’enfant l’emporte) et passe par l’expansion de Feature pilotée par annotation ; seules les valeurs scalaires apparaissent dans le contexte de rendu. Un null explicite sur une clé héritée d’une frontière parente retire la liaison héritée de l’ensemble effectif d’annotations de cette frontière (renonciation à une Feature pilotée par annotation), ce qui se propage à chaque composant routé dans cette frontière, à moins qu’une surcharge plus profonde ne réintroduise la liaison. |
features | map de object | non | Fonctionnalités à l’échelle de la frontière appliquées à tous les composants imbriqués (par ex. un mesh de sécurité par défaut). Le bloc uses d’une fonctionnalité se projette sur chaque composant de la frontière, déclarant une dépendance partagée une seule fois au niveau de la frontière au lieu de la répéter sur chaque composant. Les clés sont des noms d’instance de fonctionnalité et peuvent porter l’URI complet du type de fonctionnalité (points et barres obliques autorisés). Clés : une ou plusieurs lettres, chiffres, traits de soulignement, points, barres obliques ou traits d’union. Motif : ^[a-zA-Z0-9_./-]+$. |
boundaries | map de boundary | non | Frontières logiques imbriquées (par ex. des namespaces au sein d’un cluster). Clés : une ou plusieurs lettres, chiffres, traits de soulignement ou traits d’union. Un point n’est pas autorisé. Motif : ^[a-zA-Z0-9_-]+$. |
components | map de boundary_component | non | Quels composants de l’Aggregate sont placés dans cette frontière. Les clés sont des noms d’instance de composant ; le composant d’un sous-agrégat est désigné par son chemin pointé qualifié (par ex. ‘data.main-db’ — le nom de l’instance d’agrégat, un point, le nom du composant). Clés : une ou plusieurs lettres, chiffres, traits de soulignement, points ou traits d’union. Motif : ^[a-zA-Z0-9_.-]+$. |
aggregates | map de aggregate_routing | non | Route dans cette frontière les composants des sous-modules Aggregate imbriqués. Les clés sont des noms d’instance d’agrégat correspondant à la map spec.aggregates de l’Aggregate. Toutes les instances d’agrégat doivent être placées dans exactement une frontière si des frontières sont définies. Clés : une ou plusieurs lettres, chiffres, traits de soulignement ou traits d’union. Un point n’est pas autorisé. Motif : ^[a-zA-Z0-9_-]+$. |
Les propriétés supplémentaires ne sont pas autorisées.
uses_block
La topologie structurelle - détenue par le Développeur. Déclare les arêtes réseau logiques et les dépendances.
Clés : une ou plusieurs lettres, chiffres, traits de soulignement ou traits d’union. Un point n’est pas autorisé. Motif : ^[a-zA-Z0-9_-]+$.
Les valeurs sont string[] or map of object.
Aucune autre clé n’est autorisée.
inject_block
Routage agnostique de l’injection sur une connexion. Associe des variables locales aux clés provides de la cible. Chaque mécanisme de livraison (env, file, arg ou personnalisé) s’écrit sous forme de tableau d’entrées {in, from} — ‘from’ explicite pour les références à provides. Un mécanisme personnalisé peut porter n’importe quel nom sauf all : un template lit tous les mécanismes fusionnés en une seule vue dans .context.inject.all, de sorte qu’un mécanisme portant ce nom serait masqué par elle, et en nommer un arrête le build.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
env | inject_delivery | non | Un mécanisme de livraison unique, écrit sous forme de tableau d’entrées. Chaque entrée porte un ‘in’ (identifiant local — nom de variable d’environnement, chemin de fichier, flag d’argument ou clé personnalisée propre au mécanisme) plus exactement un parmi ‘from’ (une clé provides à résoudre) ou ‘value’. Dans une Release, chaque entrée se trouve sur une connexion, de sorte que ‘from’ se résout par rapport aux provides de la cible et qu’une entrée portant ‘value’ est refusée. |
file | inject_delivery | non | Un mécanisme de livraison unique, écrit sous forme de tableau d’entrées. Chaque entrée porte un ‘in’ (identifiant local — nom de variable d’environnement, chemin de fichier, flag d’argument ou clé personnalisée propre au mécanisme) plus exactement un parmi ‘from’ (une clé provides à résoudre) ou ‘value’. Dans une Release, chaque entrée se trouve sur une connexion, de sorte que ‘from’ se résout par rapport aux provides de la cible et qu’une entrée portant ‘value’ est refusée. |
arg | inject_delivery | non | Un mécanisme de livraison unique, écrit sous forme de tableau d’entrées. Chaque entrée porte un ‘in’ (identifiant local — nom de variable d’environnement, chemin de fichier, flag d’argument ou clé personnalisée propre au mécanisme) plus exactement un parmi ‘from’ (une clé provides à résoudre) ou ‘value’. Dans une Release, chaque entrée se trouve sur une connexion, de sorte que ‘from’ se résout par rapport aux provides de la cible et qu’une entrée portant ‘value’ est refusée. |
inject_delivery
Un mécanisme de livraison unique, écrit sous forme de tableau d’entrées. Chaque entrée porte un ‘in’ (identifiant local — nom de variable d’environnement, chemin de fichier, flag d’argument ou clé personnalisée propre au mécanisme) plus exactement un parmi ‘from’ (une clé provides à résoudre) ou ‘value’. Dans une Release, chaque entrée se trouve sur une connexion, de sorte que ‘from’ se résout par rapport aux provides de la cible et qu’une entrée portant ‘value’ est refusée.
Type : object[]