Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

WorkloadLibrary

Una WorkloadLibrary è un’entità di catalogo che contiene frammenti di template di Workload riutilizzabili. Le Recipes e le FeatureRecipes che distribuiscono la stessa forma di carico di lavoro — un server che espone metriche, un job batch, una coppia con sidecar — dichiarano quella forma una sola volta in una libreria e vi fanno riferimento al momento del consumo tramite una direttiva workload: { $import: ... }. L’entità libreria è di livello 3: facoltativa per i cataloghi che necessitano di riutilizzare i carichi di lavoro tra una Recipe e l’altra. I cataloghi le cui Recipes hanno ciascuna una propria forma di carico di lavoro distinta vengono rilasciati senza alcuna WorkloadLibrary.

Il ruolo della WorkloadLibrary

Gli architetti di piattaforma scrivono WorkloadLibraries per centralizzare il contenuto di Workload che ricorre tra le Recipes e le FeatureRecipes del catalogo. Una libreria non è un’istruzione di build distribuibile; è un namespace di definizioni. Gli autori di Recipe e di 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 associazioni comportamentali. Le WorkloadLibraries codificano solo contenuto di Workload — la forma del carico di lavoro che il provider sintetizza in manifest nativi del provider. 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 carico di lavoro condiviso non incontrano mai l’entità libreria.

Envelope dell’entità

Un’entità WorkloadLibrary porta l’envelope standard del catalogo. apiVersion: aggrega.ai/v1beta1 e kind: WorkloadLibrary indicano il tipo di entità; metadata.name è un identificatore in PascalCase; metadata.version segue rigorosamente il versionamento semantico. Entrambi sono obbligatori. metadata.description, metadata.labels e metadata.annotations sono facoltativi — etichette e annotazioni sono metadati opachi dichiarati dall’autore, trasportati perché qualunque cosa legga la libreria possa usarli per la corrispondenza, e il compilatore non ne interpreta i valori. Il contenuto della libreria si trova sotto spec.workloads, una mappa obbligatoria che deve dichiarare almeno una voce.

L’envelope è chiuso su tutti e tre i livelli — la radice del documento, metadata e spec rifiutano ciascuno le chiavi che lo schema non dichiara.

apiVersion: aggrega.ai/v1beta1
kind: WorkloadLibrary
metadata:
name: BaseWorkloads
version: 1.0.0
spec:
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 }}

Scrivere le voci Workload

Ogni voce è un frammento di template Go scritto come stringa YAML. L’output renderizzato della voce è un documento Workload completo — porta con sé i propri apiVersion: aggrega.ai/v1beta1 e kind: Workload — perché il campo workload: di una Recipe accetta un Workload completo, non un frammento innestato in uno circostante, e l’importazione sostituisce l’intero campo. Una voce di MappingLibrary è completa allo stesso modo: importarne una sostituisce l’intero valuesMapping: della Recipe.

Il corpo è opaco per l’involucro dell’entità. Il compilatore memorizza la stringa alla lettera al caricamento della WorkloadLibrary e lì non analizza il template; il parser dei template viene eseguito al momento del consumo, quando una Recipe o una FeatureRecipe importa la voce. Memorizzare il frammento alla lettera preserva la fedeltà di scrittura per la riemissione, e fa sì che un errore di template emerga dove la voce viene consumata e il suo contesto dei pilastri è noto, anziché nella libreria.

Poiché un documento Workload si estende su più righe, le voci usano lo scalare in stile letterale di YAML (|), così che a capo e indentazione sopravvivano al round-trip:

spec:
workloads:
BatchJob: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]

Il valore di una voce deve essere uno scalare stringa. Scrivere una mappa o una sequenza dove va il corpo viene rifiutato — il corpo della voce è testo di template, non YAML strutturato che il compilatore attraversa.

