Vue d’ensemble de la référence des entités
Le vocabulaire d’écriture d’Aggrega comprend Aggregate, Component, Feature, Recipe, FeatureRecipe, Plugin, Manifest, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary et ArtifactLibrary — plus le type Workload, propriété de la plateforme, intégré à l’entrée synthétisée d’une Recipe. Chaque entité est un document YAML conforme à un JSON Schema ; chaque champ, mot-clé et référence entre entités que décrit cette référence fait partie de ce contrat d’écriture.
Cet ensemble de chapitres couvre la surface d’écriture : les champs qu’accepte chaque entité, ce que chaque champ signifie pour l’auteur, la manière dont les champs interagissent entre entités (le implements: d’une Recipe qui nomme le Component qu’elle implémente, le pointeur manifest: d’une Release vers un Manifest, les containers.<name>.attachments d’un Workload qui référencent des slots déclarés dans le featuresSchema du Component). Le rôle conceptuel de chaque entité — pourquoi la taxonomie a la forme qu’elle a, quel domaine possède quelle entité, comment les quatre domaines séparent les préoccupations d’écriture — est décrit dans ../architecture/04-entity-taxonomy.md. Le rôle architectural du type Workload, l’un des trois types d’entrée d’une Recipe, est décrit dans ../architecture/16-recipe-input-composition.md.
Organisation de cette référence
Deux surfaces documentent le vocabulaire d’écriture, et elles répondent à des questions différentes.
Chaque type listé ci-dessus dispose d’une référence de schéma générée. Ces pages sont générées à partir des schémas que le compilateur lui-même publie, et schema/README.md en indexe l’ensemble complet — types d’entités, formes de transmission des plugins et fichiers de workspace. Consultez la référence de schéma pour répondre à « que peut contenir ce document ? » : chaque champ, son type, s’il est obligatoire et les contraintes que l’enveloppe impose.
Les pages ci-dessous sont les guides d’écriture. Elles sont écrites à la main pour enseigner ce que le schéma ne peut pas : à quoi sert un type, comment ses champs interagissent avec d’autres types, quelle forme d’écriture convient à quelle situation, et les conventions que suit le catalogue de la bibliothèque standard. Consultez un guide d’écriture pour répondre à « comment en écrire un, et pourquoi a-t-il cette forme ? ».
Référence par entité
- Aggregate — l’artefact d’intention déclarative du développeur. Déclare les composants, leur topologie via
uses, les contrats de paramètres pour la variation par environnement et les attachements de Feature. - Component — entité de catalogue écrite par le Platform Architect, qui définit un type de composant réutilisable. Déclare ses schémas
valuesetinfra(chacun étant une déclaration JSON Schema 2020-12 en forme compacte ou complète), son contrat de sortieprovides, son contrat d’arêtes entrantesusesSchemaet ses slots d’identifiants viafeaturesSchema. - Feature — entité de catalogue écrite par le Platform Architect pour une préoccupation transversale (sidecar de supervision, masquage de données, politique de routage). Déclare ses schémas
valuesetinfra(chacun étant une déclaration JSON Schema 2020-12), ses sélecteurs d’attachementappliesToet ses contraintes d’interopérabilité. - Recipe — traduction écrite par Ops d’un Component vers un provider spécifique. Compose trois types d’entrée (
source:+valuesMapping:,workload:,artifacts:— chacun acceptant du contenu en ligne ou$import:selon le vocabulaire unifié d’import de fichiers) plus un blocprovidesqui forme le contrat d’injection vers l’appelant. - FeatureRecipe — traduction écrite par Ops d’une Feature vers un provider spécifique. Utilise le même contrat à trois types d’entrée que la Recipe, plus un
injectMappingqui intercepte le pipe d’injection pour réécrire les variables côté appelant. - Plugin — plugin WebAssembly adressé par contenu. Déclare l’unique type de socket qu’il implémente —
provider,linter,pipeline-step,governance,cli,parserouimporter—, sa version d’ABI et les capacités que sert ce type de socket. Un Plugin de rendu de provider (pluginType: provider) déclare le ou les noms de provider qu’il sert dansspec.provider.capabilitieset porte les métadonnées de son socket de provider —workloadSchemaetwellKnownAnnotations— dans ce même blocspec.provider. - Manifest — table de mapping par projet. Lie les types abstraits Component et Feature à des URI concrets de Recipe et de FeatureRecipe, sous
componentsetfeatures, avec un ordre de recherchename>typeversionné >typenon versionné. - Release — routeur de déploiement par environnement. Lie un Aggregate à un Manifest, répartit les composants dans des frontières physiques, fournit les valeurs de paramètres par environnement et attache les Features gérées par Ops.
Entités de bibliothèque
Les quatre types de bibliothèque relèvent du niveau 3 — des entités de réutilisation facultatives. Un catalogue en déclare une lorsque le même contenu revient dans ses entités, et s’en passe sinon. Chacune contient un seul type de contenu, et le fragment d’une référence (#/schemas/, #/mappings/, #/workloads/, #/artifacts/) indique quelle bibliothèque une référence désigne.
- SchemaLibrary — définitions JSON Schema 2020-12 réutilisables plus helpers paramétrés facultatifs, référencés depuis les schémas d’un Component ou d’une Feature par
$ref: <Library>#/schemas/<name>. - MappingLibrary — fragments de templates Go réutilisables, importés dans le
valuesMapping:d’une Recipe ou d’une FeatureRecipe par$import: <Library>#/mappings/<name>. - WorkloadLibrary — contenu Workload réutilisable, importé dans le
workload:d’une Recipe ou d’une FeatureRecipe par$import: <Library>#/workloads/<name>. - ArtifactLibrary — lots réutilisables de fichiers de sortie auxiliaires, importés dans les
artifacts:d’une Recipe ou d’une FeatureRecipe par$import: <Library>#/artifacts/<name>. Un lot est l’unité de réutilisation : un import se développe en une sortie par fichier du lot.
Types propriété de la plateforme
- Workload — type du compilateur, propriété de la plateforme (et non une entité de catalogue écrite par l’utilisateur). Intégré au champ
workload:d’une Recipe (en ligne ou via$import:) ; décrit la forme de déploiement que le provider synthétise en manifestes natifs du provider.