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

Pilastri dei dati

L’inquadramento concettuale delle cinque parole chiave strutturali del DSL — parameters, values, uses, infra, inject — si trova in architecture/06-data-taxonomy-and-composition.md. Questa pagina tratta l’elenco canonico dei pilastri di dati, la semantica di scrittura per pilastro, i meccanismi tra pilastri e il vocabolario dei valori predefiniti che gli autori incontrano nei vari pilastri. La triade topologica complementare (provides, inject, uses — parole chiave che collegano gli archi del grafo) è documentata in topology-triad.md; il vocabolario dei metadati distinto dai pilastri di dati (etichette, annotazioni, campi della superficie di pubblicazione) si trova in labels-and-annotations.md e publishing-surface.md.

Elenco canonico dei pilastri

Le entità di Aggrega portano sette pilastri di dati con nome. Cinque partecipano al flusso di dati dell’IR come stato vivo per tutto il rendering; due sono transitori o privati ed esistono solo in fasi specifiche della compilazione.

PilastroRisiede suCiclo di vitaRuolo
valuesIstanze di componente / associazione dell’AggregateVivo per tutto il renderingPayload cognitivo scritto dallo sviluppatore
infraVoci di componente, associazione e connessione della ReleaseVivo per tutto il renderingDimensionamento fisico scritto dall’operatore
providesBlocco provides: della RecipeVivo per tutto il rendering (pilastro derivato — vedi sotto)Stringhe di output pubbliche calcolate dalla Recipe, che la pipe topologica consuma
usesIstanze di componente / funzionalità dell’AggregateVivo per tutto il renderingArchi topologici verso altri componenti / funzionalità
featuresIstanze di componente di Aggregate + Release; slot dichiarati nel featuresSchema di un’entità del catalogo — vedi «Features pillar (Pilastro Features)» più avantiVivo per tutto il renderingPilastro delle associazioni — una sola forma per ogni famiglia di associazioni
parametersRadici di Aggregate + ReleaseLeggibile fino alla fine della pipeline, finché ogni fase di rendering non si completa; accessibile ai template di percorso durante il rendering tramite la concessione asimmetrica; i contesti dei template di valore consumano i letterali post-interpolazione anziché .parameters direttamenteSlot per ambiente soddisfatti dalla Release
localsBlocco locals: della RecipePrivato della Recipe — visibile solo all’interno dei template della Recipe stessaStato stringa calcolato che le Recipes derivano nel preambolo dei locals

values / infra / provides / uses / features sono i cinque pilastri vivi che il contesto dei template a runtime espone rispettivamente tramite .values, .infra, .provides, .context.uses e .features. parameters e locals sono fuori dall’elenco dei pilastri vivi — parameters perché non sopravvive alla risoluzione; locals perché è privato della Recipe e non attraversa mai i confini delle entità.

I pilastri sono segnali, non muri: il motore dei template consente letture tra pilastri in ogni punto, salvo quando le regole di autosufficienza lo vietano esplicitamente (un blocco provides: della Recipe e un blocco source: della Recipe che leggono .context.inject / .context.uses; documentato in templates/expansion-matrix.md). I confini dei pilastri sono disciplina di scrittura, non un vincolo imposto dal linguaggio.

Confini dei pilastri e disciplina di scrittura

Le letture tra pilastri da un template di Recipe non sono soggette a restrizioni in ogni punto che consente il contesto dei template completo. La disciplina di scrittura si aspetta che gli autori:

  • Leggano .values per il payload cognitivo (intento scritto dallo sviluppatore).
  • Leggano .infra per il dimensionamento fisico (dimensionamento scritto dall’operatore).
  • Leggano .context.uses[].provides.<key> per le stringhe puntatore tra componenti (il flusso di dati della triade topologica).
  • Leggano .context.inject per la pipe di consegna post-idratazione (assemblata dalle sorgenti di inject in component.inject, uses[].inject e dalle intercettazioni injectMapping di FeatureRecipe).

La disciplina è fatta di segnali, non di muri. Un template di Recipe che legge .infra.replicas per pilotare un campo values: funziona; il motore dei template non blocca la lettura. L’inquadramento dell’architettura è che i confini dei pilastri descrivono l’intento di scrittura — chi possiede i dati — anziché una restrizione a runtime. Le convenzioni corrispondono alla suddivisione in quattro domini: i valori scritti dallo sviluppatore provengono da .values; il dimensionamento scritto dall’operatore proviene da .infra; le coordinate tra componenti provengono dalla pipe topologica.

Quando serve un ponte deliberato tra pilastri — per es. lo schema: di un Component espone una manopola rivolta allo sviluppatore che il template valuesMapping: della Recipe convoglia in un output con la forma di infra: sul lato Ops, secondo vocabulary/inheritance-and-interface.md — l’architettura tratta il ponte come un’eccezione segnalata. Vedi «Cross-pillar mechanics (Meccanismi tra pilastri)» più avanti.

Values

Il pilastro values: porta il payload cognitivo scritto dallo sviluppatore — i parametri che danno forma all’applicazione e che lo sviluppatore detta per ogni istanza di componente. Lo schema: del Component dichiara la forma dei valori; l’Aggregate dello sviluppatore popola valori concreti per ogni istanza. Questo è il dominio dello sviluppatore.

Scritto in:

  • Aggregate components.<id>.values: — payload cognitivo per ogni istanza di componente.
  • Aggregate subsystems.<name>.components.<id>.values: — lo stesso, all’interno di componenti raggruppati in sottosistemi.
  • Aggregate components.<id>.features.<name>.values: e features.<name>.values: di un sottosistema — payload dei valori dell’associazione, qualunque sia la famiglia a cui appartiene la Feature associata (i parametri di interrogazione del vault di un’associazione di credenziali si scrivono qui come qualsiasi altro).

