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

Architettura dei Provider

Un provider esegue il rendering dei tipi di input di una Recipe in file manifest nativi del provider. Quando una Recipe dichiara capability: helm, capability: compose o qualsiasi altro nome di provider, il compilatore smista il rendering al provider che serve quel nome. Questo capitolo spiega come un provider viene realizzato come Plugin di rendering dei provider, come funziona lo smistamento, e il contratto del socket dei plugin che lega il compilatore a ciascun provider.

Che cosa questo capitolo non tratta: il modello di composizione a tre tipi di input (source: + valuesMapping:, workload:, artifacts: — ciascuno dei quali accetta contenuto inline o $import:) che una Recipe usa per produrre il proprio output. Quel modello è trasversale a tutti i provider e si trova in ../../architecture/16-recipe-input-composition.md, compresa la Matrice delle capacità per Provider che indica quale tipo di input supporta ciascun provider.

Il Plugin di rendering dei provider

Il rendering del Provider è servito da un Plugin con pluginType: provider. Il Plugin di rendering dei provider:

  • serve uno o più nomi di provider — dichiarati in spec.provider.capabilities. Il nome di provider indicato da una Recipe (spec.capability: helm) si lega al Plugin di rendering dei provider il cui elenco spec.provider.capabilities include quel nome. Quando più di un Plugin serve la stessa destinazione, il workspace sceglie tra di essi tramite un binding di provider in .aggrega-config.yaml, risolto da aggrega pull e registrato nel lockfile; senza binding e con esattamente un candidato si usa quel candidato, e senza binding e con più di un candidato la build si arresta in modo esplicito, nominando i plugin candidati.
  • porta i propri metadati del socket dei provider nello stesso blocco — spec.provider contiene l’elenco delle capacità qui sopra insieme al resto delle dichiarazioni del provider. spec.provider.workloadSchema è una dichiarazione JSON Schema 2020-12 che documenta come il tipo Workload di proprietà della piattaforma si traduce nell’output nativo di questo provider; il catalogo della libreria standard la dichiara sui provider che sintetizzano, come contratto di traduzione documentato. spec.provider.wellKnownAnnotations enumera le annotazioni di confine aggrega.ai/ che il provider legge. Il supporto dell’input sintetizzato (workload:) è una proprietà del provider, applicata in fase di rendering — non determinata dalla presenza di workloadSchema.

Vedi ../entities/plugin.md per l’intera superficie di authoring a livello di campo dell’entità Plugin, incluso il blocco spec.provider.

Smistamento per provider

Ogni Recipe dichiara esattamente un capability: in cima al proprio spec. Il compilatore legge questo campo e smista il rendering al provider che serve il nome. Una Recipe non può avere come destinazione più provider contemporaneamente. La composizione multi-provider avviene a livello di Release: un confine può contenere componenti di provider diversi, e i contributori di ciascun provider nel percorso di assemblaggio valutato del confine vengono assemblati in modo indipendente — un assemblaggio per ciascuna tupla (path, provider).

Il percorso di smistamento per un singolo nodo:

  1. Il compilatore risolve l’URI della Recipe per questo nodo tramite la ricerca a tre livelli del Manifest nella sezione di mapping del provider di destinazione. Il raggruppamento per asse dei provider del Manifest è ciò che rende «lo stesso Component, Recipes diverse per provider diversi» un modello naturale.
  2. Lo spec.capability della Recipe risolta identifica il nome di provider verso cui smistare.
  3. Il compilatore lega il provider per quel nome: risolve il Plugin di rendering dei provider il cui elenco spec.provider.capabilities include il nome ed esegue il rendering tramite il guest di quel Plugin. Il rendering è solo Wasm — non esiste alcun renderer nell’host su cui ripiegare, quindi un nome di provider che non si risolve in alcun Plugin che lo serva arresta la build in modo esplicito al momento dell’instradamento.
  4. Il provider viene invocato con il contesto di rendering per nodo (valori dei pilastri, proiezioni .context.*, i tipi di input della Recipe).
  5. Il provider restituisce l’output renderizzato. Il compilatore instrada i file renderizzati all’assemblatore per (path, provider) indicizzato sulla directory: valutata del confine unita alla subDirectory: per componente. Due confini che si valutano nello stesso percorso con lo stesso provider condividono un assemblatore — il modello canonico è un confine padre più due confini figli con directory: "{{ .parent_boundary.directory }}" che confluiscono in un unico assemblaggio unito.

