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

Composizione degli input della Recipe — tre tipi di input, Workload, artefatti

Una Recipe produce file manifest per il suo provider di destinazione. Questo capitolo descrive come le Recipes compongono il loro output a partire da tre tipi di input ortogonali — sourced, synthesized e artifacts — come è strutturato ciascun tipo di input, e quale provider produce quale output. Il ruolo concettuale dell’entità Recipe (il template di traduzione scritto da Ops che mappa l’intento dello sviluppatore su un singolo provider fisico) è descritto in 04-entity-taxonomy.md; la superficie di authoring della Recipe a livello di parola chiave è descritta in ../language-reference/entities/recipe.md.

Motivazione

Lo strumento di rendering nativo di ciascun provider — Helm, Docker Compose — sa già come rendere manifest nativi del provider. Il compito di una Recipe è dichiarare COSA devono dire quei manifest: quali immagini container, quali porte, quali variabili d’ambiente, quali volumi, quali servizi, quali limiti di risorse.

Una Recipe deve esprimere più di quanto possa contenere un insieme fisso di chiavi (ad es. image, environment, ports, replicas) mappato su un Deployment e un Service, tra cui:

  • resources (richieste/limiti di CPU/memoria)
  • Probe di liveness, readiness o startup
  • volumeMounts / volumes
  • nodeSelector / affinity / tolerations
  • serviceAccount / securityContext
  • Pod multi-container, sidecar
  • Risorse ConfigMap / Secret / PVC / CRD
  • Service non ClusterIP (LoadBalancer, NodePort, Headless)

Il livello di astrazione deve descrivere la forma completa di un carico di lavoro, non un insieme fisso di chiavi. I tre tipi di input descritti di seguito sono quell’astrazione: una Recipe compone il proprio output in modo additivo a partire da un chart o modulo caricato esternamente (source:), da una specifica astratta di Workload che il provider sintetizza in manifest nativi del provider (workload:) e da manifest nativi del provider basati su template che la Recipe emette direttamente (artifacts:).

I tre tipi di input

Composizione per addizione

Esistono tre modi per produrre file manifest nativi del provider da una Recipe, e si compongono per addizione anziché escludersi a vicenda:

  1. source: — un artefatto caricato esternamente (chart Helm, file compose) che il provider rende in modo nativo, con valuesMapping: che fornisce i valori di overlay.
  2. workload: — una specifica astratta di Workload (tipo di proprietà della piattaforma) che il provider sintetizza in manifest nativi del provider. Il campo accetta un block scalar YAML inline o un $import: verso un singolo file locale o una voce di libreria; lo smistamento è guidato dalla forma del contenuto.
  3. artifacts: — una mappa di manifest nativi del provider, inline o caricati con $import:, elaborati come template Go rispetto all’intero contesto dei pilastri. Ogni voce può essere scritta inline (il valore della voce è un block scalar) o tramite $import: verso un singolo file o un contenuto di libreria.

Tutti e tre producono file che il compilatore emette nella directory di output del boundary. Tutti e tre possono coesistere in un’unica Recipe, nel rispetto delle regole di validazione riportate sotto. La semantica di unione è solo di primo livello: ogni tipo di input produce file completi; i file vengono emessi uno accanto all’altro; una collisione sul nome del file di output è un errore fatale.

Nomi descrittivi delle modalità

Le tre «modalità» sono un vocabolario descrittivo per la documentazione e la diagnostica. Gli autori di Recipe non dichiarano una modalità; scrivono le parole chiave di cui hanno bisogno. Una Recipe è caratterizzata dal suo input dominante:

Parole chiave dominantiNome descrittivo della modalità
source: + valuesMapping: (nessun workload:, nessun artefatto)sourced
workload: (nessun source:, nessun artefatto)synthesized
artifacts: (nessun source:, nessun workload:)artifacts-only (informalmente: «inline»)
Qualsiasi combinazione di due o piùdescritta esplicitamente (ad es. «sourced con artifacts», «synthesized con artifacts»)

Non esiste una parola chiave chiamata mode: né un enum. La modalità è una proprietà emergente di quali input sono presenti.

La forma di una Recipe in sintesi

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: ...
version: 1.0.0
spec:
capability: helm | compose | helm-chart | ...
implements: core/...:1.0.0
locals: { ... }
provides: { ... }
# ─── Sourced input (optional, paired) ───
source: ...
valuesMapping: |
# Go template → YAML/JSON overlay values
# OR:
valuesMapping:
$import: ./mappings/api-server.tmpl # local file path
# OR:
valuesMapping:
$import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ───
workload: |
# Go template → YAML → parsed Workload
# OR (single-source $import for whole-content load from a file or library):
workload:
$import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ───
artifacts:
"filename.yaml": |
# Inline Go template → manifest YAML
"other.yaml":
$import: ./artifacts/other.yaml # per-entry $import: for file or library content

Ogni campo sopra è accettato dallo schema della Recipe, e il compilatore consuma tutti e tre i tipi di input — il rendering sourced, la sintesi del Workload e l’emissione degli artifacts. Ciò che differisce è il supporto per provider — quale provider rende quale tipo di input — riportato nella matrice delle capacità dei Provider alla fine di questo capitolo.

Regole di validazione al caricamento

Lo schema della Recipe e la validazione al caricamento impongono queste regole di composizione:

  1. valuesMapping: richiede source:. Senza un source: su cui applicare l’overlay, non c’è nulla che riceva i valori mappati. Una Recipe con valuesMapping: e senza source: è un errore al caricamento. (Un source: senza valuesMapping: è consentito — il chart o il modulo viene reso con i propri valori predefiniti.)
  2. workload: accetta una sola sorgente — inline o $import:, non entrambe. Una Recipe specifica il Workload come block scalar inline oppure come $import: verso un singolo file. La forma $import: è a sorgente singola secondo il vocabolario unificato di importazione dei file; l’unione di più sorgenti non è supportata in workload:. Uno smistamento malformato è un errore al caricamento.
  3. workload: richiede un provider capace di sintesi. Il supporto alla sintesi è una proprietà del provider stesso, non di un campo dichiarato. Una Recipe workload: associata a un provider che non può sintetizzare viene rifiutata quando il nodo viene reso — tramite il controllo delle capacità del provider (vedi la matrice delle capacità dei Provider) — con una diagnostica chiara. Il catalogo della libreria standard dichiara workloadSchema sui provider capaci di sintesi per convenzione, come contratto di traduzione documentato, ma il controllo si basa sulla capacità riportata dal provider stesso anziché sulla presenza di quel campo.
  4. Deve essere presente almeno un tipo di input. Una Recipe senza nessuno tra source:+valuesMapping:, workload: o artifacts: non produce alcun output ed è un errore al caricamento.
  5. Le voci di artefatto inline e $import: possono coesistere. Una Recipe può dichiarare alcune voci di artifacts: inline e altre tramite direttive $import: per singola voce. La chiave di ogni voce nomina il proprio output, quindi le voci delle due forme non entrano mai in collisione tra loro (vedi Cosa dà il nome a ciascun file di output).
  6. Le collisioni di nomi di file tra tipi di input diversi sono errori al momento del rendering. Se due tipi di input di una Recipe — output reso dalla sorgente, output sintetizzato dal carico di lavoro o output emesso dagli artefatti — producono un file con lo stesso nome, il compilatore emette un errore fatale che identifica ogni contributore. Questo controllo viene eseguito dopo la traduzione del Workload, quindi avviene al rendering anziché al caricamento.

