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

Composizione dell’output

Una singola build di Aggrega produce file di output in directory per confine sotto dist/ attraverso sei meccanismi distinti — rendering da sorgente, sintesi del workload, generazione di risorse della FeatureRecipe, patch della pipeline di plugin della FeatureRecipe, composizione a livello di Release ed emissione diretta di artefatti. I meccanismi vengono eseguiti in un ordine definito; gli output collidono in modo deterministico quando due meccanismi producono un file con lo stesso nome nella stessa directory di confine; la build si arresta prima dell’emissione, nominando ogni contributore, quando viene rilevata una collisione, sotto la categoria che la regola di collisione indica.

Questa pagina documenta i sei meccanismi in un unico posto e indica l’ordine di rendering tra di essi. I riferimenti per capitolo e per entità coprono le proprie superfici; le regole di rilevamento delle collisioni tra tutti e sei si trovano qui.

I sei meccanismi che producono output

Ogni meccanismo risiede in una specifica superficie di authoring della Recipe / FeatureRecipe e produce file secondo specifiche convenzioni di denominazione. I meccanismi si accumulano per nodo — una singola istanza di componente può attivare più meccanismi contemporaneamente (una Recipe di base con sorgente + un file complementare sintetizzato dal Workload + un CRD ExternalSecret emesso da una FeatureRecipe + una patch della pipeline di plugin applicata al Deployment sintetizzato).

1 — Rendering con sorgente della Recipe (source: + valuesMapping:)

Superficie di authoring. La Recipe dichiara source: <path> più valuesMapping: (il campo accetta un template Go inline, un $import: di file o un $import: di libreria verso una voce di una MappingLibrary — vedi entities/recipe.md «The valuesMapping field — three authoring modes (Il campo valuesMapping — tre modalità di authoring)»). La sorgente punta a un chart Helm su disco, a un file YAML docker-compose o a un altro artefatto nativo del provider.

Posizione nella pipeline. Rendering di base, dopo che i locals e i provides della Recipe sono stati risolti.

Forma dell’output. Specifica del Provider:

  • provider helm — file YAML Kubernetes piatti, nominati in base all’identità del componente e poi alla risorsa stessa: <component-id>-<kind>[-<namespace>]-<name>.yaml, mentre un documento che non porta alcun kind o alcun nome viene invece nominato in base al percorso del suo template. Il nome deriva dalla risorsa anziché dal template, quindi due template in sottodirectory diverse che condividono un nome di file restano due file. L’SDK di Helm esegue il rendering del chart con i valori uniti; Aggrega inietta etichette e annotazioni di provenienza dopo il rendering.
  • provider helm-chart — file dei sub-chart copiati sotto charts/<instance_id>/, invariati tranne il name del chart stesso, che l’umbrella imposta sull’identità codificata dell’istanza affinché due componenti che incorporano chart che dichiarano lo stesso nome restino distinguibili (vedi providers/helm-chart.md); Chart.yaml + values.yaml dell’umbrella per confine emessi accanto.
  • provider compose — file intermedi <nodeID>.compose-fragment.yaml che confluiscono nella composizione a livello di Release (meccanismo 5).

2 — Sintesi del Workload della Recipe (workload:)

Superficie di authoring. La Recipe dichiara workload: che porta un documento Workload. Il campo accetta contenuto inline (block scalar) o $import: (percorso di file).

Posizione nella pipeline. Rendering di base, dopo che il valuesMapping della Recipe è stato risolto (il corpo del Workload è a sua volta una stringa con template Go valutata con il contesto completo del template).