Vedi ../entities/manifest.md per la forma di smistamento per asse dei provider del Manifest, e ../entities/recipe.md per la dichiarazione di provider singolo lato Recipe. Il modello di assemblaggio per (path, provider) e l’allowlist delle variabili dei template di percorso che controlla i percorsi valutati sono documentati in ../path-template-variables.md.

Il contratto dei plugin Wasm

Il rendering del Provider viene eseguito all’interno di una sandbox WebAssembly. Il compilatore Go è l’host; il Plugin di rendering dei provider è il guest. Per ogni nodo, il compilatore consegna al plugin il contesto di rendering del nodo, e il plugin restituisce i file che ha renderizzato. Questo contratto è uniforme per ogni provider:

  • Una codifica binaria canonica in entrambe le direzioni. Il compilatore codifica il contesto di rendering — i valori e le associazioni del nodo, il .workload analizzato, le voci di artefatto valutate, l’elenco dei soli nomi di un .source risolto e i metadati del confine — come CBOR canonico (RFC 8949 §4.2.1) e lo consegna al plugin. Il plugin risponde nella stessa codifica con l’elenco dei file che ha renderizzato — ciascuno con un percorso relativo alla radice di output del nodo e i byte esatti da scrivervi, facoltativamente con il formato del file — insieme a eventuali diagnostiche. Ogni export del socket, dal rendering di un nodo all’assemblaggio di un confine e al cablaggio di un collegamento tra confini, porta questa codifica in entrambe le direzioni, e il kit di sviluppo per plugin di ciascun linguaggio la decodifica e la codifica per il plugin. Una risposta che non ha la forma di output dell’export in questa codifica arresta la build. Il contratto dei plugin documenta il payload di ciascun export.
  • Nessun accesso al filesystem. I Plugins non possono leggere file arbitrari dal filesystem dell’host. Una sorgente nominata da una Recipe — un chart in un registry, un modulo in un repository — viene risolta dal compilatore prima che il plugin venga eseguito; il plugin ne riceve un elenco dei soli nomi e chiede al compilatore i file che seleziona tramite una funzione host, che risponde solo per i file sotto la sorgente di quel nodo.
  • Nessun accesso alla rete. I Plugins sono deterministici ed ermetici, e non aprono alcuna connessione propria. Un input esterno di cui un plugin ha bisogno durante il rendering — uno schema remoto a cui fanno riferimento i valori di un chart — viene richiesto tramite la funzione host per gli input esterni del compilatore, che risponde a partire dal contenuto che il workspace ha fissato per quel riferimento.
  • Output deterministico. A parità di input e con la stessa versione del plugin, un plugin deve produrre un output identico byte per byte. Questo è il contratto che fa sì che la garanzia di output identico byte per byte del compilatore valga da un capo all’altro attraverso lo strato dei plugin. Una build eseguita con --verify-determinism esegue il rendering di ogni nodo due volte e si arresta quando i due rendering di un nodo differiscono.

L’architettura dei socket dei plugin al livello più ampio dell’estensibilità, compresi gli altri socket Wasm nella pipeline di compilazione (i ruoli di trasformazione e di verdetto del socket di governance), si trova in ../../architecture/14-extensibility.md.

I provider della libreria standard di Aggrega

I provider helm, helm-chart, compose, terraform e cloudformation formano insieme il set di provider della libreria standard. Coprono le destinazioni di distribuzione comuni senza richiedere ai team aziendali di creare i propri provider.

helm supporta tutti e tre i tipi di input: da sorgente (un chart Helm upstream recuperato tramite l’SDK di Helm, con l’output del valuesMapping della Recipe come override del chart), sintetizzato (YAML Kubernetes piatto — un oggetto controller scelto dal form del Workload (Deployment, StatefulSet, DaemonSet, Job o CronJob) più Services e PVC — emesso da un Workload analizzato) e artefatti (file YAML autonomi accanto all’output del chart). Vedi la Matrice delle capacità per Provider in ../../architecture/16-recipe-input-composition.md per sapere quali dei tre tipi accetta.

