WorkloadLibrary
Une WorkloadLibrary est une entité de catalogue qui contient des fragments de template de Workload réutilisables. Les Recipes et les FeatureRecipes qui déploient la même forme de charge de travail — un serveur exposant des métriques, un job batch, une paire avec sidecar — déclarent cette forme une seule fois dans une bibliothèque et la référencent au moment de la consommation par une directive workload: { $import: ... }. L’entité bibliothèque relève du niveau 3 : facultative, pour les catalogues qui ont besoin de réutiliser des charges de travail d’une Recipe à l’autre. Les catalogues dont les Recipes portent chacune leur propre forme de charge de travail distincte sont livrés sans aucune WorkloadLibrary.
Le rôle de la WorkloadLibrary
Les architectes de plateforme rédigent des WorkloadLibraries pour centraliser le contenu de Workload qui revient dans les Recipes et les FeatureRecipes du catalogue. Une bibliothèque n’est pas une instruction de build déployable ; c’est un espace de noms de définitions. Les auteurs de Recipe et de FeatureRecipe référencent les entrées de la bibliothèque par une directive $import:, écrite une fois et consommée partout où l’import se résout.
La séparation entre « bibliothèque » et « consommateur » est intentionnelle. Les Recipes encodent des instructions de build (source, valuesMapping, artifacts). Les FeatureRecipes encodent des rattachements comportementaux. Les WorkloadLibraries n’encodent que du contenu de Workload — la forme de charge de travail que le fournisseur synthétise en manifestes natifs du fournisseur. Garder les trois rôles distincts permet à chaque type d’entité d’évoluer à son propre rythme ; les auteurs qui n’ont pas besoin de contenu de charge de travail partagé ne rencontrent jamais l’entité bibliothèque.
Enveloppe de l’entité
Une entité WorkloadLibrary porte l’enveloppe de catalogue standard. apiVersion: aggrega.ai/v1beta1 et kind: WorkloadLibrary marquent le type d’entité ; metadata.name est un identifiant en PascalCase ; metadata.version suit strictement le versionnage sémantique. Les deux sont obligatoires. metadata.description, metadata.labels et metadata.annotations sont facultatifs — les labels et les annotations sont des métadonnées opaques déclarées par l’auteur, portées pour que tout ce qui lit la bibliothèque puisse s’en servir pour la correspondance, et le compilateur n’interprète pas leurs valeurs. Le contenu de la bibliothèque se trouve sous spec.workloads, une map obligatoire qui doit déclarer au moins une entrée.
L’enveloppe est fermée aux trois niveaux — la racine du document, metadata et spec rejettent chacun les clés que le schéma ne déclare pas.
apiVersion: aggrega.ai/v1beta1kind: WorkloadLibrarymetadata: name: BaseWorkloads version: 1.0.0spec: workloads: SimpleServer: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra `replicas` 2 }} containers: app: image: "{{ .values.image }}" ports: web: {{ optional .values `port` 8080 }} services: http: type: ClusterIP ports: web: {{ optional .values `port` 8080 }}Rédiger les entrées Workload
Chaque entrée est un fragment de template Go rédigé sous forme de chaîne YAML. La sortie rendue de l’entrée est un document Workload complet — il porte ses propres apiVersion: aggrega.ai/v1beta1 et kind: Workload — parce que le champ workload: d’une Recipe accepte un Workload complet, et non un fragment inséré dans un Workload englobant, et que l’import remplace le champ entier. Une entrée de MappingLibrary est complète de la même manière : en importer une remplace l’intégralité du valuesMapping: de la Recipe.
Le corps est opaque pour l’enveloppe de l’entité. Le compilateur stocke la chaîne telle quelle au chargement de la WorkloadLibrary et n’y analyse pas le template ; l’analyseur de templates s’exécute au moment de la consommation, lorsqu’une Recipe ou une FeatureRecipe importe l’entrée. Stocker le fragment tel quel préserve la fidélité de rédaction pour la réémission, et fait qu’une erreur de template apparaît là où l’entrée est consommée et où son contexte de piliers est connu, plutôt qu’au niveau de la bibliothèque.
Comme un document Workload s’étend sur plusieurs lignes, les entrées utilisent le scalaire de style littéral de YAML (|) afin que les retours à la ligne et l’indentation survivent à l’aller-retour :
spec: workloads: BatchJob: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: task containers: worker: image: "{{ .values.image }}" command: ["{{ .values.entrypoint }}"]La valeur d’une entrée doit être un scalaire de type chaîne. Écrire un mapping ou une séquence là où le corps est attendu est refusé — le corps de l’entrée est du texte de template, pas du YAML structuré que le compilateur parcourt.
Le vocabulaire de composition complet des templates Go est disponible dans une entrée : {{ define "name" }}...{{ end }} déclare des blocs réutilisables au sein d’une même bibliothèque, {{ template "name" . }} les invoque, et les pipelines et les fonctions suivent le package standard Go text/template. Le contexte de piliers qu’une entrée peut lire — .values, .infra, .locals, .context, .features — est le même contexte que lit tout template de Workload, et il est documenté sur la page Workload, à la section sur l’évaluation des templates.
Le fournisseur cible doit prendre en charge la synthèse de charge de travail. Une Recipe qui importe une entrée de bibliothèque mais se lie à un fournisseur incapable de synthétiser un Workload s’arrête explicitement au moment du rendu au lieu d’émettre une forme dégradée ; le catalogue de la bibliothèque standard déclare workloadSchema sur les fournisseurs qui la prennent en charge, en tant que contrat documenté.
Un mode de rédaction unique
La WorkloadLibrary est livrée avec un seul mode de rédaction : les templates Go. spec n’accepte aucune surface de rédaction parallèle ni aucune porte de sortie d’expressivité au niveau de la bibliothèque.
La raison en est l’uniformité de la surface de consommation. Les Recipes et les FeatureRecipes sont entièrement en templates Go, et leur propre contenu est évalué par le même moteur de templates Go qui résout un fragment importé. Une surface de rédaction parallèle obligerait les auteurs à changer de modèle d’évaluation au sein du rendu d’une seule Recipe — un modèle pour le contenu propre de la Recipe, un autre pour chaque entrée de bibliothèque importée. Garder la surface uniforme signifie que les auteurs apprennent un seul modèle d’évaluation et l’appliquent partout.
Les auteurs qui ont besoin d’une expressivité dépassant le vocabulaire de composition des templates Go composent à un niveau supérieur — des Components ou des Features qui enveloppent les entrées de la bibliothèque avec leur propre variation substantielle — plutôt que de passer à un second langage de rédaction à l’intérieur de la bibliothèque.
Conventions de nommage
Les noms de bibliothèque et les clés des entrées de charge de travail suivent le PascalCase. Le JSON Schema de l’enveloppe de l’entité impose la convention à deux endroits au moyen de contraintes de motif :
metadata.namecorrespond à^[A-Z][A-Za-z0-9]*$.- Les clés de la map
spec.workloadsrespectent le même motif viapropertyNames.
Une WorkloadLibrary dont une clé de spec.workloads n’est pas en PascalCase échoue à la validation de l’enveloppe au chargement de l’espace de travail. Cette vérification est essentielle : les clés des entrées de charge de travail apparaissent dans le fragment de référence #/workloads/<name>, si bien qu’une clé qui n’est pas en PascalCase se propagerait à chaque consommateur qui importe l’entrée.
L’uniformité des noms garde le fragment #/workloads/<name> lisible : #/workloads/BatchJob se lit d’un coup d’œil.
Faire référence aux entrées de bibliothèque
Les auteurs de Recipe et de FeatureRecipe référencent une entrée de charge de travail dans un bloc workload: { $import: ... } par son identité de nom simple :
# Inside a Recipe's spec:spec: workload: $import: "BaseWorkloads#/workloads/SimpleServer"Le fragment #/workloads/<name> sélectionne l’entrée et distingue une référence de charge de travail du #/mappings/<name> de la MappingLibrary et du #/schemas/<name> de la SchemaLibrary. La référence ne porte aucun hôte de registre ; une forme oci://… comportant un hôte est refusée à la fois par le schéma de l’enveloppe et au point de consommation, de sorte qu’un emplacement physique de registre n’entre jamais dans la source rédigée. Un auteur peut affirmer un plancher de version minimale facultatif sous la forme <Library>:<version>#/workloads/<name> — le séparateur de version est :, comme pour les mappings recipe/feature et le pin du lockfile, et écrire @ à la place est refusé avec un diagnostic indiquant la référence corrigée. La version résolue est fournie par le lockfile propre à chaque Release, qui épingle chaque bibliothèque consommée par nom, version et digest du contenu ; l’emplacement physique est lié au moment de la résolution.
Le même champ workload: accepte deux autres formes — une chaîne de template Go en ligne, et un $import: d’un chemin de fichier local relatif au répertoire de la Recipe. Les trois formes se distinguent par la forme du contenu, et toutes trois produisent le même Workload après analyse. Voir Recipe pour la façon dont workload: se compose avec les autres types d’entrée de la Recipe, et vocabulary/cross-document-ref pour la distinction plus large $ref: / $import:.
Composition entre bibliothèques
Une entrée de WorkloadLibrary peut être une redirection $import: à la racine du champ : le premier jeton de son corps est $import: <Library>#/workloads/<entry>, qui remplace l’entrée entière par le contenu de l’entrée référencée — réutilisation par identité, et non templating sur place. La redirection se résout au moment de la consommation, pas au chargement de la WorkloadLibrary, et elle se résout récursivement, de sorte qu’une entrée importée peut elle-même être un $import: à la racine du champ. Une chaîne qui reboucle sur elle-même s’arrête avec un diagnostic nommant le cycle. $import: porte uniquement sur l’entrée entière ; ce n’est pas une fonction de template utilisable au milieu d’un fragment. Pour composer du texte de template à l’intérieur d’une même entrée, utilisez define / template des templates Go.
# In library A — alias an entry to a shared entry in another library:spec: workloads: StandardServer: | $import: PlatformWorkloads#/workloads/MetricsServerUn nom de bibliothèque inconnu, et un nom d’entrée absent d’une bibliothèque qui, elle, se résout, sont signalés par des diagnostics distincts, afin qu’un auteur puisse distinguer une dépendance manquante d’une entrée mal orthographiée.
Placement dans les tiers
La WorkloadLibrary est de niveau 3 dans le modèle de documentation par niveaux d’entités — facultative pour les catalogues qui ont besoin d’une réutilisation de charge de travail inter-Recipe. Les catalogues dont les Recipes portent leur propre contenu de charge de travail distinct sont livrés sans aucune entité WorkloadLibrary ; le marquage de niveau signale « avancé ; à ignorer si inutile » pour la navigation dans la documentation, pas pour la capacité. Le compilateur traite la WorkloadLibrary de manière uniforme avec les autres types d’entités du catalogue : même validation de l’enveloppe au chargement de l’espace de travail, même pipeline de publication OCI à la sortie d’une version, même épinglage dans le lockfile par nom, version et digest du contenu.
Le type de bibliothèque fait partie d’un ensemble au niveau du catalogue — la SchemaLibrary contient des définitions de schéma réutilisables, la MappingLibrary des fragments de mapping réutilisables, l’ArtifactLibrary des lots d’artefacts réutilisables, la WorkloadLibrary du contenu de charge de travail réutilisable. Chacun est facultatif indépendamment des autres ; les catalogues livrent ceux dont ils ont besoin et aucun des autres.
Ce que la WorkloadLibrary n’est pas
Quelques idées reçues courantes à écarter :
-
Pas un substitut au
workload:en ligne. La plupart des Recipes portent un contenu de charge de travail suffisamment spécifique pour avoir sa place en ligne, là où l’auteur le lit avec le reste de la Recipe. Une WorkloadLibrary est utile lorsque la MÊME forme de charge de travail apparaît dans de nombreuses Recipes ; pour un contenu ponctuel, la rédaction en ligne est le bon choix. -
Pas un lieu pour des fragments partiels. Une entrée est rendue en un document Workload complet. Le document de valeurs d’une Recipe a sa place dans une MappingLibrary, un ensemble de fichiers auxiliaires dans une ArtifactLibrary, et les définitions de schéma dans une SchemaLibrary. Les types de bibliothèque se répartissent par type de contenu, pas par modèle de réutilisation.
-
Pas une entité déployable indépendamment. Une entrée de bibliothèque est du contenu Workload, et le contenu Workload n’est jamais adressable seul — il existe en tant que donnée d’entrée qu’une Recipe ou une FeatureRecipe consomme. Publier une WorkloadLibrary rend ses entrées importables ; cela ne les rend pas déployables.
-
Pas une réutilisation paramétrique au-delà des mécanismes des templates Go. Les auteurs qui ont besoin de variation paramétrique utilisent les mécanismes
{{ define }}+{{ template }}des templates Go dans les entrées de bibliothèque, ou le contexte de piliers que fournit la Recipe consommatrice. L’entité de bibliothèque elle-même ne livre aucun mécanisme d’assistants paramétriques.