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

Recipe

Il ruolo concettuale dell’entità Recipe (il template di traduzione scritto da Ops che mappa il Developer Intent nel formato fisico) è descritto in architecture/04-entity-taxonomy.md. Questa pagina tratta la superficie di authoring della Recipe — il puntatore (source), il mapper (valuesMapping:), il supporto IaC nativo ed esempi pratici.

L’architettura della Recipe: puntatori e mapper

Una Recipe svolge esattamente due funzioni:

  1. Il puntatore (source): indica al compilatore esattamente dove si trova il codice dell’infrastruttura.
  2. Il mapper (valuesMapping): inietta il contesto astratto di Aggrega nelle variabili specifiche che il codice sottostante si aspetta. Il campo è un’unica superficie di template Go con tre modalità di authoring — block scalar inline, $import: da file o $import: da libreria — selezionate in base alla forma del contenuto. Vedi Il campo valuesMapping — tre modalità di authoring più avanti.

Poiché una Recipe corrisponde rigorosamente 1:1 a una capacità di rendering, tale capacità (spec.capability) è dichiarata esplicitamente al livello radice, così il compilatore Go sa esattamente quale plugin di rendering Wasm a valle invocare.

spec.implements dichiara quale tipo di componente del catalogo la Recipe è in grado di implementare. Il compilatore lo usa per verificare le mappature del Manifest (il campo implements di una Recipe mappata deve corrispondere al tipo mappato) e per suggerire candidate — le recipe elencate in una diagnostica di mappatura mancante e classificate per prime nel completamento dell’editor. Non risolve mai una build: la mappatura del Manifest è la scelta esplicita di distribuzione dell’utente, fissata nel lockfile. Una Recipe il cui implements è senza versione, esatto o un intervallo compatibile con la major si limita comunque a offrirsi per un tipo; l’utente fissa la scelta. FeatureRecipe.spec.implements svolge lo stesso ruolo per i tipi di feature.

A. Schemi di sorgente guidati da Wasm

Per tenere i pregiudizi implementativi fuori dal compilatore, il blocco source non è un insieme fisso di campi infrastrutturali. Il campo source supporta due formati:

  • La stringa universale (rapida e pulita): ideale per percorsi locali, artefatti OCI e repository Git. Il compilatore deduce il metodo di recupero dal prefisso e dal suffisso della stringa (./src, https://github.com/example/module.git, oci://...): un URL che termina con .git, o scritto con git:// o ssh://, è un repository Git recuperato al suo branch predefinito, e un URL https:// che non indica né un repository né un chart .tgz o un frammento .yaml viene rifiutato perché ambiguo.
  • L’oggetto strutturato aperto: un dizionario aperto (additionalProperties: true) le cui chiavi sono definite dal provider e sono esposte ai template della Recipe come .source.* (per esempio .source.chart). L’intento progettuale è che il socket WebAssembly di ciascun provider definisca e convalidi la propria forma di sorgente (ad es. registry/chart/appVersion per Helm).

Cosa risolve il core. Nessun provider convalida chiavi di sorgente proprie. Una sorgente recuperata viene risolta da un’identità integrata il cui kind seleziona un resolver — helm-oci-chart, helm-https-chart, compose-https-fragment e git-repository. Una sorgente destinata al recupero deve contenere kind e url; quale ulteriore coordinata selezioni il contenuto dipende dal kind. I kind di chart e di frammento accettano version e la fissano così come è scritta. git-repository accetta ref — un tag, un branch o un commit — e, facoltativamente, module_subdir, che indica la directory all’interno del repository che costituisce l’artefatto; poiché solo un commit identifica un contenuto che non può essere ripuntato, il riferimento viene risolto al momento del lock e il lockfile registra sia il riferimento scritto sia il commit a cui è stato risolto. Un module_subdir che, così come è scritto, risale sopra il repository — una barra rovesciata conta come separatore — viene rifiutato prima di qualsiasi recupero. Il repository viene archiviato dal proprio checkout: un link simbolico incluso in un commit viene archiviato come il file o la directory a cui punta, se questo si trova all’interno del repository, e uno che ne esce interrompe il pull, indicando il link in base alla sua posizione nel repository. Una sorgente strutturata il cui url: indica un percorso del filesystem non viene recuperata: viene letta dal disco alle stesse condizioni di una semplice stringa di percorso, con un url: relativo ancorato alla directory che contiene il file dell’entità che lo dichiara. Anche una sorgente strutturata che omette kind/url non viene recuperata e, se si intendeva un recupero, la build si interrompe in modo esplicito durante la discesa delle sorgenti al momento del lock, anziché risolversi silenziosamente nel nulla. Il contenuto viene sempre fissato in anticipo; il compilatore non recupera mai lo stato di runtime in tempo reale.

Cosa viene fissato accanto alla Recipe. Per una sorgente recuperata i cui kind, url, chart, module_subdir, version e ref sono tutti scritti per esteso anziché tramite template, aggrega pin registra il digest di ciò che ha recuperato in entity.lock, un file nella directory della Recipe che committi accanto a essa. Il pinning è un passaggio dell’autore della Recipe e non richiede alcuna Release; un pull su una Recipe il cui lock non registra il pin si interrompe e lo indica, a meno che al pull non venga chiesto di eseguire lo stesso passaggio. Una build confronta quel digest con quello che il lockfile della Release registra per la stessa sorgente e si interrompe se i due non coincidono — tranne per una sorgente scritta con un ref: git, la cui riga viene registrata al commit a cui il ref si è risolto e non viene confrontata. Una sorgente recuperata le cui coordinate sono compilate da un template viene invece fissata per Release, nel lockfile di ciascuna Release. Una sorgente che indica una directory o un file accanto alla Recipe non viene recuperata: aggrega pin registra un digest per ogni file che contribuisce a ciò che una pubblicazione della Recipe contiene — ogni file nella directory della Recipe, per una sorgente scritta come template — e, una volta che il lock li registra, una build confronta la sorgente con essi prima che il provider la legga, interrompendosi per un file aggiunto, modificato o rimosso dopo il pin — con E0305, oppure prima con E0130 se il lockfile della Release, scritto prima della modifica, registra la Recipe in base a ciò che contiene. Un lock che non registra alcun pin per una sorgente di questo tipo non lascia a una build nulla da confrontare, e un pull o una pubblicazione che non esegue il pin la rifiuta. Il file della Recipe stesso non viene mai scritto. aggrega pull descrive il file e come rispondere a ciascuna interruzione.

spec.capability può contenere un pin di versione nelle forme che accetta implements — esatta (helm:<version>) o un intervallo con caret (helm:^<version>) — selezionando quale versione del plugin del provider esegue il rendering della Recipe; un pin che nessuna versione disponibile soddisfa interrompe la build. Senza pin (spec.capability: "helm"), ne esegue il rendering la versione disponibile più alta. Le versioni disponibili sono quelle mostrate da aggrega plugin list: i provider integrati in aggrega hanno la versione del compilatore stesso. Il pin non fa parte del nome della Recipe: un Manifest mappa una Recipe che dichiara capability: "compose:1.2.3" come compose/<name>:<version>, esattamente come una senza pin, e cambiare il pin non la rinomina mai; un valore di mappatura che scrive il pin nel nome (compose:1.2.3/<name>:<version>) viene rifiutato come riferimento di recipe malformato (E0095) prima di qualsiasi ricerca.

Modello mentale: spec.capability indica il formato di output desiderato (ad es. helm, terraform, compose); il compilatore lo risolve nel plugin Wasm che esegue il rendering di quel formato (ad es. provider/helm). Tu dichiari il formato; Aggrega associa lo strumento.

B. Iniezione del contesto: lo strato di mappatura semantica

Per evitare che il compilatore esegua deep-merge pericolosi e non deterministici tra più ambienti, una Recipe consente una sola fonte di verità per il proprio strato di mappatura.

Gli ingegneri Ops scrivono il contenuto di mappatura per tradurre il contesto astratto prima che venga eseguito il plugin di rendering Wasm. Il linguaggio di mappatura è il template Go (text/template + Sprig); la libreria Sprig è preregistrata; le azioni standard define e template sono supportate, mentre include non è registrata.

Nome del campoAmbito e fase di esecuzioneCaso d’uso ideale
injectMapping (solo FeatureRecipe)Intercettazione pre-rendering. Valutato nella memoria Go prima della Recipe base. Esegue nativamente un deep-merge del proprio dizionario di output rigorosamente sopra la pipe .context.inject del chiamante. Volutamente assente dallo schema Recipe di base — vedi entities/featurerecipe per la motivazione architetturale.Riscrivere in modo mirato le variabili env iniettate o formattare FQDN per un chiamante senza richiedere un JSONPatch Wasm.
valuesMappingRendering di base (template Go). Valutato per mappare le variabili nel chart/modulo infrastrutturale source sottostante. Un unico campo, tre modalità di authoring (inline, $import: da file, $import: da libreria). Vedi la sottosezione più avanti per il meccanismo di selezione.Mappare variabili standard (come le repliche o i tag delle immagini) in un chart Helm direttamente nello YAML della Recipe, oppure fare riferimento a un template condiviso tramite $import: per il riuso tra Recipe.

Nota: injectMapping è esclusivo delle FeatureRecipes e isola l’intercettazione delle variabili da valuesMapping. Il valuesMapping della Recipe base consuma, senza saperlo, le stringhe .context.inject riscritte generate dai blocchi injectMapping della FeatureRecipe, così i due restano disaccoppiati.

Una chiave che valuesMapping scrive come null raggiunge il provider come null, e cosa vi faccia spetta al provider stabilirlo, quindi ogni pagina di provider lo indica: helm rimuove il valore predefinito del chart per quella chiave, helm-chart lo scrive nei values dell’umbrella, compose lo scrive nel file compose, terraform lo scrive come argomento di modulo null, e cloudformation lo rifiuta.

Il campo valuesMapping — tre modalità di authoring

Il valuesMapping: di una Recipe è un’unica superficie di template Go che accetta tre modalità di selezione. Il compilatore seleziona la modalità in base alla forma del contenuto del campo; non serve alcuna annotazione $mode:.

Modalità 1: template Go inline (block scalar YAML). Il valore del campo è una stringa scritta nella forma block scalar YAML |:

spec:
valuesMapping: |
{{- with .values -}}
image:
tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }}
pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }}
architecture: {{ optional . `architecture` "standalone" }}
primary:
replicaCount: {{ optional .primary `replicaCount` 1 }}
{{- end }}

