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

Architecture des Provider

Un fournisseur effectue le rendu des types d’entrée d’une Recipe en fichiers manifestes natifs du fournisseur. Lorsqu’une Recipe déclare capability: helm, capability: compose ou tout autre nom de fournisseur, le compilateur distribue le rendu au fournisseur qui sert ce nom. Ce chapitre explique comment un fournisseur est réalisé sous la forme d’un Plugin de rendu de fournisseur, comment fonctionne la distribution, et le contrat du socket de plugin qui lie le compilateur à chaque fournisseur.

Ce que ce chapitre ne couvre pas : le modèle de composition à trois types d’entrée (source: + valuesMapping:, workload:, artifacts: — chacun acceptant un contenu en ligne ou $import:) qu’une Recipe utilise pour produire sa sortie. Ce modèle est transversal à tous les fournisseurs et se trouve dans ../../architecture/16-recipe-input-composition.md, y compris la Matrice des capacités par Provider qui indique quel type d’entrée chaque fournisseur prend en charge.

Le Plugin de rendu de fournisseur

Le rendu Provider est assuré par un Plugin avec pluginType: provider. Le Plugin de rendu de fournisseur :

  • sert un ou plusieurs noms de fournisseur — déclarés dans spec.provider.capabilities. Le nom de fournisseur qu’une Recipe nomme (spec.capability: helm) se lie au Plugin de rendu de fournisseur dont la liste spec.provider.capabilities inclut ce nom. Lorsque plus d’un Plugin sert la même cible, l’espace de travail choisit entre eux au moyen d’une liaison de fournisseur dans .aggrega-config.yaml, résolue lors de aggrega pull et enregistrée dans le fichier de verrouillage ; sans liaison et avec exactement un candidat, ce candidat est utilisé, et sans liaison et avec plus d’un candidat, le build s’arrête bruyamment en nommant les plugins candidats.
  • porte ses métadonnées de socket de fournisseur dans le même bloc — spec.provider contient la liste de capacités ci-dessus à côté du reste des déclarations du fournisseur. spec.provider.workloadSchema est une déclaration JSON Schema 2020-12 qui documente la façon dont le type Workload, propriété de la plateforme, se traduit dans la sortie native de ce fournisseur ; le catalogue de la bibliothèque standard la déclare sur les fournisseurs qui synthétisent, comme contrat de traduction documenté. spec.provider.wellKnownAnnotations énumère les annotations de frontière aggrega.ai/ que lit le fournisseur. La prise en charge des entrées synthétisées (workload:) est une propriété du fournisseur, appliquée au moment du rendu — et non déterminée par la présence de workloadSchema.

Voir ../entities/plugin.md pour la surface de rédaction complète, au niveau des champs, de l’entité Plugin, y compris le bloc spec.provider.

Distribution par fournisseur

Chaque Recipe déclare exactement un capability: en tête de son spec. Le compilateur lit ce champ et distribue le rendu au fournisseur qui sert le nom. Une Recipe ne peut pas cibler plusieurs fournisseurs à la fois. La composition multi-fournisseur a lieu au niveau de la Release : une frontière peut contenir des composants de fournisseurs différents, et les contributeurs de chaque fournisseur au chemin d’assemblage évalué de la frontière sont assemblés indépendamment — un assemblage par tuple (path, provider).

Le chemin de distribution pour un seul nœud :

  1. Le compilateur résout l’URI de la Recipe pour ce nœud au moyen de la recherche à trois niveaux du Manifest dans la section de mapping du fournisseur cible. C’est le regroupement selon l’axe des fournisseurs du Manifest qui fait de « le même Component, des Recipes différentes pour des fournisseurs différents » un modèle naturel.
  2. Le spec.capability de la Recipe résolue identifie le nom de fournisseur vers lequel distribuer.
  3. Le compilateur lie le fournisseur pour ce nom : il résout le Plugin de rendu de fournisseur dont la liste spec.provider.capabilities inclut le nom, et effectue le rendu au moyen du guest de ce Plugin. Le rendu est exclusivement Wasm — il n’existe aucun moteur de rendu dans l’hôte sur lequel se replier, si bien qu’un nom de fournisseur qui ne se résout vers aucun Plugin qui le sert arrête bruyamment le build au moment du routage.
  4. Le fournisseur est invoqué avec le contexte de rendu par nœud (valeurs des piliers, projections .context.*, types d’entrée de la Recipe).
  5. Le fournisseur renvoie la sortie rendue. Le compilateur achemine les fichiers rendus vers l’assembleur par (path, provider) indexé sur le directory: évalué de la frontière joint au subDirectory: par composant. Deux frontières qui s’évaluent au même chemin sous le même fournisseur partagent un assembleur — le modèle canonique est une frontière parente plus deux frontières enfants avec directory: "{{ .parent_boundary.directory }}", qui se réunissent en un seul assemblage fusionné.

