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

MappingLibrary

Une MappingLibrary est une entité de catalogue qui contient des fragments de template Go réutilisables. Les Recipes et FeatureRecipes qui partagent un document valuesMapping: entier — les valeurs que plusieurs Recipes s’appuyant sur le même chart lui transmettent chacune — le déclarent une fois dans une bibliothèque et y font référence au moment de la consommation via une directive valuesMapping: { $import: ... }. L’entité bibliothèque relève du niveau 3 : facultative, pour les catalogues qui ont besoin de réutiliser des mappings entre Recipes. Les catalogues sans contenu de template répété sont livrés sans aucune MappingLibrary.

Le rôle de la MappingLibrary

Les architectes de plateforme rédigent des MappingLibraries pour centraliser les fragments de template Go qui reviennent dans les Recipes et 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 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 MappingLibraries n’encodent que des fragments de template — le contenu de template Go que d’autres entités consomment au moment du rendu. 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 template partagé ne rencontrent jamais l’entité bibliothèque.

Enveloppe de l’entité

Une entité MappingLibrary porte l’enveloppe standard du catalogue. apiVersion: aggrega.ai/v1beta1 et kind: MappingLibrary marquent le type d’entité ; metadata.name est un identifiant en PascalCase ; metadata.version suit strictement le versionnage sémantique. Le contenu de la bibliothèque se trouve sous spec.mappings, une map obligatoire qui doit déclarer au moins une entrée.

apiVersion: aggrega.ai/v1beta1
kind: MappingLibrary
metadata:
name: BaseMappings
version: 1.0.0
spec:
mappings:
SimpleValues: 'image: {{ .values.image }}'
Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'

Une entrée est évaluée par le moteur de template propre à la Recipe qui la consomme, dans le contexte de rendu de la Recipe ; elle lit donc les piliers en minuscules que lit le valuesMapping: propre d’une Recipe — .values, .infra, .context et les autres — et utilise les mêmes fonctions, comme l’helper optional sensible à la présence pour une clé absente. .Values, l’orthographe de Helm pour les valeurs du chart, n’est pas une racine que ce contexte définit : une entrée qui la lit arrête le build, en nommant la référence.

Rédiger les entrées de mapping

Chaque entrée de mapping est un fragment de template Go rédigé comme une chaîne YAML. Le fragment est opaque pour l’enveloppe de l’entité — le compilateur stocke la chaîne telle quelle au chargement de la MappingLibrary et l’analyse au moment de la consommation, lorsqu’une Recipe ou une FeatureRecipe importe l’entrée via valuesMapping: { $import: ... }. L’import remplace l’intégralité du valuesMapping: de la Recipe — la map $import: ne porte aucune autre clé — de sorte qu’une entrée est un document de valeurs complet plutôt qu’un morceau inséré dans un document.

Les fragments courts tiennent sur une seule ligne :

spec:
mappings:
AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'

Les fragments multilignes utilisent le scalaire de style littéral de YAML (|) afin que les sauts de ligne et l’indentation survivent à l’aller-retour :

spec:
mappings:
ProbeBlock: |
readinessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}
livenessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}

Tout le vocabulaire de composition des templates Go est disponible dans les fragments : {{ define "name" }}...{{ end }} déclare des blocs réutilisables au sein d’une même bibliothèque ; {{ template "name" . }} les invoque ; les pipelines et les fonctions sont pris en charge selon le paquet Go standard text/template.

Un mode de rédaction unique

MappingLibrary 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 est l’uniformité de la surface de consommation. Les Recipes et FeatureRecipes sont entièrement en template Go, et leur propre contenu est évalué par le même moteur de template Go qui résout une entrée importée ; une entrée se lit donc exactement comme le propre texte de la Recipe, et les auteurs apprennent un seul modèle d’évaluation. Le vocabulaire de composition des templates Go — {{ define }} et {{ template }} au sein d’une bibliothèque, et la directive $import: au moment de la consommation — fournit les blocs réutilisables et l’invocation paramétrée dont une bibliothèque a besoin.

Les auteurs qui ont besoin d’une expressivité au-delà de ce qu’offre le vocabulaire de composition des templates Go composent à un niveau supérieur — des Components ou des Features qui enveloppent les entrées de bibliothèque avec leur propre variation substantielle — plutôt que de passer à un langage de rédaction parallèle au sein de la MappingLibrary elle-même.

Conventions de nommage

Les noms de bibliothèque et les clés des entrées de mapping suivent le PascalCase. Le JSON Schema de l’enveloppe de l’entité applique la convention à deux endroits via des contraintes de motif :

  • metadata.name correspond à ^[A-Z][A-Za-z0-9]*$.
  • Les clés de la map spec.mappings correspondent au même motif via propertyNames.

