ArtifactLibrary
Un’ArtifactLibrary è un’entità di catalogo che contiene bundle di artefatti riutilizzabili — insiemi denominati di file di output ausiliari che vanno insieme. Le Recipes e le FeatureRecipes che emettono le stesse risorse di supporto — una CRD con il relativo RBAC e una ConfigMap, una NetworkPolicy abbinata a un HPA — dichiarano quell’insieme una sola volta in una libreria e vi fanno riferimento al momento del consumo tramite una voce artifacts: il cui valore è una direttiva $import:. L’entità libreria è di Tier 3: opzionale, per i cataloghi che necessitano di riutilizzare artefatti tra Recipe. I cataloghi le cui Recipes portano ciascuna i propri file ausiliari vengono distribuiti senza alcuna ArtifactLibrary.
Il ruolo dell’ArtifactLibrary
Gli architetti di piattaforma scrivono ArtifactLibraries per centralizzare i manifest ausiliari ricorrenti nelle Recipes e nelle FeatureRecipes del catalogo. Una libreria non è un’istruzione di build distribuibile; è uno spazio dei nomi di definizioni. Gli autori di Recipe e di FeatureRecipe fanno riferimento a un bundle tramite una direttiva $import:, scritta una volta e consumata ovunque l’import venga risolto.
Ciò che distingue questo tipo di libreria dagli altri tre è la granularità di una voce. Una voce di SchemaLibrary è uno schema, una voce di MappingLibrary è un frammento di template e una voce di WorkloadLibrary è un documento Workload — ciascuna un unico corpo consumato in un unico punto. Una voce di ArtifactLibrary è un insieme di file, perché le risorse che raggruppa sono utili solo insieme: importare una CRD senza il relativo RBAC produce un insieme di manifest che non funziona. Per questo un bundle è l’unità di riutilizzo e un singolo punto di consumo si espande in più output.
Envelope dell’entità
Un’entità ArtifactLibrary porta l’envelope standard del catalogo. apiVersion: aggrega.ai/v1beta1 e kind: ArtifactLibrary indicano il tipo di entità; metadata.name è un identificatore PascalCase; metadata.version segue un versionamento semantico rigoroso. Entrambi sono obbligatori. metadata.description, metadata.labels e metadata.annotations sono opzionali — label e annotazioni sono metadati opachi dichiarati dall’autore, presenti perché chi legge la libreria possa usarli per il matching, e il compilatore non ne interpreta i valori. Il contenuto della libreria si trova sotto spec.artifacts, una mappa obbligatoria che deve dichiarare almeno un bundle.
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/v1beta1kind: ArtifactLibrarymetadata: name: PlatformArtifacts version: 1.0.0spec: artifacts: OperatorSupport: crd.yaml: | apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: widgets.platform.example.com spec: group: platform.example.com scope: Namespaced rbac.yaml: | apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: "{{ .context.instance_id }}-operator" rules: - apiGroups: ["platform.example.com"] resources: ["widgets"] verbs: ["get", "list", "watch"]Scrivere bundle di artefatti
spec.artifacts ha due livelli di profondità, e ciascun livello ha un compito distinto. La chiave esterna è il nome del bundle — l’identificatore a cui fa riferimento un consumatore. Le chiavi interne sono nomi di file, e ogni valore interno è il corpo Go template emesso in quel file. Un bundle deve dichiarare almeno un file.
spec: artifacts: NetworkBaseline: deny-all.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-deny-all" spec: podSelector: {} policyTypes: ["Ingress"] allow-dns.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-allow-dns"Il corpo di un file è un frammento di Go template scritto come stringa YAML. Poiché un manifest si estende su più righe, i corpi dei file usano lo scalare in stile letterale di YAML (|), in modo che a capo e indentazione sopravvivano al round-trip. Il valore di una voce di bundle deve essere una mappatura da nome di file a corpo stringa; scrivere una stringa semplice dove va il bundle, oppure una sequenza, viene rifiutato — il livello che un consumatore importa è il bundle, non un singolo file.
Il corpo è opaco per l’envelope dell’entità. Il compilatore memorizza ogni stringa testualmente al caricamento dell’ArtifactLibrary e lì non analizza il template; il parser dei template viene eseguito al momento del consumo, quando una Recipe o una FeatureRecipe importa il bundle. Memorizzare i corpi testualmente preserva la fedeltà alla scrittura originale per la riemissione, e fa sì che un errore di template emerga dove il bundle viene consumato e il suo contesto di pilastri è noto, anziché nella libreria.
L’ordine dei file in un bundle è quello in cui l’autore li ha scritti, preservato attraverso caricamento e consumo, quindi l’insieme emesso è stabile tra una build e l’altra.
L’intero vocabolario di composizione dei Go template è disponibile nel corpo di un file: {{ define "name" }}...{{ end }} dichiara blocchi riutilizzabili, {{ template "name" . }} li invoca, e pipeline e funzioni seguono il pacchetto Go standard text/template. Il contesto di pilastri che il corpo di un file può leggere — .values, .infra, .locals, .context, .features, e .workload e .source dove la Recipe consumatrice li dichiara — è il contesto che leggono le voci artifacts: della Recipe consumatrice stessa, documentato nella pagina Recipe sotto il campo artifacts:. Un corpo che legge .workload dove la Recipe consumatrice non dichiara alcun workload:, o .source dove non dichiara alcun source:, si arresta con una diagnostica che indica il riferimento che non ha potuto soddisfare — ogni pilastro è verificato per conto proprio, quindi dichiararne uno non autorizza a leggere l’altro.
Un’unica modalità di authoring
L’ArtifactLibrary prevede una sola modalità di authoring: i Go template. 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 Go template che risolve un bundle 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 bundle importato. Mantenere uniforme la superficie significa che gli autori imparano un solo modello di valutazione e lo applicano ovunque.
Gli autori che necessitano di un’espressività superiore al vocabolario di composizione dei Go template compongono a un livello più alto — Components o Features che avvolgono i bundle della libreria con una propria variazione sostanziale — anziché passare a un secondo linguaggio di authoring all’interno della libreria.
Convenzioni di denominazione
I nomi delle librerie e dei bundle seguono il PascalCase. Il JSON Schema dell’envelope dell’entità impone la convenzione in due posizioni tramite vincoli di pattern:
metadata.namecorrisponde a^[A-Z][A-Za-z0-9]*$.- Le chiavi della mappa
spec.artifactscorrispondono allo stesso pattern tramitepropertyNames.
Un’ArtifactLibrary con un nome di bundle non in PascalCase non supera la validazione dell’envelope al caricamento del workspace. L’imposizione è portante: i nomi dei bundle compaiono nel frammento di riferimento #/artifacts/<name>, quindi un nome non in PascalCase si propagherebbe a ogni consumatore che importa il bundle.
L’uniformità dei nomi mantiene leggibile il frammento #/artifacts/<name>: #/artifacts/OperatorSupport si legge a colpo d’occhio.
I nomi di file all’interno di un bundle sono liberi, purché ciascuno indichi un file. Non sono in PascalCase e nessun pattern di schema li vincola, perché indicano i file che l’output di una build finisce per contenere — crd.yaml, deny-all.yaml, values-override.json sono tutti validi. Ciò che un nome di file deve essere è un ordinario nome di file relativo, scritto in modo semplice; la build rifiuta un nome che non indica un file proprio, come descritto in Riferirsi alle voci della libreria. I due livelli sono vincolati in modo diverso perché servono lettori diversi: il nome del bundle è un identificatore citato da altre entità, e i nomi di file sono quelli che un consumatore vede all’interno della directory in cui il bundle è importato.
Riferirsi alle voci della libreria
Gli autori di Recipe e di FeatureRecipe fanno riferimento a un bundle all’interno di una voce artifacts: il cui valore è una mappa $import:, tramite l’identità a nome semplice del bundle:
# Inside a Recipe's spec:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport"Il frammento #/artifacts/<name> seleziona il bundle e distingue un riferimento ad artefatti da #/mappings/<name> della MappingLibrary, da #/schemas/<name> della SchemaLibrary e da #/workloads/<name> della WorkloadLibrary. Il riferimento non contiene alcun host di registry; una forma con host oci://… viene rifiutata sia dallo schema dell’envelope sia nel punto di consumo, quindi una posizione fisica del registry non entra mai nel sorgente scritto. Un autore può asserire una soglia minima di versione opzionale come <Library>:<version>#/artifacts/<name> — il separatore di versione è :, come per gli altri tipi di libreria e per 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 per Release, che fissa ogni libreria consumata per nome, versione e digest del contenuto; la posizione fisica viene vincolata al momento della risoluzione.
Il bundle possiede i propri nomi di file, e la chiave consumatrice possiede la directory in cui finiscono. Una voce artifacts: che importa un bundle si espande in un output per ogni file di quel bundle, ciascuno annidato sotto la chiave di consumo come <key>/<filename>. La chiave nel punto di consumo — operator-support sopra — indica l’intero consumo anziché un singolo file; l’esempio emette operator-support/crd.yaml e operator-support/rbac.yaml. Quindi il nome di un bundle si sceglie per la leggibilità nel riferimento, i nomi di file si scelgono per chi legge la directory di output, e nessuno dei due deve concordare con l’altro. La chiave di consumo è a sua volta limitata a un singolo nome di file — una lettera o cifra iniziale, poi lettere, cifre, punti, trattini e trattini bassi, e una chiave fuori da quell’alfabeto non supera la validazione dell’envelope — quindi indica esattamente un segmento di directory, e tutto ciò che sta sotto quel segmento viene dal bundle. È questo che permette ai nomi di file di un bundle di restare liberi mentre la chiave resta rigorosa: un nome di file è unico all’interno del suo bundle, una chiave è unica all’interno del suo documento, e la chiave è il primo segmento di ogni percorso che la voce emette, quindi nessuna coppia di voci artifacts: indica lo stesso output. Libero significa libero all’interno di quel segmento: un nome di file può avere una propria struttura annidata — crds/widget.yaml finisce in <key>/crds/widget.yaml — ma deve essere un ordinario nome di file relativo sotto la chiave, scritto in modo semplice, e un nome di file che non lo è arresta la build anziché collocare il file in un punto che la Recipe consumatrice non ha mai indicato. Ciò rifiuta un nome che sale sopra la chiave o che indica una posizione assoluta; . o ./, e un nome che ricade sulla chiave come x/.., che indicano la directory della chiave stessa anziché un file al suo interno; e un nome con un / finale o doppio oppure una parte . o .. — x/, a//b, ./a, a/../b — che è una seconda grafia di un file che un altro nome può indicare, così a//b accanto ad a/b metterebbe due file nello stesso percorso. La diagnostica indica il file del bundle e la chiave in cui è stato importato. Due output che hanno effettivamente lo stesso nome di file arrestano la build quando il nodo viene renderizzato, il che accade quando due diversi tipi di input contribuiscono lo stesso nome di file. Vedi Recipe per come artifacts: si compone con gli altri tipi di input della Recipe e per le due modalità di authoring non basate su librerie, e vocabulary/cross-document-ref per la distinzione più ampia tra $ref: / $import:.
Composizione tra librerie
Il corpo di un file di bundle è contenuto terminale. A differenza di una voce di MappingLibrary o di WorkloadLibrary, un file di bundle non può essere un reindirizzamento $import: alla radice del campo: un singolo slot di file non ha spazio per i diversi file che un altro bundle porterebbe, quindi il compilatore rifiuta quella forma anziché risolverla in qualcosa che l’autore non ha scritto. Un corpo il cui primo token è $import: si arresta con una diagnostica che indica il bundle e il file.
La composizione avviene invece nel punto di consumo, dove c’è spazio per farla. Una Recipe che necessita di due bundle dichiara due voci artifacts:, e ciascuna si espande in modo indipendente:
# Inside a Recipe's spec — compose bundles where the outputs land:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport" network-baseline: $import: "PlatformArtifacts#/artifacts/NetworkBaseline"Un nome di libreria sconosciuto e un nome di bundle assente da una libreria che viene risolta sono segnalati come diagnostiche distinte, così un autore può distinguere una dipendenza mancante da un nome di bundle scritto in modo errato.
Collocazione nei tier
L’ArtifactLibrary è di Tier 3 nel modello di documentazione a tier delle entità — opzionale per i cataloghi che necessitano di riutilizzare artefatti tra Recipe. I cataloghi le cui Recipes portano i propri file ausiliari vengono distribuiti senza alcuna entità ArtifactLibrary; la marcatura del tier segnala «avanzato; salta se non serve» per la navigazione della documentazione, non una capacità. Il compilatore tratta l’ArtifactLibrary in modo uniforme rispetto agli altri tipi di entità di catalogo: stessa validazione dell’envelope al caricamento del workspace, stessa pipeline di pubblicazione OCI al momento del rilascio, stesso pin nel lockfile per nome, versione e digest del contenuto.
Questo tipo di libreria completa un insieme a livello di catalogo — la SchemaLibrary contiene definizioni di schema riutilizzabili, la MappingLibrary frammenti di mapping riutilizzabili, la WorkloadLibrary contenuto di workload riutilizzabile e l’ArtifactLibrary bundle di artefatti riutilizzabili. Ciascuna è opzionale in modo indipendente; i cataloghi distribuiscono quelle che servono e nessuna delle altre.
Cosa non è l’ArtifactLibrary
Alcuni equivoci comuni da prevenire:
-
Non sostituisce
artifacts:inline. La maggior parte delle Recipes porta file ausiliari abbastanza specifici da stare inline, dove l’autore li legge insieme al resto della Recipe. Un’ArtifactLibrary è utile quando lo STESSO insieme di file accompagna molte Recipes; per contenuti occasionali, la scrittura inline è la scelta giusta. -
Non è un modo per rinominare i file all’interno di un bundle. I nomi di file appartengono al bundle. Un consumatore sceglie la directory in cui finiscono — è ciò che fa la chiave di consumo — ma non come si chiama ciascuno di essi: un consumatore che ha bisogno di un nome di file diverso usa un bundle che lo dichiara oppure scrive il file inline.
-
Non è il posto per contenuti di workload, di mapping o di schema. Un documento Workload appartiene a una WorkloadLibrary, il documento dei valori di una Recipe appartiene a una MappingLibrary e le definizioni di schema appartengono a una SchemaLibrary. I tipi di libreria si dividono per tipo di contenuto, non per modello di riutilizzo.
-
Non è il meccanismo per le risorse trasversali. Le risorse ausiliarie che si applicano a molti componenti indipendentemente da quale Recipe li realizzi — un sidecar di backup collegato a ogni datastore — spettano alla generazione di risorse della FeatureRecipe, che si collega per Feature anziché per Recipe. Vedi entities/featurerecipe.md. Un’ArtifactLibrary raccoglie i file che più Recipes emettono ciascuna per conto proprio.
-
Non è un’entità distribuibile in modo indipendente. Un bundle è contenuto di artefatti, e il contenuto di artefatti non è mai indirizzabile da solo — esiste come input che una Recipe o una FeatureRecipe consuma. Pubblicare un’ArtifactLibrary rende importabili i suoi bundle; non li rende distribuibili.