Vietato in:

  • Entità Release (lo schema della Release vieta un blocco values: a ogni livello di annidamento — il Parameter Hoisting è il percorso supportato per la variazione per ambiente; vedi Parameters più avanti).

Validato da: il blocco values: dello schema del Component (e il blocco values: dello schema della Feature per le associazioni di Feature), risolto in JSON Schema 2020-12 al caricamento del Component / della Feature secondo vocabulary/validation-surface.md, livello 2.

Consumato da: i template valuesMapping: della Recipe tramite .values. Il contesto dei template completo espone il dizionario dei valori risolti in ogni punto di template del rendering di base.

Infra

Il pilastro infra: porta il dimensionamento fisico scritto dall’operatore — repliche, richieste di risorse, limiti di IOPS, vincolo di regione, classe di macchina. Esprime il dove e quanto grande, complementare al cosa e come si comporta dei values. Questo è il dominio dell’operatore.

Quattro superfici di scrittura

Gli autori incontrano infra: su quattro superfici distinte, ciascuna con un ambito diverso e un diverso comportamento a cascata:

#SuperficieAmbitoPrecedenza di unione
1Confine della Release components.<id>.infra: (spec.components.<id>.infra: in una Release senza confini)Un’istanza di componenteIl dimensionamento proprio del componente; nessun’altra superficie lo scrive
2Confine della Release features.<name>.infra:Un’associazione con ambito di confine, su ogni componente nel confineLa più bassa per quell’associazione — la superficie 3 la sovrascrive campo per campo
3Confine della Release components.<id>.features.<name>.infra:Un’associazione su un componenteSovrascrive la superficie 2 per quell’associazione, campo per campo
4Release components.<id>.uses.<socket>.<alias>.infra:Una connessioneValidato rispetto all’infraSchema del socket; raggiunge solo il rendering del componente consumatore

La superficie 1 è la più scritta: un operatore dimensiona ogni componente che la Release colloca. Un confine non porta alcun infra: proprio — lo schema della Release lo rifiuta — quindi il dimensionamento condiviso da più componenti si scrive su ciascuno, oppure si eredita da una Release genitore tramite extends: (più avanti). Le superfici 2 e 3 coprono il dimensionamento delle associazioni di Feature — le Features portano un proprio payload infra che la FeatureRecipe consuma quando sintetizza sidecar o risorse per Feature: un’associazione con ambito di confine si dimensiona una volta, e un componente ne regola un singolo campo.

«Infra principalmente localizzato» — la regola con eccezioni

L’obiettivo architetturale per infra: è locale al componente: il dimensionamento di un componente si applica a quell’istanza di componente e non si propaga ad altri componenti. È il meccanismo che permette a Ops di aumentare gli IOPS del database senza influire sulla richiesta di CPU del server API.

La regola: infra: è principalmente localizzato sulla superficie che lo ha scritto. Le eccezioni a cascata esistono per progettazione:

  • Cascata delle annotazioni del confine. Le annotations: di un confine si propagano a cascata attraverso i confini annidati fino ai componenti interni (superficie 5 della matrice delle annotazioni in labels-and-annotations.md). Le annotazioni consumate dalle Recipes come input di instradamento diventano una portata indiretta di infra — l’annotazione a livello di confine fluisce attraverso .context.annotations.release nell’output renderizzato della Recipe per nodo.
  • Ereditarietà della Release tramite extends:. Una Release che fa extends: di una Release genitore eredita le dichiarazioni infra del genitore su ogni superficie che le porta, a meno che la figlia non le sovrascriva chiave per chiave. Il valore della figlia prevale chiave per chiave, fino al primo valore indivisibile — uno scalare, un elenco, un template — che viene sostituito per intero, e una chiave che la figlia scrive come null viene rimossa anziché impostata a nulla. L’ereditarietà attraversa deliberatamente il confine della singola Release; per l’intera regola di fusione e per ciò che viaggia con essa, vedi entities/release.md.
  • Convogliamento tra pilastri tramite ponte di schema. Lo schema: di un Component può esporre una manopola values: rivolta allo sviluppatore che il template valuesMapping: della Recipe convoglia nell’output del provider con la forma di infra: (vedi «Cross-pillar mechanics — Schema-bridge cross-pillar piping (Meccanismi tra pilastri — Convogliamento tra pilastri tramite ponte di schema)» più avanti). A rigore il valore ha origine in values: e fluisce nell’output renderizzato; la cascata è interna all’istanza ma tra pilastri.

La localizzazione è l’intento progettuale, non un muro che il motore impone: le cascate sopra descritte sono eccezioni deliberate, ciascuna documentata sulla superficie che la porta.

Partizione tra lato e pilastro per l’espansione delle Feature guidata dalle annotazioni. L’invariante dell’Aggregate come superficie di scrittura si estende al percorso di espansione delle Feature guidata dalle annotazioni: le annotazioni lato Aggregate (ambito di sottosistema e di istanza di componente) possono attivare solo sottochiavi maps.values; le annotazioni lato Release (ambito di confine e di istanza di componente) possono attivare solo sottochiavi maps.infra. Un binding di Manifest può dichiarare percorsi in entrambi i pilastri; ciascun lato attiva solo il proprio sottoinsieme compatibile, e la composizione tra i lati unisce i contributi campo per campo al momento della build dell’IR. La partizione preserva la separazione di scrittura values-sviluppatore / infra-operatore sulla superficie delle annotazioni — la stessa separazione che values: e infra: impongono sulle superfici di associazione esplicita. Vedi providers/well-known-annotations.md §«Side-vs-pillar partition per subkey (Partizione tra lato e pilastro per sottochiave)» per la spiegazione per sottochiave e il pattern di composizione tra i lati.