Il tipo Workload

Proprietà e posizione

Workload è un tipo di proprietà della piattaforma in apiVersion: aggrega.ai/v1beta1. La sua dichiarazione JSON Schema 2020-12 è incorporata nel binario del compilatore in fase di build; gli autori di catalogo non modificano lo schema del Workload, né scrivono file YAML Workload autonomi come entità di catalogo. La grammatica del Workload viene consumata all’interno del campo workload: di una Recipe o di una FeatureRecipe (inline, o tramite $import: verso un singolo file o una voce di WorkloadLibrary) e in nessun altro punto.

Il Workload è un tipo della piattaforma e un concetto del compilatore, non un’entità separata nella tassonomia delle entità. La Recipe è l’entità di authoring; il Workload è la forma che assume l’input sintetizzato della Recipe.

Un Workload per Recipe

Una Recipe dichiara al massimo un workload:. Il Workload rappresenta la singola unità di calcolo associata al Component che questa Recipe implementa. Allo stesso modo, una FeatureRecipe dichiara al massimo un proprio workload: — un’unità di calcolo di proprietà della Feature, sintetizzata tramite lo stesso tipo Workload — vedi FeatureRecipe. I casi d’uso che richiedono carichi di lavoro secondari aggiuntivi si esprimono tramite:

  • artifacts: — manifest aggiuntivi accanto al carico di lavoro, nella stessa Recipe (inline o tramite $import: per singola voce).
  • Features con generazione di risorse — carichi di lavoro secondari trasversali (ad es. un sidecar di backup associato ai database) dichiarati come entità di catalogo separate, in cui la FeatureRecipe sintetizza il proprio workload: (o esegue il rendering tramite source: / artifacts:). Vedi 14-extensibility.md per la generazione di risorse della FeatureRecipe.

Questo preserva il modello di un’unità di calcolo per autore: una Recipe sintetizza il carico di lavoro del Component; una FeatureRecipe sintetizza il proprio.

La superficie completa

L’insieme dei campi del Workload è ampio e cresce. Invece di riportarlo qui, dove una copia resterebbe indietro rispetto al contratto senza che nulla lo segnali, questo capitolo rimanda alle due superfici che lo contengono per intero:

  • Il riferimento generato dello schema del Workload — ogni campo, il suo tipo, il suo valore predefinito e i suoi vincoli, generato dal JSON Schema pubblicato e confrontato con esso a ogni build, così non può descrivere una forma che il compilatore non accetta.
  • La pagina di authoring del Workload — indicazioni di authoring a livello di campo: cosa significa ciascun campo, in cosa lo rende ciascun provider e quali combinazioni la build rifiuta.

La dichiarazione JSON Schema 2020-12 del Workload è autorevole ed è distribuita incorporata nel binario del compilatore. I provider helm e compose sintetizzano il workload: di una Recipe, inline o caricato tramite $import:; vedi la matrice delle capacità dei Provider per il supporto per provider.

Integrazione dei secret con featuresSchema

Il blocco containers.<name>.attachments del Workload fa riferimento a slot dichiarati dal featuresSchema del Component; non dichiara nuovi slot. Vedi ../language-reference/entities/component.md per la superficie di authoring di featuresSchema.

Il contratto di validazione:

  • Ogni valore attachments.<KEY>.from deve corrispondere a un nome di slot dichiarato nel featuresSchema del Component — oppure, per una voce che nomina una connessione con connection: <alias>, a uno slot che il socket di quella connessione dichiara in usesSchema.<socket>.featuresSchema. Una voce di questo tipo viene riscritta sul nome che l’associazione della connessione assume sul componente (<alias>.<slot>) prima che venga applicata una qualsiasi di queste regole, così ogni regola sotto la legge come legge una voce che nomina uno slot proprio del Component.
  • Il meccanismo di consegna as: (env o file) deve essere presente nella lista consentita dell’array inject: di quello slot.
  • Gli slot marcati inject: [] (blackbox) nel featuresSchema del Component non possono comparire nei blocchi attachments: del Workload — quegli slot vengono consegnati dalla logica interna della Recipe (ad es. tramite existingSecret di Helm), non tramite l’esposizione del Workload.

Esempio:

# In the Component
spec:
featuresSchema:
db_password:
required: true
inject: [env, file] # transparent: Workload may dictate delivery
root_password:
required: true
inject: [] # blackbox: Recipe handles internally
# In the Recipe
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected — root_password is blackbox

Probe di salute: intento, non meccanismo

Le probe di Kubernetes e gli healthcheck di Docker Compose hanno forme diverse. Un’unica forma astratta di intento si traduce in modo pulito in entrambe:

health:
ready:
http: /healthz # intent: HTTP GET probe
timeoutSeconds: 5
live:
tcp: 8080 # intent: TCP socket check
timeoutSeconds: 5
startup:
exec: ["check-ready.sh"] # intent: command exec
timeoutSeconds: 30
periodSeconds: 10

I Providers traducono ogni intento nella propria forma nativa:

IntentoHelm (K8s)Compose
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"
exec: [cmd]exec.command: [cmd]CMD [cmd]

La risoluzione della porta per http: senza una porta esplicita prende il primo nome di porta in ordine alfabetico che il container dichiara sotto containers.<name>.ports, su entrambi i target. Un container che non dichiara alcuna porta con nome non può avere una probe HTTP, e la build si interrompe indicando la probe.