Forma dell’output. Specifica del Provider:

  • provider helm — un oggetto controller scelto dal form del Workload (Deployment per stateless, StatefulSet per stateful, DaemonSet per daemon, Job per task, CronJob per scheduled) + un Service per servizio + un PVC per ogni volume persistent. Due forme di denominazione, e non sono la stessa: l’oggetto controller prende il nome dal nome della release del nodo e dal suo kind — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml — mentre un file per risorsa prende il nome dalla risorsa che porta, con il kind per ultimo: <release name>-<svcName>-service.yaml e <release name>-<volName>-pvc.yaml, perché ciascuno è nominato a partire dal metadata.name della risorsa stessa. Il nome della release è l’identità del nodo scritta nell’alfabeto ammesso da un nome Kubernetes, quindi coincide con l’ID del nodo ovunque questo non contenga trattini bassi né lettere maiuscole: il nodo my_api scrive my-zuapi-deployment.yaml (vedi entities/workload.md «Synthesized-name convention (Convenzione dei nomi sintetizzati)»). Un Workload la cui unica esposizione è un nome esterno emette invece <release name>-service.yaml, non essendoci alcuna chiave di servizio da portare.
  • provider compose — file intermedi <nodeID>.compose-fragment.yaml che confluiscono nella composizione a livello di Release.
  • provider helm-chart — non supportato; il ruolo di helm-chart è solo la composizione di chart in modalità con sorgente. Una Recipe che ha come target helm-chart con workload: viene rifiutata al momento del rendering (il provider helm-chart non dichiara alcuna capacità di sintesi).

3 — Generazione di risorse della FeatureRecipe (modalità con sorgente per le FeatureRecipes)

Superficie di authoring. La FeatureRecipe dichiara source: più valuesMapping: (o equivalente), lo stesso schema del rendering da sorgente della Recipe, ma per le associazioni di Feature anziché per i Components primari.

Posizione nella pipeline. Rendering di base, accanto al rendering della Recipe di base per il Component padre. Ogni associazione di Feature esegue il proprio passaggio di rendering della FeatureRecipe.

Forma dell’output. Decisa dal provider del Component padre, perché l’output dell’associazione si unisce al gruppo di assemblaggio di quel Component anziché a uno proprio — e deriva da come quel provider combina il gruppo, poiché è questo a dire se esista o meno un posto in cui mettere un’associazione. Tre forme, una per ciascun modo di combinare:

  • Un provider che dà a ogni contributore una posizione propria — un chart che contiene un chart per contributore, una configurazione radice che contiene un modulo per contributore — dà anche a un’associazione una posizione propria, accanto al componente a cui è associata anziché al suo interno. Le due coordinate compongono il singolo segmento di directory di quella posizione, <component-id>--<feature-instance-id>, quindi un componente api che porta un’associazione aux si trova in api--aux accanto ad api, sotto qualunque directory quel provider designi per i suoi contributori. Accanto anziché all’interno, perché il target di un tale provider scopre i suoi contributori nelle posizioni che ha dato loro: una directory un livello sotto una di quelle posizioni è contenuto che appartiene a quel contributore anziché un contributore a sé, quindi non è indirizzata da nulla e non è letta da nulla. Un’associazione dichiarata sul confine non ha alcun componente ospite da nominare, quindi il suo segmento è soltanto il nome della sua istanza. Ogni coordinata viene codificata prima che le due vengano unite, così una coordinata che contiene essa stessa la sequenza di unione non può essere scambiata per l’unione.
  • Un provider che scrive ogni documento direttamente nella directory di confine non ha un posto del genere, perché è esattamente ciò che dichiara del proprio target: vengono letti solo i file che si trovano direttamente in una directory. Così le stesse due coordinate escono dai segmenti di directory ed entrano nel nome del file, e i file dell’associazione finiscono accanto a quelli del componente come <component-id>--<feature-instance-id>--<file>. Le due coordinate vengono codificate, perché un nome di file non ha alcun separatore su cui ripiegare, e vengono unite al nome proprio del file in corrispondenza di un limite di due caratteri che nessuna coordinata codificata può contenere — ed è questo che mantiene due associazioni che emettono uno stesso nome di file in due file distinti.
  • Un provider che fonde i contributori del suo gruppo in un unico documento fonde in quel documento anche l’output dell’associazione, dove ogni risorsa porta l’identità propria dell’associazione, così ciò che proviene da dove resta leggibile. Dove un tale provider porta un’associazione che ha eseguito il rendering per un target diverso, quel contenuto non può essere fuso in un documento a cui non appartiene, quindi viene scritto accanto a quello assemblato — nella forma con prefisso nel nome del file descritta sopra, per la stessa ragione.