La modalità inline è la forma di authoring tipica per le Recipes il cui contenuto di mappatura è di dimensioni medio-piccole (meno di ~50 righe). Il corpo del template sta inline con il resto dell’envelope della Recipe; il contenuto della Recipe è autosufficiente.

Modalità 2: $import: da file. Il valore del campo è una mappa che contiene solo $import: con un percorso di file locale:

spec:
valuesMapping:
$import: ./mappings/api-server.tmpl

Il compilatore carica il contenuto del file (un template Go), ne esegue il rendering rispetto al contesto standard dei template della Recipe e tratta il risultato come output della mappatura. La risoluzione del percorso è relativa alla directory della Recipe — un percorso relativo è ancorato alla directory che contiene il recipe.yaml che lo dichiara, non alla directory da cui si invoca la build — e il percorso deve restare all’interno di quella directory, come spiega I percorsi dei contenuti restano nella directory della Recipe. La modalità file è adatta a contenuti di mappatura medio-grandi (~50+ righe) e a flussi di revisione in cui le modifiche alla mappatura compaiono come diff di file separati.

Modalità 3: $import: da libreria. Il valore del campo è una mappa che contiene solo $import: con un riferimento di identità a nome semplice a una voce di una MappingLibrary:

spec:
valuesMapping:
$import: DatastoreHelpers#/mappings/MariaDBCore