Provides

Il pilastro provides: è derivato — lo dichiara una Recipe, ma a differenza di values / infra, lo sviluppatore non lo scrive direttamente. Le Recipes calcolano le stringhe di output pubbliche che la pipe topologica consumerà.

Il blocco provides: di una Recipe è una mappa di coppie <key>: <template>. Ogni template viene valutato rispetto alla superficie autosufficiente propria della Recipe (.values, .infra, .context.instance_id, .context.rendered_name dove il provider del nodo ne riporta uno, e i .locals risolti del nodo) durante la valutazione dei provides. Le stringhe risultanti vengono esposte tramite .provides e consumate dai blocchi uses[].inject dei chiamanti tramite riferimenti from: "<key>". .locals è disponibile perché i locals del nodo si risolvono nel preambolo di quella fase, prima dei suoi provides (vedi Locals più avanti); nominare una chiave che il blocco locals non dichiara provoca un arresto.

Invariante di autosufficienza. I template provides: della Recipe non devono fare riferimento a .context.inject o .context.uses. La valutazione dei provides esegue quei template in qualsiasi ordine — si chiudono solo sui dati propri del nodo, quindi l’ordine non conta. Riferimenti tra nodi legherebbero quella valutazione all’ordine di iterazione topologica, cosa che la progettazione evita deliberatamente. Vedi templates/expansion-matrix.md, riga 6, per la regola e la sua motivazione.

Perché provides: è un pilastro. Le stringhe di output sono la superficie pubblica canonica di ogni Recipe; i consumatori a valle (uses[].inject del chiamante, blocchi injectMapping di FeatureRecipe che leggono i provides risolti del target tramite .context.uses) trattano il dizionario come un contratto tipizzato. Chiamare provides: un pilastro riconosce il suo status di prima classe accanto a values / infra / uses / features. Trattarlo come «solo un dettaglio interno della Recipe» ne sminuisce il ruolo di fonte dati primaria della pipe topologica.

Uses

Il pilastro uses: è la dichiarazione degli archi topologici. Il blocco uses: di un’istanza di componente nomina gli archi a cui il componente partecipa — i socket attraverso cui consuma i target. La grammatica completa è documentata in topology-triad.md; questa sezione nomina uses: come pilastro per completezza.

uses: risiede sulle istanze di componente dell’Aggregate + sulle associazioni di funzionalità; il contesto dei template a runtime espone una voce per ogni connessione in uscita, indicizzata dal suo alias, come .context.uses. La proiezione porta i metadati risolti del target di ogni arco (i provides del target, le etichette, le annotazioni), così le Recipes dei chiamanti possono leggere le stringhe puntatore tra componenti durante la valutazione dei template del rendering di base, e le associazioni scritte su quella connessione, in .context.uses.<alias>.features.<slot>.

Pilastro Features

features: è il pilastro delle associazioni: una parola chiave, una forma, ogni associazione. Una Feature operativa, una Feature di credenziali e una Feature di identità si dichiarano tutte qui, sotto il nome di istanza scelto dall’autore. Il contesto dei template a runtime espone le associazioni del nodo come .features.<name>, ciascuna con type, values, infra e i provides risolti dell’associazione. Un’associazione scritta su una delle connessioni del componente viene invece esposta nella stessa forma sotto la connessione, in .context.uses.<alias>.features.<slot>, e mai sotto .features — così una Recipe che itera su .features incontra solo le associazioni proprie del componente (vedi il contratto del contesto dei template).

Un’associazione il cui nome di istanza corrisponde a uno slot che l’entità dichiara in featuresSchema riempie quello slot; qualsiasi altro nome di istanza è un’associazione libera. Riempire uno slot è ciò che collega le quattro superfici attraverso cui viaggia una credenziale basata su slot:

SuperficieDove viene scrittoRuolo
Component / Feature featuresSchema:entità del catalogoDichiara gli slot che l’entità si aspetta; per ogni slot, delimita l’allowlist di consegna (env / file / blackbox) e, facoltativamente, un selettore di etichette che il riempimento deve soddisfare
Aggregate components.<id>.features.<slot>:Istanza di componente dell’AggregateRiempie lo slot con un’associazione; fornisce il values: proprio dell’associazione e, per uno slot trasparente, la sua mappatura inject:
Workload containers.<name>.attachments.<KEY>.from/as:Corpo del Workload della RecipeFa riferimento a uno slot dichiarato — oppure, accanto a connection: <alias>, a uno slot dichiarato dal socket di quella connessione — e detta la consegna per container di ciò che lo ha riempito
FeatureRecipe (source / workload / artifacts / valuesMapping, injectMapping, pipeline:)la FeatureRecipe legataProduce l’output dell’associazione — una risorsa emessa, una riscrittura della consegna, o entrambe

Il nome dello slot è l’identificatore portante in tutte e quattro: la superficie 1 lo dichiara, le superfici 2–4 vi fanno riferimento, e il flusso di dati va in una sola direzione (dichiarare → riempire → fare riferimento → produrre).

Per la checklist di scrittura, vedi examples/04-secrets.md «The secret-delivery checklist (La checklist della consegna dei secret)».

Locals

Il pilastro locals: è lo stato privato della Recipe. L’intero blocco si risolve nel preambolo dei locals, prima del provides: di quel nodo; le stringhe risultanti sono visibili a tutti i template successivi propri della Recipe — provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, pipeline[].with. Un template provides: che nomina una chiave non dichiarata dal blocco provoca un arresto.

