Panoramica del riferimento alle entità
Il vocabolario di authoring di Aggrega comprende Aggregate, Component, Feature, Recipe, FeatureRecipe, Plugin, Manifest, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary e ArtifactLibrary, oltre al tipo Workload di proprietà della piattaforma, incorporato nell’input sintetizzato di una Recipe. Ogni entità è un documento YAML conforme a uno JSON Schema; ogni campo, parola chiave e riferimento tra entità descritto in questo riferimento fa parte di quel contratto di authoring.
Questo insieme di capitoli tratta la superficie di authoring: quali campi accetta ciascuna entità, che cosa significa ciascun campo per l’autore, come i campi interagiscono tra entità (l’implements: di una Recipe che nomina il Component che implementa, il puntatore manifest: di una Release a un Manifest, containers.<name>.attachments di un Workload che fa riferimento a slot dichiarati nel featuresSchema del Component). Il ruolo concettuale di ciascuna entità — perché la tassonomia ha la forma che ha, quale dominio possiede quale entità, come i quattro domini separano le responsabilità di authoring — è descritto in ../architecture/04-entity-taxonomy.md. Il ruolo architetturale del tipo Workload come uno dei tre tipi di input delle Recipe è descritto in ../architecture/16-recipe-input-composition.md.
Come è organizzato questo riferimento
Due superfici documentano il vocabolario di authoring, e rispondono a domande diverse.
Ogni tipo elencato sopra ha un riferimento di schema generato. Quelle pagine sono generate dagli schemi che il compilatore stesso pubblica, e schema/README.md indicizza l’insieme completo: tipi di entità, forme wire dei plugin e file del workspace. Ricorri al riferimento di schema per rispondere a «che cosa può contenere questo documento»: ogni campo, il suo tipo, se è obbligatorio e i vincoli che l’envelope impone.
Le pagine qui sotto sono le guide di authoring. Sono scritte a mano per insegnare ciò che lo schema non può: a che cosa serve un tipo, come i suoi campi interagiscono con altri tipi, quale forma di authoring si adatta a quale situazione, e le convenzioni che il catalogo della libreria standard segue. Ricorri a una guida di authoring per rispondere a «come ne scrivo uno, e perché ha questa forma».
Riferimento per entità
- Aggregate — l’artefatto di intento dichiarativo dello sviluppatore. Dichiara i componenti, la loro topologia tramite
uses, i contratti di parametro per la variazione per ambiente e gli attachment di Feature. - Component — entità di catalogo scritta dal Platform Architect che definisce un tipo di componente riutilizzabile. Dichiara i propri schemi
valueseinfra(ciascuno una dichiarazione JSON Schema 2020-12 in forma compatta o completa), il proprio contratto di outputprovides, il proprio contratto degli archi in ingressousesSchemae gli slot di credenziali tramitefeaturesSchema. - Feature — entità di catalogo scritta dal Platform Architect per una responsabilità trasversale (sidecar di monitoraggio, mascheramento dei dati, policy di routing). Dichiara i propri schemi
valueseinfra(ciascuno una dichiarazione JSON Schema 2020-12), i selettori di attachmentappliesToe i vincoli di interoperabilità. - Recipe — traduzione scritta da Ops da un Component a un provider specifico. Compone tre tipi di input (
source:+valuesMapping:,workload:,artifacts:— ciascuno accetta contenuto inline o$import:secondo il vocabolario unificato di importazione dei file) più un bloccoprovidesche forma il contratto di iniezione verso il chiamante. - FeatureRecipe — traduzione scritta da Ops da una Feature a un provider specifico. Usa lo stesso contratto a tre tipi di input della Recipe, più un
injectMappingche intercetta la pipe di inject per la riscrittura delle variabili lato chiamante. - Plugin — plugin WebAssembly indirizzato per contenuto. Dichiara l’unico tipo di socket che implementa —
provider,linter,pipeline-step,governance,cli,parseroimporter—, la propria versione ABI e le capability servite da quel tipo di socket. Un Plugin di rendering dei provider (pluginType: provider) dichiara il nome o i nomi di provider che serve inspec.provider.capabilitiese porta i metadati del proprio socket provider —workloadSchemaewellKnownAnnotations— in quello stesso bloccospec.provider. - Manifest — tabella di mapping per progetto. Associa i tipi astratti Component e Feature a URI concreti di Recipe e FeatureRecipe, sotto
componentsefeatures, con un ordine di ricercaname>typecon versione >typesenza versione. - Release — router di distribuzione per ambiente. Associa un Aggregate a un Manifest, mappa i componenti in confini fisici, fornisce i valori dei parametri per ambiente e collega le Features gestite da Ops.
Entità di libreria
I quattro tipi di libreria sono di livello 3: entità di riuso opzionali. Un catalogo ne dichiara una quando lo stesso contenuto ricorre tra le sue entità, e altrimenti ne fa a meno. Ciascuna contiene un solo tipo di contenuto, e il frammento in un riferimento (#/schemas/, #/mappings/, #/workloads/, #/artifacts/) indica a quale libreria si rivolge il riferimento.
- SchemaLibrary — definizioni JSON Schema 2020-12 riutilizzabili più helper parametrizzati opzionali, a cui gli schemi di un Component o di una Feature fanno riferimento con
$ref: <Library>#/schemas/<name>. - MappingLibrary — frammenti di template Go riutilizzabili, importati nel
valuesMapping:di una Recipe o di una FeatureRecipe con$import: <Library>#/mappings/<name>. - WorkloadLibrary — contenuto Workload riutilizzabile, importato nel
workload:di una Recipe o di una FeatureRecipe con$import: <Library>#/workloads/<name>. - ArtifactLibrary — bundle riutilizzabili di file di output ausiliari, importati negli
artifacts:di una Recipe o di una FeatureRecipe con$import: <Library>#/artifacts/<name>. Un bundle è l’unità di riuso: un’importazione si espande in un output per ogni file del bundle.
Tipi di proprietà della piattaforma
- Workload — tipo del compilatore di proprietà della piattaforma (non un’entità di catalogo scritta dall’utente). Incorporato nel campo
workload:di una Recipe (inline o tramite$import:); descrive la forma di distribuzione che il provider sintetizza in manifest nativi del provider.