Forme comuni:

  • Un CRD ExternalSecret / VaultSecret generato dal Fetcher di una FeatureRecipe di credenziali.
  • Un CRD ServiceMonitor / PrometheusRule generato da una Feature di osservabilità.
  • Un CRD HTTPRoute / Gateway generato da una Feature di instradamento.

4 — Pipeline di plugin della FeatureRecipe (patch RFC 6902 + emissione di risorse)

Superficie di authoring. La FeatureRecipe dichiara pipeline: — un array di passi di plugin Wasm (principio del Plugin in due parti: Fetcher + Injector per le Features di credenziali; pipeline di plugin arbitrarie per le Features non di credenziali).

Posizione nella pipeline. La pipeline di plugin, dopo il completamento del rendering di base e del rendering da sorgente della FeatureRecipe.

Forma dell’output. Specifica del Plugin. Un passo restituisce due classi di output:

  • Patch RFC 6902 che il motore di applicazione applica ai documenti indirizzati nell’insieme renderizzato (per es. aggiungendo un container sidecar, montando un volume di secret, riscrivendo una variabile d’ambiente sul Deployment sintetizzato).
  • Effetti collaterali — risorse nuove complete emesse accanto alla patch tramite il side_effects di un passo (tipicamente il CRD vault-fetch del Fetcher a cui l’Injector poi fa riferimento).

Stato attuale: disponibile secondo Stato del linguaggio → Fasi della pipeline di compilazione. Ogni passo dichiarato viene eseguito durante aggrega build: l’host invoca il plugin Wasm del passo sull’insieme renderizzato, applica le patch restituite ed emette gli effetti collaterali del passo. Vedi plugins/plugin-contract.md per la superficie del contratto dei plugin.

5 — Composizione a livello di Release (assemblaggio del confine per provider)

Superficie di authoring. Guidata dalla forma della Release — nessun authoring per Recipe. Una capacità che assembla un confine lo fa una sola volta, dopo che ogni nodo di quel confine ha completato il rendering: la capacità compose raccoglie tutti i frammenti per nodo in un unico docker-compose.yaml per confine, e la capacità helm-chart raccoglie le copie dei sub-chart per nodo in un unico umbrella chart per confine.

Posizione nella pipeline. Dopo il rendering di base, una volta che l’output per Recipe di ogni nodo si è accumulato per il confine.

Forma dell’output. Per provider:

  • provider compose — un unico docker-compose.yaml nella radice del confine, che aggrega i servizi, i volumi e le reti di ogni nodo contributore. I file intermedi <nodeID>.compose-fragment.yaml (meccanismi 1 + 2) vengono uniti nell’unico output; i frammenti non compaiono nella directory finale del confine.
  • provider helm-chart — un unico umbrella Chart.yaml + values.yaml nella radice del confine, più directory di sub-chart per nodo sotto charts/<instance_id>/.

6 — Emissione diretta di artefatti della Recipe (artifacts:)

Superficie di authoring. La Recipe dichiara artifacts: come una mappa di voci con nome; ogni voce è o contenuto inline (una stringa con template che porta il corpo del file) o un riferimento $import: a un percorso di file di template — emissione diretta di file senza passare per un provider.

Posizione nella pipeline. Valutazione degli artefatti, all’interno del rendering di base.

Forma dell’output. Un file per ogni voce di artefatto, nominato secondo la chiave della voce nella mappa artifacts:. L’autore della Recipe stabilisce direttamente nome del file e contenuto.

Stato attuale: disponibile secondo Stato del linguaggio → Tipi di input della Recipe. Ogni voce viene valutata con il contesto completo del template dopo la sintesi del workload e la risoluzione della sorgente, e il file risultante viene emesso sotto la chiave della voce. Ciò che un target fa con un artefatto emesso dipende dalla capacità: un provider che accetta un artefatto autonomo lo emette come file a sé, mentre uno che accetta artefatti solo insieme a un altro tipo di input fonde la voce in ciò che assembla — quindi un corpo che non ha la forma attesa da quell’assemblatore provoca un arresto sotto la categoria TRANSLATION_ERROR anziché essere emesso così com’è. Consulta la griglia per capacità in architecture/16-recipe-input-composition.md prima di scrivere un artefatto per una capacità.

Ordine di rendering

