MappingLibrary
Una MappingLibrary è un’entità di catalogo che contiene frammenti di template Go riutilizzabili. Le Recipes e le FeatureRecipes che condividono un intero documento valuesMapping: — i valori che diverse Recipes basate sullo stesso chart gli passano ciascuna — lo dichiarano una volta in una libreria e vi fanno riferimento al momento del consumo tramite una direttiva valuesMapping: { $import: ... }. L’entità libreria è di livello 3: facoltativa, per i cataloghi che necessitano di riutilizzare i mapping tra Recipe. I cataloghi senza contenuto di template ripetuto vengono distribuiti senza alcuna MappingLibrary.
Il ruolo della MappingLibrary
Gli architetti di piattaforma scrivono MappingLibraries per centralizzare i frammenti di template Go ricorrenti tra le Recipes e le FeatureRecipes del catalogo. Una libreria non è un’istruzione di build distribuibile; è uno spazio dei nomi di definizioni. Gli autori di Recipe e FeatureRecipe fanno riferimento alle voci della libreria tramite una direttiva $import:, scritta una volta e consumata ovunque l’import venga risolto.
La separazione tra «libreria» e «consumatore» è intenzionale. Le Recipes codificano istruzioni di build (source, valuesMapping, artifacts). Le FeatureRecipes codificano collegamenti comportamentali. Le MappingLibraries codificano solo frammenti di template — il contenuto Go-template che altre entità consumano al momento del rendering. Mantenere distinti i tre ruoli consente a ciascun tipo di entità di evolvere al proprio ritmo; gli autori che non hanno bisogno di contenuto di template condiviso non incontrano mai l’entità libreria.
Envelope dell’entità
Un’entità MappingLibrary porta l’envelope standard del catalogo. apiVersion: aggrega.ai/v1beta1 e kind: MappingLibrary contrassegnano il tipo di entità; metadata.name è un identificatore in PascalCase; metadata.version segue rigorosamente il versionamento semantico. Il contenuto della libreria si trova sotto spec.mappings, una mappa obbligatoria che deve dichiarare almeno una voce.
apiVersion: aggrega.ai/v1beta1kind: MappingLibrarymetadata: name: BaseMappings version: 1.0.0spec: mappings: SimpleValues: 'image: {{ .values.image }}' Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'Una voce viene valutata dal motore di template della Recipe che la consuma, sul contesto di rendering della Recipe, quindi legge i pilastri in minuscolo che legge il valuesMapping: della Recipe stessa — .values, .infra, .context e gli altri — e usa le stesse funzioni, come l’helper optional sensibile alla presenza per una chiave assente. .Values, la grafia di Helm per i valori del chart, non è una radice definita da quel contesto: una voce che la legge arresta la build, nominando il riferimento.
Scrivere le voci di mapping
Ogni voce di mapping è un frammento di template Go scritto come stringa YAML. Il frammento è opaco per l’envelope dell’entità — il compilatore memorizza la stringa alla lettera al caricamento della MappingLibrary e la analizza al momento del consumo, quando una Recipe o una FeatureRecipe importa la voce tramite valuesMapping: { $import: ... }. L’import sostituisce l’intero valuesMapping: della Recipe — la mappa $import: non porta altre chiavi — quindi una voce è un documento di valori completo anziché un pezzo innestato in uno.
I frammenti brevi stanno su una sola riga:
spec: mappings: AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'I frammenti su più righe usano lo scalare in stile letterale di YAML (|), così che a capo e indentazione sopravvivano al round-trip:
spec: mappings: ProbeBlock: | readinessProbe: httpGet: path: /healthz port: {{ .values.port }} livenessProbe: httpGet: path: /healthz port: {{ .values.port }}L’intero vocabolario di composizione dei template Go è disponibile all’interno dei frammenti: {{ define "name" }}...{{ end }} dichiara blocchi riutilizzabili all’interno di una singola libreria; {{ template "name" . }} li invoca; pipeline e funzioni sono supportate secondo il pacchetto Go standard text/template.
Un’unica modalità di authoring
La MappingLibrary viene distribuita con un solo modo di authoring: i template Go. spec non accetta alcuna superficie di authoring parallela né alcuna via d’uscita di espressività a livello di libreria.
Il motivo è l’uniformità della superficie di consumo. Le Recipes e le FeatureRecipes sono interamente in Go-template, e il loro contenuto viene valutato tramite lo stesso motore di template Go che risolve una voce importata, quindi una voce si legge esattamente come il testo della Recipe stessa e gli autori imparano un solo modello di valutazione. Il vocabolario di composizione dei template Go — {{ define }} e {{ template }} all’interno di una libreria, e la direttiva $import: al momento del consumo — fornisce i blocchi riutilizzabili e l’invocazione parametrizzata di cui una libreria ha bisogno.
Gli autori che necessitano di un’espressività superiore a quella offerta dal vocabolario di composizione dei template Go compongono a un livello più alto — Components o Features che avvolgono le voci della libreria con una propria variazione sostanziale — anziché passare a un linguaggio di authoring parallelo all’interno della MappingLibrary stessa.
Convenzioni di denominazione
I nomi delle librerie e le chiavi delle voci di mapping seguono il PascalCase. Il JSON Schema dell’envelope dell’entità applica la convenzione in due posizioni tramite vincoli di pattern:
metadata.namecorrisponde a^[A-Z][A-Za-z0-9]*$.- Le chiavi della mappa
spec.mappingscorrispondono allo stesso pattern tramitepropertyNames.
Una MappingLibrary con una chiave non in PascalCase in spec.mappings non supera la validazione dell’envelope al caricamento del workspace. L’applicazione è portante: le chiavi delle voci di mapping compaiono nel frammento di riferimento #/mappings/<name>; chiavi non in PascalCase si propagherebbero attraverso ogni consumatore che importa la voce.
L’uniformità dei nomi mantiene leggibile il frammento #/mappings/<name>: #/mappings/ProbeBlock si legge a colpo d’occhio.
Riferirsi alle voci della libreria
Gli autori di Recipe e FeatureRecipe fanno riferimento a una voce di mapping all’interno di un blocco valuesMapping: { $import: ... } tramite la sua identità a nome semplice:
# Inside a Recipe's valuesMapping block:spec: valuesMapping: $import: "BaseMappings#/mappings/ProbeBlock"Il frammento #/mappings/<name> seleziona la voce e distingue un riferimento di mapping dal #/schemas/<name> della SchemaLibrary. Il riferimento usa lo stesso modello di identità a nome semplice del $ref: della SchemaLibrary — <Library>#/mappings/<name>, senza alcun host di registry. La versione è fornita dal lockfile per Release (nome + versione + digest del contenuto); un autore può asserire un limite minimo di versione facoltativo come <Library>:<version>#/mappings/<name> (il separatore di versione è :, in linea con i mapping di recipe/feature e con il pin del lockfile), e la posizione fisica viene legata al momento della risoluzione.
Composizione tra librerie
Una voce di MappingLibrary può essere un reindirizzamento $import: alla radice del campo: il primo token del suo corpo è $import: <Library>#/mappings/<entry>, che sostituisce l’intera voce con il contenuto della voce referenziata — riuso per identità, non templating sul posto. Il reindirizzamento viene risolto al momento del consumo (rendering della Recipe), non al caricamento della MappingLibrary, e in modo ricorsivo — una voce importata può essere a sua volta un $import: alla radice del campo. $import: vale solo per l’intera voce; non è una funzione di template a metà frammento. Per comporre testo di template all’interno di un singolo frammento, usa define / template dei template Go.
# In library A — alias an entry to a shared entry in another library:spec: mappings: StandardProbe: | $import: MonitoringLibrary#/mappings/PrometheusAnnotationsLe librerie possono fare riferimento le une alle altre liberamente. Una catena che torna su sé stessa si arresta quando la Recipe che la consuma viene renderizzata, con una diagnostica che nomina ogni passo del ciclo.
Collocazione nei tier
La MappingLibrary è di livello 3 nel modello di documentazione a livelli delle entità — facoltativa per i cataloghi che necessitano di riutilizzare i mapping tra Recipe. I cataloghi senza contenuto di template ripetuto vengono distribuiti senza alcuna entità MappingLibrary; la marcatura del livello segnala «avanzato; salta se non serve» per la navigazione della documentazione, non una capacità. Il compilatore tratta la MappingLibrary in modo uniforme rispetto agli altri tipi di entità del catalogo: stessa validazione dell’envelope al caricamento del workspace, stessa pipeline di pubblicazione OCI al momento del rilascio.
Il tipo libreria si abbina naturalmente alla SchemaLibrary a livello di catalogo — la SchemaLibrary contiene definizioni di schema riutilizzabili; la MappingLibrary contiene frammenti di template riutilizzabili. I cataloghi che hanno bisogno di entrambe le distribuiscono entrambe; quelli che non hanno bisogno di nessuna delle due non ne distribuiscono nessuna.
Cosa non è la MappingLibrary
Alcuni equivoci comuni da prevenire:
-
Non sostituisce
valuesMapping:inline. La maggior parte delle Recipes contiene semplici contenutivaluesMapping:che traggono vantaggio dall’essere scritti inline — la Recipe resta autosufficiente e l’autore legge il contenuto della mappatura insieme al resto della Recipe. La MappingLibrary è utile quando lo STESSO frammento compare in molte Recipes; per mappature una tantum, la scrittura inline è la scelta giusta. -
Non è il posto per contenuti di schema. Le definizioni di schema (JSON Schema 2020-12) vanno nella SchemaLibrary; i frammenti di template vanno qui. I tipi di libreria si dividono per tipo di contenuto, non per modello di riutilizzo.
-
Nessun riutilizzo parametrico oltre i meccanismi dei template Go. Gli autori che necessitano di variazione parametrica usano i meccanismi
{{ define }}+{{ template arg }}dei template Go all’interno delle voci della libreria, oppure compongono Components / Features che avvolgono le voci della libreria con una propria variazione. L’entità di libreria in sé non fornisce alcun meccanismo di helper parametrici (nessun bloccotemplatesanalogo agli helper parametricispec.templatesdella SchemaLibrary); il vocabolario di composizione dei template Go copre lo stesso caso d’uso.