Scritto in: blocco spec.locals: della Recipe — una mappa di coppie <key>: <template> valutate rispetto a una superficie autosufficiente locale al nodo: .context.instance_id, .values, .infra e le voci dello stesso blocco già risolte. Nient’altro vi si trova: .provides, .metadata e il resto di .context.* no, e un riferimento a uno di essi provoca un arresto.

L’ordine è portante. Le voci si risolvono nell’ordine in cui sono scritte e una voce può leggere una voce sorella definita sopra di essa, ricevendone il valore risolto. Il concatenamento procede solo verso il basso — dove una voce ne legge un’altra, spostare la definizione sotto chi la legge viene rifiutato, e il compilatore non riordina mai il blocco per far risolvere il riferimento. Un riferimento a una voce successiva provoca un arresto che nomina l’errore di ordinamento; un riferimento a una chiave non dichiarata provoca un arresto che nomina la chiave. Su una Recipe il cui source: è un blocco strutturato, entrambi gli errori vengono rifiutati anche mentre l’artefatto che esso nomina viene fissato, così aggrega pull li segnala prima che qualsiasi build renderizzi output. Il controllo legge il percorso a cui un riferimento si risolve anziché i caratteri digitati, quindi raggiunge allo stesso modo la forma diretta, un blocco with .locals, una variabile legata a .locals e il blocco tra parentesi, (.locals).<key> o ($.locals).<key>. Una grafia che non copre: una chiave raggiunta tramite una funzione, come index .locals o (default dict .locals).<key>. Una chiave assente raggiunta in questo modo non provoca un arresto, e renderizza il testo letterale <no value> anziché niente del tutto — tranne tramite index stesso, che provoca un arresto nominando la chiave su ogni superficie di template quando la mappa che legge non la contiene.

Visibilità: privata della Recipe. Non esiste un campo .context.uses[].locals — un chiamante non può leggere i locals del suo target attraverso l’arco. Ciò che un chiamante può leggere è il provides: del target.