Compose degrada le probe HTTP/TCP a comandi shell di healthcheck, e un servizio compose porta un solo healthcheck: quando è dichiarata più di una probe, ne viene tradotta una e un avviso nomina quelle scartate.

Tipi di volume

Cinque tipi di volume; nessun tipo composto:

TipoSemanticaK8s (helm)Compose
ephemeralTmpfs / emptyDir; muore con il podemptyDir: { sizeLimit }mount tmpfs:, senza dimensione (un avviso segnala un sizeLimit scritto dall’autore)
configmapFile di configurazione in sola letturaRiferimento a un volume ConfigMapriferimento configs: a livello di servizio a una config di primo livello dichiarata da artifacts: della Recipe
secretFile di secret in sola letturaRiferimento a un volume Secretfile di secret di sola lettura montato in bind
persistentPVC singolo; sopravvive ai riavvii del podRisorsa PVC + volume.persistentVolumeClaimvolume con nome
persistentTemplatePVC per replica; complemento di form: statefulStatefulSet.volumeClaimTemplatesvolume con nome (degradato; viene emesso un avviso)

Compose non può esprimere template per replica. Quando persistentTemplate viene tradotto in compose, degrada a un singolo volume con nome condiviso da tutte le repliche, e un avviso segnala la degradazione. Un volume persistentTemplate richiede form: stateful; dichiararlo su qualsiasi altra forma interrompe la build.

Esposizioni multi-servizio

Ogni servizio è un’esposizione indipendente. Uno schema comune: un servizio HTTP sulla porta 8080 (ClusterIP interno) + un servizio di metriche sulla porta 9090 (ClusterIP) + un endpoint di amministrazione sulla porta 9901 (LoadBalancer):

services:
http:
type: ClusterIP
ports:
web: 8080
metrics:
type: ClusterIP
ports:
prom: 9090
admin:
type: LoadBalancer
ports:
admin: 9901

Ciascuno diventa un oggetto Service Kubernetes separato quando viene reso con il provider helm, che invece si interrompe su una voce Loopback. In compose, i servizi NodePort e LoadBalancer pubblicano le loro porte su ogni interfaccia host del servizio compose, quelli Loopback solo sull’indirizzo di loopback dell’host, e quelli ClusterIP e Headless non pubblicano nulla.

Nell’output K8s i nomi dei servizi hanno come prefisso l’instance_id del componente, per garantirne l’unicità. I nomi delle porte devono corrispondere ai nomi delle porte del container dichiarati in containers.<name>.ports.

Contratto di traduzione lato Provider: workloadSchema

Un Plugin di rendering per provider (pluginType: provider) dichiara un spec.provider.workloadSchema — una dichiarazione JSON Schema 2020-12 che documenta come i campi del Workload si traducono nell’output nativo di quel provider. Questo è il contratto di traduzione autodocumentante. Vedi ../language-reference/entities/plugin.md per la superficie di authoring del Plugin, incluso il blocco spec.provider.

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: helm-renderer
version: 1.0.0
pluginType: provider
spec:
abiVersion: v1beta1
provider:
workloadSchema: | # how Workload translates to K8s manifests
// Each Workload produces: 1 controller object chosen by workload.form
// (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job)
// + 1..N Services (one per workload.services entry)
// + 1..N PVCs (one per workload.volumes.*.persistent entry)
// + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source)
// ...

Il campo workloadSchema comunica l’intento di traduzione agli autori di catalogo e agli strumenti IDE. È il contratto di traduzione documentato, dichiarato per convenzione sui provider che sintetizzano — ma il supporto alla sintesi è determinato dal provider stesso, non dalla presenza di questo campo. Una Recipe che punta con workload: a un provider che non può sintetizzare viene rifiutata quando il nodo viene reso — tramite il controllo delle capacità del provider — con un errore chiaro, che il provider dichiari o meno workloadSchema.

Lo schema del Plugin dichiara spec.provider.workloadSchema — il suo corpo viene compilato in JSON Schema 2020-12 quando il Plugin viene caricato — e il consumo di workload: lato Recipe è disponibile. Il supporto alla sintesi è imposto al momento del rendering dal controllo delle capacità del provider, basato sulla capacità riportata dal provider associato; workloadSchema è il contratto documentato che il catalogo della libreria standard mantiene allineato con quella capacità, non è esso stesso l’input del controllo. aggrega validate, eseguito sull’intero catalogo, segnala inoltre in anticipo, prima di una build, una Recipe workload: associata a un provider che non sintetizza, quando il catalogo contiene l’entità Plugin di quel provider.

Le risorse ausiliarie vivono fuori dal Workload

La specifica del Workload non ha un campo additionalResources, né extras, né dichiarazioni inline di ConfigMap/Secret/CRD. Il Workload modella solo la forma del carico di lavoro: container, volumi, servizi, repliche, scheduling, contesto di sicurezza, service account — tutto ciò che descrive come viene eseguita la singola unità di calcolo.

Le risorse ausiliarie hanno due collocazioni legittime fuori dal Workload:

  1. Features + FeatureRecipes — il meccanismo per le esigenze trasversali. Un ServiceMonitor associato a «qualsiasi server con metriche esposte» è core/prometheus-exporter come Feature. Anche la risorsa di routing che pubblica un server su un hostname è una Feature, e la forma di routing decide quale: core/public-ingress dove il target riconcilia un Ingress, core/http-route dove esegue la Gateway API — ciascuna realizzata da una FeatureRecipe che il Manifest seleziona per ogni Release. Una NetworkPolicy imposta su tutti i carichi di lavoro di produzione è una Feature che la Release di produzione associa all’intero boundary. Le Features si compongono in modo ortogonale e possono essere riutilizzate tra Recipes. Vedi 14-extensibility.md per la generazione di risorse della FeatureRecipe.
  2. artifacts: a livello di Recipe — per le risorse che appartengono all’implementazione di questa specifica Recipe e per cui non vale la pena creare una Feature. Una registrazione di CRD una tantum di cui la Recipe ha bisogno. Un PodDisruptionBudget specifico della Recipe che si applica solo quando questa Recipe è usata. Una ConfigMap a cui fa riferimento il Workload della Recipe. Ogni voce è inline o caricata con $import:; vedi più avanti la sezione sul meccanismo degli artefatti.

Il confine tra Feature e artefatto è una convenzione sociale. Se una risorsa ausiliaria è trasversale (si applica a molte Recipes, o è associata in modo condizionale tramite selettori), è una Feature. Se è intrinseca a questa sola Recipe (la Recipe non può svolgere il suo compito senza emettere quella risorsa), è un artefatto. Gli autori scelgono in base al riuso e alla semantica di associazione; il compilatore non controlla la scelta.