Dentro una voce è disponibile l’intero vocabolario di composizione dei template Go: {{ define "name" }}...{{ end }} dichiara blocchi riutilizzabili all’interno di una singola libreria, {{ template "name" . }} li invoca, e pipeline e funzioni seguono il pacchetto standard Go text/template. Il contesto dei pilastri che una voce può leggere — .values, .infra, .locals, .context, .features — è lo stesso contesto che legge qualsiasi template di Workload, ed è documentato nella pagina Workload nella sezione sulla valutazione dei template.

Il provider di destinazione deve supportare la sintesi del carico di lavoro. Una Recipe che importa una voce di libreria ma si lega a un provider che non sa sintetizzare un Workload si arresta con un errore esplicito al momento del rendering, anziché emettere una forma degradata; il catalogo della libreria standard dichiara workloadSchema sui provider che la supportano, come contratto documentato.

Un’unica modalità di authoring

La WorkloadLibrary offre una sola modalità di scrittura: i template Go. spec non accetta alcuna superficie di authoring parallela né alcuna via d’uscita per l’espressività a livello di libreria.

La ragione è l’uniformità della superficie di consumo. Le Recipes e le FeatureRecipes sono interamente basate su template Go, e il loro contenuto viene valutato dallo stesso motore di template Go che risolve un frammento importato. Una superficie di authoring parallela costringerebbe gli autori a cambiare modello di valutazione all’interno del rendering di una singola Recipe — un modello per il contenuto proprio della Recipe, un altro per ogni voce di libreria importata. Mantenere uniforme la superficie significa che gli autori imparano un solo modello di valutazione e lo applicano ovunque.

Gli autori che hanno bisogno di un’espressività superiore al 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 secondo linguaggio di scrittura dentro la libreria.

Convenzioni di denominazione

I nomi delle librerie e le chiavi delle voci dei carichi di lavoro seguono il PascalCase. Il JSON Schema dell’involucro dell’entità impone la convenzione in due posizioni tramite vincoli di pattern:

  • metadata.name corrisponde a ^[A-Z][A-Za-z0-9]*$.
  • Le chiavi della mappa spec.workloads corrispondono allo stesso pattern tramite propertyNames.

Una WorkloadLibrary con una chiave non in PascalCase in spec.workloads non supera la validazione dell’involucro al caricamento del workspace. L’imposizione è essenziale: le chiavi delle voci dei carichi di lavoro compaiono nel frammento di riferimento #/workloads/<name>, quindi una chiave non in PascalCase si propagherebbe a ogni consumatore che importa la voce.

L’uniformità dei nomi mantiene leggibile il frammento #/workloads/<name>: #/workloads/BatchJob si legge a colpo d’occhio.

Riferirsi alle voci della libreria

Gli autori di Recipe e FeatureRecipe fanno riferimento a una voce di carico di lavoro all’interno di un blocco workload: { $import: ... } tramite la sua identità a nome semplice:

# Inside a Recipe's spec:
spec:
workload:
$import: "BaseWorkloads#/workloads/SimpleServer"

Il frammento #/workloads/<name> seleziona la voce e distingue un riferimento a un carico di lavoro dal #/mappings/<name> della MappingLibrary e dal #/schemas/<name> della SchemaLibrary. Il riferimento non contiene alcun host di registry; una forma oci://… che include l’host viene rifiutata sia dallo schema dell’involucro sia nel punto di consumo, così che una posizione fisica di registry non entri mai nel sorgente scritto. Un autore può indicare una soglia minima di versione facoltativa come <Library>:<version>#/workloads/<name> — il separatore di versione è :, in linea con le mappature di recipe/feature e con il pin del lockfile, e scrivere @ al suo posto viene rifiutato con una diagnostica che indica il riferimento corretto. La versione risolta è fornita dal lockfile di ciascuna Release, che fissa ogni libreria consumata per nome, versione e digest del contenuto; la posizione fisica viene vincolata al momento della risoluzione.

Lo stesso campo workload: accetta altre due forme — una stringa di template Go inline e un $import: di un percorso di file locale relativo alla directory della Recipe. Le tre forme si distinguono dalla forma del contenuto, e tutte e tre producono lo stesso Workload dopo il parsing. Vedi Recipe per come workload: si compone con gli altri tipi di input della Recipe, e vocabulary/cross-document-ref per la distinzione più ampia tra $ref: / $import:.