Casi d’uso:

  • Calcolare stringhe puntatore interne alla Recipe (per es. secret_target_admin_password: "redis-auth", il suffisso del nome di un Secret) che sia il valuesMapping: sia il provides: della Recipe consumano, e che una FeatureRecipe di credenziali associata allo stesso componente legge come .locals.secret_target_admin_password — i template di un’associazione vedono i locals risolti della Recipe ospite uniti a quelli propri dell’associazione. Sul target helm ciascuno di essi scrive il nome completo come {{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}: il nome renderizzato è il nome del componente scritto con i caratteri ammessi in un nome Kubernetes, e un local non può leggerlo, quindi il local porta il suffisso e ogni lettore unisce i due.
  • Applicare il principio DRY ai valori calcolati ripetuti all’interno di una Recipe (un hostname calcolato una volta, referenziato da più campi valuesMapping:).
  • Valori intermedi per logiche di template complesse che sarebbero illeggibili inline.

provides: e locals: — volto pubblico e volto privato

I due pilastri lato Recipe portano una separazione deliberata della visibilità che gli autori dovrebbero tenere a mente:

  • provides: è il volto pubblico. Ogni chiave è la superficie canonica della pipe topologica — i blocchi uses[].inject dei chiamanti a valle le consumano tramite riferimenti from: "<key>". Il dizionario provides: è un contratto tipizzato da cui i chiamanti dipendono; rinominare o rimuovere una chiave è una modifica incompatibile per ogni Recipe le cui dichiarazioni uses[].inject vi fanno riferimento.
  • locals: è il volto privato. Ogni chiave è stato interno alla Recipe, visibile solo all’interno dei template successivi propri della Recipe. Nessun chiamante può leggere i locals di una Recipe; i nomi in locals: non fanno parte di alcuna interfaccia pubblicata e rinominarli è un refactoring interno alla Recipe senza effetti a valle.

I due sono anche ordinati: locals: si risolve per primo, quindi provides: può leggere .locals ma locals: non può leggere .provides. Pubblicare il valore di un local tramite provides: significa quindi aggiungere una voce provides che legge il local — l’espressione resta in un solo punto.

La separazione è deliberata, secondo la distinzione architetturale tra gli interni della Recipe (privati) e l’interfaccia della Recipe (pubblica). Gli autori che trattano provides: e locals: come un unico namespace perdono la distinzione di visibilità e rischiano di esporre stato interno attraverso la pipe topologica — ogni chiave dichiarata in provides: entra a far parte della superficie contrattuale della Recipe, che l’autore lo intendesse o no. L’obiettivo della disciplina: dichiarare una chiave prima in locals:; promuoverla a provides: solo quando un chiamante a valle ne ha effettivamente bisogno.

La visibilità è determinata dal pilastro in cui una chiave è dichiarata: non esiste un marcatore di visibilità per chiave, quindi un valore insieme privato e pubblicato è una voce locals: più una voce provides: che la legge.

Parameters

Sia lo schema Aggregate sia lo schema Release portano un dizionario parameters alla radice. Gli sviluppatori dichiarano le chiavi che l’Aggregate si aspetta; Ops compila i valori a partire da file di Release specifici per ambiente. Questo disaccoppiamento è il meccanismo della promozione GitOps: un unico Aggregate.yaml immutabile attraversa gli ambienti Dev, Staging e Production, e la Release di ciascun ambiente fornisce i propri valori dei parametri.

aggregate.yaml
spec:
parameters:
corp_db_name:
type: string
required: true
env_workers:
type: integer
required: true
region:
type: string
required: true
enable_debug:
type: boolean
required: true
components:
my-backend:
type: core/python-worker:1.0.0
values:
workers: {{ .parameters.env_workers }}
region: "{{ .parameters.region }}"
# release-prod.yaml — inline parameter values
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
corp_db_name: "enterprise_data"
env_workers: 10
region: "eu-west-1"
enable_debug: false

Per i flussi CI/CD che tengono i valori dei parametri in un file separato (per es. un .yaml per ambiente versionato accanto alla Release), la Release usa la forma $import:: parameters: { $import: ./prod-values.yaml }. Il contenuto del file sostituisce la mappa inline sulla superficie della Release. Il percorso si risolve a partire dalla directory che contiene la Release, da qualunque punto venga eseguito un comando, e deve condurre a un file all’interno del workspace — oppure, per una Release indicata fuori dal workspace, all’interno della directory che la contiene. La stratificazione multi-file (la combinazione di un file base con un overlay specifico per ambiente) si esprime con catene extends: di Release — la Release genitore fornisce i parametri di base; la Release figlia estende e sovrascrive chiave per chiave.

Ciclo di vita dei parametri. Il compilatore risolve i parametri in tre fasi. (1) Riempimento dei default — gli slot con default: definito e nessun valore della Release ricevono il loro default. (2) Validazione del contratto dei parametri — il contratto tipizzato parameters: valida ogni valore rispetto ai vincoli type / enum / min / max / pattern dichiarati, compreso un default riempito, così un default che viola il proprio contratto arresta la build. (3) Interpolazione — il compilatore valuta l’intero testo dell’Aggregate come un template e sostituisce ogni riferimento {{ .parameters.<slot> }} con il valore risolto. La mappa unita resta poi leggibile durante il rendering, così che i template di percorso (confine della Release directory: / subDirectory:) possano leggere .parameters.<slot> direttamente, rispetto all’allowlist chiusa documentata in ../path-template-variables.md. Le superfici dei template di valore (Recipe valuesMapping, FeatureRecipe injectMapping / provides / pipeline.with, corpi dei Workload) NON ricevono .parameters nel loro contesto dei template — consumano i valori risolti scritti nelle stringhe values: circostanti dall’interpolazione della fase 3.

La checklist del sollevamento dei parametri

Ogni valore che varia tra ambienti attraversa in sequenza quattro punti di contatto della scrittura. Il modello mentale che gli autori portano con sé: per qualsiasi valore che varia tra Dev / Staging / Production, aspettati di toccare l’Aggregate (dichiarare), il template dei values (fare riferimento), la Release (soddisfare) e il template della Recipe (consumare).

PassoSuperficieAzione
1Aggregate spec.parameters.<name>Dichiara il parametro come parte del contratto di scrittura tipizzato dell’Aggregate. Ogni slot di parametro porta un type dichiarato (string, integer, number, boolean, array, object), una description facoltativa, un default facoltativo, vincoli facoltativi sullo spazio dei valori (enum, min, max, pattern, minLength, maxLength) e una struttura annidata facoltativa per gli slot di tipo oggetto. Il contratto valida ogni valore fornito dalla Release prima dell’interpolazione.
2Template values: del Component all’interno dello stesso AggregateFai riferimento al parametro tramite {{ .parameters.<name> }} dall’interno del blocco values: di qualsiasi componente (o funzionalità, o sotto-aggregato) che lo consuma. Il riferimento è un’espressione di template Go — il compilatore la valuta durante la fase di interpolazione della risoluzione.
3Release spec.parameters.<name> (inline o parameters: { $import: ./path.yaml })Soddisfa il parametro con il valore specifico per ambiente sulla superficie della Release. File di Release per ambiente forniscono valori diversi per la stessa chiave di parametro senza modificare l’Aggregate.
4Template valuesMapping: della RecipeConsuma il valore risolto tramite {{ .values.<key> }} — la Recipe è una superficie di template di valore; il suo contesto dei template non porta .parameters direttamente. La variazione per ambiente raggiunge la Recipe attraverso il dizionario values: post-interpolazione che la fase di interpolazione descritta sopra scrive. (I template di percorso sui confini della Release sono l’eccezione: leggono .parameters.<slot> direttamente durante il rendering secondo la concessione asimmetrica.)

I quattro punti di contatto sono sequenziali e portanti: saltare la dichiarazione nell’Aggregate lascia la Release senza alcuno slot da soddisfare; saltare il riferimento nei values lascia la Recipe senza alcun valore da consumare; saltare il soddisfacimento nella Release lascia il parametro vuoto. Il compilatore valida la catena durante la risoluzione (validazione del contratto dei parametri rispetto alla dichiarazione tipizzata parameters:, poi interpolazione nelle stringhe values: circostanti, poi validazione JSON Schema del dizionario values: risultante rispetto allo schema: del Component o della Feature); le discrepanze emergono come violazione del contratto dei parametri (intercettata rispetto alla dichiarazione tipizzata parameters:), come errore di template non riempito (intercettato all’interpolazione) o come violazione di un vincolo JSON Schema rispetto allo schema values: (intercettata alla validazione dello schema).

Il pattern è il meccanismo canonico della promozione GitOps: un unico Aggregate immutabile attraversa gli ambienti e la Release di ciascun ambiente fornisce i propri valori dei parametri. Ogni valore per ambiente che un autore vuole far variare appartiene alla catena dei parametri anziché essere incorporato direttamente nell’Aggregate.

Semantica di unione di extends: per pilastro

Quando un’entità del catalogo dichiara extends: e il compilatore percorre la catena di ereditarietà, il contenuto di ciascun pilastro si unisce secondo regole specifiche del pilastro. La semantica differisce da un pilastro all’altro; la tabella seguente è il riferimento canonico per pilastro.

PilastroComportamento di unione sulla catena extends:
values (JSON Schema 2020-12)Su una catena di Feature, gli schemi si compongono tramite la composizione di JSON Schema 2020-12. Un Component che estende non scrive alcun contenuto di pilastro e riceve il blocco della sua base esattamente come la base lo ha scritto, a ogni profondità di una catena.
infra (frammento JSON Schema 2020-12)Come values — composto su una catena di Feature, ereditato per intero da un Component che estende.
provides (mappa di template della Recipe)Sostituzione superficiale di primo livello: la chiave figlia sostituisce completamente la chiave genitore con lo stesso nome; le chiavi sorelle vengono mantenute dal genitore. I template non vengono composti; il template della figlia possiede interamente il proprio slot.
uses (usesSchema)Sovrapposizione dell’intera voce per socket, per nome del socket. Una figlia aggiunge socket che la sua base non dichiara, e un socket che ridichiara con un nome esistente sostituisce interamente quella voce — i suoi schemi di valore e di infra e il suo selector insieme. Le voci dei socket non vengono composte, e nulla confronta un selector ridichiarato con quello della base.
features (schema per slot di featuresSchema)Sovrapposizione dell’intera voce per slot, per nome dello slot, alle stesse condizioni di usesSchema. Una figlia aggiunge slot liberamente; uno slot che ridichiara sostituisce interamente la voce della base anziché comporsi con essa.
locals (mappa di template della Recipe)Sostituzione superficiale di primo livello — come provides.
parameters (mappa alla radice dell’Aggregate)Un Aggregate non ha alcun campo extends:, quindi nessuna catena di Aggregate unisce i parametri. Su una catena extends: di Release un parametro con valore mappa si unisce in profondità con prevalenza della chiave figlia, uno con valore scalare viene sostituito dalla figlia, e una chiave che la figlia scrive come null viene rimossa.

Il pattern generale dipende dal tipo e dalla superficie. I pilastri validati da schema di una Feature si compongono secondo JSON Schema 2020-12. I pilastri di un Component che estende sono ereditati per intero — non ne scrive nessuno, quindi il suo contratto è esattamente quello della sua base, e un vincolo della base non può quindi essere allentato, per costruzione. Le superfici a forma fissa — usesSchema e featuresSchema — si sovrappongono per nome su entrambi i tipi: una figlia aggiunge voci, e una voce che ridichiara sostituisce interamente quella della base. I pilastri scritti come template usano la sostituzione superficiale per chiave, dando alla figlia la piena proprietà di qualsiasi slot di template che dichiara.

Un Component che estende rafforza un vincolo tramite assertions: anziché tramite un pilastro — un predicato che aggiunge, valutato accanto a quelli che eredita. Vedi inheritance-and-interface.md per quel meccanismo.

Per il meccanismo di ereditarietà in sé, vedi inheritance-and-interface.md «Inheritance via extends (Ereditarietà tramite extends)», che copre i tipi del catalogo. Una Release non è un’entità del catalogo e si fonde secondo una propria regola; quella regola è in entities/release.md «Composite Release and extends: inheritance (Release composita ed ereditarietà tramite extends:)».

Meccanismi tra pilastri

L’inquadramento dei segnali consente letture tra pilastri ovunque, tranne sulle superfici di autosufficienza documentate. I pattern seguenti formalizzano i meccanismi comuni tra pilastri; un sintomo di scrittura problematica è documentato perché gli autori riconoscano il compromesso.

Convogliamento tra pilastri tramite ponte di schema — segnalato, non recintato

I confini dei pilastri sono disciplina di scrittura: l’architettura segnala cosa va dove (values: per l’intento cognitivo dello sviluppatore, infra: per il dimensionamento fisico di Ops, provides: per le stringhe emesse dalla Recipe, e così via) e il revisore del catalogo fa rispettare la convenzione. Il motore dei template stesso consente letture tra pilastri, a meno che le regole di autosufficienza documentate non le vietino (il provides: della Recipe non vede .context.inject; il provides: con ambito di confine della FeatureRecipe non vede i campi per consumatore). I muri dei pilastri sono segnali, non imposizioni.

Un’eccezione segnalata canonica: lo schema: di un Component può dichiarare una manopola values: rivolta allo sviluppatore che il template valuesMapping: della Recipe convoglia nell’output renderizzato con la forma di infra:. Lo sviluppatore detta l’intento tramite un campo values: tipizzato; il template della Recipe convoglia il valore risultante nel livello infrastrutturale del provider senza che lo sviluppatore scriva codice infrastrutturale. Un esempio svolto:

# Component schema declares a developer-facing dial in values
spec:
schema:
values:
required_iops: { type: integer, min: 100 }
# Recipe valuesMapping pipes the developer's intent into the provider's infra-side knob
valuesMapping:
iops_limit: "{{ .values.required_iops }}"

Il ponte è documentato in inheritance-and-interface.md con esempi svolti. L’intento architetturale (una manopola tra pilastri dichiarata che la Recipe convoglia) ha una sola direzione — values: lato sviluppatore che fluisce nell’output renderizzato lato Ops — e si concretizza nei template di mappatura della Recipe, non nello schema del Component stesso. Il confine dei pilastri resta segnalato: lo sviluppatore vede values:, la Recipe vede sia values: sia infra:, l’output renderizzato li combina.

Accumulatore inject tra pilastri

La pipe .context.inject è il punto di unione di tre sorgenti che attraversano i pilastri:

  1. Self-inject a livello di Component (component.inject) — prende le stringhe dai values e dai provides propri del componente.
  2. Uses-inject (uses[].inject) — prende le stringhe dai provides del target.
  3. Intercettazioni injectMapping: della FeatureRecipe — prende le stringhe da una qualsiasi delle sorgenti precedenti, più il payload infra: proprio della FeatureRecipe.

Quando viene eseguito il rendering di base, .context.inject.<mechanism>.<key> ha accumulato voci da tutte e tre le sorgenti. L’accumulatore è tra pilastri per costruzione — le voci che hanno origine in values, provides e infra confluiscono tutte nella stessa mappa .context.inject. Le Recipes che consumano .context.inject vedono lo stato successivo all’unione senza dover sapere quale pilastro ha contribuito con quale voce.

Per la grammatica di inject e le regole sulle collisioni, vedi topology-triad.md.

Duplicazione dei vincoli tra pilastri

Un campo che vive in due pilastri con livelli di validazione diversi può portare vincoli duplicati. L’esempio canonico: un numero di porta dichiarato nell’usesSchema di un Component (validato tramite JSON Schema, intervallo min: 1, max: 65535) e lo stesso numero di porta consumato nel campo services.<name>.ports.<port> di un Workload, per il quale lo spec.provider.workloadSchema del plugin di rendering del provider può aggiungere una regola min: 1024 per le porte non privilegiate. Lo spec.provider.workloadSchema di un Plugin di rendering del provider documenta come il provider traduce un Workload e indica che il provider è in grado di sintetizzarne uno; non valida nulla. Ogni corpo di Workload viene validato rispetto allo schema Workload della piattaforma, qualunque sia il provider, quindi un vincolo scritto solo in un workloadSchema — una regola min: 1024 sulle porte, per esempio — non viene applicato; per rifiutare un valore del genere, metti il vincolo nello schema del Component o in un’asserzione.

Associazione di Feature / isolamento dei pilastri del Component

Un’associazione di Feature non scrive nei pilastri del Component genitore. Ogni Feature associata porta il proprio payload di pilastro (il proprio blocco values: e il proprio blocco infra:). La FeatureRecipe che sintetizza le risorse della Feature legge il proprio payload di pilastro indipendentemente da quello del Component. L’isolamento riguarda gli input: ciò che un’associazione legge è suo, qualunque sorte abbia ciò che scrive. Dove il provider del target scrive documenti distinti, l’output renderizzato dell’associazione si trova accanto a quello del Component, in una directory propria; dove il provider riunisce i contributori di un confine in un unico documento, l’associazione contribuisce a quel documento come fa il Component, e ogni risorsa porta comunque l’identità propria dell’associazione, così che resti leggibile cosa proviene da dove.

Due conseguenze per gli autori:

  • Un’impostazione values: su un’associazione di Feature non compare in .values del template valuesMapping: del Component. Il Component vede solo i propri valori.
  • Il payload infra: di una Feature non confluisce nell’infra: del Component. Ogni Feature associata ha il proprio dimensionamento fisico, circoscritto alle risorse della Feature.

L’isolamento è esplicito secondo la separazione delle responsabilità dell’architettura: le Features sono contributori indipendenti stratificati sui Components tramite il modello a cipolla a 5 livelli. Per le superfici di associazione e il loro ordine, vedi labels-and-annotations.md «Feature attachment — five surfaces (Associazione di Feature — cinque superfici)».

Lo stesso nome di proprietà in entrambi i pilastri

Un Component o una Feature il cui spec.schema.values: e il cui spec.schema.infra: dichiarano lo stesso nome di proprietà — alla radice, a qualsiasi profondità di annidamento, o in entrambi i casi — è un frequente sintomo di scrittura problematica. I due pilastri sono namespace separati per progettazione (il compilatore accetta la sovrapposizione), quindi lo schema viene validato e l’output renderizzato è ben formato. Il sintomo è cognitivo: lettori e autori di template incontrano l’attrito «quale pilastro contiene il foo che sto leggendo?» ogni volta che scorrono lo schema o scrivono un template basato su di esso.

# Smell — both pillars declare `mode`. A reader of the schema or a
# template against the Feature has to disambiguate every reference.
spec:
schema:
values:
mode: { type: string }
infra:
mode: { type: string }

Gli autori con una sovrapposizione intenzionale hanno un motivo reale per mantenerle entrambe — per es., un mode che significa «modalità operativa dell’applicazione» sotto values ("debug" / "production") e «modalità di topologia della distribuzione» sotto infra ("standalone" / "clustered") porta semantiche distinte, e i nomi coincidono per caso. Gli autori con una sovrapposizione accidentale (il caso più comune) rinominano una delle voci.

Una seconda forma intenzionale è un singolo dato che l’uno o l’altro autore può fornire. Le Features di credenziali della libreria standard che portano il localizzatore di un chiamante — core/referenced-secret, core/referenced-secret-set, core/secret-value e core/secret-provided — lo dichiarano in entrambi i pilastri con un solo nome e una sola forma, così lo sviluppatore lo scrive in values oppure l’operatore in infra, e l’asserzione propria di ciascuna Feature rifiuta un’associazione che lo scrive in entrambi o in nessuno dei due. La segnalazione descritta più avanti nomina queste quattro a ogni caricamento che le raggiunge; per esse riporta il contratto, non una svista.

Il caricamento del catalogo emette una segnalazione notice: LINT: <kind> "<name>" at <path> declares property "<property>" in both values: and infra: pillars (path: <dotted-path>) per ogni proprietà con lo stesso nome la cui sovrapposizione si risolve in una foglia terminale su almeno un lato. Le proprietà con lo stesso nome che esistono come namespace organizzativi condivisi (entrambi i pilastri portano un oggetto chiamato ingress con sottoproprietà disgiunte) non producono avvisi; viene segnalata solo la sovrapposizione delle foglie. L’avviso ha valore di segnalazione — la build prosegue.

Stadi di validazione dei pilastri

I pilastri portano la validazione su tre stadi. Ogni stadio copre un aspetto diverso; lo stesso campo può essere validato da più di uno stadio (vedi «Cross-pillar constraint duplication (Duplicazione dei vincoli tra pilastri)» sopra).

LivelloCosa validaDove viene eseguito
1 — Involucro JSON SchemaForma strutturale (quali chiavi sono presenti, i tipi corrispondono alle dichiarazioni dei campi)Risoluzione, a ogni caricamento di file
2 — Schema per pilastro (schema / featuresSchema / usesSchema)Contenuto tipizzato per pilastro, validato come JSON Schema 2020-12Risoluzione, dopo il superamento dell’involucro
3 — controllo delle capacità del providerContenuto del Workload subordinato alla capacità di modalità sintetizzata del provider legato, documentata dallo spec.provider.workloadSchema del plugin di rendering del providerRendering di base, dopo la risoluzione di valuesMapping

Per la tabella delle forme di errore a quattro livelli e i prefissi di errore per livello, vedi validation-surface.md.

Meccanismi dei valori predefiniti

I valori predefiniti compaiono nel corpus attraverso diversi meccanismi distinti. Gli autori incontrano la parola «default» in più di cinque contesti; la tabella seguente è il riferimento canonico per stabilire quale meccanismo produce un valore quando l’autore lascia vuoto un campo.

#MeccanismoDove viene scrittoAttivazione
1default: di JSON Schema (forma compatta { default: <value> })schema: di Component / Feature, parameters: dell’AggregateIl campo viene validato con il valore predefinito quando lo sviluppatore omette la chiave. Per i parametri dell’Aggregate, l’unione dei parametri inserisce il valore predefinito dichiarato prima che venga eseguita la validazione del contratto (vedi templates/parameters-context.md).
2Template Go optional .X `Y` <fallback>valuesMapping: della Recipe, corpo del Workload, template della FeatureRecipe, il valutatore delle asserzioniFallback sensibile alla presenza — restituisce <fallback> solo quando la chiave è assente dalla mappa; uno zero / vuoto / false scritto dall’autore nella chiave restituisce quel valore scritto. La forma canonica, lato Aggrega, del fallback per campo assente. Vedi templates/sprig-functions.md.
3Template Go | default <expr>valuesMapping: della Recipe, corpo del Workload, template della FeatureRecipePipeline inline che scatta sul «vuoto» (il controllo di vuotezza di Sprig — zero, stringa vuota, false, nil). Confonde l’assenza dalla mappa con la presenza di un valore zero/vuoto/false. Adatta alla semantica di override per singolo punto di chiamata (il fallback del binding differisce dal valore predefinito a livello di schema del campo) dove la confusione è accettabile. Non adatta al fallback per campo assente quando uno zero / vuoto / false scritto dall’autore è un intento legittimo — in quel caso usa optional (meccanismo 2).
4Funzione default di Sprig ({{ default <expr> .field }})Come per 3Forma funzionale del meccanismo 3, con la stessa confusione sulla vuotezza.
5Fallback in locals: della RecipeTemplate locals: della RecipeUna voce di locals calcola una stringa portatrice di un valore predefinito che il resto della Recipe consuma

Indicazioni consigliate sulla collocazione. Quando un valore predefinito fa davvero parte del contratto del tipo (per es., «questa porta è 5432 per impostazione predefinita, a meno che lo sviluppatore non la sovrascriva»), il default: di JSON Schema (meccanismo 1) è canonico — il completamento automatico dell’IDE mostra il valore predefinito; gli strumenti di validazione lo rispettano; il contratto viaggia con l’entità del catalogo Component / Feature OPPURE con la dichiarazione del parametro dell’Aggregate. Quando un template di Recipe ha bisogno di un fallback per una chiave di mappa facoltativa, l’helper optional (meccanismo 2) è la forma canonica del fallback per campo assente — distingue zero / vuoto / false scritti dall’autore dall’assenza. Il | default del template Go (meccanismo 3) è riservato al caso di override per singolo punto di chiamata, dove la confusione tra valori assenti e falsy è accettabile; ricorrivi solo quando la semantica di override è l’intento esplicito.

Riferimenti incrociati

  • inheritance-and-interface.md — meccanismo extends:, binding di interfaccia implements:, convogliamento tra pilastri tramite ponte di schema.
  • topology-triad.md — meccanismi topologici provides, inject, uses.
  • labels-and-annotations.md — vocabolario dei metadati lato contenuto, distinto dai pilastri di dati (l’elenco canonico dei pilastri sopra non include etichette / annotazioni / campi di pubblicazione — quelli sono vocabolario dei metadati).
  • publishing-surface.md — vocabolario dei metadati lato pubblicazione, distinto dai pilastri di dati.
  • validation-surface.md — quattro livelli di validazione dello schema, inclusi i tre stadi di validazione dei pilastri descritti sopra.
  • templates/expansion-matrix.md — disponibilità per punto di template delle letture tra pilastri + regole di autosufficienza per provides: e source: della Recipe.
  • examples/04-secrets.md — la checklist della consegna dei segreti in sei punti di contatto.
  • architecture/06-data-taxonomy-and-composition.md — inquadramento concettuale canonico delle cinque parole chiave strutturali del DSL.