Le Features e gli artefatti delle Recipe coprono insieme le risorse ausiliarie di cui una Recipe ha bisogno.

Il meccanismo degli artefatti

Artefatti inline e caricati da file

Il tipo di input artifacts emette file manifest nativi del provider basati su template direttamente nell’output del boundary, accanto a qualsiasi output reso dalla sorgente o sintetizzato dal carico di lavoro. Gli autori lo dichiarano tramite due superfici:

spec:
artifacts:
"servicemonitor.yaml": |
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: {{ .context.instance_id }}-monitor
spec:
endpoints:
- port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml":
$import: ./artifacts/networkpolicy.yaml
"crd-registration.yaml":
$import: ./artifacts/crd-registration.yaml

I percorsi di $import: sono relativi alla directory della Recipe e devono restare al suo interno, perché ogni file che una pubblicazione della Recipe porta con sé viene preso da quella directory — ogni file nominato da un’importazione viaggia con essa — e un file al di fuori non lo farebbe. Una convenzione tipica li colloca in una sottodirectory ./artifacts/, anche se il compilatore non lo impone. La chiave della mappa dà il nome a ciascun file emesso — la sezione successiva spiega cosa significa in ciascuna delle tre forme.

Ogni voce (inline o caricata con $import:) viene elaborata come template Go rispetto all’intero contesto del template prima di essere emessa nella directory di output.

Cosa dà il nome a ciascun file di output

La mappa è indicizzata per nome di voce, e la chiave nomina ciò che la voce emette in ogni forma di authoring. Per una voce inline la chiave è il nome del file di output, usato così come è scritto:

artifacts:
"configmap-config.yaml": |
...
"pdb.yaml": |
...

Produce configmap-config.yaml e pdb.yaml. La chiave fissa il nome del file; dove il file finisce è una decisione del target, e la sezione sull’emissione per provider più avanti lo descrive.

Per una voce $import: da file anche la chiave è il nome del file di output. Il file importato fornisce il contenuto; non fornisce il nome, quindi un autore che vuole un determinato nome di file di output scrive quel nome come chiave:

artifacts:
"monitor.yaml":
$import: ./artifacts/monitor.yaml
"netpol.yaml":
$import: ./artifacts/subdir/some-other-name.yaml

Produce .../monitor.yaml e .../netpol.yaml. Il file importato dalla seconda voce si chiama some-other-name.yaml, e quel nome non arriva all’output — ci arriva la chiave. Due voci che importano file diversi che per caso condividono un nome, ./extras/shared.yaml e ./overrides/shared.yaml, sono quindi due output distinti, ciascuno nominato dalla propria chiave.

Per una voce $import: da libreria, che importa un bundle di file come un’unica unità, la voce si espande in un output per ogni file del bundle, ciascuno annidato sotto la chiave come <key>/<filename>. Una chiave nomina molti file, quindi la chiave da sola non può nominarli: è la directory in cui finiscono i file del bundle anziché il nome di uno di essi.

Poiché ogni forma nomina il proprio output a partire dalla chiave, la chiave è limitata, nella superficie di authoring, a ciò che può essere un singolo nome di file: una lettera o una cifra iniziale, seguita da lettere, cifre, punti, trattini e underscore. I punti portano l’estensione che un consumer si aspetta, ed è ciò che rende una chiave utilizzabile direttamente come nome di file; e l’alfabeto non contiene / né un . iniziale, quindi una chiave non può mai comporre più di un segmento di percorso e non può mai essere il segmento della directory padre. Una chiave fuori dall’alfabeto non supera la validazione dell’envelope al caricamento del workspace, in aggrega validate e nella diagnostica dell’editor.

Due output di artifacts: con lo stesso nome di file interrompono la build quando il nodo viene reso, qualunque siano le forme che li hanno prodotti. Due voci di una stessa mappa artifacts: non nominano mai uno stesso output: una chiave è unica all’interno di un documento ed è un singolo nome di file, quindi il nome dell’output di una voce a file singolo è la sua chiave e gli output di una voce bundle si trovano tutti sotto una directory nominata dalla sua chiave. Il primo segmento di ogni percorso emesso è quindi la chiave che lo ha prodotto, e chiavi distinte restano nomi di output distinti. Ciò che l’interruzione copre è il caso che attraversa i tipi di input — un nome di file fornito da due di essi, un template del chart e una voce di artefatto che producono entrambi servicemonitor.yaml — con una diagnostica che nomina ogni origine che vi contribuisce.

Contesto dei template per gli artefatti

I template degli artefatti hanno accesso all’intero contesto dei pilastri:

  • .values, .infra, .context.*, .locals, .provides, .features, .metadata — i pilastri standard di Aggrega descritti in 06-data-taxonomy-and-composition.md.
  • .workload — la specifica del Workload analizzata per questa Recipe (se presente). Permette agli artefatti di fare riferimento ai valori del Workload senza duplicazioni, ad es. un ServiceMonitor che fa riferimento a .workload.services.metrics.ports.prom.
  • .source — il contenuto risolto del campo source: (se presente).

Gli artefatti vengono valutati dopo l’analisi del Workload, quindi .workload è disponibile quando presente. Per le Recipes senza workload:, .workload è nil; un template che tenta di dereferenziarlo fallisce con un errore chiaro. Per le Recipes senza source:, .source è nil con la stessa modalità di errore.

L’invariante di autocontenimento

Gli artefatti devono essere autocontenuti. Possono fare riferimento solo agli input dichiarati della Recipe: il contesto dei pilastri, il Workload della Recipe stessa (quando presente) e il valore source: della Recipe stessa. Non possono fare riferimento a:

  • Output di altre Recipes nello stesso boundary.
  • Risorse Kubernetes dell’ambiente che la Recipe non ha dichiarato.
  • Secret, ConfigMap o altre risorse che si presume esistano esternamente (a meno che non vi si faccia riferimento tramite un pilastro dichiarato).

Un artefatto ConfigMap a cui fa riferimento volumes.*.configmap.source del Workload deve essere emesso da QUESTA Recipe (tramite artifacts: che produce quella ConfigMap) o da una Feature associata a questo nodo. Le dipendenze tra una Recipe e l’altra all’interno di un boundary non sono supportate.

Questa invariante preserva la riusabilità della Recipe: una Recipe può essere inserita in qualsiasi combinazione Aggregate + Release che soddisfi il suo contratto dei pilastri, senza dipendenze nascoste.