Une MappingLibrary avec une clé qui n’est pas en PascalCase dans spec.mappings échoue à la validation de l’enveloppe au chargement du workspace. L’application est structurante : les clés des entrées de mapping apparaissent dans le fragment de référence #/mappings/<name> ; des clés qui ne seraient pas en PascalCase se propageraient à travers chaque consommateur qui importe l’entrée.

L’uniformité de nommage garde le fragment #/mappings/<name> lisible : #/mappings/ProbeBlock 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 mapping dans un bloc valuesMapping: { $import: ... } par son identité de nom simple :

# Inside a Recipe's valuesMapping block:
spec:
valuesMapping:
$import: "BaseMappings#/mappings/ProbeBlock"

Le fragment #/mappings/<name> sélectionne l’entrée et distingue une référence de mapping du #/schemas/<name> de la SchemaLibrary. La référence utilise le même modèle d’identité par nom simple que le $ref: de la SchemaLibrary — <Library>#/mappings/<name>, sans hôte de registre. La version est fournie par le lockfile propre à chaque Release (nom + version + digest du contenu) ; un auteur peut affirmer un plancher de version minimale facultatif sous la forme <Library>:<version>#/mappings/<name> (le séparateur de version est :, comme pour les mappings de recipe/feature et l’épinglage du lockfile), et l’emplacement physique est lié au moment de la résolution.

Composition entre bibliothèques

Une entrée de MappingLibrary peut être une redirection $import: à la racine du champ : le premier jeton de son corps est $import: <Library>#/mappings/<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 (rendu de la Recipe), et non au chargement de la MappingLibrary, et de façon récursive — une entrée importée peut elle-même être un $import: à la racine du champ. $import: ne s’applique qu’à des entrées entières ; ce n’est pas une fonction de template en milieu de fragment. Pour composer du texte de template au sein d’un même fragment, utilisez define / template des templates Go.

# In library A — alias an entry to a shared entry in another library:
spec:
mappings:
StandardProbe: |
$import: MonitoringLibrary#/mappings/PrometheusAnnotations

Les bibliothèques peuvent se référencer librement les unes les autres. Une chaîne qui reboucle sur elle-même s’arrête lorsque la Recipe qui la consomme est rendue, avec un diagnostic nommant chaque étape du cycle.

Placement dans les tiers

MappingLibrary relève du niveau 3 dans le modèle de documentation des niveaux d’entités — facultative pour les catalogues qui ont besoin de réutiliser des mappings entre Recipes. Les catalogues sans contenu de template répété sont livrés sans aucune entité MappingLibrary ; le marquage de niveau signale « avancé ; à ignorer si inutile » pour la navigation dans la documentation, et non une capacité. Le compilateur traite MappingLibrary de manière uniforme avec les autres types d’entités de catalogue : même validation de l’enveloppe au chargement du workspace, même pipeline de publication OCI au moment de la publication d’une version.

Le type bibliothèque s’associe naturellement à SchemaLibrary au niveau du catalogue — SchemaLibrary contient des définitions de schéma réutilisables ; MappingLibrary contient des fragments de template réutilisables. Les catalogues qui ont besoin des deux livrent les deux ; ceux qui n’ont besoin d’aucun des deux n’en livrent aucun.

Ce que la MappingLibrary n’est pas

Quelques idées reçues courantes à écarter :

  • Pas un substitut à valuesMapping: en ligne. La plupart des Recipes contiennent un contenu valuesMapping: simple qui gagne à être rédigé en ligne — la Recipe reste autonome et l’auteur lit le contenu du mapping avec le reste de la Recipe. La MappingLibrary est utile lorsque le MÊME fragment apparaît dans de nombreuses Recipes ; pour des mappings ponctuels, la rédaction en ligne est le bon choix.

  • Pas un emplacement pour du contenu de schéma. Les définitions de schéma (JSON Schema 2020-12) ont leur place dans la SchemaLibrary ; les fragments de template ont leur place ici. Les types de bibliothèque se répartissent par type de contenu, non par modèle de réutilisation.

  • Pas de 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 arg }} des templates Go à l’intérieur des entrées de bibliothèque, ou composent des Components / Features qui enveloppent les entrées de bibliothèque avec leur propre variation. L’entité de bibliothèque elle-même ne fournit aucun mécanisme d’assistants paramétriques (aucun bloc templates analogue aux assistants paramétriques spec.templates de la SchemaLibrary) ; le vocabulaire de composition des templates Go couvre le même cas d’usage.