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

Variabili dei template di percorso

I campi directory: e subDirectory: di un confine di una Release sono template Go valutati al momento della build. Controllano dove gli artefatti renderizzati finiscono su disco e, di conseguenza, quali artefatti vengono assemblati insieme — due confini che si valutano nella stessa tupla (path, provider) condividono un assemblatore e producono un unico output unito (un Chart.yaml, un docker-compose.yaml). Questa pagina è il riferimento di authoring per le variabili a cui questi template possono fare riferimento, per la semantica di valutazione rigorosa e per le regole di cascata che permettono ai confini di ereditare dai propri genitori.

Per la trattazione concettuale della separazione spaziale e del dispatch per (path, provider), vedi architecture/16-recipe-input-composition.md. Per la superficie di authoring della Release a livello di entità, vedi entities/release.md. Le conseguenze lato provider si trovano in providers/architecture.md e nelle pagine dei singoli provider.

Valutazione rigorosa: missingkey=error

I template di percorso vengono valutati con la modalità missingkey=error di Go. Un riferimento a un campo non dichiarato, a una chiave parameters.X non impostata o un refuso come {{ .parmaeters.region }} produce un errore esplicito anziché renderizzare silenziosamente una stringa vuota in un percorso.

Questa rigorosità è asimmetrica rispetto al resto del compilatore — valuesMapping, injectMapping e le altre superfici di rendering dei valori usano missingkey=zero secondo la convenzione di Helm/Sprig. L’emissione dei percorsi è strutturalmente diversa: un template di rendering dei valori che produce una stringa vuota finisce in un campo di manifest, dove la conseguenza è circoscritta; un template di percorso che produce una stringa vuota finisce in un layout di directory, dove la conseguenza non è circoscritta (collisioni, assemblaggio rotto, percorsi fantasma). Il regime rigoroso dei template di percorso esiste per far emergere questi errori al momento della build anziché al momento della distribuzione.

Validazione con allowlist al momento del parsing

Oltre alla rigorosità a runtime, i template di percorso vengono validati al momento del parsing rispetto a una allowlist chiusa di nomi di variabile. Un riferimento a un nome di variabile assente dall’allowlist arresta la build prima che inizi qualsiasi lavoro di rendering, con una diagnostica che indica il campo in errore e il confine su cui compare.

L’allowlist è chiusa per progettazione: superfici come .context.inject, .values e .locals deliberatamente non sono esposte ai template di percorso. L’emissione dei percorsi è una questione strutturale, non di rendering dei valori; legare i percorsi di assemblaggio a valori per componente renderebbe il grafo dei percorsi dipendente dai dati ed eroderebbe l’invariante dell’output deterministico.

La matrice delle variabili

Variabiledirectory:subDirectory:Descrizione
{{ .capability }}sìsìLa capacità di rendering (helm, helm-chart, compose, terraform, cloudformation) che la Recipe del componente contributore dichiara, per gli artefatti emessi in questo percorso.
{{ .boundary_name }}sìsìIl nome scritto del confine nella Release (ad es. production, eu-prod).
{{ .parameters.X }}sìsìQualsiasi parametro tipizzato dichiarato sull’Aggregate e soddisfatto dalla Release. Accesso rigoroso — fare riferimento a .parameters.unknown arresta la build.
{{ .manifest.recipe_name }}sìsìIl nome della Recipe risolto tramite il Manifest per il componente contributore. Utile per instradare gli artefatti di ogni Recipe in sottocartelle per Recipe.
{{ .parent_boundary.* }}sìsìAccesso in cascata ai valori valutati del confine che lo racchiude. Vedi Cascata del confine padre più avanti.
{{ .component_id }}—sìL’ID di istanza del componente che contribuisce. Per una Feature associata a un confine la cui FeatureRecipe viene eseguita una sola volta per il confine (executionScope: boundary), è l’identità composta che le risorse di quell’associazione portano nella loro etichetta aggrega.ai/component-id — bfr--app--shared per un’associazione shared al confine app, abbreviata dove il provider dell’associazione limita i nomi — così l’output dell’associazione finisce in una directory che prende il nome da quell’etichetta. Disponibile solo in subDirectory: perché directory: è una proprietà per confine — la stringa della directory viene calcolata una volta per confine, prima che avvenga qualsiasi instradamento per componente.

Il campo directory: ha come valore predefinito boundaries/ seguito dal percorso del confine (un identificatore stabile al momento della build, derivato dall’albero dei confini); una Release che elenca i propri componenti senza dichiarare confini li scrive senza alcun segmento di directory. Il campo subDirectory: ha come valore predefinito {{ .capability }}, così gli artefatti di ogni capacità finiscono in una propria sottocartella sotto la directory del confine — sia che venga omesso sia che venga scritto come subDirectory: "", che si legge esattamente come uno omesso. Impostare subDirectory: ".", o scrivere un template che si valuta in una stringa vuota, appiattisce quel raggruppamento.

Ciò che questi template non decidono: il posizionamento di artifacts:

Un segmento del percorso di output non spetta a un template di percorso impostarlo. Un file indicato dal blocco artifacts: di una Recipe viene scritto in una directory che porta il nome del componente che lo ha dichiarato, all’interno di ciò in cui si valuta subDirectory:. Quel segmento è fisso e sempre presente, per un target che scrive i file dei propri contributori uno accanto all’altro anziché annidare ogni contributore in un chart o in un modulo proprio.

Il motivo è ciò che dà il nome al file. Un manifest che un target renderizza o sintetizza riceve dal target il nome del componente a cui appartiene, quindi identifica già il proprio componente. Un artefatto prende il nome dalla chiave che il suo autore ha scritto — app-config.yaml, netpol.yaml — e quella chiave non dice nulla del componente, perché la Recipe che lo dichiara non sa quali componenti le verranno legati. Due componenti in un confine legati a una stessa Recipe scriverebbero un unico percorso, e né l’autore della Recipe né l’autore della Release hanno una superficie su cui separarli.

Viene aggiunta solo la directory; il nome del file resta la chiave scritta, così il file che un autore rilegge nell’output porta il nome che ha scritto.

Che cosa offre ancora subDirectory:, e come si combinano i due. subDirectory: sposta ogni file che un contributore emette — manifest renderizzati, manifest sintetizzati e artefatti insieme — quindi è lo strumento per dare a un componente una directory propria per gli strumenti a valle che operano sull’intero insieme di manifest di un singolo componente, o per instradare più componenti in un’unica cartella condivisa. Il segmento di artifacts: si applica sotto qualunque cosa esso valuti. Scrivere subDirectory: "{{ .capability }}/{{ .component_id }}" su un componente la cui Recipe dichiara artifacts: produce quindi il nome del componente due volte — l’artefatto finisce in <capability>/<component>/<component>/<key> mentre i manifest renderizzati di quel componente finiscono in <capability>/<component>/<key>. Ricorri alla sovrascrittura quando vuoi raccogliere l’intero output del componente, e lasciala da parte quando ti basta separare gli artefatti, cosa che il valore predefinito fa già.

.capability viene risolto per componente, e la directory: di un confine viene valutata per due scopi distinti. La valutazione per confine che pubblica .parent_boundary.directory ai confini figli viene eseguita prima che qualsiasi componente sia legato, quindi lì .capability è vuoto. La valutazione per componente che fissa dove finiscono effettivamente gli artefatti di un contributore porta la capacità di quel componente. Un padre che scrive directory: "d-{{ .capability }}" pubblica quindi d- lungo la cascata, mentre i suoi artefatti finiscono sotto d-compose.

Cascata del confine padre

I confini annidati ricevono una vista .parent_boundary che espone il percorso valutato del confine padre immediato e i suoi dati risolti in cascata. La cascata è di un solo livello — il .parent_boundary di un confine è il suo padre diretto, non il nonno. Per risalire più in alto, il confine padre stesso usa .parent_boundary nei propri template, propagando esplicitamente i valori lungo l’albero.

Campi disponibili sotto .parent_boundary:

CampoDescrizione
.parent_boundary.directoryIl valore valutato di directory: del confine padre (dopo il template).
.parent_boundary.boundary_nameIl nome scritto del confine padre.
.parent_boundary.parametersLa stessa mappa .parameters.* vista dal confine padre (i valori dei parametri sono globali alla Release, ma l’alias viene fornito per simmetria).
.parent_boundary.annotationsLe annotazioni risolte in cascata del confine padre.

Il pattern canonico: un confine padre che scrive una directory: una sola volta, più confini figli che instradano i propri artefatti sotto il padre dichiarando directory: "{{ .parent_boundary.directory }}". Questo fa collassare i figli sul percorso di assemblaggio del padre, producendo un unico output unito che contiene i contributori di ogni figlio. La Feature core/compose-bridge si basa esattamente su questo: un confine padre che contiene la funzionalità bridge, due confini figli (per esempio services-net e data-net) che condividono la directory: del padre, e un unico docker-compose.yaml unito che contiene ogni componente più il servizio bridge.

Il caso speculare: ometti .parent_boundary.directory sui figli (o fai in modo che si valutino in un percorso distinto) e ogni figlio ottiene il proprio assemblaggio. Entrambe le forme sono di prima classe.

Layout di esempio

Layout 1 — separazione predefinita per confine

spec:
boundaries:
api-prod:
directory: "deploy/api-prod"
components:
api: {}
cache: {}
data-prod:
directory: "deploy/data-prod"
components:
db: {}

Ogni confine si valuta in una directory: distinta, quindi ciascuno ottiene il proprio assemblaggio:

deploy/api-prod/<capability>/...
deploy/data-prod/<capability>/...

Il valore predefinito subDirectory: "{{ .capability }}" separa gli artefatti per capacità all’interno della directory di ogni confine. Due confini, due output di assemblaggio per capacità, nessuna unione.

Layout 2 — assemblaggio unificato tramite una directory padre condivisa