I sei meccanismi vengono eseguiti in un ordine definito, così i meccanismi a valle possono leggere gli output di quelli a monte. L’ordine:

  1. Valutazione dei provides — per nodo, il blocco locals: della Recipe viene risolto per primo, nell’ordine dell’autore, con ogni voce che legge le voci sopra di essa; i template provides: del nodo vengono poi valutati, in qualsiasi ordine tra loro (autonomi: .context.instance_id, .context.rendered_name dove il provider del nodo ne riporta uno, .values, .infra, i .locals risolti, testo statico). L’ordine locals-prima-dei-provides è ciò che permette a una voce provides: di leggere un local e ricevere un valore risolto.
  2. Pubblicazione dei locals e risoluzione della sorgente — quei locals vengono pubblicati su .locals, e il template URI source: della Recipe viene valutato su di essi (risolvendo il puntatore della sorgente se è un template). La superficie della sorgente condivide il contesto dei locals, quindi legge .locals e non .provides.
  3. Mappatura di iniezione — i blocchi injectMapping: della FeatureRecipe vengono valutati (il pipe di iniezione viene intercettato prima del rendering della Recipe).
  4. Mappatura dei valori — il valuesMapping: della Recipe viene valutato (la modalità con sorgente + la modalità senza sorgente producono dizionari di valori).
  5. Sintesi del Workload — sintesi del Workload della Recipe (il meccanismo 2 emette manifest per la modalità sintetizzata).
  6. Valutazione degli artefatti — valutazione di artifacts: della Recipe (meccanismo 6).
  7. Render del Provider — il provider esegue il rendering (meccanismo 1 — la modalità con sorgente produce manifest piatti; la modalità senza sorgente produce manifest generativi).
  8. Rendering delle Feature — rendering della FeatureRecipe per ogni associazione di Feature sul nodo (meccanismi 3 + 4 — la generazione di risorse viene eseguita qui; la pipeline di plugin viene eseguita più tardi, al passo 9).
  9. La pipeline di plugin — mutazione post-rendering: i passi di plugin pipeline: della FeatureRecipe applicano patch RFC 6902 ed emettono risorse aggiuntive (meccanismo 4).
  10. Composizione a livello di Release — l’assemblaggio del confine della capacità raccoglie i frammenti per nodo in output per confine (meccanismo 5).

L’ordine conta perché i meccanismi a valle possono leggere gli output di quelli a monte — per esempio, un passo della pipeline di plugin può applicare una patch a un Deployment renderizzato dal provider, e un compositore a livello di Release può unire frammenti emessi dal render del provider, dal rendering delle funzionalità e dalla pipeline di plugin.

Insieme di regole di rilevamento delle collisioni

Quando due meccanismi producono un file con lo stesso nome nella stessa directory di confine, la build si arresta, nominando ogni contributore, sotto la categoria indicata da ciascuna regola qui sotto. L’insieme di regole:

Regola di forma della Recipe: collisione delle chiavi delle voci di artifacts:

Una Recipe dichiara due voci sotto artifacts: con la stessa chiave (la chiave determina il nome del file emesso, sia che il corpo della voce sia scritto inline sia che venga caricato tramite $import:). Rilevata al momento del caricamento della Recipe secondo errors/fatal-halts.md «artifacts: entry keys must be unique (Le chiavi delle voci degli artefatti devono essere univoche)».

Regola di forma della Recipe: collisione in fase di emissione tra tipi di input

I tre tipi di input di una Recipe — con sorgente, sintetizzato e artefatti — emettono ciascuno file nella stessa directory di confine. Se l’output renderizzato dalla sorgente, sintetizzato dal workload o emesso come artefatto produce un file il cui nome è stato prodotto anche da un altro tipo di input, la build si arresta all’emissione. Rilevata al momento dell’emissione secondo errors/fatal-halts.md «Emission-time filename collision across input kinds (Collisione di nomi di file in fase di emissione tra tipi di input)».

Collisione dei nomi dei servizi Compose (a livello di Release)