Label di provenienza

Dopo la traduzione, ogni file emesso porta la provenienza aggrega.ai/* nei suoi metadati — che sia stato reso dalla sorgente, sintetizzato dal carico di lavoro o emesso da un template di artefatto. Ogni superficie di emissione la applica a partire da un unico insieme condiviso di builder, così lo stesso file porta sempre la stessa provenienza qualunque sia il tipo di input che lo ha prodotto. L’insieme si divide a seconda che un valore rispetti il set di caratteri dei valori delle label Kubernetes: le chiavi sicure per le label sono label (interrogabili); le chiavi non sicure per il set di caratteri — recipe-uri (contiene un :), boundary-path (un percorso annidato contiene /) e sync-wave (il - iniziale di un wave negativo) — sono annotazioni, i cui valori non hanno vincoli. Un valore di identità che la build non vincola alle regole delle label — il nome dell’aggregato, l’ambiente, il nome del provider, le versioni del compilatore e del provider — è una label scritta in una forma che una label ammette e, dove quella forma differisce dal valore, il valore letterale è anche un’annotazione sotto la stessa chiave (un Aggregate chiamato imported/flow riceve la label imported-flow e l’annotazione imported/flow). Tutti i file che portano l’output della stessa Recipe condividono la stessa provenienza:

metadata:
labels:
aggrega.ai/component-id: api
# ... plus the recommended app.kubernetes.io/name label
annotations:
aggrega.ai/recipe-uri: api-server-helm:1.0.0
aggrega.ai/boundary-path: production

Questa suddivisione è uniforme tra tutti e tre i tipi di input. (Il provider Compose non ha il concetto di annotazione e i suoi valori di label non hanno vincoli, quindi emette l’intero insieme come label del servizio.) Vedi 11-governance-and-compliance.md per l’applicazione della provenienza in fase di compilazione.

Poiché un provider applica la provenienza dove il proprio formato di output la prevede, un provider il cui formato non offre un tale spazio per un dato file emette quel file invariato e lo segnala. Compose è il caso da conoscere: il punto in cui applica la provenienza è il blocco labels: di un servizio, quindi un frammento di artefatto compose che contribuisce solo volumes:, configs: o models: di primo livello non porta alcuna provenienza, e la build emette un avviso «skipped provenance label injection (iniezione delle label di provenienza saltata)» che nomina l’artefatto. Quell’avviso è previsto per un frammento di quella forma e non è il segno di un problema — i servizi che lo stesso componente emette portano l’insieme completo, e nulla dei byte emessi cambia. Ciò che esclude è la terza possibilità: un file che esce dalla build senza provenienza senza essere nominato.

CloudFormation è l’altro caso da conoscere, e differisce per dove finisce la provenienza piuttosto che per il fatto che finisca o meno. Un template CloudFormation non ha un blocco di metadati a livello di documento che viaggi con una risorsa, quindi la provenienza va sull’attributo Metadata di ciascuna risorsa, sotto un’unica chiave aggrega.ai/provenance che contiene l’intero insieme:

"StoreBucket": {
"Type": "AWS::S3::Bucket",
"Metadata": {
"aggrega.ai/provenance": {
"aggrega.ai/component-id": "store",
"aggrega.ai/recipe-uri": "store-recipe:1.0.0",
"aggrega.ai/boundary-path": "stack"
}
}
}

Da quella collocazione derivano tre proprietà. L’attributo Metadata è disponibile su ogni risorsa, qualunque sia il suo tipo, quindi ogni risorsa contenuta in uno stack assemblato riceve la provenienza — compresi i molti tipi di risorsa che non accettano alcun tag, su cui una provenienza basata sui tag non avrebbe avuto spazio. La provenienza viene aggiunta a qualunque Metadata l’autore abbia scritto anziché sostituirlo, così le voci proprie dell’autore restano accanto a essa. E poiché è per risorsa anziché per template, uno stack in cui più componenti si assemblano porta l’identità di provenienza di ciascuna risorsa — il suo componente, la sua Recipe e il suo boundary — che una singola voce valida per l’intero template non potrebbe esprimere.

L’intero insieme viaggia unito sotto quella chiave. Un valore Metadata è JSON senza vincoli, quindi non c’è alcuna suddivisione per set di caratteri da fare; le due chiavi che legge solo un runtime Kubernetes — il nome della label raccomandata standard e l’annotazione di ordinamento del deployment consumata da un controller GitOps — sono escluse, poiché nessuna delle due nomina qualcosa in uno stack. La semplice voce di provenienza aggrega.ai/sync-wave resta, perché registra il wave dichiarato dal componente anziché istruire un controller.

La forma che qui non ha collocazione è un template o un frammento che non dichiara alcuna risorsa — uno che contribuisce solo Parameters, Mappings, Conditions o Rules. Non porta alcuna provenienza, raggiunge lo stack assemblato con il proprio contenuto intatto, e la build emette un avviso «skipped provenance injection (iniezione della provenienza saltata)» che lo nomina. Come per compose, quell’avviso è previsto per un contributo di quella forma: le risorse che lo stesso componente contribuisce altrove portano l’insieme completo, e i byte emessi sono gli stessi che qualcosa sia in ascolto o meno.

Semantica degli artefatti per Provider

La semantica per provider descritta di seguito illustra come ciascun provider integra gli artefatti nel proprio output nativo.

provider helm: gli artefatti sono documenti YAML di Kubernetes scritti in una directory che porta il nome del componente che li ha dichiarati, all’interno della directory di output che contiene i manifest renderizzati dal chart e sintetizzati dal Workload. Il motivo è la denominazione: un manifest renderizzato o sintetizzato riceve dal provider un nome derivato dal componente a cui appartiene, mentre un artefatto prende il nome dalla chiave scritta dal suo autore, che non dice nulla su quale componente sia — così due componenti legati a una stessa Recipe scriverebbero un unico percorso senza che nessuno dei due autori possa separarli. La directory ha il nome del componente stesso, quindi il file che l’autore ritrova nell’output ha il nome che ha scritto, un livello più in basso.

Un operatore che desidera una disposizione diversa ha a disposizione il template subDirectory: del boundary, che sposta ogni file emesso da un contributore e non solo gli artefatti. Vedi ../language-reference/path-template-variables.md.

provider compose: gli artefatti sono frammenti compose. Le chiavi di primo livello (services:, volumes:, configs:, models:) vengono unite nel docker-compose.yaml combinato di ciascun boundary durante la fase di composizione del boundary.

provider helm-chart (caso speciale): gli artefatti non vengono scritti nella directory di output come file autonomi — è Helm a gestire la pipeline di rendering. Il provider helm-chart colloca invece ogni voce di artifacts: all’interno del chart stesso, e la forma in cui la voce è scritta decide dove finisce. Ogni voce viene elaborata come template Go con il contesto dei pilastri di Aggrega PRIMA di qualsiasi collocazione; da lì le due forme divergono. Una voce caricata con $import: è un file di template pre-Helm: viene iniettata nella directory templates/ del chart PRIMA del rendering di Helm, così Helm la renderizza insieme ai template del chart di origine. Uno scalare di blocco inline è un file sciolto del chart: viene collocato nella radice del chart sotto la chiave scritta dall’autore, senza prefisso templates/ e senza etichette di provenienza unite, così i template del chart possono leggerlo tramite .Files.Get / .Files.Glob di Helm — il pattern ConfigMap-da-file. Ciò offre al provider helm-chart un meccanismo di estensione equivalente a quello che artifacts: fornisce al provider helm semplice, nel rispetto del modello di chart di Helm.

Il file iniettato finisce in boundaries/<bp>/charts/<nodeID>/templates/<authored-key> — i file di un bundle annidati sotto quella chiave — quindi si trova accanto ai template del chart di origine e Helm lo raccoglie durante il passaggio di rendering successivo. Uno scalare di blocco inline finisce in boundaries/<bp>/charts/<nodeID>/<authored-key> — la radice del chart, un livello sopra templates/ — perché un file letto tramite .Files deve trovarsi dove il chart lo cerca, e un file collocato sotto templates/ viene invece renderizzato come manifest. Entrambe le forme prendono il nome dalla chiave sotto cui sono scritte; ciò che le distingue è la directory in cui il provider le colloca.

Convenzione dei delimitatori di helm-chart. Il passaggio di pre-template di Aggrega sulle voci di artefatto helm-chart, sia caricate con $import: sia inline, usa i delimitatori [[ ]] invece dei predefiniti {{ }}, così la sintassi {{ ... }} propria di Helm all’interno del file arriva intatta al passaggio di rendering di Helm. Gli autori scrivono le sostituzioni lato Aggrega come [[ .context.instance_id ]], [[ .values.name ]] ecc.; le sostituzioni lato Helm restano {{ .Values.x }}, {{ .Release.Name }}, {{- include "common.labels" . }} ecc. Mescolare le due coppie di delimitatori in un unico file è la forma di authoring supportata.

Provenienza e artefatti helm-chart. La provenienza viene unita in metadata.labels e metadata.annotations (secondo la suddivisione per set di caratteri descritta sopra) per i file caricati con $import: che superano il round-trip YAML con i token Helm preservati — file che usano solo il contesto Aggrega [[ ]] o con {{ }} di Helm solo in posizioni di scalari tra virgolette. I file con azioni di template Helm strutturali ({{- include ... }}, {{- if ... }}, {{- range ... }}, {{- with ... }} in posizioni in cui emettono struttura YAML anziché foglie scalari), o con {{ ... }} senza virgolette in posizioni di valore, non sopravvivono al round-trip YAML di Aggrega; la build emette un avviso «skipped provenance label injection (iniezione delle label di provenienza saltata)» che nomina l’artefatto e lascia passare il file invariato. Questo avviso è previsto per qualsiasi file di artefatto helm-chart caricato con $import: che usi azioni di template Helm strutturali o sostituzioni di valori Helm senza virgolette — è il caso comune nell’authoring Helm in produzione, non il caso limite. Gli autori che hanno bisogno di label di provenienza su tali file le iniettano tramite un template con nome che scrivono nel _helpers.tpl del chart stesso (ad esempio uno chiamato aggrega.commonLabels) o un meccanismo equivalente lato Helm, non tramite l’iniezione pre-template di Aggrega.

Collisioni con i nomi di file della radice del chart. Un artefatto caricato con $import: la cui chiave coincide con un nome di file della radice del chart (Chart.yaml, values.yaml, .helmignore ecc.) non viene rilevato dal controllo di collisione dei nomi di file di Aggrega — l’artefatto finisce in templates/<authored-key> mentre il file della radice finisce nella radice del chart, e il prefisso del percorso li rende distinti dal punto di vista di Aggrega. Gli autori evitano questi nomi di chiave; la conseguenza del loro uso è che Helm vede entrambi i file (uno nella radice del chart, uno dentro templates/) e può renderizzare inaspettatamente la copia in templates.

provider terraform: gli artefatti sono file di configurazione Terraform, emessi così come sono nella directory propria del componente sotto l’albero modules/ del boundary. HCL (main.tf) è il default più ergonomico e Terraform JSON (.tf.json) è accettato in modo equivalente; nessuno dei due viene transpilato o riformattato. La configurazione radice del boundary dichiara quel componente come blocco module il cui source punta a quella directory, così un intero boundary resta un unico grafo di dipendenze; è la stessa directory occupata dai file di un modulo vendorizzato, quindi una Recipe che dichiara sia source: sia artifacts: li scrive fianco a fianco. La provenienza viaggia come blocco di commento Terraform iniziale; quando un componente contribuisce un corpo JSON, che non ha sintassi per i commenti, ogni corpo viene emesso invariato e la provenienza viaggia in un file .tf di accompagnamento contenente solo commenti, così il timbro non viene mai duplicato tra i due. Vedi la pagina del provider terraform.

provider cloudformation: gli artefatti sono frammenti di stack — le risorse che un componente contribuisce anziché un template intero. Il provider normalizza ogni frammento in funzioni intrinseche in forma lunga in puro JSON e lo unisce nell’unico stack assemblato per quella directory di output, dove le risorse confluiscono in un’unica mappa Resources e i provides del componente emergono come Outputs dello stack sotto nomi circoscritti al componente che li pubblica. Quali altre sezioni di primo livello di un frammento sopravvivano all’assemblaggio è spiegato in Che cosa porta un documento unito da artifacts:. Vedi la pagina del provider cloudformation.

L’ambito del boundary: file per l’output condiviso di un boundary

Il meccanismo degli artefatti ha un secondo ambito. Tutto ciò che precede viene scritto nella posizione propria del componente nell’output del suo boundary; spec.boundary.artifacts di una Recipe è la stessa mappa — le stesse tre forme, la stessa regola chiave-nome di file, lo stesso contesto di template — scritta invece una sola volta per il boundary nel suo insieme. Esiste per un file che il target legge una sola volta per tutto ciò che un boundary distribuisce, e che nessuna posizione propria di un componente può contenere: la documentazione di Terraform dice che un modulo destinato a essere richiamato non deve contenere blocchi provider, e un modulo che li contiene non può essere richiamato con depends_on, count o for_each, quindi la configurazione di un provider appartiene alla configurazione radice del boundary e non al modulo di un componente.

Dove finisce. Nella directory che contiene l’output assemblato del gruppo di dispatch, accanto ai file che vi scrive l’assemblaggio proprio del provider — per terraform, accanto alla configurazione radice. Il compilatore valuta ogni voce una volta per ciascun componente renderizzato dalla Recipe, rispetto al contesto di quel componente, e scrive il file da sé: al provider non viene passato nessuno di questi file, e in nessuno viene timbrato da quale componente provenga, perché appartiene a ogni contributore che lo ha dichiarato.

Come si incontrano i contributori. I file dichiarati da ogni contributore di uno stesso gruppo di dispatch vengono uniti per nome. Un nome dichiarato con byte identici è un unico file; un nome dichiarato con byte diversi, o un nome che l’assemblaggio del provider scrive da sé, arresta la build nominando il file e ogni contributore — lo stesso rifiuto che incontrano due contributori che scrivono un unico percorso di output. Così una configurazione del provider di cui hanno bisogno due Recipes viene scritta da entrambe sotto un unico nome, e la build verifica che coincidano.

Chi lo accetta. Che un file collocato accanto all’output assemblato di un boundary abbia un significato è una proprietà del target del provider, quindi è una dichiarazione del provider stesso, letta dalla dichiarazione propria del provider come i suoi tipi di input. Una Recipe che dichiara il blocco per un provider che non lo dichiara viene rifiutata prima di qualsiasi rendering. La griglia qui sotto riporta la dichiarazione nell’ultima colonna; tra i provider distribuiti con il compilatore, la fa terraform.

Che cosa non sono gli artefatti

Tre distinzioni strutturali:

Non multi-provider all’interno di una singola Recipe. Una Recipe dichiara esattamente una capability: in cima alla sua spec. Tutto ciò che la Recipe produce — output renderizzato dal source, output sintetizzato dal workload ed emissioni di artefatti — è nel formato nativo di quel provider. Gli artefatti di una Recipe helm contengono YAML di Kubernetes. Gli artefatti di una Recipe compose contengono frammenti compose. Una Recipe punta a un solo provider; ogni output è nel formato nativo di quel provider.

La composizione multi-provider avviene a livello di Release. I boundary contengono componenti con provider misti; i contributori di ciascun provider nel percorso valutato di un boundary vengono smistati e assemblati in modo indipendente per (percorso, provider). Una Release con componenti destinati rispettivamente a helm, helm-chart e compose può collocarli tutti e tre in un unico boundary; il raggruppamento di dispatch li partiziona per provider, i contributori di ciascun provider finiscono nel proprio output assemblato sotto il percorso del boundary, e l’operatore scrive il coordinamento tra provider tramite la struttura di boundary che sceglie. Il coordinamento tra provider è responsabilità dell’autore della Release.

Non Recipes dentro Recipes. Gli artefatti non caricano né compongono altre Recipes. Sono manifest inline (o percorsi di file verso manifest inline), elaborati come template con i pilastri di questa Recipe ed emessi nell’output di questa Recipe. Il riuso di una Recipe avviene tramite tre meccanismi: l’extends: di un Component (una Recipe scritta per un Component base serve ogni Component che lo estende; ciò che si eredita sono metadati e schemi, non file di output — una Recipe di per sé non dichiara alcun extends:); la mappatura a URI piatti del Manifest (lo stesso Component può risolversi in Recipes diverse tra cataloghi — vedi ../language-reference/entities/manifest.md); e Features + FeatureRecipes (aspetti trasversali collegati in modo ortogonale).

Non uno strato di collante tra Recipe. Gli artefatti non possono fare riferimento a nomi, risorse o stato che la Recipe non abbia dichiarato essa stessa. Un artefatto ConfigMap a cui fa riferimento il Workload della Recipe deve essere emesso da questa Recipe. Un artefatto che si aspetta un Secret fornito esternamente deve ottenere il nome di quel Secret tramite il pilastro .features — dai provides risolti dell’attachment che lo emette — anziché presumere che esista. Questo è l’invariante di autocontenimento (vedi sopra) espresso dal punto di vista dell’authoring degli artefatti: ogni Recipe emette file in un solo formato, applicati da un solo strumento, nella directory di output di un solo boundary.

Matrice delle capacità per Provider

Ogni provider dichiara quali tipi di input renderizza; un gate centrale dei tipi di input accetta le combinazioni supportate e rifiuta le altre con una diagnostica uniforme quando il nodo viene renderizzato. La capacità è una proprietà del provider, non della Recipe — un provider renderizza un sottoinsieme dei tre tipi. La colonna artifacts: distingue gli artefatti che viaggiano accanto a un input primario sourced/synthesized da una Recipe autonoma composta solo di artefatti (nessun source:, nessun workload:). Le ultime due colonne sono le dichiarazioni del provider di rispettare omits: e di accettare i file che una Recipe contribuisce all’output condiviso del suo boundary sotto boundary.artifacts: (sopra); nessuna delle due è un tipo di input.

Leggi ogni colonna per conto suo. Una riga dice quali tipi un provider renderizza presi uno alla volta. Non dice che due tipi spuntati possano essere dichiarati insieme. Poiché i tipi si compongono per addizione, ogni tipo dichiarato viene smistato ed emesso separatamente, quindi una coppia può essere rifiutata per un motivo che nessuna delle due colonne riporta — il più delle volte perché entrambi i tipi producono un file con lo stesso nome di output. Quali combinazioni ciascun provider accetti effettivamente è indicato in prosa in Che cosa accetta ciascun provider, per intero.

Providersource: + valuesMapping:workload:artifacts: (accanto)solo artefatti (autonomo)omits:boundary.artifacts:
helm✅✅✅✅✅❌
compose✅✅✅✅✅❌
helm-chart✅❌✅ elaborato come template con i delimitatori [[ ]]❌❌❌
terraform✅❌✅✅❌✅
cloudformation✅❌✅✅✅❌

Questa griglia copre i provider distribuiti con il compilatore. Un provider fornito separatamente dichiara allo stesso modo i tipi di input che accetta, se rispetta omits: e se accetta boundary.artifacts:, e il compilatore legge quella dichiarazione per la stessa via — non è elencato qui, perché una pagina pubblicata non può enumerare provider che non ha mai visto.

Le celle contrassegnate con ✅ vengono renderizzate; ❌ è un rifiuto per capacità del provider segnalato dal gate. I frammenti compose per nodo vengono uniti per percorso di assemblaggio, quindi i boundary che condividono una directory: condividono un unico file.

Che cosa accetta ciascun provider, per intero

helm — ogni combinazione. source: + valuesMapping:, workload:, artifacts:, due qualsiasi di essi, o tutti e tre. È l’unico provider distribuito con il compilatore che non rifiuta alcuna combinazione, e il motivo è il modo in cui nomina l’output: ogni file emesso prende il nome dalla risorsa che contiene, quindi i manifest renderizzati di un chart e i manifest di un Workload sintetizzato non finiscono mai sotto uno stesso nome. Una Recipe che dichiara tutti e tre emette i file del chart, i file del Workload e i file degli artefatti fianco a fianco nella directory di output del boundary.

compose — ogni combinazione tranne le due in cui source: e workload: compaiono insieme. Ciascun tipo da solo viene costruito, e artifacts: può affiancare l’uno o l’altro. source: con workload: non può essere costruito, e nemmeno tutti e tre insieme; Perché compose non può combinare un source con un workload spiega il motivo, e non si tratta di un rifiuto per capacità.

helm-chart — source: + valuesMapping:, da solo o con artifacts: accanto. Nient’altro. Non sintetizza un workload: e non ha una forma composta solo di artefatti: una Recipe il cui unico tipo di input è artifacts: si arresta. Il motivo è il punto in cui questo provider colloca un artefatto — all’interno del chart proprio del componente — quindi una Recipe senza source: non gli lascia alcun chart in cui collocarlo.

terraform — tre forme: source: + valuesMapping: da solo, artifacts: da solo, o i due insieme. Non sintetizza un workload:.

cloudformation — le stesse tre forme di terraform, con la stessa unica esclusione. source: + valuesMapping: da solo, artifacts: da solo, o i due insieme; nessun workload:.

Come si presenta un tipo di input rifiutato

Una Recipe che dichiara un tipo di input che il provider a cui è legata non renderizza arresta la build quando il nodo viene renderizzato, e la arresta qualunque altra cosa la Recipe dichiari accanto a quel tipo — affiancare un workload: a un source: che il provider può renderizzare non fa passare il workload. L’arresto nomina il provider, il tipo che non può renderizzare e i tipi che renderizza:

[CATALOG_ERROR E0265] instance unit
provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesized

Il rifiuto della forma composta solo di artefatti si legge allo stesso modo e nomina quella forma: provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced). E0265 è l’identificatore da registrare quando questo arresto va nominato in modo duraturo — in un gate di integrazione continua, in una issue o in un runbook; la tabella di ogni condizione lo risolve.

Perché compose non può combinare un source con un workload

Il provider compose produce un frammento per componente e gli dà il nome del componente. Il rendering da source e la sintesi del Workload producono ciascuno il frammento di quel componente sotto quell’unico nome, quindi una Recipe che dichiara entrambi produce due file con lo stesso nome, e la build si arresta sulla collisione:

[CATALOG_ERROR E0211] instance unit
rendering node "unit"
caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit
filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")

Il nome del frammento deriva dall’identificatore proprio del componente e non esiste una superficie di authoring per esso, quindi nessuna modifica al contenuto della Recipe evita la collisione. L’arresto è una proprietà della coppia e non di uno dei due tipi — compose renderizza un source, compose sintetizza un Workload, e la griglia fa bene a spuntarli entrambi. Per usare entrambe le forme per un componente sotto compose, dividile tra due componenti, oppure incorpora il contenuto del source nel Workload.

Che cosa porta un documento unito da artifacts:

Due provider uniscono i propri contributori in un unico documento per percorso di assemblaggio: compose in un unico docker-compose.yaml, cloudformation in un unico template di stack. Un documento unito può portare solo le sezioni che il suo assemblatore modella, quindi una spunta su artifacts: dice dove viene collocato il contenuto di un frammento, non che ogni chiave all’interno del frammento sopravviva.

compose porta da un frammento di artefatto services:, volumes:, configs: e models:, insieme alle sue chiavi di estensione con prefisso x-. Un frammento che dichiara qualsiasi altra cosa al primo livello arresta la build, nominando la chiave — networks:, perché le reti sono derivate per boundary anziché accumulate dai contributori, e allo stesso modo un blocco secrets: o un name: di primo livello. La pagina del provider compose fornisce le regole di unione per chiave e l’alternativa per il routing tra reti.

cloudformation porta Resources, Outputs, Parameters, Mappings, Conditions, Metadata e Rules, e costruisce Transform a partire da quelli di ogni contributore. Le trasformazioni vengono unite nell’ordine documentato da CloudFormation, con i Globals di SAM che viaggiano insieme alla trasformazione che li legge, e una trasformazione che cambierebbe il modo in cui viene distribuito il contenuto di un altro contributore arresta la build nominandola. Description non viene portata, e la build lo dice: emette un avviso di campo non supportato che nomina la sezione e il componente, come per qualsiasi altra chiave di primo livello che lo stack non porta, quindi nulla viene scartato in silenzio. L’avviso è informativo — il template emesso è identico byte per byte a quello che sarebbe senza di esso, e --no-unsupported-field-warnings silenzia la classe. Outputs viene portato sotto un nome che il provider circoscrive al componente che contribuisce, quindi due componenti che contribuiscono a uno stack un output con lo stesso nome li mantengono separati. Sezioni di primo livello nello stack assemblato rende conto di ogni sezione, una per una.

Gli altri tre provider non uniscono, quindi nessuna chiave di artefatto rischia di essere scartata da un assemblatore. helm non assembla nulla: i manifest di ciascun componente raggiungono la directory di output del boundary così come sono. terraform e helm-chart annidano — i file di ciascun componente finiscono in una directory propria, una directory di modulo Terraform o un subchart, e un documento radice nel boundary vi fa riferimento — quindi una voce di artefatto viene collocata come file intero anziché letta in un documento condiviso. Dove finisce una voce di artefatto helm-chart, e perché la sua coppia di delimitatori è diversa, è spiegato in Semantica degli artefatti per Provider.