spec:
boundaries:
cluster:
directory: "deploy/cluster"
annotations:
aggrega.ai/chart-name: "cluster-umbrella"
features:
bridge:
type: core/compose-bridge:1.0.0
boundaries:
services-net:
directory: "{{ .parent_boundary.directory }}"
annotations: { aggrega.ai/namespace: services }
components:
api: {}
data-net:
directory: "{{ .parent_boundary.directory }}"
annotations: { aggrega.ai/namespace: data }
components:
db: {}

Entrambi i confini figli valutano directory: in deploy/cluster (la directory del padre), quindi tutti i contributori si uniscono in un unico percorso di assemblaggio. Con il valore predefinito subDirectory: "{{ .capability }}", i contributori compose di entrambi i figli finiscono in deploy/cluster/compose/ e producono un unico docker-compose.yaml unito. La Feature compose-bridge associata al padre viene eseguita una sola volta (dispatch con ambito di confine) e contribuisce il servizio bridge allo stesso file unito.

L’annotazione aggrega.ai/chart-name: "cluster-umbrella" del padre si propaga in cascata a entrambi i figli; se i confini contenessero anche contributori helm-chart, i sotto-chart helm-chart di entrambi i figli si comporrebbero sotto un unico umbrella chiamato cluster-umbrella. Valori di chart-name non corrispondenti tra i contributori di uno stesso percorso arrestano la build.

Layout 3 — instradamento per componente tramite subDirectory: più parametri

spec:
parameters:
region: "eu-west-1"
boundaries:
eu-prod:
directory: "deploy/{{ .parameters.region }}"
components:
api:
subDirectory: "{{ .capability }}/{{ .component_id }}"
db:
subDirectory: "{{ .capability }}/{{ .component_id }}"
ingress:
subDirectory: "shared"

La directory: del confine si valuta in deploy/eu-west-1 (sostituzione dei parametri). Le sovrascritture di subDirectory: per componente instradano ogni contributore in una sottocartella per componente, con il componente ingress che sovrascrive verso una sottocartella piatta shared per gli artefatti trasversali:

deploy/eu-west-1/<capability>/api/...
deploy/eu-west-1/<capability>/db/...
deploy/eu-west-1/shared/...

Questo pattern si adatta alle aziende che vogliono directory di artefatti per componente per gli strumenti a valle che operano sui manifest di un singolo componente. Se la Recipe di un componente dichiara anche artifacts:, leggi Ciò che questi template non decidono più sopra prima di scegliere questa forma: quei file portano già un segmento di componente, quindi questa sovrascrittura ne aggiunge un secondo.

Diagnostica

La superficie dei template di percorso arresta la build in ciascuna delle situazioni seguenti, e errors/fatal-halts.md le documenta con questi nomi. Quella pagina riporta il messaggio che ciascun arresto emette; confronta l’output della build con quel testo.

  • Path-template references a variable outside the allowlist (Il template di percorso fa riferimento a una variabile al di fuori dell’allowlist) — al momento del parsing: un template di percorso fa riferimento a una variabile assente dall’allowlist.
  • Path collision (Collisione di percorsi) — al momento dell’assemblaggio: due contributori di confine si valutano nello stesso percorso ma non concordano su una proprietà che deve essere uniforme tra i contributori di quel percorso.
  • Instance-ID collision (Collisione di ID di istanza) — al momento dell’assemblaggio: due confini che si valutano nella stessa tupla (path, provider) contribuiscono componenti con ID di istanza identici.
  • Chart-name mismatch (Nome di chart non corrispondente) — al momento dell’assemblaggio: un assemblaggio helm-chart unito riceve contributori con annotazioni aggrega.ai/chart-name risolte in cascata in conflitto tra loro.
  • Missing template key (Chiave di template mancante) — un template di percorso fa riferimento a un campo sotto una variabile aperta che non si risolve in alcun valore (ad es. {{ .parameters.region }} quando la Release omette region, o una chiave di .parent_boundary in un confine di primo livello che non ha padre); missingkey=error produce un messaggio esplicito che indica il confine, il campo del template (directory: o subDirectory:) e la chiave mancante. .parameters e .parent_boundary sono aperte — le loro chiavi sono dati scritti dall’autore — mentre .manifest dichiara le proprie chiavi, quindi una chiave digitata male sotto .manifest viene invece rifiutata al momento del parsing come riferimento sconosciuto, con la diagnostica che elenca le chiavi definite da .manifest.

Riferimenti incrociati

  • entities/release.md — authoring della Release, compresa la separazione spaziale e i campi directory: / subDirectory:.
  • providers/architecture.md — dispatch dei provider e il modello di assemblaggio per (path, provider).
  • providers/compose.md — output lato compose per (path, provider), compreso lo scenario del percorso unito.
  • providers/helm-chart.md — composizione umbrella di helm-chart e la regola di cascata del chart-name per i percorsi uniti.
  • entities/featurerecipe.md — FeatureRecipes con ambito di confine (la Feature core/compose-bridge si basa sul modello di assemblaggio a percorso unito documentato qui).
  • errors/fatal-halts.md — catalogo completo delle diagnostiche, compresi gli arresti del dispatch dei percorsi elencati sopra.