Quando due nodi diversi (in qualsiasi combinazione di confini) contribuiscono servizi con lo stesso nome all’output compose unito, il provider compose si arresta mentre compone il confine, sotto la categoria TRANSLATION_ERROR, nominando ogni tupla (boundary, node, serviceName) contributrice. Rilevata durante la composizione a livello di Release secondo la sezione sull’output a livello di Release di providers/compose.md.

Un servizio viene rifiutato solo in base al nome, senza confrontare ciò che i due nodi hanno dichiarato. Un servizio compose è un singolo container in esecuzione, quindi due nodi che ne volevano ciascuno uno ne ottengono uno solo in due, e l’intento di un contributore va perso per quanto identiche siano le due definizioni.

Conflitto dei nomi di volume e di config di Compose (a livello di Release)

Quando due nodi diversi contribuiscono una voce di primo livello volumes: o configs: con lo stesso nome all’output compose unito, e le due dichiarazioni differiscono, il provider compose si arresta sotto la categoria TRANSLATION_ERROR, nominando la voce e ogni tupla (boundary, node) contributrice. Rilevato durante la composizione a livello di Release secondo la sezione sull’output a livello di Release di providers/compose.md.

A differenza della regola sui servizi qui sopra, questa confronta le dichiarazioni, e un nome condiviso è legittimo dove i contributori concordano. Un volume o una config con nome è un unico oggetto, quindi due nodi che lo dichiarano in modo identico hanno entrambi chiesto esattamente la voce con cui finisce il documento unito, e nulla va perso. Due nodi che lo dichiarano in modo diverso sono in disaccordo su quell’unico oggetto, e mantenere l’una o l’altra dichiarazione scarterebbe l’altra da una build che altrimenti andrebbe a buon fine. Due dichiarazioni contano come concordi quando descrivono la stessa voce nel file assemblato, quindi un corpo scritto come mappatura vuota e uno omesso del tutto concordano.

Alias e directory dei sub-chart di helm-chart

Un sub-chart di helm-chart si trova in charts/<instance_id>/ e i suoi valori sono circoscritti sotto il suo alias, che è l’ID dell’istanza codificato per la posizione dell’alias. Due istanze non possono arrivare a uno stesso alias a meno che i loro ID di istanza non siano la stessa stringa, perché la codifica scrive per esteso i caratteri che un alias non accetta anziché sostituirli — quindi un alias identifica esattamente un sub-chart, e i valori scritti sotto di esso raggiungono solo quel sub-chart. Gli ID di istanza sono a loro volta univoci per confine in base alle regole di appiattimento dell’Aggregate, quindi nemmeno la directory può collidere. Entrambe le metà sono strutturali: nessuna delle due si basa su un controllo.

Collisione dei nomi delle risorse renderizzate da Helm

All’interno di un confine, due nodi il cui rendering produce lo stesso nome di risorsa Kubernetes producono due file YAML con campi metadata.name sovrapposti. I nomi dei file differiscono, perché ciascuno ha come prefisso la propria base di denominazione, mentre il metadata.name al loro interno può comunque coincidere — quindi la build controlla i nomi che portano le risorse renderizzate, e due contributori che derivano uno stesso nome per uno stesso kind in uno stesso namespace la arrestano sotto la categoria TRANSLATION_ERROR prima che venga scritto qualsiasi cosa, nominando il nome e ciascun componente, e ciascuna associazione, che lo ha derivato (vedi errors/fatal-halts.md).

Il caso più ampio è chiuso per costruzione anziché controllato. Un chart con sorgente che nomina le proprie risorse in base al nome della release non può più produrre questo tra due componenti, perché due basi di denominazione che differiscono anche minimamente arrivano a due nomi di release — vedi providers/helm.md «How the release name is derived (Come viene derivato il nome della release)». Restano due casi, e il controllo descritto sopra è ciò che li segnala. Uno è un chart che scrive letteralmente un nome di risorsa nei propri template, e nessuna derivazione può distinguere un tale nome da qualsiasi altro letterale. L’altro sono due associazioni di Feature su un componente che forniscono ciascuna un chart scritto dal suo autore: entrambe eseguono il rendering con il nome della release di quel componente, per progettazione, quindi due chart che nominano una risorsa in base a .Release.Name si incontrano lì — dai alle risorse dei due chart nomi distinti, oppure associali a componenti diversi.