Composizione tra librerie

Una voce di WorkloadLibrary può essere un reindirizzamento $import: alla radice del campo: il primo token del suo corpo è $import: <Library>#/workloads/<entry>, che sostituisce l’intera voce con il contenuto della voce referenziata — riuso per identità, non templating sul posto. Il reindirizzamento si risolve al momento del consumo, non al caricamento della WorkloadLibrary, e si risolve in modo ricorsivo, quindi una voce importata può essere a sua volta un $import: alla radice del campo. Una catena che ritorna su sé stessa si arresta con una diagnostica che indica il ciclo. $import: vale solo per l’intera voce; non è una funzione di template utilizzabile a metà di un frammento. Per comporre testo di template all’interno di una singola voce, usa define / template dei template Go.

# In library A — alias an entry to a shared entry in another library:
spec:
workloads:
StandardServer: |
$import: PlatformWorkloads#/workloads/MetricsServer

Un nome di libreria sconosciuto e un nome di voce assente da una libreria che invece si risolve vengono segnalati come diagnostiche distinte, così che un autore possa distinguere una dipendenza mancante da una voce scritta male.

Collocazione nei tier

La WorkloadLibrary è di livello 3 nel modello di documentazione a livelli delle entità — facoltativa per i cataloghi che necessitano di riuso dei carichi di lavoro tra Recipe diverse. I cataloghi le cui Recipes contengono un proprio contenuto di carico di lavoro distinto vengono distribuiti senza alcuna entità WorkloadLibrary; la marcatura di livello segnala «avanzato; salta se non serve» per la navigazione della documentazione, non per la capacità. Il compilatore tratta la WorkloadLibrary in modo uniforme rispetto agli altri tipi di entità del catalogo: stessa validazione dell’involucro al caricamento del workspace, stessa pipeline di pubblicazione OCI al momento del rilascio, stesso pinning nel lockfile per nome, versione e digest del contenuto.

Il tipo di libreria è uno di un insieme a livello di catalogo — la SchemaLibrary contiene definizioni di schema riutilizzabili, la MappingLibrary contiene frammenti di mappatura riutilizzabili, l’ArtifactLibrary contiene bundle di artefatti riutilizzabili, la WorkloadLibrary contiene contenuto di carico di lavoro riutilizzabile. Ciascuno è facoltativo in modo indipendente; i cataloghi distribuiscono quelli di cui hanno bisogno e nessuno degli altri.

Che cosa non è la WorkloadLibrary

Alcuni equivoci comuni da prevenire:

  • Non è un sostituto del workload: inline. La maggior parte delle Recipes contiene contenuto di carico di lavoro abbastanza specifico da stare inline, dove l’autore lo legge insieme al resto della Recipe. Una WorkloadLibrary è utile quando la STESSA forma di carico di lavoro compare in molte Recipes; per un contenuto occasionale, la scrittura inline è la scelta giusta.

  • Non è un luogo per frammenti parziali. Una voce viene renderizzata in un documento Workload completo. Il documento dei valori di una Recipe va in una MappingLibrary, un insieme di file ausiliari in un’ArtifactLibrary, e le definizioni di schema in una SchemaLibrary. I tipi di libreria si dividono per tipo di contenuto, non per schema di riuso.

  • Non è un’entità distribuibile in modo indipendente. Una voce di libreria è contenuto Workload, e il contenuto Workload non è mai indirizzabile da solo — esiste come input che una Recipe o una FeatureRecipe consuma. Pubblicare una WorkloadLibrary rende importabili le sue voci; non le rende distribuibili.

  • Non è riuso parametrico oltre i meccanismi dei template Go. Gli autori che necessitano di variazione parametrica usano i meccanismi {{ define }} + {{ template }} dei template Go all’interno delle voci di libreria, oppure il contesto dei pilastri fornito dalla Recipe che consuma la voce. L’entità libreria in sé non include alcun meccanismo di helper parametrici.