Il compilatore risolve il riferimento rispetto all’insieme risolto di MappingLibrary (il catalogo locale più le librerie fissate nel lockfile), carica il contenuto della voce e lo tratta come output della mappatura; una voce il cui corpo è a sua volta un $import: alla radice del campo viene risolta ricorsivamente. Il riferimento non contiene alcun host di registry — il nome della libreria viene risolto per identità e la versione proviene dal lockfile per Release, con una soglia minima di versione facoltativa :<version> (<Library>:<version>#/mappings/<entry>). Il contenuto della libreria condivide il contesto standard dei template della Recipe. La modalità libreria è adatta al riuso tra Recipe — schemi di mappatura che ricorrono in molte Recipes (più Recipes di datastore che condividono la logica di supporto per i datastore; più Recipes del provider Helm che condividono schemi di pod template). L’entità MappingLibrary fornisce versionamento, pinning nel lockfile ed esposizione nell’interfaccia dell’hub.

Regole di selezione. Il compilatore percorre il nodo YAML e seleziona la modalità in base alla forma del contenuto:

  1. Se il nodo è uno scalare stringa, si seleziona la modalità inline (Modalità 1).
  2. Altrimenti il nodo è una mappa; si verifica la presenza della chiave $import:.
  3. Se il valore di $import: è un riferimento di libreria a nome semplice (<Library>#/mappings/<Entry>, eventualmente con una soglia :<version>), si seleziona la modalità libreria (Modalità 3).
  4. Altrimenti (un percorso di file locale) si seleziona la modalità file (Modalità 2).
  5. Qualsiasi altra forma (una mappa senza $import:, una mappa con chiavi aggiuntive oltre a $import:, ecc.) produce un errore in fase di build.

Solo $import: a sorgente singola. $import: accetta una sola sorgente. Il merge di più sorgenti non è supportato in valuesMapping:. Una Recipe che deve comporre più frammenti di mappatura usa una voce di MappingLibrary con una composizione interna define / template dei template Go, un file locale con direttive template dei template Go che invocano file affiancati, oppure una composizione inline per contenuti brevi. Vedi entities/mappinglibrary per l’entità della libreria e vocabulary/cross-document-ref per la distinzione più generale $ref: / $import:.

Provenienza. I messaggi di errore dovuti a errori di rendering dei template citano la provenienza appropriata per ciascuna modalità: i template inline citano il file:riga della Recipe in cui inizia il block scalar; gli import da file citano il contenuto del file importato; gli import da libreria citano la posizione di origine della voce della MappingLibrary, con l’identità della libreria senza host (<Library>#/mappings/<entry>) come puntatore canonico per riferimenti stabili — un host di registry in un riferimento viene rifiutato, quindi la posizione fisica non entra mai nel puntatore.

C. Supporto IaC nativo

Un team Ops che porta il proprio infrastructure-as-code lo tiene nella directory della Recipe — una directory di modulo o di template come ./src, indicata da source: — oppure lo recupera con un source: strutturato (un modulo Terraform dal suo repository git, con kind: git-repository), oppure lo scrive come corpi basati su template sotto artifacts:. Lo strato di mappatura (valuesMapping: — inline, import da file o import da libreria) fornisce il contesto astratto a quel codice, e il provider emette il risultato nel formato proprio del target; nessun linguaggio di configurazione viene convertito in un altro:

  1. Terraform: un modulo viene copiato file per file, e un corpo scritto dall’autore viene emesso esattamente come è scritto, sia HCL nativo (main.tf) sia Terraform JSON (.tf.json) — la CLI terraform legge entrambi. La configurazione radice del boundary, aggrega.modules.tf, richiama la directory di ciascun componente come blocco module, e l’output di valuesMapping: di un modulo con sorgente diventa gli argomenti di quel blocco. Vedi il provider terraform.
  2. CloudFormation: un template con sorgente, YAML o JSON, e i frammenti di risorse scritti da una Recipe vengono normalizzati in JSON in forma estesa e uniti in un unico template di stack per boundary, con l’output di valuesMapping: che compila i parametri dichiarati da un template con sorgente. Vedi il provider cloudformation.

Un valore che esiste solo una volta applicata l’infrastruttura resta un puntatore che il target risolve — un’interpolazione Terraform ${ ... }, un Ref o un Fn::GetAtt di CloudFormation — e non viene mai valutato in fase di build.

Esempio A: il chart Helm remoto (mapping inline e contratto dei locals)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-chart
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
# The shipped fetch form: { kind, url, version }. 'kind' selects a built-in
# resolver (helm-oci-chart, helm-https-chart, compose-https-fragment).
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
# Default chart version. Override via infra.source_version.
version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals:
primary_compute: mariadb
listen_port: "3306"
volumes_path: "/spec/template/spec/volumes"
root_path: "/-"
# The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm
# pipeline: the suffix it follows the rendered name with. A local cannot read
# .context.rendered_name, so each template writing the full name joins the two.
secret_target_db_password: "mariadb-auth"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
# Every key the Component's provides contract declares is published
user: "{{ .values.user }}"
database: "{{ .values.database }}"
protocol: "mariadb"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"
auth:
# Reads the suffix from the local rather than restating it, so the secret
# name is authored once and every reader follows that one definition
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"
primary:
persistence:
size: "{{ .infra.storage.size }}"

Esempio B: il modulo Terraform locale (mapping da file)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: aws-s3-tf
version: 1.0.0
spec:
capability: terraform
implements: aws/s3-bucket:1.0.0
source: "./src"
locals:
primary_compute: bucket_instance
resource_path: "/resource/aws_s3_bucket/main"
root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments
valuesMapping: |
bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data"
region: "{{ .infra.aws_region }}"

Esempio C: Recipe di Component concreta (vincola l’infrastruttura) Ops mappa l’interfaccia generica sulla realtà fisica. (È qui che vengono vincolati i dettagli di rete L4 — scritti direttamente nel codice oppure, come per la porta del proxy qui sotto, presi dal blocco infra che la Release compila.)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: kong-gateway
version: 1.0.0
spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
# A chart repository root paired with the chart's name.
kind: helm-https-chart
url: https://charts.konghq.com
chart: kong
version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides:
# The chart's proxy Service: it suffixes the name pinned below with "-proxy"
host: "{{ .context.rendered_name }}-proxy"
port: "{{ .infra.proxy_port }}"
protocol: "http"
# The contract's other keys: empty while nothing is wired to the models
# socket, and while metrics are off
endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}'
model: '{{ optional .values "model" "" }}'
metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

Disciplina di denominazione delle risorse cloud.

Le Recipes che emettono nomi di risorse cloud — nomi di bucket S3, identificatori di database RDS, nomi di ruoli IAM, nomi di stack CloudFormation e qualsiasi altro campo il cui valore occupa uno spazio dei nomi globale presso il cloud provider — devono concatenare {{ .metadata.release_name }} e/o {{ .context.instance_id }} nel nome renderizzato per evitare collisioni quando la stessa Recipe viene eseguita su più Releases o istanze di component. Il bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" dell’Esempio B è il pattern canonico.

La disciplina si applica ovunque un unico spazio dei nomi globale vincoli il nome. I nomi dei bucket AWS S3 condividono uno spazio dei nomi globale tra tutti gli account di una regione; due Releases dello stesso Aggregate (prod-billing e staging-billing) non possono entrambe distribuire bucket chiamati customer-data — la seconda distribuzione fallisce a runtime con un rifiuto lato AWS. Concatenare release_name differenzia la Release; concatenare context.instance_id differenzia per istanza di component; concatenarli entrambi differenzia per component e per Release.

Che cosa il compilatore controlla e che cosa no. Il compilatore non ispeziona gli output di valuesMapping: alla ricerca di campi con nomi di risorse cloud privi di queste interpolazioni. La disciplina è sostenuta dagli autori delle Recipe (che sanno quali campi nominano risorse globalmente univoche per il provider di destinazione) e dai revisori (che individuano i pattern di risorse senza nome durante la revisione delle PR). Un plugin linter potrebbe segnalare le Recipes i cui output di valuesMapping: fanno riferimento a campi con nomi di risorse cloud senza interpolazione di release_name / instance_id; il socket linter è disponibile e viene eseguito tramite aggrega lint (vedi plugins/plugin-contract.md «Criterio di collocazione: il socket linter e i ruoli di verdetto della governance»), e nessuna delle regole del linter di pubblicazione verifica questo aspetto.

Questa disciplina è uno dei diversi contratti sociali sostenuti per convenzione — disciplina di authoring che gli autori apprendono dalla documentazione anziché dall’imposizione da parte del compilatore. Vedi vocabulary/social-contracts.md per l’elenco completo delle convenzioni e la motivazione architetturale della classificazione di ciascun contratto.

Templating del campo source. Il campo source di una Recipe è esso stesso una superficie di templating. Entrambe le forme di source accettano template Go: la forma a stringa universale

source: "{{ optional .infra `module_path` \"./src\" }}"

e la forma a oggetto strutturato (ogni sotto-campo con valore stringa viene valutato come template; i sotto-campi non stringa passano invariati). Ciò che un template di source può leggere dipende dal fatto che il source indichi o meno un artefatto remoto. La coordinata di un source remoto — version, chart, ref e module_subdir di un blocco strutturato che indica un registry, un repository di chart o un repository git — viene valutata quando aggrega pull risolve l’artefatto per fissarlo, soltanto rispetto a .values, .infra e .locals, con gli helper propri di Aggrega (optional, capitalizedWords e index) e nessuna delle funzioni di Sprig. .context non è disponibile su quella superficie, quindi quale artefatto viene fissato per un component è deciso dai values e dall’infra che riceve e mai dal nome della sua istanza. Le voci di locals: valutate lì sono quelle che quei campi leggono, e quelle che una tale voce legge a sua volta: una voce che nessun campo di source legge non viene valutata mentre il source viene risolto, quindi un local che serve solo al render — uno che chiama una funzione di Sprig, o che legge .context.instance_id — non influisce sul pinning e viene valutato quando il nodo viene renderizzato. Un campo che legge .locals in un modo che non nomina alcuna voce specifica, come {{ index .locals "version" }}, fa valutare ogni voce. Un source che indica un percorso nel workspace, come quello sopra, non viene risolto per il pinning: il suo template viene valutato quando il nodo viene renderizzato, rispetto allo stesso contesto autosufficiente dei locals della Recipe — .context.instance_id, .values, .infra e .locals, l’intero blocco risolto del nodo — quindi ammette e rifiuta le stesse radici di riferimento di una voce di locals:, con una differenza a suo favore: può leggere qualsiasi voce dichiarata dal blocco, non solo quelle sopra di esso. Una coordinata remota può allo stesso modo leggere qualsiasi voce dichiarata dal blocco. .provides non è disponibile in nessuno dei due contesti, e un template di source che cerca di raggiungere i provides del proprio nodo interrompe la build e nomina il riferimento incriminato. Si tratta di una proprietà fissa della superficie e non di una lacuna in attesa di lavoro futuro — i locals di un nodo si risolvono prima dei suoi provides affinché provides: possa leggere .locals, e un template di source legge quegli stessi locals risolti invece di spingersi in avanti verso i provides. I riferimenti a .context.inject e .context.uses sono vietati per le stesse ragioni di autosufficienza; l’URI del source deve risolversi prima che la pipe della topologia venga idratata e prima che qualsiasi elemento a valle carichi il chart, il modulo o il corpo dell’artefatto a cui l’URI punta. Le regole complete di disponibilità e la motivazione dei riferimenti vietati si trovano nella riga #5 della matrice di espansione dei template. L’uso canonico è un override infra.source_version esposto dal Component e convogliato nel campo version del source — vedi entities/component «Il pilastro infra» — così che un catalogo non debba ripubblicare una Recipe a ogni aumento compatibile della versione upstream.

Inventario degli schemi del campo source. Il campo source: accetta diverse varianti di forma nello schema. Il supporto a runtime di ciascuna variante varia a seconda del provider; la tabella seguente documenta che cosa fa ciascuna forma.

FormaEsempioStato
Percorso relativo semplice del filesystemsource: "./charts/postgres"available — ogni provider distribuito (helm, helm-chart, compose, terraform, cloudformation) accetta una stringa con un percorso semplice del filesystem.
Percorso assoluto semplice del filesystemsource: "/abs/path/to/chart"accepted but blocked — lo schema lo accetta e ogni comando che legge la Recipe lo rifiuta: un percorso assoluto indica un luogo sulla macchina su cui è stato scritto anziché contenuto all’interno della directory della Recipe stessa, quindi non viaggerebbe con la Recipe. Sposta il chart nella directory della Recipe e indicalo in modo relativo rispetto a essa; vedi I percorsi dei contenuti restano nella directory della Recipe stessa.
Stringa vuotasource: ""accepted but blocked — lo schema accetta la stringa vuota e ogni comando che carica la Recipe la rifiuta mentre la Recipe viene letta, perché una stringa vuota non nomina nessuna delle due modalità. Il rifiuto nomina l’ambiguità insieme ai due modi per uscirne: omettere il campo per la modalità senza source, oppure dargli un percorso o un URI reale per la modalità con source. aggrega validate <recipe-file> la segnala per la Recipe, e aggrega pull, aggrega build e aggrega validate --release la segnalano per una Release che raggiunge la Recipe. Vedi errors/fatal-halts.md «Recipe source: is an empty string (Il campo source della Recipe è una stringa vuota)».
Oggetto strutturato il cui url: porta uno schema di trasportosource: { url: "oci://…/mariadb", version: "25.0.8" }available — il source-resolver integrato legge la forma {kind, url, version, chart, ref, module_subdir} (lo schema di url: seleziona il tipo — oci:// → chart OCI, https://….tgz → archivio di chart, radice di repository https:// abbinata a chart: → chart di repository — oppure lo si indica con kind:), recupera e fissa l’artefatto in aggrega pull, e la build lo estrae dalla cache. Il vendoring locale di un chart è supportato come alternativa, e non è obbligatorio. Lo schema accetta un oggetto strutturato aperto. Vedi providers/helm.md «Insieme di chiavi source:».
Oggetto strutturato il cui url: indica un percorso del filesystemsource: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" }available — un url: senza schema di trasporto indica un percorso, quindi nulla viene recuperato e nulla viene fissato; la build legge il contenuto dal disco. Un url: relativo è ancorato alla directory che contiene il recipe.yaml che lo dichiara, e uno che esce da quella directory — compreso uno assoluto — viene rifiutato: la stessa lettura che ricevono le due righe di percorso semplice qui sopra, e la forma in cui lo hai scritto non la cambia. Solo url: decide da dove viene letto il contenuto; gli altri campi selezionano che cosa verrebbe recuperato, e raggiungono comunque i template della Recipe come .source.*.
URI OCI (oci://...)source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0"planned — obiettivo di design per la distribuzione dei cataloghi. L’attuale resolver a tre livelli (i file che una Release indica per percorso, i cataloghi del workspace, il registry OCI remoto) è documentato in architecture/13-catalog-and-registry.md; il resolver a livello di entità consuma gli URI OCI attraverso quella cascata, ma la forma OCI del campo source: di ciascuna Recipe oggi non è collegata nei provider.
Altri schemi di URL (https://, git+https://, ecc.)(illustrativo)planned — documentato come intento di design nella roadmap dell’architettura per le sorgenti collegabili; oggi nessun supporto nei provider.

Come viene ancorato un percorso source:. L’ancoraggio si applica ai percorsi del filesystem e a nient’altro, e si applica qualunque delle due forme porti il percorso. Un percorso relativo è ancorato alla directory che contiene il recipe.yaml che lo dichiara, e un percorso che esce da quella directory — compreso un percorso assoluto — viene rifiutato, come spiega I percorsi dei contenuti restano nella directory della Recipe stessa. Un riferimento che porta uno schema di trasporto — oci://, https://, http://, git://, ssh://, git+ssh://, o qualsiasi riferimento che termina con .git — indica qualcosa da recuperare anziché un percorso, quindi viene trasmesso esattamente come lo hai scritto e non viene mai unito a una directory.

Nella forma strutturata il percorso è il campo url:, e viene letto allo stesso modo: un url: relativo è ancorato alla directory che contiene il recipe.yaml, uno che esce da quella directory viene rifiutato, e uno che porta uno schema di trasporto viene recuperato. Ogni altro campo di un source: strutturato viene trasmesso senza modifiche, compresi quelli definiti dal provider.

Un source: scritto come template viene ancorato rispetto al valore che il template produce, non rispetto al testo del template stesso. Un template non indica nulla finché non è stato valutato, quindi la lettura precedente si applica al suo risultato: un risultato che è un percorso relativo viene ancorato alla directory che contiene il recipe.yaml, uno che esce da quella directory — compreso un percorso assoluto — interrompe la build, e uno che porta uno schema di trasporto viene trasmesso e recuperato. Un template è quindi libero di produrre qualsiasi delle forme dell’inventario precedente, e ciascuna viene trattata esattamente come lo sarebbe lo stesso valore scritto letteralmente; la differenza riguarda solo il momento in cui il percorso può essere giudicato, che per un template è quando la build lo valuta anziché quando viene letta la Recipe.

Un template che non produce nulla — un risultato vuoto — lascia la Recipe senza source, cioè in modalità senza source. Questo è diverso dallo scrivere tu stesso source: "", che non indica nessuna delle due modalità e viene rifiutato; vedi la riga dell’inventario sopra.

L’inventario è il riferimento canonico per ciò che gli autori possono inserire in source:; le sue etichette sono quelle definite da 10-status.md.

I percorsi dei contenuti restano nella directory della Recipe stessa

Il contenuto di una Recipe risiede nella directory della Recipe stessa, perché ogni file che una sua pubblicazione porta con sé viene preso da lì. Ogni percorso che una Recipe scrive per il contenuto che porta con sé — il suo source:, che sia un percorso semplice o l’url: della forma strutturata, e ogni file che le sue voci valuesMapping:, workload: e artifacts: importano con $import: — viene letto rispetto alla directory che contiene il recipe.yaml e deve restare al suo interno. Quei percorsi sono anche ciò che una pubblicazione porta con sé: i file che indicano viaggiano con la Recipe, e nient’altro nella sua directory lo fa (vedi aggrega push). Un percorso che esce dalla directory punta a un file che non viaggerebbe con la Recipe, quindi il file non c’è per chi la consuma, e un pin registrato su di esso garantirebbe byte che costoro non possono ottenere.

Due forme escono dalla directory, ed entrambe vengono rifiutate:

  • un percorso che risale sopra di essa, come ../shared/charts/app;
  • un percorso assoluto, come /opt/charts/app, che indica un luogo sulla macchina su cui è stato scritto.

Un percorso che risale e poi rientra è un normale percorso all’interno della directory: ./charts/../values.tmpl indica il values.tmpl accanto alla Recipe. Ciò che viene giudicato è dove arriva il percorso, misurato dalla directory della Recipe senza uscirne — quindi anche una risalita verso l’esterno che nomina di nuovo la directory al ritorno, come ../1.0.0/values.tmpl scritto in una directory chiamata 1.0.0, viene rifiutata. Il nome stesso della directory non viaggia: una Recipe pubblicata viene letta da una directory a cui dà il nome la cache del consumatore, dove quel nome non trova nulla.

Dove viene rifiutato. Ogni comando che legge la Recipe rifiuta un tale percorso mentre la legge, prima che qualcosa venga recuperato, renderizzato o pubblicato: aggrega validate, sul catalogo o sul file della Recipe stessa, aggrega pull, aggrega build, aggrega pin e aggrega push. Un source: scritto come template non indica nulla finché la build non lo valuta, quindi un template che produce un percorso fuori dalla directory viene rifiutato dalla build, nel momento in cui il valore esiste. L’arresto è A path names content outside the entity’s own directory (Un percorso indica contenuti esterni alla directory dell’entità), e nomina il percorso che hai scritto.

Che cosa fare invece. Metti il file nella directory della Recipe, o in una directory sottostante, e indicalo in modo relativo rispetto alla Recipe: ./charts/app, ./extras/netpol.yaml. Un chart usato da più Recipes viene copiato nella directory di ciascuna Recipe, poiché ogni Recipe viene pubblicata separatamente; un corpo di mapping, workload o artefatto condiviso da più Recipes appartiene a una MappingLibrary, WorkloadLibrary o ArtifactLibrary, a cui ciascuna Recipe fa riferimento per identità.

Perché una Release è diversa. Una Release punta ad altre entità — il suo Aggregate, il suo Manifest, la Release che estende — e non viene mai pubblicata, quindi nulla di ciò che legge viaggia da qualche parte. Quei riferimenti, e il file che il suo parameters: importa, vengono letti così come sono scritti, ed è questo che consente a un Aggregate di essere condiviso da varianti di Release in sottodirectory. Vedi entities/release.md.

Lo stesso limite vale per una FeatureRecipe, e per ogni schema che un Component o una Feature importa.

Il campo workload: — tipo di input sintetizzato

Recipe.spec.workload: dichiara il corpo del Workload che il compilatore sintetizza in risorse native del provider. È uno dei tre tipi di input che una Recipe può dichiarare insieme a source: (rendering da source) e artifacts: (manifest ausiliari). Almeno uno dei tre deve essere presente su ogni provider; un servizio di cui la build non esegue il provisioning dichiara un workload: con form: reference.

Il campo accetta tre modalità di authoring — block scalar inline, file $import: o libreria $import:. Il compilatore smista in base alla forma del contenuto del campo; non serve alcuna annotazione $mode:.

Modalità 1: inline (scalare stringa di template Go). Il valore è un block scalar YAML il cui output viene interpretato come aggrega.ai/v1beta1 Workload:

spec:
capability: helm
implements: core/web-server:1.0.0
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra "replicas" 1 }}
containers:
app:
image: "{{ .values.image }}"
ports:
http: 8080

I campi di un Workload si trovano alla radice del documento — non c’è alcun wrapper spec: — e containers: e i ports: di ciascun container sono mappe indicizzate per nome anziché sequenze, con l’ordine dell’autore preservato. Il provider traduce quella forma nella propria forma nativa, quindi una voce della mappa dei container compare nell’output renderizzato di helm come un elemento containers[] denominato dalla sua chiave; la forma scritta dall’autore è la mappa, non la lista renderizzata.

Modalità 2: file $import:. Il valore è una mappa con un’unica chiave $import: che punta a un file locale di template Go:

spec:
workload:
$import: ./workload/web-server.yaml.tmpl

La risoluzione del percorso è la stessa di valuesMapping:: un percorso relativo è ancorato alla directory che contiene il recipe.yaml che lo dichiara, non alla directory da cui viene invocata la build, e deve restare all’interno di quella directory. Il corpo importato è un template Go valutato nel contesto di render della Recipe, esattamente come un corpo inline.

Modalità 3: libreria $import:. Il valore è una mappa con un’unica chiave $import: che porta un riferimento d’identità per nome semplice a una voce di una WorkloadLibrary:

spec:
workload:
$import: BaseWorkloads#/workloads/StatelessService

Il frammento #/workloads/ è ciò che seleziona una voce Workload, ed è il frammento che distingue questo riferimento dalla forma #/mappings/ usata da valuesMapping: — quella indirizza una voce di una MappingLibrary e non nomina un corpo di Workload. Il riferimento non porta alcun host di registry, la versione risolta proviene dal lockfile per Release, una soglia minima di versione :<version> opzionale può essere asserita come <Library>:<version>#/workloads/<Entry>, e una voce il cui corpo è a sua volta un $import: alla radice del campo si risolve ricorsivamente. Il corpo importato è un template Go valutato nel contesto di render della Recipe che lo consuma, quindi .values, .infra e .features vi confluiscono esattamente come in un corpo inline. Vedi entities/workloadlibrary per l’entità libreria e la grammatica completa del riferimento.

Il provider di destinazione deve supportare la sintesi (il catalogo della libreria standard dichiara workloadSchema su tali provider per convenzione); puntare a un provider che non può sintetizzare viene rifiutato quando il nodo viene renderizzato, con la diagnostica di capacità del provider — basata sulla capacità del provider, non sulla presenza di workloadSchema. Per la grammatica completa di Workload, i campi pass-through con forma K8s e il comportamento di traduzione per provider, vedi entities/workload.md. Per il modello più ampio dei tre tipi di input e l’assembler che unisce la sintesi con l’output renderizzato da source e gli artefatti, vedi architecture/16-recipe-input-composition.md.

Consegnare i valori propri di un componente all’immagine dello sviluppatore. Per convenzione del catalogo della libreria standard, ci si aspetta che una Recipe che esegue un’immagine costruita dallo sviluppatore consegni tutto ciò che i blocchi inject: dello sviluppatore hanno risolto, da .context.inject; la Recipe può anche consegnare i valori propri del componente con nomi scelti da essa. Dove il Component dichiara spec.inject, i nomi li sceglie il blocco dello sviluppatore stesso, e .context.self_inject indica alla Recipe l’unico valore proprio letto dal template di ciascuna voce — values.<key> per una voce che legge esattamente un valore proprio e nient’altro. La convenzione del catalogo della libreria standard è trattare i nomi che una Recipe assegna a quei valori come predefiniti anziché come un contratto che il codice dello sviluppatore deve leggere, consegnando un valore con il suo nome predefinito solo quando nessuna voce lo mappa; un catalogo aziendale può scegliere diversamente. Il contratto del contesto dei template fornisce le regole esatte della mappa e un template di esempio completo.

Il campo artifacts: — manifest ausiliari

Recipe.spec.artifacts: è una mappa da nome di voce → definizione del corpo di un artefatto, le cui voci emettono file manifest aggiuntivi accanto all’output primario della Recipe, ottenuto da una sorgente o sintetizzato. È uno dei tre tipi di input (da sorgente / sintetizzato / artefatti) — una Recipe può dichiarare artifacts: da solo, oppure insieme a workload: e/o source:.

Il valore di ogni voce adotta una di tre modalità, selezionate in base alla forma del contenuto e parallele a quelle di workload: — contenuto inline, un $import: da file o un $import: da libreria. Il compilatore sceglie la modalità in base alla forma del contenuto del valore; non serve alcuna annotazione $mode:. In tutte e tre la chiave della mappa dà il nome a ciò che la voce emette: per le due modalità a file singolo è il nome del file di output, e per la modalità bundle è la directory sotto cui vengono annidati i file del bundle. Poiché la chiave dà il nome all’output, è limitata a ciò che può essere un singolo nome di file: una lettera o una cifra iniziale, poi lettere, cifre, punti, trattini e trattini bassi. I punti conservano l’estensione che una chiave porta per convenzione — main.tf, template.yaml, serviceaccount.yaml — mentre l’alfabeto non ammette /, che farebbe di una chiave il nome di un percorso anziché di un file, né un . iniziale, così una chiave non può mai essere il segmento della directory padre. Una chiave fuori da quell’alfabeto non supera la validazione dell’envelope al caricamento del workspace, in aggrega validate e nella diagnostica dell’editor.

spec:
capability: helm
implements: core/web-server:1.0.0
artifacts:
extra-configmap.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: "{{ .context.instance_id }}-extras"
data:
threshold: "{{ .values.threshold }}"
network-policy.yaml:
$import: ./artifacts/network-policy.tmpl
operator-support:
$import: PlatformArtifacts#/artifacts/OperatorSupport

Modalità 1: inline (scalare stringa con template Go). Il valore è un block scalar e la chiave della mappa è il nome del file di output, usato così come è scritto — la prima voce qui sopra emette extra-configmap.yaml.

Modalità 2: $import: da file. Il valore è una mappa con un’unica chiave $import: che punta a un file locale di template Go, e la chiave della mappa è il nome del file di output, esattamente come nella modalità 1. Il file importato fornisce il contenuto; non fornisce il nome. La seconda voce qui sopra ha la chiave network-policy.yaml ed emette network-policy.yaml, anche se il file che importa si chiama network-policy.tmpl. Quindi un autore che vuole un determinato nome di file di output lo scrive come chiave, e due voci che importano file diversi che hanno per caso lo stesso nome — ./extras/shared.yaml e ./overrides/shared.yaml — sono due output distinti. La risoluzione dei percorsi è la stessa di valuesMapping: e workload:: un percorso relativo è ancorato alla directory che contiene il recipe.yaml che lo dichiara, non alla directory da cui viene invocata la build, e deve restare all’interno di quella directory.

Modalità 3: $import: da libreria. Il valore è una mappa con un’unica chiave $import: che porta un riferimento d’identità a nome semplice a un bundle di un’ArtifactLibrary, <Library>#/artifacts/<name>. Un bundle è un insieme di file importati come un’unica unità, quindi una voce si espande in un output per ciascun file del bundle, ognuno annidato sotto la chiave della mappa come <key>/<filename> — la chiave dà il nome al punto di utilizzo ed è la directory in cui finiscono quei file, non il nome di uno di essi. La terza voce qui sopra ha la chiave operator-support; se PlatformArtifacts#/artifacts/OperatorSupport dichiara crd.yaml e rbac.yaml, quell’unica voce emette operator-support/crd.yaml e operator-support/rbac.yaml. Il riferimento non porta alcun host di registry — una forma oci://… con host viene rifiutata — la versione risolta proviene dal lockfile per Release, e una soglia minima di versione :<version> facoltativa può essere indicata come <Library>:<version>#/artifacts/<name>. Vedi entities/artifactlibrary per l’entità libreria e la grammatica completa del riferimento.

Un $import: da file viene fissato accanto alla Recipe. aggrega pin registra il digest dei byte di ciascun file importato nel file entity.lock della directory della Recipe, indicizzato dalla chiave della mappa della voce, e aggrega build ricalcola il digest del file e si interrompe con [CATALOG_ERROR E0026] quando non corrisponde più — oppure prima con E0130 se il lockfile della Release, scritto prima della modifica, registra la Recipe in base a ciò che contiene — così un file modificato dopo essere stato fissato non viene mai renderizzato senza verifica. Se la modifica era voluta, esegui aggrega pin sulla Recipe per registrare il nuovo digest; altrimenti ripristina il file. Una voce inline fa parte del file della Recipe, e una voce da libreria è fissata dalla versione della libreria che il lockfile registra, quindi nessuna delle due ha un pin proprio. aggrega pull descrive il file.

Il template di ogni voce di artefatto viene valutato con lo stesso contesto di template di valuesMapping:, qualunque sia la modalità che ne ha fornito il corpo. Due output con lo stesso nome di file interrompono la build quando il nodo viene renderizzato. Due voci di una stessa mappa artifacts: non possono dare il nome a uno stesso output: una chiave di mappa è unica all’interno di un documento e scrive un unico nome di file, quindi l’output di una voce a file singolo è la sua chiave e i file di una voce bundle stanno sotto una directory che porta il nome della sua chiave — il primo segmento di ogni percorso che una voce emette è la chiave che lo ha prodotto, così chiavi distinte restano nomi di output distinti comunque si chiamino i file importati. Ciò che l’interruzione copre è un unico nome di file fornito da due tipi di input diversi — un template di chart e una voce di artefatto che producono entrambi servicemonitor.yaml — segnalato su quella Recipe con una diagnostica che nomina ogni origine che vi contribuisce.

Casi d’uso. artifacts: è il posto per le risorse ausiliarie che il chart o il modulo primario non produce: una NetworkPolicy che accompagna un carico di lavoro, un HPA abbinato a un Deployment, un ConfigMap sidecar indicizzato su instance_id. Le risorse ausiliarie trasversali che si applicano a molti componenti (un sidecar di backup collegato a ogni datastore, per esempio) appartengono alla Resource Generation della FeatureRecipe anziché agli artifacts: di ogni singola Recipe — vedi entities/featurerecipe.md per la superficie di estensione della FeatureRecipe.

Il blocco boundary: — file per l’output condiviso del boundary

La maggior parte delle Recipes non ne ha mai bisogno. Tutto il resto di ciò che una Recipe scrive appartiene al suo componente: il provider lo colloca nella posizione propria di quel componente nell’output del boundary. Alcuni file appartengono invece al boundary nel suo insieme — un file che il target legge una sola volta per tutto ciò che il boundary distribuisce. La configurazione dei provider di Terraform è il caso tipico: la documentazione di Terraform tiene i blocchi provider fuori da un modulo chiamato da un’altra configurazione, e un modulo che ne contiene uno proprio non può essere chiamato con depends_on, count o for_each. spec.boundary.artifacts è dove una Recipe scrive un file di questo tipo.

spec:
capability: terraform
implements: core/api-gateway/azure-api-management:1.0.0
artifacts:
main.tf:
$import: ./module/main.tf
boundary:
artifacts:
# Terraform reads this beside the root configuration; one copy serves every
# component of the boundary that declares it.
provider-azurerm.tf: |
provider "azurerm" {
features {}
}

Il blocco è artifacts: a un secondo livello. artifacts è il suo unico membro, e ha esattamente la forma del campo artifacts: della Recipe stessa: le stesse tre modalità — contenuto inline, un $import: da file, un $import: da libreria i cui file si annidano sotto la chiave della voce come <key>/<filename> — la stessa regola da chiave a nome di file e lo stesso alfabeto per una chiave, e lo stesso contesto di template, così una voce legge .values, .infra, .locals e il resto esattamente come fa una voce di artifacts:. Richiede almeno una voce, e qualsiasi altro membro sotto boundary: viene rifiutato quando la Recipe viene letta. Una FeatureRecipe non ha un blocco di questo tipo.

Dove viene scritto un file. Una sola volta, nella directory che contiene l’output assemblato del boundary, accanto ai file che l’assemblaggio proprio del provider vi scrive — per terraform, accanto alla configurazione radice aggrega.modules.tf anziché all’interno del modulo del componente. Al provider non viene passato nessuno di questi file: il compilatore li valuta e li scrive da sé, e non vi imprime nulla che indichi da quale componente provenga, perché il file appartiene a ogni componente che lo ha dichiarato. Una voce il cui template viene renderizzato in nulla non scrive alcun file.

Come si incontrano più contributori. Ogni voce viene valutata per ciascun componente che la Recipe renderizza nel boundary, e i file dichiarati da tutti i contributori del boundary vengono uniti per nome. Un nome valutato agli stessi byte — da due componenti legati a una stessa Recipe, o da due Recipes che configurano uno stesso provider in modo identico — è un solo file. Un nome valutato a byte diversi interrompe la build, indicando il file e ogni contributore, perché nessun singolo file corrisponde a ciò che tutti hanno scritto; lo stesso vale per un nome che scrive l’assemblaggio proprio del provider, come aggrega.modules.tf. Entrambi sono la collisione dell’output assemblato. Due Recipes che configurano uno stesso provider con due nomi di file diversi non vengono unite — viene scritto ciascun file — ed è il target a segnalare poi la configurazione duplicata, quindi le Recipes destinate a condividere una configurazione del provider ne condividono il nome di file, per convenzione uno che porta il nome del provider che configura.

Quali provider lo accettano. Che un file collocato accanto all’output assemblato di un boundary abbia un significato è una proprietà del target del provider, quindi fa parte della dichiarazione del provider stesso. Una Recipe che dichiara il blocco e il cui provider non lo accetta viene rifiutata prima di qualsiasi rendering, qualunque sia il risultato del rendering delle sue voci; vedi The provider does not support boundary artifacts (Il provider non supporta gli artefatti del confine). La griglia delle capacità elenca ciò che dichiara ciascun provider.

Providerboundary.artifacts:
terraformAccettato. Ogni file viene scritto accanto alla configurazione radice del boundary, che Terraform legge insieme a ogni altro file di configurazione in quella directory.
helm, compose, helm-chart, cloudformationRifiutato prima di qualsiasi rendering.

Un $import: da file qui viene fissato come quello importato da una voce di artifacts:. Il lock dell’entità ne registra il digest nella stessa lista artifactDigests, sotto boundary/<key> anziché sotto la sola chiave, così una voce di ciascun blocco scritta sotto una stessa chiave viene fissata separatamente. Il passo di pin lo registra, un pull che non esegue il pin si interrompe dove il suo pin manca o non corrisponde più, e una build rifiuta un file modificato dopo essere stato fissato esattamente come rifiuta un file di artifacts:.

Il campo outputLabels: — etichette dichiarate dall’autore sull’output renderizzato

Recipe.spec.outputLabels: è una mappa da chiave di etichetta → valore che il provider imprime su ogni oggetto prodotto dall’output renderizzato della Recipe. È la collocazione onesta per un tratto di realizzazione — una proprietà di come una particolare Recipe realizza un componente, in contrapposizione a ciò che il componente è. Si prenda lo storage con cui una realizzazione rende persistenti i dati, scritto più sotto con la chiave illustrativa example.io/storage-backing: una Recipe Helm che monta un PersistentVolumeClaim e una Recipe Compose che monta un volume con nome realizzano lo stesso componente con meccanismi diversi, quindi portano outputLabels diverse e gli strumenti a valle (allocazione dei costi, policy, inventario) possono distinguerle sulle risorse emesse. La chiave è illustrativa — example.io/ è un namespace di esempio, e un catalogo sceglie le chiavi che leggono i suoi strumenti.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/storage-backing: persistent-volume
example.io/team: platform

Le etichette di output viaggiano sullo stesso binario delle etichette fisse di provenienza della build: vengono unite all’insieme di etichette che ogni superficie di emissione imprime, quindi arrivano ovunque arrivi la provenienza. Ciò che cambia è la titolarità — le chiavi di provenienza appartengono al compilatore, le outputLabels all’autore della Recipe.

L’etichetta d’identità propria di un componente non si scrive qui — una convenzione del catalogo, non una regola che il compilatore impone. Le chiavi che dicono che cosa il componente è anziché come una Recipe lo realizza — la sua categoria cognitiva, il suo tipo operativo, le sue etichette di capacità per ruolo, chi gestisce la risorsa sottostante, la classe di licenza di ciò che incapsula — si dichiarano nei metadata.labels del Component; vedi entities/component «La tassonomia semantica delle etichette» per gli assi. Una Recipe porta una di queste sul proprio output renderizzato nominando la chiave in outputComponentLabels: più sotto, non scrivendo qui la chiave e un valore. Il motivo è che una voce letterale è una seconda copia di un valore che il componente porta già, e una seconda copia può essere in disaccordo con la prima: l’autore di una Recipe può scrivere una postura su un nodo il cui Component ne dichiara un’altra, dicendo a un lettore a valle qualcosa che il grafo non dice. Una voce promossa copia per riferimento e quindi non ha una seconda copia che possa divergere. Il core accetta qualunque delle due tu scriva, al di là della regola sui namespace riservati più sotto; la convenzione è sostenuta dagli autori del catalogo.

Namespace riservati. I namespace aggrega.ai/ e app.kubernetes.io/ sono riservati alla provenienza nativa della piattaforma. Una Recipe che dichiara una chiave di outputLabels sotto uno dei due prefissi viene rifiutata al caricamento con un errore di catalogo chiaro che nomina la chiave in questione. Ogni altra chiave è accettata. Per il resto il core non controlla la chiave né il valore — una chiave o un valore non valido per la superficie delle etichette del motore di destinazione è responsabilità dell’autore, e il runtime a valle lo rifiuta; il compilatore non interviene oltre la regola sui namespace riservati.

Esposizione per provider. Ogni provider traduce le etichette sulla propria superficie di output:

  • helm, sintesi del workload — sia sui metadata.labels dell’oggetto sia sui metadata.labels del pod template, in corrispondenza di dove la sintesi colloca la provenienza.
  • helm, rendering da sorgente e artefatti — sui metadata.labels dell’oggetto.
  • compose — sulla mappa labels: di ogni servizio.
  • terraform — come tag per risorsa sui corpi di artefatto .tf.json indirizzabili strutturalmente, al meglio delle possibilità: un blocco di risorsa che dichiara già una mappa tags (AWS/azurerm) o labels (Google) vi riceve le etichette di output, una chiave dichiarata dall’autore non viene mai sovrascritta, e una risorsa priva di tale attributo resta intatta (un attributo non viene mai inventato). I corpi in HCL nativo (main.tf, *.tf) e i moduli vendorizzati vengono emessi testualmente e non portano tag iniettati. La provenienza di Terraform continua a viaggiare nel suo file di commento associato, separato dal binario dei tag.

Le etichette di output sono solo etichette; non esiste una superficie separata per le annotazioni di output. outputLabels è dichiarato dall’autore della Recipe (il livello di realizzazione scritto da Ops), non dall’Aggregate — descrive la realizzazione, mai l’identità del grafo astratto dello sviluppatore.

Il campo outputComponentLabels: — promuovere le etichette proprie di un componente

Recipe.spec.outputComponentLabels: è una lista di chiavi di etichetta, non di coppie chiave-valore. Per ogni chiave che nomina, il provider imprime quella chiave sull’output renderizzato con il valore che la chiave ha sull’istanza del componente in fase di rendering. Dove outputLabels indica un valore, outputComponentLabels indica da dove va letto il valore.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/team: platform
outputComponentLabels:
- component.aggrega.ai/hosting

Dato un Component i cui metadata.labels dichiarano component.aggrega.ai/hosting: managed, ogni oggetto che questa Recipe renderizza per quel componente porta component.aggrega.ai/hosting: managed. Si leghi la stessa Recipe a un componente che dichiara self-hosted e gli oggetti di quel componente porteranno invece self-hosted — una Recipe, una chiave nominata, un valore per componente.

La promozione avviene per riferimento, ed è proprio questo il punto. Il valore viene letto dal componente ogni volta che l’output viene renderizzato, quindi non può divergere dall’identità da cui proviene: non c’è una seconda copia da tenere allineata quando l’etichetta del componente cambia. Una voce letterale di outputLabels che ripete l’etichetta di un componente è quella seconda copia, e le due divergono non appena una delle due cambia. Quindi usa outputLabels quando il valore è una proprietà di come questa Recipe realizza il componente, e outputComponentLabels quando il valore esiste già sul componente e anche l’output renderizzato deve portarlo.

Una chiave promossa finisce esattamente sulla stessa superficie di una letterale — l’esposizione per provider descritta sopra si applica invariata, e nessun provider distingue una chiave promossa da una scritta sul posto.

Namespace riservati. I namespace aggrega.ai/ e app.kubernetes.io/ sono riservati alla provenienza nativa della piattaforma, e una chiave promossa sotto uno dei due prefissi viene rifiutata al caricamento con un errore di catalogo che nomina la chiave e il campo in cui compare. Il criterio è il prefisso nudo: una chiave come component.aggrega.ai/hosting si trova in un namespace proprio anziché sotto la radice riservata, ed è promuovibile.

Una chiave appartiene a un blocco o all’altro. Dichiarare la stessa chiave sia in outputLabels sia in outputComponentLabels viene rifiutato al caricamento, così ogni chiave impressa ha un’unica fonte — o il valore letterale scritto sulla Recipe o l’etichetta propria del componente, mai entrambi.

Una chiave promossa che il componente non dichiara non imprime nulla. La build prosegue ed emette un avviso che nomina il nodo, la Recipe e la chiave mancante. È voluto: una Recipe legata a componenti con insiemi di etichette diversi viene comunque renderizzata, e la discrepanza viene segnalata anziché interrompere la build.

Componenti a postura singola — una convenzione, non una regola. La promozione porta qualunque valore il componente dichiari, e il compilatore non interpreta quel valore. Un componente la cui etichetta d’identità contiene un segnaposto che sta per «varia» promuove quindi quel segnaposto su ogni oggetto renderizzato per esso. Dove un componente ha davvero più di una postura, la convenzione del catalogo della libreria standard prevede che ogni Recipe indichi la postura della propria realizzazione tramite una chiave di outputLabels di cui la Recipe è titolare, anziché tramite la chiave d’identità del componente, che la stessa convenzione fa passare invece per outputComponentLabels: — oppure che non imprima nulla. Le due chiavi rispondono a domande diverse e nessuna sostituisce l’altra: la chiave d’identità dice che cosa è il componente in ogni realizzazione, la chiave di cui è titolare la Recipe dice che cosa fa questa singola realizzazione. È una convenzione del catalogo sostenuta dai suoi autori, non un vincolo che il compilatore impone.

Il blocco locals:

Recipe.spec.locals: è lo Stato privato di Ops — una mappa di stringhe di template Go con nome il cui output renderizzato espone una mappa .locals.* ai template successivi della Recipe. È lo spazio di lavoro in cui calcolare una volta sola le realtà fisiche (container di destinazione, percorsi JSON, hostname derivati) e riutilizzarle nei payload di provides:, source:, valuesMapping:, workload:, artifacts:, assertions: e pipeline[].with senza ricalcolarle. L’output renderizzato di ciascuna voce viene memorizzato senza gli spazi bianchi iniziali e finali.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
locals:
primary_compute: postgresql
listen_port: "5432"
secret_target_db_password: "postgres-auth"
volumes_path: "/spec/template/spec/volumes"
valuesMapping: |
primary:
auth:
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"

locals: non è mai esposto ai chiamanti — i componenti a valle che consumano questa Recipe tramite uses: vedono solo provides:. I template provides:, source:, valuesMapping:, workload:, artifacts:, assertions: e pipeline[].with della Recipe stessa vedono tutti la mappa .locals.* risolta. I valori per chiave possono essere stringhe semplici o template Go; il compilatore risolve l’intero blocco nel preambolo dei locals, prima del provides: di quel nodo, così ogni template successivo osserva valori risolti stabili.

Ogni voce viene valutata rispetto a un contesto autosufficiente e locale al nodo: .context.instance_id, .values, .infra e le voci di questo stesso blocco già risolte. Un local non può leggere .provides — quel pilastro non è su questa superficie, e una voce che vi accede interrompe la build. Né può leggere .context.rendered_name, il nome che un provider come helm dà alle risorse che renderizza per il nodo, quindi un local che nomina una di quelle risorse porta solo la parte che segue quel nome, come fa secret_target_db_password sopra, e il template che scrive il nome completo unisce le due parti.

L’ordine di scrittura è determinante

Le voci si risolvono nell’ordine in cui sono scritte, e una voce può leggere una voce sorella definita sopra di essa, ricevendo il valore risolto di quella voce sorella:

spec:
locals:
db_identifier: "{{ .context.instance_id }}-postgres" # defined first
secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry above

Il concatenamento procede solo verso il basso. Dove una voce ne legge un’altra, l’ordine delle voci decide se la build riesce: sposta db_identifier sotto secret_target e la build si interrompe. Il compilatore non ordina né riordina mai il blocco per far risolvere un riferimento, quindi l’ordine scritto è il contratto — riordinare un blocco locals: è una modifica di comportamento, non estetica.

Due interruzioni distinte separano i due errori che un autore può commettere, perché hanno correzioni diverse:

  • Un riferimento a una voce che il blocco definisce più avanti interrompe la build indicando l’errore di ordine; la correzione è spostare la definizione sopra chi la legge.
  • Un riferimento a una chiave che il blocco non dichiara affatto interrompe la build indicando la chiave; la correzione è sistemare l’ortografia.

Il controllo segue un alias del blocco. Una chiave raggiunta tramite il punto che il corpo di un with .locals riassegna, o tramite una variabile legata a .locals, viene controllata esattamente alle stesse condizioni della forma diretta: {{ with .locals }}{{ .nope }}{{ end }} e {{ $l := .locals }}{{ $l.nope }} interrompono entrambi la build indicando .locals.nope, proprio come fa {{ .locals.nope }}, e lo stesso vale per {{ (.locals).nope }} e {{ ($.locals).nope }}, perché le parentesi producono il blocco stesso e nient’altro. Una sola forma sfugge al controllo: una chiave raggiunta tramite una chiamata il cui risultato il testo del template non può nominare — {{ index .locals "nope" }}, oppure {{ (default dict .locals).nope }} — perché ciò che una tale chiamata produce si decide quando il template viene eseguito e non in base a ciò che è scritto. Una chiave assente letta come campo del risultato di una tale chiamata non interrompe la build, e viene renderizzata come il testo letterale <no value> anziché come nulla. Una chiave assente raggiunta tramite index interrompe la build, indicando la chiave, perché index si interrompe su ogni superficie di template quando la mappa che legge non contiene la chiave richiesta — una segnalazione diversa da quella di questo controllo, documentata in errors/fatal-halts.md sotto «A template indexes a map with a key the map does not hold (Un template indicizza una mappa con una chiave che la mappa non contiene)». index resta quindi il modo per raggiungere una chiave il cui nome è a sua volta calcolato, come {{ index .locals (printf "secret_target_%s" .values.slot) }}, e un nome calcolato che il blocco non dichiara viene comunque segnalato in base alla sua chiave.

provides: legge .locals e riceve valori risolti, perché i locals di un nodo si risolvono prima dei suoi provides. Un template provides: che nomina una chiave che il blocco locals non dichiara interrompe la build. Ciò significa che un valore di cui hanno bisogno sia una voce di provides: sia un artefatto si scrive una sola volta, in locals:, e si legge da entrambi i punti.

Per la controparte di API pubblica, vedi Il blocco provides: più sotto. La superficie della FeatureRecipe segue le stesse regole — vedi entities/featurerecipe.md «Il blocco locals:».

Il blocco provides:

Recipe.spec.provides: è la API pubblica per gli sviluppatori — una mappa nome → stringa di template Go che dichiara i valori che questa Recipe fornisce ai pipe .context.inject e .context.uses dei chiamanti a valle. Il compilatore valuta i template provides: durante la valutazione dei provides (autonoma, in qualsiasi ordine); le chiavi inject dei chiamanti si risolvono rispetto a questi valori durante l’idratazione degli inject.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
provides:
# The Service this chart names after its release name, suffixed "-postgresql"
host: "{{ .context.rendered_name }}-postgresql"
port: "5432"
database: "{{ .values.db_name }}"

Il template di ogni voce viene valutato sulla superficie autonoma di valutazione dei provides — .context.instance_id, .context.rendered_name dove il provider del nodo ne riporta uno, .values, .infra, i .locals risolti del nodo e testo statico. Il namespace in cui è collocato il nodo non vi compare, quindi un host pubblicato non ne porta alcuno: un consumatore in un altro namespace lo qualifica dal proprio lato. .locals vi compare perché i locals del nodo si risolvono nel preambolo della stessa fase, prima dei suoi provides; un template provides che nomina una chiave che il blocco locals non dichiara arresta la build. Separare la valutazione dei provides dall’idratazione degli inject è fondamentale: il provides: di una Recipe non può fare riferimento allo stato di alcun chiamante perché i chiamanti non sono ancora stati risolti quando viene eseguita la valutazione dei provides — provides: è autonomo secondo l’invariante architetturale. I chiamanti leggono poi questi valori tramite .context.uses.<alias>.provides.<provided-name> nei propri template — i nomi forniti sono annidati sotto provides sull’arco, accanto agli altri campi dell’arco. Un chiamante che dichiara una allowlist inject: sull’arco raggiunge invece gli stessi valori attraverso il proprio pipe .context.inject.

Le chiavi provides: fanno parte della superficie contrattuale della Recipe. Rinominare o rimuovere una chiave è una modifica incompatibile per ogni chiamante che si basa sul vecchio nome; la versione dell’interfaccia implements: dovrebbe riflettere l’evoluzione del contratto. Per la semantica di risoluzione a cascata, il contratto del pipe di inject ed esempi completi che coprono l’instradamento tra namespace e tra regioni, vedi architecture/06-data-taxonomy-and-composition.md §3 e templates/expansion-matrix.md.

Leggere i valori pubblicati di un’associazione

Una Recipe legge le Features associate al proprio componente in .features.<instance-name> e le Features di credenziali in .features.<slot>. Entrambe hanno la stessa forma di associazione — .type, .values, .infra, .provides — quindi un’associazione si legge allo stesso modo qualunque sia la mappa che la contiene; ciò che le distingue è ciò che l’associazione produce.

.provides è l’output pubblicato dell’associazione, risolto dalla FeatureRecipe vincolata a essa. È la controparte del blocco provides: descritto sopra, vista dal lato del consumatore: dove una Recipe pubblica verso i propri chiamanti, un’associazione pubblica verso il proprio componente ospite.

workload: |
# The identity attachment emits a ServiceAccount and publishes its name;
# the pod binds to that published name rather than restating it.
serviceAccount: "{{ .features.identity.provides.name }}"
containers:
main:
env:
DB_SECRET: "{{ .features.app_credentials.provides.name }}"

Leggere il valore pubblicato invece di ricalcolarlo dagli stessi input values/infra è la differenza tra un’unica dichiarazione di un nome e due che possono divergere. La forma completa campo per campo, comprese le regole di disponibilità, si trova in templates/template-context-contract.md.

Un’associazione scritta su una delle connessioni del componente — una credenziale che il componente presenta a una destinazione — si legge con la stessa forma sotto quella connessione, in .context.uses.<alias>.features.<slot>, e non è mai tra le .features. Una Recipe che raggiunge più destinazioni legge la credenziale propria di ciascuna destinazione sotto l’alias di quella destinazione, e un ciclo su .features che seleziona le associazioni per tipo incontra solo quelle del componente stesso:

artifacts:
routes.yaml: |
{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
{{- end }}{{ end }}
{{- end }}

Vedi Le associazioni di una connessione per la forma e per l’ordine in cui un template percorre le connessioni.

Il campo pipeline:

Recipe.spec.pipeline: è un array sequenziale di passi di pipeline Wasm che vengono eseguiti dopo il rendering sull’insieme dei documenti renderizzati, ciascuno dei quali restituisce patch RFC 6902 ed effetti collaterali. Ogni voce dichiara un id (identificatore del passo: lettere, cifre e trattini bassi), un plugin (l’entità Plugin che il passo esegue, qualificata dal suo tipo di plugin — pipeline-step/<name>, facoltativamente con una versione; un semplice riferimento .wasm o un riferimento a un artefatto viene rifiutato), una function (l’export del plugin da invocare), un corpo di template Go with: facoltativo che fornisce il payload del plugin e un template Go when: facoltativo che stabilisce se il passo viene eseguito — un risultato falso salta il passo come pass-through, lasciando invariato l’insieme dei documenti. Il gate when:, la sua indipendenza da optional: e la sua regola di veridicità sono trattati per intero in entities/featurerecipe.md «Passi condizionali — when:»:

spec:
capability: helm
implements: core/web-server:1.0.0
source: { kind: helm-oci-chart, url: "oci://…", version: "…" }
pipeline:
- id: inject_sidecar
plugin: pipeline-step/envoy-sidecar:1.0.0
function: Inject
with: |
target_container: "{{ .locals.primary_compute }}"
envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"

Il compilatore esegue i passi pipeline: di una Recipe di base nell’ordine dichiarato, nello stesso modo in cui esegue il pipeline: di una FeatureRecipe: invoca il plugin Wasm indicato da ciascun passo sull’output renderizzato, applica le operazioni JSON Patch restituite ai documenti indirizzati ed emette gli effetti collaterali del passo. Il campo pipeline: della FeatureRecipe condivide la stessa forma di schema e la stessa esecuzione — vedi entities/featurerecipe.md «Contratto di authoring» e Stato del linguaggio per lo stato di esecuzione di ciascuna superficie.

La meccanica del campo rispecchia la semantica della FeatureRecipe: valutazione sequenziale nell’ordine dichiarato, operazioni JSON Patch applicate ai documenti renderizzati, effetti collaterali emessi insieme a esse ed errori riportati con una provenienza che punta al passo responsabile. Un passo il cui gate when: viene renderizzato come falso viene saltato come pass-through, lasciando invariato l’insieme dei documenti per il passo successivo.

Il blocco assertions:

Recipe.spec.assertions: è una mappa facoltativa di regole con nome che esprimono invarianti di implementazione della Recipe — regole tra campi che valgono dato lo specifico chart o modulo da cui la Recipe attinge. Ogni chiave è un identificatore di regola che compare nel messaggio di errore; ogni valore è un corpo di template Go. A differenza delle asserzioni del Component (che esprimono invarianti a livello di contratto indipendentemente da quale Recipe venga vincolata), le asserzioni della Recipe sono proprietà della specifica implementazione scelta.

spec:
implements: core/datastore/mariadb:^1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "20.0.0"
assertions:
# Bitnami 20.x: serviceMonitor namespace requirement.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}

La regola sopra è specifica del chart Bitnami 20.x; non si applica se viene vincolata una diversa Recipe MariaDB. Le regole a livello di Component provenienti dal contratto continuano ad applicarsi in parallelo, valutate in una fase precedente della pipeline.

Le asserzioni della Recipe vengono valutate dopo il binding della Recipe e prima del rendering, una volta risolti i locals e i provides di ogni nodo. Il contesto del template include .provides, .locals e .recipe.source della Recipe, oltre ai campi dell’istanza dell’entità (.values, .infra, .uses, .features). Lì .uses e .features sono le forme più ristrette della superficie delle asserzioni, non quelle di un template di Recipe: la voce di una connessione porta la sua destinazione e il suo alias, le labels della destinazione, i values propri della connessione e le associazioni scritte su di essa sotto features, ma nulla di ciò che la destinazione pubblica; e la voce di un’associazione, propria del componente o di una connessione, porta il suo type, il resolved_version e i values, ma né il suo infra né il suo provides — la FeatureRecipe di un’associazione non ha ancora risolto i propri provides quando l’asserzione viene eseguita. Un riferimento a .features.<name>.provides quindi arresta la build, e una lettura che tiene conto della presenza restituisce il suo valore di fallback. Per la grammatica completa di authoring, la ripartizione delle responsabilità tra regole a livello di contratto e regole a livello di implementazione ed esempi completi, vedi templates/assertions-block.md.

Il campo omits: — escludere documenti renderizzati da una sorgente

Alla maggior parte delle Recipes non serve mai. Serve per una sorgente che prendi così com’è — il più delle volte un chart scaricato da un registry — che renderizza un documento che la tua Release non deve distribuire: un Secret che il chart genera da capo a ogni rendering, per esempio, che rende diverse due build e, una volta applicato, sovrascrive il Secret fornito dall’operatore. Non modifichi un chart scaricato, e nessuna regola di esclusione vi arriva dentro, quindi omits: è il modo in cui una Recipe lascia fuori dalla build un documento del genere. Un file compose scaricato è lo stesso caso: può includere un servizio, un volume o una config che la Release non deve avere, e un overlay valuesMapping: può modificarne uno ma mai rimuoverlo. Lo stesso vale per un template CloudFormation scaricato, che può dichiarare una risorsa che la Release non deve creare: un valuesMapping: può valorizzare i parametri che dichiara ma mai rimuovere una delle sue risorse.

spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/gateway
version: "2.4.0"
omits:
# The chart generates this key on every render; the operator supplies it.
- kind: Secret
name: "{{ .context.rendered_name }}-session-key"
# Left out only where the Release asks for it.
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: "{{ .context.rendered_name }}-dashboards"
namespace: monitoring

Cosa copre. Solo ciò che source: renderizza. Un workload: e le voci di artifacts: non vengono mai filtrati: li scrivi tu nella Recipe, quindi un documento che lì non vuoi è uno che semplicemente non scrivi. La chiave richiede source:; un documento che viola questa regola viene rifiutato quando viene letto, indicando la regola.

Una voce. Ogni voce indica cosa lasciare fuori tramite tre campi, e un quarto decide se si applica. Ciò che i primi tre nominano è il vocabolario proprio del provider per ciò che la sua sorgente renderizza, esposto per ciascun provider nella tabella seguente:

  • kind — il tipo di ciò che la sorgente renderizza: per un chart, il kind di un documento renderizzato — Secret, ConfigMap, Deployment; per un file compose, service, volume o config; per un template CloudFormation, il Type di una risorsa — AWS::S3::Bucket. Non ha relazione con il kind: che porta un source: strutturato, che indica come viene recuperata la sorgente.
  • name — il suo nome: il metadata.name di un documento; la chiave di un’unità compose sotto services:, volumes: o configs:; l’ID logico di una risorsa CloudFormation, la sua chiave sotto Resources.
  • namespace (facoltativo) — il namespace in cui si trova il documento, per un provider il cui output ha namespace. Senza di esso la voce nomina il kind e il nome in qualsiasi namespace; un namespace il cui rendering è vuoto è trattato come assente.
  • when (facoltativo) — se la voce si applica a questa build. Viene valutato per primo e letto con la stessa regola del when: di un passo di pipeline: un risultato falso scarta la voce, quindi i suoi altri campi non vengono valutati e la voce non viene né passata al provider né verificata, mentre un when: assente o vuoto la mantiene.

kind e name sono obbligatori, e una voce che porta qualsiasi altro campo viene rifiutata quando la Recipe viene letta.

Ogni valore è un template, valutato sullo stesso contesto di valuesMapping:. Quel contesto porta .context.rendered_name, il nome che il provider dà alle risorse del nodo e quello da cui un chart tipicamente le nomina, quindi una voce può nominare un documento esattamente come farà il chart. Un template il cui rendering non riesce arresta la build come fa un template valuesMapping: che fallisce.

Ogni voce che si applica deve lasciare fuori qualcosa. Il provider riporta quante unità ha lasciato fuori ciascuna voce, e una voce che non ne ha lasciata fuori nessuna arresta la build, nominando la voce; vedi An omits entry left out nothing the source rendered (Una voce omits non ha lasciato fuori nulla di ciò che la sorgente ha renderizzato). La causa abituale è un aggiornamento della sorgente che rinomina o rimuove il documento, e l’arresto è ciò che impedisce a un documento rinominato di raggiungere il tuo output senza che te ne accorga. Per lasciare fuori un documento solo a volte, dillo con when: invece di affidarti all’assenza del documento.

La sorgente viene comunque renderizzata per intero. Solo il suo output viene filtrato: ogni template del chart viene comunque eseguito, quindi un template che fallisce fa comunque fallire la build, e un documento lasciato fuori viene renderizzato e poi scartato. Una volta scartato non raggiunge nulla di ciò che la build fa in seguito — nessun file emesso, nessun nome confrontato con i nomi di altri componenti, nessun fatto che una Feature legge sul rendering, nulla di ciò che viene passato a un passo di pipeline.

Una Release raggiunge la chiave attraverso infra e parameters. La chiave appartiene alla Recipe, quindi una Release non può scriverla. Può comunque decidere cosa fa una voce: i template di una voce leggono l’infra che la Release compila, e i parameters che fornisce raggiungono i .values della Recipe ovunque l’Aggregate li instradi lì. Così una Release attiva o disattiva una voce con when:, come fa la seconda voce sopra, oppure decide cosa nomina.

Ciò che lasci fuori è sotto la tua responsabilità. Nulla nella build sa a cosa serve un documento. Lasciarne fuori uno da cui il resto del chart dipende a runtime — il Secret che un Deployment monta, il ServiceAccount con cui gira un pod — produce un output che si compila senza errori e poi fallisce quando viene applicato, a meno che qualcos’altro applicato accanto non fornisca quel documento. Per un file compose e un template CloudFormation la build effettua invece il controllo, perché ciascuno dichiara i propri riferimenti: ciò che resta e nomina ancora un’unità lasciata fuori — un servizio che nomina un servizio lasciato fuori, una risorsa o un output che nomina una risorsa lasciata fuori — arresta la build, come descrive la tabella seguente.

Quali provider lo rispettano. Lasciare fuori un documento è qualcosa che solo il provider può fare, perché solo il provider sa cosa renderizza la sua sorgente, quindi il fatto che un provider rispetti la chiave fa parte della dichiarazione propria del provider. Una Recipe che dichiara omits: e il cui provider non lo rispetta viene rifiutata prima che venga renderizzato alcunché, qualunque sia il risultato del rendering dei when: delle sue voci; vedi The provider does not support omits (Il provider non supporta omits).

Provideromits:
helmRispettato. Una voce nomina un documento che il chart renderizza — da un template o dalla sua directory crds/ — tramite il kind e il metadata.name propri del documento e, dove la voce ne nomina uno, il namespace in cui si trova il documento. Vedi helm → Modalità con sorgente.
composeRispettato. Una voce nomina un service, un volume o un config del file compose di origine tramite la sua chiave sotto services:, volumes: o configs:, confrontata dopo che valuesMapping: è stato unito al file, e non nomina alcun namespace: una voce che nomina un altro kind, o un namespace, arresta la build quando il componente viene renderizzato. Un file in cui ciò che resta nomina ancora un’unità lasciata fuori — tramite depends_on, links, volumes_from, una modalità di rete o di namespace service:, extends, un contesto di build, o una voce volumes: o configs: — arresta la build, nominando ogni riferimento. Vedi compose → Modalità con sorgente.
cloudformationRispettato. Una voce nomina una risorsa del template di origine tramite il suo Type e il suo ID logico, in ogni template di una sorgente di tipo directory, e non nomina alcun namespace: una voce che ne porta uno arresta la build quando il componente viene renderizzato. Un template in cui ciò che resta nomina ancora una risorsa lasciata fuori — tramite Ref, Fn::GetAtt, DependsOn o una variabile Fn::Sub — arresta la build, nominando ogni riferimento. Vedi cloudformation → Lasciare risorse fuori da un template di origine.
helm-chart, terraformRifiutato: il provider passa la propria sorgente perché venga renderizzata al momento della distribuzione, quindi in fase di build non esiste alcun documento da lasciare fuori. Per un chart o un modulo locale, una riga nel .aggregaignore accanto alla Recipe ne lascia invece fuori un file.

La stessa chiave si scrive su una FeatureRecipe; vedi entities/featurerecipe.md.

Per un esempio completo — il Secret generato di un chart scaricato lasciato fuori, l’arresto per determinismo che lo stesso chart incontra senza la voce, e l’arresto su una voce che non corrisponde a nulla, ciascuno da una build reale — vedi ai-gateway-own-webhook-certificate.