Ogni nome sintetizzato inizia con l’identità propria del nodo — quello dell’oggetto controller, e ogni nome per risorsa tramite la convenzione sintetizzata dei nomi dei Service <release name>-<svcName> (secondo entities/workload.md «Synthesized-name convention (Convenzione dei nomi sintetizzati)») — il che rende le collisioni tra nodi strutturalmente impossibili per costruzione. Gli autori la cui build si arresta su un nome di Deployment / Service dovrebbero verificare innanzitutto se due Recipes diverse stanno emettendo risorse con lo stesso nome tramite percorsi di rendering diversi (per es. il templates/deployment.yaml di un chart con sorgente che collide con il metadata.name di un Deployment sintetizzato dal workload).

Modelli di interazione tra meccanismi

Workload sintetizzato + patch della pipeline di plugin

Il modello canonico: il meccanismo 2 (sintesi del workload) emette un Deployment di base; il meccanismo 4 (il plugin Injector) applica una patch RFC 6902 che monta un volume di secret nel Deployment. I due meccanismi si compongono — il Deployment è la stessa risorsa K8s, con la patch che sovrappone riferimenti a ConfigMap / Secret alla base sintetizzata.

Questo è il modello dominante per l’iniezione di credenziali sui workload sintetizzati. Il Fetcher (meccanismo 3, generazione di risorse) emette un CRD ExternalSecret che il cluster recupera a runtime; l’Injector (meccanismo 4, una patch della pipeline di plugin) modifica il Deployment per montare il Secret K8s risultante.

Con sorgente + sintesi del Workload su confini diversi

Un singolo Aggregate può avere un componente legato a una Recipe helm con sorgente (meccanismo 1) sul confine A e un componente fratello legato a una Recipe helm che sintetizza il Workload (meccanismo 2) sul confine B. La directory di ciascun confine porta la forma di output appropriata; la denominazione dei file tra confini non collide perché le directory dist/ per confine sono isolate l’una dall’altra.

Unione di Compose a livello di Release per directory di output

L’assemblaggio della capacità compose raccoglie i frammenti per nodo di ogni confine la cui directory viene valutata come uno stesso percorso in un unico docker-compose.yaml in quel percorso; due confini destinati a compose in una stessa Release scrivono due file quando le loro directory differiscono, e un unico file unito quando condividono una directory.

Le collisioni dei nomi dei servizi vengono quindi rilevate per file, alla sua unione a livello di Release, secondo la regola qui sopra. Due confini destinati a compose in directory diverse che dichiarano ciascuno un servizio chiamato api non collidono: il file di ciascun confine porta il proprio. Due che condividono una directory scrivono un unico file, e la build si arresta nominando entrambi i contributori.

Riferimenti incrociati

  • entities/recipe.md — superficie di authoring della Recipe (i meccanismi 1 + 2 + 6 emettono a partire dal contenuto della Recipe).
  • entities/featurerecipe.md — superficie di authoring della FeatureRecipe (i meccanismi 3 + 4 emettono a partire dal contenuto della FeatureRecipe).
  • providers/helm.md — forme di output per meccanismo e convenzioni di denominazione del provider helm.
  • providers/helm-chart.md — composizione umbrella + sub-chart del provider helm-chart (meccanismo 5).
  • providers/compose.md — frammentazione per nodo + composizione a livello di Release del provider compose (meccanismo 5).
  • errors/fatal-halts.md — le regole di forma della Recipe sulle chiavi univoche delle voci di artifacts: e sulla collisione dei nomi di file tra tipi di input.
  • templates/expansion-matrix.md — tempistica di valutazione per sito di template lungo l’ordine di rendering.
  • plugins/plugin-contract.md — la superficie del contratto della pipeline di plugin (meccanismo 4).
  • 10-status.md — stato di disponibilità attuale del meccanismo 6 (artifacts:) e del runtime della pipeline di plugin del meccanismo 4.
  • architecture/10-compilation-pipeline.md — la pipeline di compilazione completa, incluso l’ordine delle fasi di rendering.
  • architecture/16-recipe-input-composition.md — i tre tipi di input della Recipe (l’inquadramento a monte dei meccanismi 1 + 2 + 6).