Voir ../entities/manifest.md pour la forme de distribution selon l’axe des fournisseurs du Manifest, et ../entities/recipe.md pour la déclaration d’un fournisseur unique côté Recipe. Le modèle d’assemblage par (path, provider) et la liste autorisée des variables de template de chemin qui contrôle les chemins évalués sont documentés dans ../path-template-variables.md.

Le contrat des plugins Wasm

Le rendu Provider s’exécute dans un bac à sable WebAssembly. Le compilateur Go est l’hôte ; le Plugin de rendu de fournisseur est le guest. Pour chaque nœud, le compilateur remet au plugin le contexte de rendu du nœud, et le plugin renvoie les fichiers qu’il a rendus. Ce contrat est uniforme pour tous les fournisseurs :

  • Un encodage binaire canonique dans les deux sens. Le compilateur encode le contexte de rendu — les valeurs et les rattachements du nœud, le .workload analysé, les entrées d’artefact évaluées, la liste des seuls noms d’un .source résolu et les métadonnées de la frontière — en CBOR canonique (RFC 8949 §4.2.1) et le remet au plugin. Le plugin répond dans le même encodage avec la liste des fichiers qu’il a rendus — chacun sous la forme d’un chemin relatif à la racine de sortie du nœud et des octets exacts à y écrire, éventuellement avec le format du fichier — à côté d’éventuels diagnostics. Chaque export du socket, du rendu d’un nœud à l’assemblage d’une frontière et au câblage d’un lien entre frontières, porte cet encodage dans les deux sens, et le kit de développement de plugins de chaque langage le décode et l’encode pour le plugin. Une réponse qui n’a pas la forme de sortie de l’export dans cet encodage arrête le build. Le contrat des plugins documente la charge utile de chaque export.
  • Aucun accès au système de fichiers. Les Plugins ne peuvent pas lire de fichiers arbitraires depuis le système de fichiers de l’hôte. Une source qu’une Recipe nomme — un chart dans un registre, un module dans un dépôt — est résolue par le compilateur avant l’exécution du plugin ; le plugin en reçoit une liste des seuls noms et demande au compilateur les fichiers qu’il sélectionne au moyen d’une fonction hôte, qui ne répond que pour les fichiers situés sous la source de ce nœud.
  • Aucun accès réseau. Les Plugins sont déterministes et hermétiques, et n’ouvrent aucune connexion propre. Une entrée externe dont un plugin a besoin pendant le rendu — un schéma distant auquel les valeurs d’un chart font référence — est demandée au moyen de la fonction hôte d’entrées externes du compilateur, qui répond à partir du contenu que l’espace de travail a épinglé pour cette référence.
  • Sortie déterministe. À entrée identique et avec la même version de plugin, un plugin doit produire une sortie identique octet pour octet. C’est le contrat qui fait que la garantie de sortie identique octet pour octet du compilateur tient de bout en bout à travers la couche des plugins. Un build lancé avec --verify-determinism effectue le rendu de chaque nœud deux fois et s’arrête lorsque les deux rendus d’un nœud diffèrent.

L’architecture des sockets de plugin au niveau plus large de l’extensibilité, y compris les autres sockets Wasm du pipeline de compilation (les rôles de transformation et de verdict du socket de gouvernance), se trouve dans ../../architecture/14-extensibility.md.

Les fournisseurs de la bibliothèque standard d’Aggrega

Les fournisseurs helm, helm-chart, compose, terraform et cloudformation forment ensemble le jeu de fournisseurs de la bibliothèque standard. Ils couvrent les cibles de déploiement courantes sans que les équipes d’entreprise aient à créer leurs propres fournisseurs.

helm prend en charge les trois types d’entrée : issu d’une source (un chart Helm amont récupéré au moyen du SDK Helm, avec la sortie du valuesMapping de la Recipe comme surcharges du chart), synthétisé (YAML Kubernetes plat — un objet contrôleur choisi par le form du Workload (Deployment, StatefulSet, DaemonSet, Job ou CronJob) plus des Services et des PVC — émis à partir d’un Workload analysé) et artefacts (fichiers YAML autonomes à côté de la sortie du chart). Voir la Matrice des capacités par Provider dans ../../architecture/16-recipe-input-composition.md pour savoir lesquels des trois types il accepte.

