MappingLibrary
Eine MappingLibrary ist eine Katalogentität, die wiederverwendbare Go-Template-Fragmente enthält. Recipes und FeatureRecipes, die ein ganzes valuesMapping:-Dokument teilen — die Werte, die mehrere Recipes, die dasselbe Chart beziehen, ihm jeweils übergeben —, deklarieren es einmal in einer Bibliothek und referenzieren es zum Verbrauchszeitpunkt über eine valuesMapping: { $import: ... }-Direktive. Die Bibliotheksentität gehört zu Ebene 3: optional für Kataloge, die eine Recipe-übergreifende Wiederverwendung von Mappings benötigen. Kataloge ohne wiederholten Template-Inhalt werden ohne jede MappingLibrary ausgeliefert.
Die Rolle der MappingLibrary
Plattformarchitekten verfassen MappingLibraries, um Go-Template-Fragmente zu zentralisieren, die in den Recipes und FeatureRecipes des Katalogs wiederkehren. Eine Bibliothek ist keine bereitstellbare Build-Anweisung; sie ist ein Namensraum für Definitionen. Autoren von Recipe und FeatureRecipe referenzieren Bibliothekseinträge über eine $import:-Direktive, die einmal geschrieben und überall dort verwendet wird, wo der Import aufgelöst wird.
Die Trennung zwischen „Bibliothek“ und „Verbraucher“ ist beabsichtigt. Recipes codieren Build-Anweisungen (source, valuesMapping, artifacts). FeatureRecipes codieren verhaltensbezogene Anbindungen. MappingLibraries codieren nur Template-Fragmente — den Go-Template-Inhalt, den andere Entitäten zur Renderzeit verwenden. Indem die drei Rollen getrennt bleiben, kann sich jede Entitätsart in ihrem eigenen Tempo weiterentwickeln; Autoren, die keinen gemeinsamen Template-Inhalt benötigen, begegnen der Bibliotheksentität nie.
Entitätshülle
Eine MappingLibrary-Entität trägt den Standard-Katalog-Envelope. apiVersion: aggrega.ai/v1beta1 und kind: MappingLibrary kennzeichnen die Entitätsart; metadata.name ist ein Bezeichner in PascalCase; metadata.version folgt strikter semantischer Versionierung. Der Inhalt der Bibliothek liegt unter spec.mappings, einer erforderlichen Map, die mindestens einen Eintrag deklarieren muss.
apiVersion: aggrega.ai/v1beta1kind: MappingLibrarymetadata: name: BaseMappings version: 1.0.0spec: mappings: SimpleValues: 'image: {{ .values.image }}' Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'Ein Eintrag wird von der eigenen Template-Engine des verwendenden Recipe gegen den Render-Kontext des Recipe ausgewertet, daher liest er die kleingeschriebenen Säulen, die auch das eigene valuesMapping: eines Recipe liest — .values, .infra, .context und die übrigen — und verwendet dieselben Funktionen, etwa den anwesenheitsbewussten Helfer optional für einen fehlenden Schlüssel. .Values, die Helm-Schreibweise für Chart-Werte, ist keine Wurzel, die dieser Kontext definiert: Ein Eintrag, der sie liest, hält den Build an und benennt die Referenz.
Mapping-Einträge verfassen
Jeder Mapping-Eintrag ist ein Go-Template-Fragment, das als YAML-Zeichenkette verfasst wird. Das Fragment ist für den Entitäts-Envelope undurchsichtig — der Compiler speichert die Zeichenkette beim Laden der MappingLibrary unverändert und parst sie zum Verbrauchszeitpunkt, wenn ein Recipe oder FeatureRecipe den Eintrag über valuesMapping: { $import: ... } importiert. Der Import ersetzt das gesamte valuesMapping: des Recipe — die $import:-Map trägt keinen anderen Schlüssel —, sodass ein Eintrag ein vollständiges Values-Dokument ist und kein Stück, das in eines eingefügt wird.
Kurze Fragmente passen in eine einzige Zeile:
spec: mappings: AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'Mehrzeilige Fragmente verwenden den YAML-Skalar im Literal-Stil (|), damit Zeilenumbrüche und Einrückung den Round-Trip überstehen:
spec: mappings: ProbeBlock: | readinessProbe: httpGet: path: /healthz port: {{ .values.port }} livenessProbe: httpGet: path: /healthz port: {{ .values.port }}Das vollständige Kompositionsvokabular von Go-Templates steht innerhalb von Fragmenten zur Verfügung: {{ define "name" }}...{{ end }} deklariert wiederverwendbare Blöcke innerhalb einer einzelnen Bibliothek; {{ template "name" . }} ruft sie auf; Pipelines und Funktionen werden gemäß dem Standard-Go-Paket text/template unterstützt.
Ein einziger Authoring-Modus
MappingLibrary wird mit einem einzigen Authoring-Modus ausgeliefert: Go-Templates. spec akzeptiert keine parallele Authoring-Oberfläche und keinen Ausweg für mehr Ausdrucksstärke auf Bibliotheksebene.
Der Grund ist die Einheitlichkeit der Verbrauchsoberfläche. Recipes und FeatureRecipes sind durchgehend Go-Template, und ihr eigener Inhalt wird von derselben Go-Template-Engine ausgewertet, die einen importierten Eintrag auflöst, sodass sich ein Eintrag genau wie der eigene Text des Recipe liest und Autoren ein einziges Auswertungsmodell lernen. Das Kompositionsvokabular von Go-Templates — {{ define }} und {{ template }} innerhalb einer Bibliothek und die $import:-Direktive zum Verbrauchszeitpunkt — stellt die wiederverwendbaren Blöcke und den parametrisierten Aufruf bereit, die eine Bibliothek braucht.
Autoren, die mehr Ausdrucksstärke benötigen, als das Kompositionsvokabular von Go-Templates bietet, komponieren auf einer höheren Ebene — Components oder Features, die die Bibliothekseinträge mit ihrer eigenen substanziellen Variation umhüllen —, statt innerhalb der MappingLibrary selbst auf eine parallele Authoring-Sprache auszuweichen.
Namenskonventionen
Bibliotheksnamen und Schlüssel von Mapping-Einträgen folgen PascalCase. Das JSON Schema des Entitäts-Envelope erzwingt die Konvention an zwei Stellen über Pattern-Constraints:
metadata.nameentspricht^[A-Z][A-Za-z0-9]*$.- Die Schlüssel der Map
spec.mappingsentsprechen überpropertyNamesdemselben Muster.
Eine MappingLibrary mit einem Schlüssel in spec.mappings, der nicht in PascalCase ist, besteht die Envelope-Validierung beim Laden des Workspace nicht. Die Durchsetzung ist tragend: Schlüssel von Mapping-Einträgen erscheinen im Referenzfragment #/mappings/<name>; Schlüssel, die nicht in PascalCase sind, würden sich durch jeden Verbraucher fortpflanzen, der den Eintrag importiert.
Die einheitliche Benennung hält das Fragment #/mappings/<name> lesbar: #/mappings/ProbeBlock ist auf einen Blick verständlich.
Auf Bibliothekseinträge verweisen
Autoren von Recipe und FeatureRecipe referenzieren einen Mapping-Eintrag innerhalb eines valuesMapping: { $import: ... }-Blocks über seine Identität als bloßer Name:
# Inside a Recipe's valuesMapping block:spec: valuesMapping: $import: "BaseMappings#/mappings/ProbeBlock"Das Fragment #/mappings/<name> wählt den Eintrag aus und unterscheidet eine Mapping-Referenz von #/schemas/<name> der SchemaLibrary. Die Referenz verwendet dasselbe Identitätsmodell mit bloßem Namen wie $ref: der SchemaLibrary — <Library>#/mappings/<name>, ohne Registry-Host. Die Version liefert die Lockfile pro Release (Name + Version + Inhalts-Digest); ein Autor kann eine optionale Mindestversion als <Library>:<version>#/mappings/<name> angeben (das Versionstrennzeichen ist :, passend zu den recipe/feature-Mappings und zum Lockfile-Pin), und der physische Ort wird zum Auflösungszeitpunkt gebunden.
Bibliotheksübergreifende Komposition
Ein MappingLibrary-Eintrag kann eine $import:-Umleitung an der Feldwurzel sein: Das erste Token seines Rumpfs ist $import: <Library>#/mappings/<entry>, das den gesamten Eintrag durch den Inhalt des referenzierten Eintrags ersetzt — Wiederverwendung über Identität, kein Templating an Ort und Stelle. Die Umleitung wird zum Verbrauchszeitpunkt (beim Rendern des Recipe) aufgelöst, nicht beim Laden der MappingLibrary, und rekursiv — ein importierter Eintrag kann selbst ein $import: an der Feldwurzel sein. $import: gilt nur für ganze Einträge; es ist keine Template-Funktion mitten im Fragment. Um Template-Text innerhalb eines einzelnen Fragments zu komponieren, verwenden Sie define / template von Go-Templates.
# In library A — alias an entry to a shared entry in another library:spec: mappings: StandardProbe: | $import: MonitoringLibrary#/mappings/PrometheusAnnotationsBibliotheken können frei aufeinander verweisen. Eine Kette, die auf sich selbst zurückführt, hält an, wenn das verwendende Recipe gerendert wird, mit einer Diagnose, die jeden Schritt des Zyklus benennt.
Einordnung in die Tiers
MappingLibrary gehört im Dokumentationsmodell der Entitätsebenen zu Ebene 3 — optional für Kataloge, die eine Recipe-übergreifende Wiederverwendung von Mappings benötigen. Kataloge ohne wiederholten Template-Inhalt werden ohne jede MappingLibrary-Entität ausgeliefert; die Ebenen-Kennzeichnung signalisiert „fortgeschritten; überspringen, wenn nicht benötigt“ für die Navigation in der Dokumentation, nicht für den Funktionsumfang. Der Compiler behandelt MappingLibrary genauso wie die anderen Katalog-Entitätsarten: dieselbe Envelope-Validierung beim Laden des Workspace, dieselbe OCI-Veröffentlichungspipeline zum Veröffentlichungszeitpunkt.
Die Bibliotheksart passt auf Katalogebene natürlich zur SchemaLibrary — die SchemaLibrary enthält wiederverwendbare Schemadefinitionen; die MappingLibrary enthält wiederverwendbare Template-Fragmente. Kataloge, die beide brauchen, liefern beide aus; Kataloge, die keine von beiden brauchen, liefern keine aus.
Was die MappingLibrary nicht ist
Einige häufige Missverständnisse, denen man vorbeugen sollte:
-
Kein Ersatz für Inline-
valuesMapping:. Die meisten Recipes enthalten einfachevaluesMapping:-Inhalte, die davon profitieren, inline geschrieben zu werden — das Recipe bleibt in sich geschlossen, und der Autor liest den Mapping-Inhalt zusammen mit dem Rest des Recipe. Die MappingLibrary hilft, wenn DASSELBE Fragment in vielen Recipes vorkommt; für einmalige Mappings ist das Inline-Schreiben die richtige Wahl. -
Kein Ort für Schema-Inhalte. Schema-Definitionen (JSON Schema 2020-12) gehören in die SchemaLibrary; Template-Fragmente gehören hierher. Die Bibliotheksarten sind nach Inhaltstyp getrennt, nicht nach Wiederverwendungsmuster.
-
Keine parametrische Wiederverwendung über die Mechanismen von Go-Templates hinaus. Autoren, die parametrische Variation benötigen, verwenden die Mechanik
{{ define }}+{{ template arg }}von Go-Templates innerhalb von Bibliothekseinträgen oder komponieren Components / Features, die die Bibliothekseinträge mit eigener Variation umhüllen. Die Bibliotheksentität selbst bringt keine Mechanik für parametrische Helfer mit (keinentemplates-Block analog zu den parametrischen Helfernspec.templatesder SchemaLibrary); das Kompositionsvokabular von Go-Templates deckt denselben Anwendungsfall ab.