helm-chart supporta la modalità da sorgente (composizione a chart ombrello: un chart per confine, un sotto-chart per componente) e gli artifacts: che la accompagnano, in entrambe le forme di authoring. Una voce artifacts: caricata con $import: viene prima elaborata da Aggrega come template Go, poi iniettata nella directory templates/ del chart prima del rendering; una voce artifacts: a contenuto inline viene valutata allo stesso modo e collocata nella radice del sotto-chart, senza alcuna provenienza unita, dove i template del chart stesso la leggono tramite .Files.Get / .Files.Glob di Helm. Una Recipe autonoma composta solo da artefatti non è uno dei tipi che dichiara, e non lo è nemmeno il tipo sintetizzato: il chart ombrello orchestra i sotto-chart, mentre il tipo Workload è un concetto foglia che appartiene a ciascun sotto-chart (il dominio del provider helm).

compose supporta da sorgente (carica un file compose e vi unisce in profondità l’overlay del valuesMapping), sintetizzato (emette services: + volumes: + networks: di compose da un Workload analizzato per le forme stateless e stateful, con una gestione dei volumi degradata per persistentTemplate — i PVC per replica confluiscono in un unico volume con nome condiviso, con un avviso; le forme daemon, scheduled e task non hanno alcuna corrispondenza in compose e si arrestano in modo esplicito) e artefatti (frammenti compose le cui chiavi di primo livello services: / networks: / volumes: / configs: si uniscono nel docker-compose.yaml combinato per confine). Gli artefatti possono accompagnare l’uno o l’altro degli altri due tipi, e anche una Recipe autonoma composta solo da artefatti — artifacts: senza source: e senza workload: — è un tipo che questo provider dichiara: i suoi frammenti si uniscono secondo le stesse regole, così il nodo contribuisce esattamente ciò che dichiara e non ha bisogno di alcun Workload che faccia le veci di risorse di calcolo che non ha.

terraform supporta da sorgente (incorpora un modulo Terraform così com’è e fornisce l’output del valuesMapping come argomenti del blocco module di quel componente nella configurazione radice del confine) e artefatti (emette un corpo HCL o .tf.json scritto dall’autore così come lo valuta il suo template, senza riscriverlo). Non offre il tipo di input sintetizzato — non esiste una corrispondenza fedele dal tipo Workload della piattaforma a risorse Terraform arbitrarie. Il provider emette configurazione e non esegue mai Terraform; i valori dipendenti dal runtime restano stringhe di interpolazione ${ ... } che il runtime di Terraform risolve al momento dell’apply.

cloudformation esegue il rendering di un confine in un unico template di stack AWS CloudFormation, assemblando i frammenti di risorse scritti dai suoi componenti in un unico template in JSON puro, esponendo i provides di ciascun componente come Outputs dello stack e cablando gli archi uses come Fn::GetAtt all’interno di uno stack e come Fn::ImportValue / Fn::GetStackOutput tra stack. Supporta l’input da sorgente e l’input ad artefatti ed emette configurazione senza mai eseguire CloudFormation; i valori disponibili solo a runtime restano funzioni intrinseche di CloudFormation.

L’indice di riferimento dei Provider ti indirizza alla pagina di riferimento di ciascun provider; quali tipi di input accetti ciascuno lo indica la matrice delle capacità in ../../architecture/16-recipe-input-composition.md.

Provider personalizzati

I team aziendali che creano i propri provider seguono lo stesso schema della libreria standard: creano un Plugin di rendering dei provider (pluginType: provider) che dichiara in spec.provider.capabilities il nome o i nomi di provider che serve, insieme al resto dei suoi metadati spec.provider, poi pubblicano l’artefatto Wasm che implementa il contratto di rendering descritto sopra. Il compilatore tratta i provider personalizzati in modo identico ai provider della libreria standard; lo smistamento per provider opera sul nome di provider dichiarato dalla Recipe.

Come crearne uno è documentato, non rimandato. Creare un provider costruisce da un capo all’altro un guest di provider funzionante — l’autodescrizione describe(), la build, l’entità Plugin, l’associazione e un rendering il cui output puoi leggere. La Guida per sviluppatori di plugin Wasm è il riferimento per l’entità e per il ciclo di vita di pubblicazione, e il contratto dei plugin documenta le forme del payload e del risultato di ciascun socket. I guest si scrivono in Go, Rust o TypeScript con il kit di sviluppo per plugin.