helm-chart prend en charge le mode issu d’une source (composition en chart parapluie : un chart par frontière, un sous-chart par composant) et des artifacts: qui l’accompagnent, dans les deux formes de rédaction. Une entrée artifacts: chargée par $import: est d’abord traitée par Aggrega comme template Go, puis injectée dans le répertoire templates/ du chart avant le rendu ; une entrée artifacts: à contenu en ligne est évaluée de la même façon et placée à la racine du sous-chart, sans provenance fusionnée, où les propres templates du chart la lisent via .Files.Get / .Files.Glob de Helm. Une Recipe autonome composée uniquement d’artefacts ne fait pas partie des types qu’il déclare, pas plus que le type synthétisé : le chart parapluie orchestre des sous-charts, tandis que le type Workload est un concept feuille qui appartient à chaque sous-chart (le domaine du fournisseur helm).

compose prend en charge issu d’une source (charge un fichier compose et y fusionne en profondeur la surcouche du valuesMapping), synthétisé (émet les services: + volumes: + networks: de compose à partir d’un Workload analysé pour les formes stateless et stateful, avec une gestion dégradée des volumes pour persistentTemplate — les PVC par réplique se réduisent à un seul volume nommé partagé, avec un avertissement ; les formes daemon, scheduled et task n’ont aucune correspondance compose et s’arrêtent bruyamment) et artefacts (fragments compose dont les clés de premier niveau services: / networks: / volumes: / configs: sont fusionnées dans le docker-compose.yaml combiné par frontière). Les artefacts peuvent accompagner l’un ou l’autre des deux autres types, et une Recipe autonome composée uniquement d’artefacts — artifacts: sans source: ni workload: — est aussi un type que ce fournisseur déclare : ses fragments fusionnent selon les mêmes règles, de sorte que le nœud apporte exactement ce qu’il déclare et n’a besoin d’aucun Workload tenant lieu de ressources de calcul qu’il n’a pas.

terraform prend en charge issu d’une source (intègre un module Terraform tel quel et fournit la sortie du valuesMapping comme arguments du bloc module de ce composant dans la configuration racine de la frontière) et artefacts (émet un corps HCL ou .tf.json rédigé tel que son template l’évalue, sans le réécrire). Il ne propose pas le type d’entrée synthétisé — il n’existe aucune correspondance fidèle entre le type Workload de la plateforme et des ressources Terraform arbitraires. Le fournisseur émet de la configuration et n’exécute jamais Terraform ; les valeurs dépendant de l’exécution restent sous forme de chaînes d’interpolation ${ ... } que l’environnement d’exécution Terraform résout au moment de l’apply.

cloudformation effectue le rendu d’une frontière en un seul template de stack AWS CloudFormation, en assemblant les fragments de ressources que rédigent ses composants en un seul template en JSON pur, en exposant les provides de chaque composant comme Outputs de la stack, et en câblant les arêtes uses comme Fn::GetAtt au sein d’une stack et comme Fn::ImportValue / Fn::GetStackOutput entre stacks. Il prend en charge les entrées issues d’une source et les entrées artefacts, et émet de la configuration sans jamais exécuter CloudFormation ; les valeurs connues uniquement à l’exécution restent des fonctions intrinsèques CloudFormation.

L’index de référence des Provider vous oriente vers la page de référence propre à chaque fournisseur ; les types d’entrée que chacun accepte sont indiqués par la matrice des capacités dans ../../architecture/16-recipe-input-composition.md.

Fournisseurs personnalisés

Les équipes d’entreprise qui créent leurs propres fournisseurs suivent le même schéma que la bibliothèque standard : rédiger un Plugin de rendu de fournisseur (pluginType: provider) déclarant dans spec.provider.capabilities le ou les noms de fournisseur qu’il sert, à côté du reste de ses métadonnées spec.provider, puis livrer l’artefact Wasm qui implémente le contrat de rendu décrit ci-dessus. Le compilateur traite les fournisseurs personnalisés de la même manière que les fournisseurs de la bibliothèque standard ; la distribution par fournisseur s’appuie sur le nom de fournisseur déclaré par la Recipe.

La création d’un fournisseur est documentée plutôt que reportée. Créer un fournisseur construit de bout en bout un guest de fournisseur fonctionnel — l’auto-description describe(), le build, l’entité Plugin, le rattachement et un rendu dont vous pouvez lire la sortie. Le Guide du développeur de plugins Wasm est la référence pour l’entité et le cycle de vie de publication, et le contrat des plugins documente les formes de charge utile et de résultat de chaque socket. Les guests sont rédigés en Go, Rust ou TypeScript avec le kit de développement de plugins.