FeatureRecipe
Il ruolo concettuale dell’entità FeatureRecipe (Dominio 3 — l’implementazione di un’interfaccia di Feature guidata da plugin Wasm) si trova in architecture/04-entity-taxonomy.md. Questa pagina descrive la superficie di authoring del catalogo per la FeatureRecipe.
Posizione nel catalogo
Le FeatureRecipes sono organizzate con il provider nel primo segmento del percorso (stesso schema delle Recipes):
aggrega-catalog/└── feature-recipe/ └── {provider}/ # e.g., `helm`, `compose` └── {feature-recipe-name}/ └── {version}/ └── recipe.yamlURI OCI: hub.aggrega.ai/featurerecipe/{provider}/{name}:{version} (ad es. hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).
Contratto di authoring
Le FeatureRecipes si legano a un’interfaccia di Feature tramite implements e dichiarano un provider concreto. La loro superficie di authoring è l’insieme completo dei tipi di input della Recipe di base più due blocchi specifici della FeatureRecipe:
- I tre tipi di input —
source+valuesMapping(con sorgente),workload(sintetizzato) eartifacts: identici nella forma a quelli della Recipe di base (vedi Composizione degli input della Recipe eentities/recipe.md). Una FeatureRecipe che porta uno di questi è generatrice di risorse — renderizza risorse accanto al componente di base. Il punto in cui finiscono quelle risorse porta il componente a cui la Feature è collegata e poi il nome con cui è collegata, in quella delle due forme che il layout proprio del target ammette: come directory{component}--{instance}/accanto a quella del suo ospite, sotto la directory in cui quel target colloca i suoi contributori, su un target il cui provider dà a ogni contributore una posizione propria; come prefisso di nome file{component}--{instance}--accanto ai file propri del componente, su un target che legge solo i file collocati direttamente in una directory. Su un provider che compone i suoi contributori in un unico documento, le risorse vengono invece incorporate in quel documento — qualunque sia la famiglia a cui appartiene la Feature: una CRDServiceMonitoroExternalSecretcomeartifacts:inline o$import; un chart o modulo esterno tramitesource:+valuesMapping:; oppure il proprio compute (per esempio un Deployment di un agente sidecar) tramiteworkload:.valuesMapping:condivide le tre modalità di authoring della Recipe di base (block scalar inline,$import:di file,$import:di libreria verso una voce di una MappingLibrary) — vedientities/recipe.md«Il campovaluesMapping— tre modalità di authoring». Per convenzione una FeatureRecipe modifica il componente di base o aggiunge risorse accanto a esso, ma lo schema non limita quali tipi di input possa usare — il compilatore renderizza qualunque cosa la FeatureRecipe dichiari, vincolato solo dalla capacità del provider associato, e resta privo di opinioni sul fatto che un dato tipo sia «adatto a un modificatore» (vedi gli invarianti fondativi). La sintesi (workload:) richiede un provider che la supporti; altrimenti il build si arresta al render con la diagnostica di capacità del provider. injectMapping(intercettazione pre-render): un blocco di template Go nativo eseguito prima del render della Recipe di base. Produce un dizionario JSON o YAML che il compilatore unisce nativamente in profondità sopra la pipe di memoria.context.injectdel chiamante, consentendo una mutazione lato chiamante, senza Wasm, delle variabili d’ambiente e delle stringhe di connessione.pipeline: un array sequenziale di passi di plugin WebAssembly (Wasm) per la mutazione del Workload post-render (ad es. l’iniezione di un sidecar Envoy tramite JSONPatch, o il montaggio di un volume secret). Il campoplugindi ogni passo nomina un’entitàPlugintramite il suo URI, sempre qualificato dal tipo di socket proprio del plugin (<pluginType>/<name>, facoltativamente con versione, come inparser/yamloparser/yaml:1.0.0); il build risolve l’entità nel suo artefatto.wasmindirizzato per contenuto, individuato a partire dall’identità del plugin e dal registry configurato, e un.wasmsemplice o un riferimento ad artefatto non è accettato qui. Vedi la guida per sviluppatori di plugin Wasm per creare e referenziare un plugin, e architecture/04-entity-taxonomy.md §«Dominio 3: base dell’infrastruttura» per il principio del Plugin in due parti (Fetcher / Injector). Il compilatore esegue ogni passo nell’ordine dichiarato: invia l’export guest del plugin nominato contro l’output renderizzato e applica i JSON Patch restituiti e gli effetti collaterali emessi; vedi Stato del linguaggio per lo stato di esecuzione di ogni superficie della pipeline. Unpipeline:è autonomo: una FeatureRecipe può dichiararne uno e nessun tipo di input, nel qual caso non emette risorse proprie e tutto il suo effetto è ciò che i suoi passi applicano come patch ai documenti che il build ha già renderizzato, o emettono accanto a essi.
Una FeatureRecipe può anche non portare nessuno di questi blocchi: una Feature di puro cablaggio il cui effetto è l’arco uses che porta non renderizza nulla, e la sua FeatureRecipe esiste solo per soddisfare la risoluzione — ogni istanza di feature si risolve in una FeatureRecipe, così come ogni componente si risolve in una Recipe. Tra i blocchi sopra, injectMapping è l’unico campo senza controparte nella Recipe di base; i tre tipi di input e pipeline sono condivisi con la Recipe di base.
Ciò che viene fissato accanto a una FeatureRecipe è ciò che viene fissato accanto a una Recipe: il digest di ogni file che una voce artifacts importa, e di ogni source: remota le cui coordinate sono scritte per intero, in un entity.lock nella directory propria della FeatureRecipe, che aggrega pin scrive e che tu committi accanto a essa. Un pull su una FeatureRecipe il cui lock non registra quei pin si arresta e nomina quel passo, a meno che al pull non venga chiesto di eseguirlo. Un build si arresta quando un file importato non corrisponde più al suo digest, e quando il digest di una sorgente non concorda con quello registrato dal lockfile della Release (una sorgente scritta a un ref: git è registrata al commit in cui si è risolta e non viene confrontata); il file della FeatureRecipe stesso non viene mai scritto. aggrega pull descrive il file e come rispondere a ogni arresto.
Templating del campo source
Il source: di una FeatureRecipe è una superficie di templating alle stesse condizioni di quello di una Recipe: il template viene valutato alla risoluzione della sorgente, e ciò che ha prodotto è ciò che la build risolve poi. Entrambe le forme accettano template Go — la forma a stringa universale e la forma a oggetto strutturato, i cui sottocampi con valore stringa vengono valutati come template mentre i sottocampi non stringa passano invariati. L’inventario delle forme, la gestione degli schemi e la lettura dell’ancoraggio sono quelli esposti in entities/recipe.md «Templating del campo source», «Inventario degli schemi del campo source» e «Come viene ancorato un percorso source:»; questa sezione indica solo ciò che cambia per un collegamento.
locals: chart_dir: ./charts/exportersource: "{{ .locals.chart_dir }}"Rispetto a cosa viene risolto un risultato relativo. La directory che contiene il documento FeatureRecipe che lo ha dichiarato — il file del collegamento stesso, mai quello del componente — e il risultato deve restare all’interno di quella directory, esattamente come per una Recipe: un risultato che ne esce, o che è un percorso assoluto, indica un file che non viaggerebbe con la FeatureRecipe e arresta la build. Uno che porta uno schema di trasporto viene scaricato anziché unito a una directory. Una FeatureRecipe risolta da un registry viene letta dai file contenuti nel suo archivio pubblicato, disposti nella cache dei contenuti, quindi un risultato relativo si risolve all’interno di ciò che è stato pubblicato esattamente come si risolve accanto alla FeatureRecipe in una directory del catalogo, soggetto allo stesso vincolo.
Cosa può leggere il template. L’insieme dei riferimenti è quello rispetto a cui vengono verificate le voci locals: della FeatureRecipe stessa, che differisce da quello di una Recipe in due modi che derivano dal fatto che si risolve un collegamento anziché un componente:
.attachment_nameè disponibile e indica l’istanza con cui la Feature è collegata. Il template della sorgente di una Recipe lo rifiuta, perché la sorgente di una Recipe si risolve per un nodo e non è in gioco alcun collegamento..context.instance_idindica il componente host per cui il collegamento si sta risolvendo, non il collegamento, e.context.rendered_nameporta il nome che il provider dell’host riporta per l’host — presente solo dove quel provider ne riporta uno, e con arresto della build dove non lo fa. Consulta Denominare una risorsa renderizzata.
.locals porta l’insieme che leggono gli altri template di questa FeatureRecipe: il suo blocco risolto, con sotto quello della Recipe host, così una chiave dichiarata dal collegamento prevale su una chiave dell’host con lo stesso nome. Un riferimento a una chiave che quell’insieme non contiene arresta la build e la nomina, anziché eliminare la chiave dal rendering. .provides, .context.inject e .context.uses vengono rifiutati per le stesse ragioni di autocontenimento per cui li rifiuta la superficie della sorgente di una Recipe.
Una FeatureRecipe con ambito di confine legge invece il confine. Una Feature la cui FeatureRecipe dichiara executionScope: boundary viene renderizzata una sola volta per il confine anziché una volta per componente, quindi il suo template della sorgente non ha un componente host da leggere. Legge .boundary.* — gli stessi pilastri che leggono i suoi locals: e provides: — e i pilastri per componente (.context, .workload, .attachment_name, .inject) non gli sono disponibili.
Un risultato vuoto. Un template che non produce nulla lascia il collegamento senza sorgente, che è la modalità senza sorgente — la stessa lettura che adotta la sorgente di una Recipe, e distinta dallo scrivere tu stesso source: "".
Che cosa legge .source in seguito. Il source viene valutato prima del valuesMapping:, come quello di una Recipe prima del proprio, e ciò che ha prodotto è .source in ogni template eseguito dopo di esso: il valuesMapping:, l’omits:, i corpi workload: e artifacts: e i passi pipeline:. Quindi un valuesMapping: che legge .source legge il source di questa FeatureRecipe, mai il source del componente a cui è associata, e non legge nulla dove questa FeatureRecipe non dichiara alcun source o il suo template non produce nulla. Una FeatureRecipe con ambito boundary legge il proprio source allo stesso modo. L’injectMapping: viene eseguito prima che venga valutato il source dell’associazione, quindi lì .source è quello del componente host.
Esclusività di injectMapping
Il campo injectMapping è esclusivo delle FeatureRecipes — è volutamente assente dallo schema base Recipe. Questa esclusività 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. Consulta più sotto la sezione sull’intercettazione dell’inject mapping per come funziona il meccanismo, e architecture/10-compilation-pipeline.md sull’inject mapping per la semantica completa dell’intercettazione pre-rendering.
Intercettazione dell’inject mapping: come funziona injectMapping
Quando un chiamante ha bisogno che la stringa di connessione verso la sua destinazione abbia una forma diversa dal .provides.host non modificato della destinazione — aggiungendo un namespace per il DNS Kubernetes tra confini, anteponendo un codice di regione per un gateway multiregione o aggiungendo un suffisso di modalità SSL a un DSN — injectMapping gestisce la modifica presso il chiamante, prima ancora che il valuesMapping della Recipe base veda il canale di inject.
Il campo injectMapping è un text/template Go che il renderer valuta durante l’inject mapping, prima che venga eseguito il rendering della Recipe base. Il template produce un dizionario JSON o YAML con chiavi di meccanismo opzionali (env, file, arg, o un meccanismo personalizzato che la Recipe del componente legge in .context.inject.<name>) — oppure una mappa piatta che per impostazione predefinita vale env — e il renderer unisce in profondità questa sovrapposizione sul canale .context.inject del nodo chiamante. L’instradamento lato chiamante tramite injectMapping viene eseguito durante l’inject mapping senza invocare una sandbox Wasm per la semplice manipolazione di stringhe; i plugin Wasm restano riservati alle modifiche strutturali dell’AST tramite l’array pipeline.
Scrivi ogni valore tramite toJson. Il renderer legge l’output del template come YAML, quindi un valore interpolato tra virgolette così com’è rompe quell’output oppure viene riletto modificato non appena contiene un doppio apice o una barra rovesciata — una password è il caso tipico. toJson scrive il valore come stringa JSON, che YAML rilegge esattamente, così il valore viene consegnato con ogni carattere che contiene:
injectMapping: | env: {{ .values.key }}: {{ .values.origin | toJson }}Un valore composto da più parti viene prima composto e poi scritto tramite toJson una sola volta, come fanno gli esempi seguenti.
Un output che non può essere letto arresta la build. Quando l’output del template non si legge come nessuna delle due forme — la causa tipica è uno scalare tra virgolette rotto dal valore che contiene — nessuna delle sue chiavi potrebbe essere consegnata, quindi la build si arresta nominando l’associazione e la FeatureRecipe anziché eseguire il rendering del componente come se nulla fosse stato consegnato; vedi fatal-halts.md «An attached Feature’s injectMapping output cannot be read (L’output injectMapping di una Feature associata non può essere letto)». Il motivo che riporta viene omesso quando dipende da un valore dichiarato sensibile. Un output vuoto, o che viene interpretato come un dizionario che non consegna nulla, non consegna nulla e non è un errore.
Una chiave di primo livello è un meccanismo, e all non lo è. Ogni chiave di primo livello di un output a dizionario nomina il meccanismo attraverso cui vengono consegnate le sue voci: env, file e arg, o qualsiasi altro nome, che viene consegnato come meccanismo a sé con quel nome. .context.inject.all viene costruito da quei meccanismi dopo l’unione e non viene mai unito da un output, quindi le voci scritte sotto all: non raggiungerebbero nulla; la build invece si arresta, nominando l’associazione, la chiave e la FeatureRecipe, e indicando quali chiavi può contenere un output — vedi fatal-halts.md «An attached Feature’s injectMapping output writes deliveries under a key nothing delivers (L’output injectMapping di una Feature associata scrive consegne sotto una chiave che nulla consegna)». Scrivi tali voci sotto il meccanismo da cui il componente le legge.
La modifica è strettamente locale al chiamante. La FeatureRecipe modifica solo il canale di inject del nodo a cui è collegata, mai l’output .provides della destinazione. Il .provides.host di una destinazione viene consumato potenzialmente da molti chiamanti in tutto il cluster; injectMapping lato chiamante si unisce solo al canale del chiamante specifico, quindi le modifiche di instradamento restano circoscritte all’arco che le ha richieste.
Cosa può riscrivere una mappatura. Ogni blocco inject: ha già consegnato quando le mappature vengono renderizzate, quindi l’output di una mappatura viene sempre unito su chiavi che qualcos’altro ha già scritto — e chi ha scritto una chiave decide cosa succede. Una chiave consegnata dal blocco inject: del chiamante stesso o dal blocco inject: di una delle sue connessioni può essere riscritta dalla mappatura: questa è intercettazione, e il valore della mappatura sostituisce quella singola voce. Una chiave che il collegamento stesso della mappatura ha consegnato tramite il suo blocco inject: può ugualmente essere riscritta da essa. Una chiave che una Feature collegata diversa ha già consegnato — tramite il proprio blocco inject: o tramite l’injectMapping della propria FeatureRecipe — no: la build si arresta nominando entrambi i collegamenti, anziché lasciare che sia la mappatura eseguita per ultima a decidere quale valore legge il chiamante. Così due Features di instradamento possono qualificare ciascuna una chiave propria, ma due Features non possono consegnare entrambe una stessa chiave — compreso il caso di due Features di instradamento che riscrivono la chiave della stessa connessione, poiché la prima è intercettazione e la seconda incontra la consegna della prima; consulta fatal-halts.md «Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping» (Due Features collegate consegnano una stessa chiave, la seconda tramite l’injectMapping della sua FeatureRecipe).
Inferenza della destinazione senza accoppiamento
Poiché il compilatore incorpora le annotazioni in cascata di ogni destinazione nel canale .context.uses del chiamante, il template injectMapping può estrarre le coordinate di instradamento senza che Ops codifichi in modo fisso l’identità della destinazione nell’infra della Feature:
- Il template cerca in
.context.usesl’esatto arco topologico che ha iniettato la variabile richiesta dallo sviluppatore. - Estrae le
release_annotationsin cascata della destinazione (ad es.aggrega.ai/namespace). - Formatta il nome di dominio completo (FQDN) o la stringa di connessione.
- Emette il dizionario di override.
Il compilatore resta agnostico rispetto alla semantica di rete — namespace Kubernetes, regioni cloud, topologie bridge-proxy — ed esegue semplicemente l’unione in profondità con qualunque cosa il template abbia prodotto. Quando in seguito viene eseguito il valuesMapping della Recipe base, questo consuma le stringhe intercettate e riscritte da .context.inject.env come se fossero gli originali dello sviluppatore.
Esempio completo: resolver DNS K8s
Il catalogo standard lo fornisce come core/k8s-dns-resolver con una FeatureRecipe helm. Poiché i nomi delle variabili d’ambiente devono essere univoci all’interno di un container, la target_var (ad es. API_HOST) funge da identificatore globalmente univoco per uno specifico contratto di iniezione all’interno del chiamante. Scorrendo gli archi espliciti in .context.uses e controllando quale arco ha rivendicato la target_var, il template individua il nodo di destinazione corretto e ne legge il namespace. L’unico parametro è la variabile da riscrivere; la destinazione e il suo namespace vengono scoperti, mai codificati in modo fisso.
Lo schema della Feature di instradamento (core/k8s-dns-resolver):
infra: { target_var: string # Ops dictates WHICH injected var to rewrite}L’implementazione della FeatureRecipe:
injectMapping: | # 1. Grab the atomic base host directly from the flattened pipe, or an # empty value when nothing was injected under target_var {{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable {{ $target_edge := dict }} {{ range $alias, $edge := .context.uses }} {{ if hasKey $edge.inject.env $.infra.target_var }} {{ $target_edge = $edge }} {{ end }} {{ end }}
# 3. Read the target's namespace from its cascaded release annotation, # coalescing an absent namespace to "default" {{ $ns := "default" }} {{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }} {{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }} {{ if $raw }}{{ $ns = $raw }}{{ end }} {{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection # and a base host were actually found, so a target_var that matches no # connection injects nothing instead of a spurious variable. An unset # namespace resolves to "default", where the helm provider deploys an # unannotated workload, so the qualified host always matches the service's # actual location and is never malformed. {{ if and $target_edge $base_host }} {{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge env: {{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }} {{ end }}Casi d’uso oltre l’instradamento
injectMapping è usato più comunemente per la risoluzione degli indirizzi tra confini (come il resolver DNS K8s qui sopra), ma quella modifica lato chiamante si applica a qualsiasi scenario che richieda di intercettare e formattare l’intento dello sviluppatore prima del rendering dell’infrastruttura. Altri due pattern illustrano la gamma.
Formattazione dinamica della sicurezza (l’appender SSL). Se un’azienda impone che tutte le connessioni a database esterni usino una verifica TLS rigorosa, una Feature può intercettare il DB_URL richiesto dallo sviluppatore e aggiungere la modalità SSL necessaria, così l’applicazione si avvia con i parametri di sicurezza corretti.
# Inside force-ssl-featureinjectMapping: | {{ $base_url := index .context.inject.env .infra.target_var }} env: {{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}Prefisso del gateway multiregione. Se un componente API generico viene distribuito globalmente, una Feature di instradamento regionale può cercare in autonomia le annotazioni del proprio confine d’ambiente per anteporre un prefisso alle stringhe di connessione iniettate per i suoi chiamanti.
# Inside regional-routerinjectMapping: | {{ $base_host := index .context.inject.env .infra.target_var }} {{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }} env: {{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}Il limite di injectMapping. Il meccanismo si limita a modificare il canale di memoria .context.inject (il contratto di consegna). Non può aggiungere nuovi container, montare volumi o alterare l’output del valuesMapping della Recipe base. Qualsiasi modifica che richieda cambiamenti strutturali all’AST renderizzato (come array JSON o YAML) appartiene all’array pipeline della FeatureRecipe, eseguito tramite plugin WebAssembly.
Il limite dei target di patch di pipeline. Uno step di pipeline applica patch solo all’output che il provider renderizza in un albero strutturato. L’output in forma YAML e JSON è strutturato — compresi i moduli Terraform .tf.json scritti in JSON — quindi il JSONPatch di uno step modifica sul posto i valori indirizzati, lasciando intatto ogni altro byte (commenti, ordinamento, formattazione). L’output che il provider emette come corpo opaco, come la configurazione Terraform in HCL nativo, non è un target di patch: una patch su un corpo opaco arresta la build con una diagnostica anziché modificare un testo che non può indirizzare strutturalmente. Scrivere uno step di pipeline contro un output opaco è quindi un errore di progettazione segnalato da un arresto esplicito, non un no-op silenzioso.
Gli input di un modulo Terraform vendorizzato non sono un target di patch, e vale la pena dichiararne l’assenza. Sono gli argomenti del blocco module di quel componente, che il provider terraform scrive nella configurazione radice del confine: HCL nativo, quindi opaco secondo la regola precedente, e un artefatto dell’intero confine anziché del nodo il cui output lo step modifica. Non esiste quindi alcuna posizione da cui uno step di pipeline possa indirizzarli, né nulla che possa fare per cambiare ciò che riceve un modulo Terraform referenziato tramite source. Quei valori prendono forma dove vengono scritti — nel valuesMapping: della Recipe base.
Step condizionali — when:
Uno step di pipeline può avere un campo opzionale when:: un template Go inline che il compilatore valuta durante l’attraversamento della pipeline, con lo stesso contesto di template e lo stesso valutatore usati dal corpo with: dello step. Il risultato renderizzato decide se lo step viene eseguito.
- Un risultato falsy salta lo step come pass-through: l’insieme di documenti passa invariato allo step successivo, e lo step saltato non contribuisce nulla — nessuna patch, nessun effetto collaterale, nessuna traccia di esecuzione.
- Un
when:vuoto o assente esegue sempre lo step.
when: e optional: sono indipendenti. when: decide se uno step viene eseguito; optional: attenua il fallimento di uno step in esecuzione. Uno step può dichiararli entrambi — when: controlla l’ingresso e, se lo step viene eseguito, optional: governa come viene gestito un errore al suo interno. Un template when: il cui rendering fallisce è un difetto di scrittura e arresta la build indipendentemente da optional:.
Il testo when: renderizzato viene giudicato con la regola condivisa dei template booleani: le stringhe true, True e TRUE, qualsiasi numero diverso da zero e qualsiasi altra stringa non vuota sono veri; le stringhe false, False e FALSE, la stringa vuota e un numero zero sono falsi.
Pattern della FeatureRecipe per le credenziali
Quando una FeatureRecipe implementa una Feature di credenziali (una etichettata feature.aggrega.ai/kind: secret), può seguire il principio del Plugin in due parti: una pipeline che concatena un plugin Fetcher (che genera la CRD specifica del vault) e un plugin Injector (che monta il secret nel container di destinazione), la forma che descrive examples/04-secrets. Le FeatureRecipes di credenziali della libreria standard non dichiarano alcuna pipeline: ed eseguono esse stesse il rendering della risorsa secret; consulta examples/05-credential-features.
Una FeatureRecipe di credenziali viene renderizzata nella stessa passata di generazione delle risorse di quella di qualsiasi altro collegamento, e la sua pipeline: viene eseguita alle stesse condizioni: il compilatore percorre ogni collegamento che ha lavoro in quella passata come un’unica sequenza ordinata ed esegue la pipeline dichiarata da ciascuno, con la stessa semantica degli insiemi di documenti /own e /host. Un collegamento entra in quella sequenza per una di due ragioni — la sua FeatureRecipe dichiara un tipo di input, quindi genera risorse proprie, oppure dichiara una pipeline:, quindi riscrive documenti già emessi. Un collegamento di credenziali può quindi intervenire sui documenti renderizzati del componente host — montando un volume di secret, aggiungendo un riferimento env — esattamente come un collegamento operativo, e l’unica differenza tra i due è dove finiscono i suoi file generati.
Su un componente, una dichiarazione di sensibilità sulla Feature segue il valuesMapping: della FeatureRecipe esattamente come quella di un Component segue quello della sua Recipe. Dove una FeatureRecipe renderizza da un source: senza valuesMapping:, i valori che riceve la sua destinazione hanno come chiavi i percorsi foglia dichiarati dalla Feature, quindi una foglia dichiarata sensitive: true contrassegna la sua chiave renderizzata. Dove la FeatureRecipe dichiara un valuesMapping:, le chiavi sono un’invenzione di quel template, nessuna dichiarazione le nomina, e la build stampa un avviso per ciascuna di tali foglie indicando il collegamento, la foglia e la FeatureRecipe. Una Feature collegata a un confine non ne genera nessuno: il suo .values è sempre vuoto, quindi nessuna foglia dichiarata ha un valore da contrassegnare — consulta A declared-sensitive value reaches the target through a values mapping (Un valore dichiarato sensibile raggiunge la destinazione tramite un values mapping).
Il blocco provides: — pubblicazione verso il consumatore
Il blocco provides: di una FeatureRecipe è il suo output pubblicato: una mappa con valori stringa di template Go valutati nell’ambito del collegamento stesso (.values, .infra, i .locals completamente risolti della FeatureRecipe, e .context.instance_id e .context.rendered_name del nodo host). I locals si risolvono per primi, quindi una voce di provides: li legge e riceve valori risolti; nominare una chiave che il blocco locals: non dichiara arresta la build. È il modo in cui un collegamento comunica al suo consumatore ciò che ha prodotto — il nome di una risorsa emessa, una chiave di dati generata, un’identità cloud — senza che il consumatore ricavi di nuovo quell’identità dagli stessi input.
Il consumatore lo legge in .features.<instance-name>.provides.<key> (o .features.<slot>.provides.<key> per un collegamento di credenziali), rispecchiando .context.uses.<alias>.provides per un arco uses. Dove il collegamento è scritto su una delle connessioni del consumatore, il consumatore legge la stessa mappa sotto quella connessione, in .context.uses.<alias>.features.<slot>.provides.<key>, e il collegamento non è tra i suoi .features (consulta I collegamenti di una connessione). Il blocco inject: del collegamento stesso risolve i suoi riferimenti from: sulla stessa mappa, quindi un autore può scegliere l’uno o l’altro canale: provides per una lettura da template, inject per la consegna in una variabile d’ambiente, un file o un argomento.
# FeatureRecipe: emits a ServiceAccount and publishes its name.provides: name: "{{ .infra.service_account_name }}"# Consuming Recipe: binds the pod to what the attachment published.workload: | serviceAccount: "{{ .features.identity.provides.name }}"Quando la Feature che questa FeatureRecipe implements dichiara un contratto schema.provides, il contratto viene applicato alla FeatureRecipe: ogni chiave dichiarata dalla Feature deve comparire nel provides: della FeatureRecipe, altrimenti la build si arresta nominando la chiave mancante. Chiavi pubblicate aggiuntive sono consentite — il contratto è un minimo, non un massimo. I valori non vengono mai ispezionati; sono puntatori deterministici opachi che il runtime risolve.
La risoluzione avviene una volta per collegamento, prima che il consumatore venga renderizzato, e la stessa mappa risolta alimenta la lettura del consumatore, la verifica del contratto e la generazione delle risorse del collegamento stesso — quindi ciò che il consumatore legge e ciò che il collegamento emette non possono divergere.
Provider & implements
spec.capability è obbligatorio e indica il provider il cui plugin di rendering Wasm renderizza l’output della FeatureRecipe (helm, helm-chart, compose, ecc.), alle stesse condizioni dello spec.capability di una Recipe (consulta entities/recipe.md): un pin di versione seleziona quale versione di quel plugin lo renderizza, e non fa parte del nome della FeatureRecipe — un Manifest mappa una FeatureRecipe che dichiara capability: "compose:1.2.3" come compose/<name>:<version>, e un valore di mappatura che scrive il pin nel nome viene rifiutato come riferimento di ricetta malformato (E0095) prima di qualsiasi ricerca. Il campo implements lega la FeatureRecipe alla sua interfaccia Feature e supporta la corrispondenza esatta, per intervallo compatibile con la versione major o senza versione — consulta vocabulary/inheritance-and-interface per la semantica della corrispondenza di versione di implements.
Ambito di esecuzione — spec.executionScope
L’enum opzionale spec.executionScope seleziona il modello di dispatch della generazione delle risorse. Sono accettati due valori; quando il campo è omesso, il valore predefinito è component.
component(predefinito). La generazione delle risorse della FeatureRecipe viene eseguita una volta per ogni istanza di componente collegata. Ogni invocazione riceve un contesto dei template per componente con radice in.context.*:.context.instance_id,.context.inject,.context.uses,.context.annotationse così via. I suoivaluesMapping:,workload:eartifacts:leggono anche.context.used_by, i componenti le cui vociusespuntano all’host — ciascuno con la propria identità, il proprio socket, ciò che pubblica e il namespace e il confine in cui è collocato — che nessun template renderizzato dall’host stesso può vedere.boundary. La generazione delle risorse viene eseguita una volta per ogni confine collegato, indipendentemente da quanti componenti nel sottoalbero del confine consumino la funzionalità. Ogni invocazione riceve un contesto dei template con ambito di confine con radice in.boundary.*anziché in.context.*.
L’intercettazione injectMapping descritta sopra è sempre per consumatore, indipendentemente da executionScope. Ogni componente che usa la funzionalità riceve comunque la propria riscrittura lato chiamante di .context.inject. Solo il passaggio di generazione delle risorse (source/valuesMapping e l’array pipeline) viene deduplicato con ambito di confine.
I template di una FeatureRecipe con ambito di confine vengono quindi eseguiti in due ambiti. Il suo injectMapping viene eseguito una volta per ogni componente raggiunto dal collegamento, sul contesto di quel componente — lo stesso che legge l’injectMapping di una FeatureRecipe con ambito di componente: .context.*, .attachment_name, .features e i .values, .infra e .locals propri del collegamento. Il suo .infra è il blocco infra: del collegamento al confine, e il suo .locals è il blocco valutato una sola volta per il confine. Ogni altro template che scrive — tra cui i suoi locals:, provides:, source:, valuesMapping: e artifacts: e i with: e when: dei passaggi della sua pipeline — viene eseguito una volta per il confine, sul contesto con ambito di confine descritto sotto. Ogni template viene verificato rispetto all’ambito in cui viene eseguito: un valuesMapping: che legge .context.instance_id arresta la build, mentre un injectMapping che lo legge renderizza l’identità di quel componente. .boundary non è impostato nel contesto di alcun componente, quindi un injectMapping che lo legge arresta la build indicando il riferimento, qualunque sia l’executionScope della FeatureRecipe.
Contesto dei template con ambito di confine
Quando executionScope: boundary, i template della FeatureRecipe diversi dal suo injectMapping vengono valutati su una vista .boundary.* del confine a cui la funzionalità è collegata. La vista espone:
.boundary.path— il percorso del confine della Release a cui la funzionalità è collegata: i nomi dei confini dal più esterno verso l’interno, uniti con/(bridge,bridge/frontend). Indica il confine, non la directory in cui viene scritto il suo output, che è impostata dadirectory:(sostituisce.context.instance_id)..boundary.assembly_path— la directory, relativa alla directory di output della build, in cui viene assemblato l’output proprio del collegamento: idirectory:esubDirectory:valutati del confine, ossia la directory verso cui la build instrada quell’output (bridge/compose). È uguale alsource_assembly_patho altarget_assembly_pathdi un’estremità di una connessione esattamente quando quell’estremità viene renderizzata nello stesso file assemblato, quindi una FeatureRecipe li confronta per distinguere una connessione all’interno del proprio file da una in un altro file..boundary.boundary_name— il nome del confine così come è scritto nella Release..boundary.components— una mappa indicizzata per ID di istanza che contiene ogni componente nel sottoalbero del confine (instance_id,component,resolved_version,boundary_path)..boundary.internal_uses_edges— gli archiuses:le cui due estremità si trovano entrambe nel sottoalbero di questo confine (il pattern compose-bridge li enumera, mantenendo gli archi le cui due estremità sono assemblate nel suo file compose e collocate su reti diverse di quel file, per derivare la propria configurazione di proxy per arco). Ogni arco porta i provides risolti delle sue estremità, le variabili d’ambiente iniettate e la collocazione di ciascuna estremità:source_namespaceetarget_namespace, l’annotazioneaggrega.ai/namespaceche si applica a quell’estremità — l’impostazione della sua voce nella Release, se ne ha una, altrimenti quella del suo confine;source_boundary_pathetarget_boundary_path, il percorso del confine della Release che la contiene; esource_assembly_pathetarget_assembly_path, la directory sotto la directory di output della build in cui il suo provider la assembla, composta daidirectory:esubDirectory:valutati del suo confine (bridge/compose). Due estremità con lo stesso percorso di assemblaggio vengono renderizzate in un unico file assemblato, e il provider compose legge il percorso di assemblaggio come la rete dell’estremità dove non si applica alcun namespace..boundary.outgoing_cross_boundary_uses_edges— gli archi con la sorgente all’interno del sottoalbero e la destinazione all’esterno..boundary.incoming_cross_boundary_uses_edges— gli archi con la destinazione all’interno del sottoalbero e la sorgente all’esterno (usati dagli aggregatori di tipo ingress)..boundary.cross_boundary_uses_edges— l’unione degli archi tra confini in ingresso e in uscita, quando la FeatureRecipe vuole la vista completa tra confini..boundary.labels— l’unione delle label del sottoalbero, con l’ordine di scrittura preservato..boundary.annotations— le annotazioni proprie del confine più quelle ereditate in cascata..boundary.feature_attachments— ogni funzionalità collegata a questo confine (così una FR con ambito di confine può ispezionare le funzionalità sorelle, se necessario).
Il pilastro .infra su una FR con ambito di confine si risolve nel blocco infra: della funzionalità collegata al confine (il dimensionamento fisico scritto lato Release per quel collegamento al confine). .values è sempre vuoto per le FR con ambito di confine: la regola di separazione dei pilastri dello schema della Release vieta values: sui collegamenti di Feature a livello di Release, quindi una funzionalità collegata a un confine non porta valori da proiettare. Le FR con ambito di confine che necessitano di dati sotto forma di parametri dovrebbero consumarli tramite .infra (la superficie di authoring dell’operatore per la configurazione delle funzionalità di confine) o tramite .boundary.annotations (valori stringa risolvibili in cascata, scritti sul confine o su un qualsiasi antenato); .parameters non fa parte della vista, e un template che lo legge si arresta indicando le radici che la vista definisce. .locals continua a essere il blocco locals proprio della FR. .steps e .metadata restano invariati.
Allowlist dei campi dei template con ambito di confine
Le FR con ambito di confine possono fare riferimento solo ai campi disponibili nella vista con ambito di confine, in ogni template tranne l’injectMapping. Scrivere un template di questo tipo che fa riferimento a un campo solo per componente (ad es. .context.instance_id, .context.inject, .context.uses) quando executionScope: boundary fa fallire la validazione della FeatureRecipe al momento del parsing, con un errore che indica la FR, il campo non valido e i campi che la vista con ambito di confine definisce. La regola speculare vale nella direzione opposta: una FR con ambito di componente che fa riferimento a campi .boundary.* non supera lo stesso validatore. L’injectMapping viene verificato rispetto al contesto del componente in cui viene eseguito, in entrambi gli ambiti, quindi può leggere .context.*, e un riferimento a .boundary al suo interno si arresta indicando il riferimento e le radici che quel contesto definisce.
Il validatore esegue lo stesso attraversamento dell’AST dei template usato dall’allowlist delle variabili dei template di percorso, con un insieme di riferimenti diverso per ciascun ambito.
Deduplicazione e output della generazione delle risorse
Per executionScope: boundary, il compilatore deduplica la generazione delle risorse in base alla tupla (boundary_path, FR-instance). Due componenti nello stesso sottoalbero di confine che consumano entrambi la stessa funzionalità collegata al confine attivano un’unica invocazione della FR, non due. I collegamenti della stessa funzionalità su confini diversi vengono eseguiti in modo indipendente per ciascun confine.
Una FR con ambito di confine emette un insieme di file non intermedi per ogni tupla (boundary_path, FR-instance), e la loro posizione dipende da come il provider combina l’output del suo confine. Qui la coordinata è il solo nome dell’istanza, mentre un collegamento con ambito di componente porta anche il suo componente: una funzionalità con ambito di confine è collegata al confine e non a un componente, quindi la directory del confine che la racchiude dice già tutto ciò che direbbe un segmento di componente, e non c’è alcun componente da nominare.
Un provider che scrive ogni documento direttamente nella directory del confine dichiara che il suo target legge solo i file che si trovano direttamente in una directory. Non esiste quindi una directory racchiudente in cui collocare un collegamento, e il nome dell’istanza diventa invece un prefisso del nome del file: <boundary_directory>/<fr-provider>/<feature-instance>--<file>, accanto ai file propri del confine. Il nome dell’istanza è codificato, perché un nome di file non ha un separatore su cui ripiegare, e si unisce al nome proprio del file in corrispondenza di un delimitatore di due caratteri che nessuna coordinata codificata può contenere — quindi due collegamenti che emettono lo stesso nome di file producono comunque due file distinti.
Un provider che compone l’output del proprio confine in una struttura racchiudente — un chart che contiene un chart per ogni contributore, una configurazione radice che contiene un modulo per ogni contributore — colloca ogni contributore in una sottodirectory propria, e un collegamento al confine è un contributore come qualsiasi altro. Il suo output si trova quindi in <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/, dove <contributors-directory> è il nome che quel target dà al luogo in cui risiedono le sue unità figlie. La sottodirectory porta il nome dell’istanza del collegamento, cioè il nome con cui l’hai scritto nel blocco features: del confine, quindi la directory prodotta da una build è una che puoi ritrovare in ciò che hai scritto.
L’output intermedio confluisce nell’assemblatore per (percorso, provider) del confine, nel percorso valutato della FR e sotto la spec.capability propria della FR — è il meccanismo che la Feature core/compose-bridge usa per unire un servizio bridge ai contributori compose per componente nello stesso percorso di assemblaggio. Tale output viene scritto solo come parte del file assemblato in quel percorso a partire dai componenti del confine, quindi se nessuno di essi finisce in quel percorso — perché ogni componente è stato inviato altrove dal proprio subDirectory:, per esempio — la build si arresta indicando il confine, la Feature, il percorso verso cui il suo output è stato instradato e il provider, anziché scrivere l’output da nessuna parte (vedi «A boundary-level Feature’s output reaches no assembled file (L’output di una Feature a livello di confine non raggiunge alcun file assemblato)» in fatal-halts.md).
Risoluzione di provides: consapevole della cascata
Le FR con ambito di confine producono un insieme provides: per ogni tupla (boundary_path, FR-instance), valutato una sola volta. Il template provides: della FR viene valutato con il contesto dei template con ambito di confine (quindi può fare riferimento a .boundary.components, .boundary.path, .infra, ma non ai campi per consumatore né a .values). I valori dei provides sono costanti rispetto ai consumatori — ogni consumatore nel sottoalbero del confine vede gli stessi valori forniti.
La risoluzione lato consumatore dei provides di una FR con ambito di confine legge ovunque quell’unica valutazione. Ogni componente raggiunto dal collegamento la legge in .features.<instance-name>.provides.<key> — nei template della propria Recipe e nell’injectMapping proprio della FeatureRecipe, che viene eseguito nel contesto di quel componente. Un Component consumatore che legge tramite un arco uses portato dal collegamento, in .context.uses.<feature-alias>.provides.<provided-name>, ottiene gli stessi valori: il compilatore lo risolve nel provides: della FeatureRecipe con ambito di confine per il confine in cui si trova il consumatore, risalendo dall’arco uses del consumatore — che porta l’identità dell’istanza di funzionalità per collegamento — fino al provides: della FR con ambito di confine. Un pre-passaggio valuta quei provides prima dell’assemblaggio dei consumatori, quindi i valori sono presenti quando viene costruito il pipe del consumatore.
Un effetto per consumatore è una tabella in provides: letta da injectMapping. Una FeatureRecipe con ambito di confine che deve modificare qualcosa per ogni consumatore calcola una sola volta, nel suo provides:, una tabella indicizzata per consumatore a partire dalle connessioni del confine, e il suo injectMapping legge le righe del componente corrente — (index .features .attachment_name).provides, indicizzate per .context.instance_id — e le consegna tramite il pipe proprio del consumatore, secondo la regola che ogni mapping segue (vedi Che cosa può riscrivere un mapping). Il compilatore instrada la tabella scritta dalla FeatureRecipe e non legge nulla al suo interno.
Il pattern compose-bridge
La FeatureRecipe compose-bridge è il pattern canonico di FR con ambito boundary, ed è contenuto di catalogo scritto con i meccanismi descritti sopra: né il compilatore né il provider compose contengono alcuna logica del bridge, quindi un catalogo può realizzare la Feature core/compose-bridge in modo diverso. Una feature core/compose-bridge è collegata a un boundary padre che contiene due sotto-boundary (ad es. services-net e data-net) con directory: condivisa, ciascuno con la propria annotazione aggrega.ai/namespace (aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net) in modo che ciascuno finisca su una rete propria; senza le annotazioni, entrambi condividono l’unica rete che prende il nome dal percorso del loro file compose e si raggiungono a vicenda senza bridge. Il suo executionScope: boundary esegue la FR una volta per ogni collegamento al boundary padre.
Il suo provides: calcola la tabella del bridge, una sola volta. Da .boundary.internal_uses_edges conserva gli archi i cui due estremi sono assemblati nel suo stesso file compose — source_assembly_path e target_assembly_path entrambi uguali a .boundary.assembly_path — e si trovano su reti diverse di quel file, dove la rete di un estremo è la sua aggrega.ai/namespace, altrimenti il suo percorso di assemblaggio. Un arco tra due file compose non viene collegato tramite bridge, e il suo consumer mantiene il nome proprio del target. Ogni arco collegato tramite bridge riceve una porta di ascolto — la porta propria del target oppure, dove un arco precedente è già in ascolto su di essa, la prima porta libera uguale o superiore al portBase del collegamento (predefinito 10000) — e un upstream, l’host pubblicato del target (il campo provides che il providesField del collegamento nomina, predefinito host) e la sua port; l’upstream è derivato dall’arco, mai scritto a mano. Dalla stessa tabella calcola la riscrittura di ciascun consumer: una variabile che l’arco consegna dal campo host diventa aggrega-gw:<listen port>, oppure aggrega-gw dove lo stesso arco consegna anche una variabile da port, che diventa allora la porta di ascolto.
Il suo injectMapping consegna le righe di ciascun consumer. Eseguito nel contesto di ciascun consumer, legge le righe della tabella relative a quel consumer in .features.<attachment>.provides e le consegna al di sopra dei valori consegnati dalla connessione propria del consumer (ad es. DB_HOST), il che costituisce un’intercettazione; un consumer senza alcuna riga non riceve nulla. Dove un’altra Feature collegata al consumer ha consegnato quella chiave — tramite il suo blocco inject: o il suo injectMapping — la build si arresta nominando entrambe le Features anziché sostituire quella consegna (vedi «Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Due Features collegate consegnano una stessa chiave, la seconda tramite l’injectMapping della sua FeatureRecipe)» in fatal-halts.md). Il listen del gateway e la riscrittura del consumer sono letti da un’unica tabella, quindi concordano per ciascun arco per costruzione, comprese le collisioni riassegnate tramite portBase.
Il suo valuesMapping scrive il gateway. Il frammento compose proprio della FeatureRecipe dichiara il servizio aggrega-gw. Dove qualcosa è collegato tramite bridge, il suo valuesMapping aggiunge un blocco nginx stream server per ogni arco collegato tramite bridge (listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;, sotto una direttiva resolver in modo che ciascun upstream venga risolto al momento della connessione anziché una sola volta all’avvio; il $ in quelle variabili è scritto $$ affinché l’interpolazione $ di Docker Compose lasci un $ letterale per nginx), consegnato come configurazione compose montata — una voce configs: di primo livello con content: inline, referenziata da aggrega-gw e montata in /etc/nginx/nginx.conf (così nginx la carica senza un command: scritto dall’autore). configs.content inline richiede Docker Compose ≥ 2.23.1. Nomina inoltre ogni endpoint collegato tramite bridge sotto il x-aggrega-networks-of del gateway, che il provider compose risolve nelle reti su cui quegli endpoint sono collocati, così il gateway si unisce a ogni rete attraversata dai suoi archi collegati tramite bridge (la rete del consumer e quella del target) — a runtime il consumer può raggiungere aggrega-gw:<port> e il gateway può fare proxy_pass verso il target. Dove nulla è collegato tramite bridge, il gateway dichiarato dal frammento viene comunque renderizzato, inattivo: nessuna configurazione, nessuna rete aggiuntiva e nessuna riscrittura.
L’assemblatore compose per (percorso, provider) unisce il gateway ai contributori per componente nello stesso percorso valutato: un unico docker-compose.yaml contenente ogni componente più il gateway del bridge. Dove nessuno dei componenti del boundary è assemblato nel file del gateway, la build si arresta anziché scrivere il gateway da nessuna parte. L’upstream è un puntatore deterministico, fissato in fase di compilazione, a un servizio compose; il DNS di runtime di compose lo risolve (nessuna risoluzione di runtime in fase di compilazione).
Rendering dopo i chiamanti — spec.readsCallerRenderFacts
Il campo opzionale spec.readsCallerRenderFacts (booleano, predefinito false) dichiara che i template di questa FeatureRecipe leggono ciò che hanno renderizzato i componenti che si connettono al suo host: i fatti di render che il provider di ciascuno di quei chiamanti riporta sull’output che ha emesso. Che cosa un provider riporta, e con quali nomi, è il contratto proprio di quel provider; Riportare fatti su ciò che un guest ha emesso descrive i fatti che un provider può riportare.
Quando un tale collegamento viene renderizzato. La build renderizza i suoi componenti uno alla volta, in un ordine fisso, e un collegamento normalmente viene renderizzato subito dopo il componente a cui è collegato. Un componente che si connette all’host e viene dopo in quell’ordine non è ancora stato renderizzato a quel punto, quindi non esiste nulla di ciò che ha emesso da leggere. Un collegamento la cui FeatureRecipe imposta readsCallerRenderFacts: true viene invece renderizzato una volta che ogni componente della build è stato renderizzato, insieme a ogni collegamento che non imposta né questa chiave né readsTargetRenderFacts — così il render di ciascun chiamante è completo prima che il collegamento venga valutato. Il suo output finisce dove sarebbe finito e con gli stessi nomi; la chiave cambia quando il collegamento viene renderizzato, non che cosa renderizza. Dal render successivo discende un ordinamento: dove la FeatureRecipe porta una pipeline che riscrive i documenti del suo componente host e il provider dell’host scrive documenti distinti, quei passi vengono eseguiti dopo le pipeline degli altri collegamenti dell’host anziché nel loro ordine di collegamento.
Che cosa legge. Con la chiave impostata, ogni voce di .context.used_by porta .render_facts: i fatti di render del chiamante, indicizzati per nome del fatto. Ogni fatto di render è una lista, quindi un template la scorre sempre con range — anche quando contiene una sola voce. Le sue voci possono provenire dal render proprio del chiamante e dai render delle Features collegate al chiamante: le liste che un nome riceve da ciascuno vengono unite in una sola, prima le chiamate del provider proprio del chiamante, poi ciascuna delle sue Features nell’ordine in cui sono state renderizzate. Una Feature del chiamante che imposta a sua volta la chiave viene renderizzata anch’essa dopo ogni componente, quindi ciò che ha riportato non è tra queste. Un chiamante i cui provider non riportano nulla porta un .render_facts vuoto, quindi un nome che nessuno ha riportato si legge come nulla:
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}Quali nomi di fatto esistono, e che cosa contiene ciascuna voce, è il contratto documentato del provider del chiamante — quelli del provider helm, per esempio, sono i suoi fatti di render, che nominano le label dei pod che ha renderizzato. I fatti dei chiamanti si trovano sulle connessioni che leggono valuesMapping:, workload: e artifacts: della FeatureRecipe; with: e when: di un passo pipeline: non vedono affatto i componenti che si connettono all’host, quindi un passo legge solo i fatti propri dell’host. Ogni FeatureRecipe collegata a un componente — che imposti o meno la chiave — legge i fatti propri del componente in .context.render_facts, nella stessa forma; il contesto dei template descrive entrambi.
Dichiarala ogni volta che un template legge i fatti. Un template scritto inline in una FeatureRecipe che non imposta la chiave — il suo valuesMapping:, il suo workload: o una voce di artifacts: — e che legge render_facts sotto .context.used_by arresta la build prima che venga renderizzato qualsiasi cosa, nominando il riferimento e il campo in cui è stato scritto (vedi «A template reads its callers’ render facts without declaring it (Un template legge i fatti di render dei suoi chiamanti senza dichiararlo)» in fatal-halts.md). Il controllo legge il template così come è scritto, quindi non vede un riferimento costruito durante l’esecuzione del template, né uno scritto in contenuto importato da un file o da una libreria — e un template che legge un campo chiamato render_facts da qualche altra lista accanto a .context.used_by, o che legge i fatti propri dell’host come .render_facts dentro {{ with .context }} accanto a esso, viene trattato come se leggesse i fatti dei chiamanti; scrivi quelli propri dell’host per esteso come .context.render_facts. È la chiave, non il controllo, a decidere quando il collegamento viene renderizzato, quindi impostala su ogni FeatureRecipe i cui template leggono i fatti di render dei loro chiamanti, in qualunque modo vi arrivino; impostarla non costa nulla se non il render successivo.
Un passo di pipeline legge solo i fatti propri del suo host. Un passo può riscrivere i documenti propri del componente host, e l’output proprio di un componente resta lo stesso chiunque vi si connetta, quindi with: e when: di un passo non vedono mai i componenti che si connettono all’host — che la FeatureRecipe imposti o meno la chiave, la quale decide quando il collegamento viene renderizzato e nulla di ciò che un passo vede. Un with: o when: di un passo scritto inline che legge render_facts sotto .context.used_by arresta quindi la build prima che venga renderizzato qualsiasi cosa, con il codice breve E0326, nominando il riferimento e il campo del passo — anziché renderizzare un valore vuoto. Leggi i fatti propri dell’host in un passo in .context.render_facts, scritto per esteso, e leggi i fatti dei chiamanti in valuesMapping:, workload: o artifacts: della FeatureRecipe. Questo controllo legge il template così come è scritto, con gli stessi limiti di quello sopra.
Ambito. La chiave si applica a una FeatureRecipe che viene renderizzata una volta per componente — executionScope: component, il valore predefinito. Una FeatureRecipe che dichiara executionScope: boundary viene renderizzata dove lo è sempre, che imposti o meno la chiave, e i template che producono le sue risorse leggono .boundary anziché .context.
Rendering dopo i target — spec.readsTargetRenderFacts
Il campo opzionale spec.readsTargetRenderFacts (booleano, predefinito false) dichiara che i template di questa FeatureRecipe leggono ciò che hanno renderizzato i componenti a cui il suo host è collegato: i fatti di render che il provider di ciascuno di quei target riporta sull’output che ha emesso. Legge l’altra estremità di una connessione rispetto a readsCallerRenderFacts — i componenti a cui puntano le voci uses dell’host, anziché i componenti le cui voci uses puntano all’host — e tutto ciò che riguarda i fatti stessi si legge allo stesso modo.
Ciascuna delle due chiavi fa renderizzare il collegamento dopo ogni componente. Un collegamento la cui FeatureRecipe imposta readsCallerRenderFacts: true, readsTargetRenderFacts: true o entrambe viene renderizzato una volta che ogni componente della build è stato renderizzato, come descrive la sezione precedente — esiste un solo render successivo di questo tipo, e ciò che comporta per la posizione in cui finisce l’output del collegamento e per l’ordine dei suoi passi di pipeline è lo stesso qualunque chiave abbia spostato lì il collegamento. Le due chiavi differiscono solo per quali connessioni portano fatti nel contesto del collegamento: un target che viene dopo l’host nell’ordine della build è stato renderizzato a quel punto, quindi ciò che ha emesso è lì da leggere.
Che cosa legge. Con la chiave impostata, ogni voce di .context.uses porta .render_facts: i fatti di render del target, indicizzati per nome del fatto, nella forma che porta la voce di un chiamante. Ogni fatto di render è una lista, quindi un template la scorre sempre con range. Le sue voci possono provenire dal render proprio del target e dai render delle Features collegate al target, prima le chiamate del provider proprio del target, poi ciascuna delle sue Features nell’ordine in cui sono state renderizzate; una Feature del target che viene a sua volta renderizzata dopo ogni componente non è tra queste. Un target i cui provider non riportano nulla porta un .render_facts vuoto. Un template legge i fatti di una connessione sotto il suo alias, .context.uses.<alias>.render_facts.<name>, oppure quelli di ciascuna connessione a turno:
artifacts: targets.yaml: | targets: {{- range .context.uses }} - component: {{ .target }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}Una FeatureRecipe che non imposta la chiave non vede alcun .render_facts su nessuna connessione, qualunque altra cosa imposti. Quali nomi di fatto esistono è il contratto documentato del provider di ciascun target — quelli del provider helm sono i suoi fatti di render, che nominano le label, i selettori dei controller e le porte dei container dei pod che ha renderizzato, e quindi ciò di cui una policy di egress ha bisogno per selezionare esattamente i pod che il suo host può raggiungere.
Dichiarala ogni volta che un template legge i fatti. Un template scritto inline in una FeatureRecipe che non imposta la chiave — il suo valuesMapping:, il suo workload: o una voce di artifacts: — e che legge render_facts sotto .context.uses arresta la build prima che venga renderizzato qualsiasi cosa, con il codice breve E0347, nominando il riferimento e il campo in cui è stato scritto (vedi «A template reads its targets’ render facts without declaring it (Un template legge i fatti di render dei suoi target senza dichiararlo)» in fatal-halts.md). Impostare readsCallerRenderFacts non lo evita. Il controllo legge il template così come è scritto, con i limiti del controllo sui chiamanti: non vede un riferimento costruito durante l’esecuzione del template, né uno scritto in contenuto importato da un file o da una libreria — e un template che legge .context.uses in qualunque modo e legge anche un campo chiamato render_facts da qualche altro valore, compresa la voce di un chiamante dentro {{ range .context.used_by }}, viene trattato come se leggesse i fatti dei suoi target. Un template che legge i fatti di entrambe le estremità imposta entrambe le chiavi.
Un passo di pipeline legge solo i fatti propri del suo host. with: e when: di un passo leggono le connessioni che l’host stabilisce, come le legge la Recipe propria dell’host, e mai i fatti di render dei loro target — che la FeatureRecipe imposti o meno la chiave. Un passo può riscrivere i documenti propri del componente host, e il render proprio dell’host legge ciò che i suoi target pubblicano, mai ciò che hanno emesso. Un with: o when: di un passo scritto inline che legge render_facts sotto .context.uses arresta quindi la build prima che venga renderizzato qualsiasi cosa, con il codice breve E0348, nominando il riferimento e il campo del passo — anziché renderizzare un valore vuoto. Leggi i fatti dei target in valuesMapping:, workload: o artifacts: della FeatureRecipe.
Ambito. Come per la chiave dei chiamanti: si applica a una FeatureRecipe che viene renderizzata una volta per componente. Una FeatureRecipe che dichiara executionScope: boundary viene renderizzata dove lo è sempre, che imposti o meno la chiave, e le connessioni che legge sotto .boundary non portano fatti di render.
Il blocco locals:
FeatureRecipe.spec.locals: è una mappa opzionale di stringhe di template Go con nome il cui output renderizzato espone una mappa .locals.* a ogni altro template all’interno della stessa FeatureRecipe. È l’equivalente, privato della FeatureRecipe, di locals: della Recipe — un punto in cui calcolare una sola volta stringhe derivate e farvi riferimento da injectMapping, valuesMapping, pipeline[].with e provides senza ricalcolarle. Le assertions: della FeatureRecipe non le leggono: i .locals di un’asserzione sono quelli della Recipe del componente host, come indica assertions-block.md. L’output renderizzato di ciascuna voce viene memorizzato senza gli spazi bianchi iniziali e finali. Il blocco è una mappa, non un singolo corpo di template; uno scalare in questa posizione viene rifiutato dallo schema.
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: regional-routerspec: implements: core/regional-router:^1.0.0 capability: helm locals: region_prefix: "{{ .infra.region | lower }}" fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}" injectMapping: | env: "{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}".locals.* è per invocazione: ogni invocazione di una FR risolve il proprio blocco locals:, e il risultato è visibile solo ai template a valle di quell’invocazione. Il blocco si risolve prima che vengano valutati gli altri template della superficie di authoring della FR, quindi ognuno di essi vede valori risolti.
Ogni voce viene valutata rispetto a un contesto autonomo: .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra e le voci di questo stesso blocco già risolte. È deliberatamente più ristretto del contesto che leggono gli altri template della FR — una voce di locals: non può raggiungere .context.annotations, .context.inject, .context.uses o .provides, e un riferimento a uno qualsiasi di essi interrompe la build indicando il riferimento. I valori derivati che richiedono quei pilastri vanno nel template che li legge, non in locals:.
I nomi in quel contesto rispondono a domande diverse, e una voce di locals: li legge esattamente come fanno gli altri template della FeatureRecipe:
.context.instance_idè il componente host per cui si sta risolvendo il collegamento. Indica il componente host su ogni superficie di template che il compilatore valuta, quindi lo stesso riferimento si legge allo stesso modo qualunque sia l’entità di cui stai scrivendo il blocco..context.rendered_nameè il nome del componente host così come lo riporta il suo provider — conhelm, il nome della release, ovvero l’identità dell’host scritta nell’alfabeto ammesso da un nome Kubernetes. È presente solo dove il provider dell’host riporta un nome, e leggerlo su un host il cui provider non ne riporta alcuno interrompe la build..attachment_nameè l’istanza di collegamento che si sta risolvendo — lo slot che occupa nelfeaturesSchemadell’entità proprietaria, o il nome libero che le hai dato.
Così una voce di locals: che deriva un nome per una risorsa emessa compone l’host e il collegamento, esattamente come farebbe un template di artifacts::
spec: locals: scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_targetDove il nome deve essere uno che la piattaforma accetta e il provider dell’host ne riporta uno, componilo invece a partire da .context.rendered_name: per un host chiamato my_api con helm e un collegamento scrape, {{ .context.rendered_name }}-{{ .attachment_name }} produce my-zuapi-scrape, mentre l’identità produrrebbe my_api-scrape, che un nome Kubernetes rifiuta. Vedi Assegnare un nome a una risorsa renderizzata.
.values e .infra in una voce di locals: sono i pilastri propri del collegamento, scritti nella dichiarazione del collegamento — non quelli del componente host.
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: region_prefix: "{{ .infra.region | lower }}" # defined first bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry aboveIl concatenamento procede solo verso il basso. Dove una voce ne legge un’altra, l’ordine delle voci decide se la build riesce: sposta region_prefix sotto bucket e la build si interrompe. Il compilatore non riordina mai il blocco per far risolvere un riferimento, quindi riordinare un blocco locals: è una modifica comportamentale, non estetica.
Un riferimento a una voce che il blocco definisce più avanti interrompe la build indicando l’errore di ordinamento (sposta la definizione sopra chi la legge); un riferimento a una chiave che il blocco non dichiara affatto la interrompe indicando la chiave (correggi l’ortografia). Il controllo segue un alias del blocco: una chiave raggiunta tramite il punto che un corpo with .locals ricollega, o tramite una variabile legata a .locals, interrompe la build esattamente negli stessi termini della scrittura diretta, e lo stesso fa una chiave letta dal blocco tra parentesi — {{ (.locals).nope }} o {{ ($.locals).nope }}. Una sola scrittura lo elude: una chiave raggiunta tramite una chiamata il cui risultato il testo del template non può nominare — {{ index .locals "nope" }}, oppure {{ (default dict .locals).nope }}. Un campo letto dal risultato di una tale chiamata non interrompe la build e produce il testo letterale <no value>; la lettura con index la interrompe indicando la chiave, perché index interrompe la build su ogni superficie di template quando la mappa che legge non contiene la chiave — vedi errors/fatal-halts.md «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)». provides: legge il blocco completamente risolto, perché i locals di questa FeatureRecipe si risolvono prima dei suoi provides; un template di provides: che nomina una chiave non dichiarata interrompe la build. Sono le stesse regole che segue il blocco locals: di una Recipe — vedi entities/recipe.md «Il blocco locals:».
Comportamento in base all’ambito. Per executionScope: component (predefinito), locals: viene valutato per ogni istanza di componente collegata rispetto al contesto autonomo descritto sopra. Per executionScope: boundary, locals: viene valutato per ogni collegamento di confine rispetto alla vista con ambito di confine radicata in .boundary.*; i campi per componente (.context.instance_id, .context.inject, .context.uses) e .attachment_name non sono disponibili, perché la FeatureRecipe viene eseguita una volta per il confine anziché una volta per componente. L’allowlist dei campi di template con ambito di confine si applica a locals: nello stesso modo in cui si applica agli altri template della superficie di authoring della FR. L’injectMapping, che viene eseguito per ogni componente raggiunto dal collegamento, legge quell’unica valutazione di confine come proprio .locals. Il contratto di valutazione — ordine di scrittura, letture delle voci sorelle solo verso il basso, le due interruzioni — è identico in entrambi gli ambiti; cambia solo la forma del contesto circostante.
Differenza rispetto agli overlay di injectMapping e alle mappature di pipeline[].with. locals: produce una mappa visibile nel contesto per i template a valle; non contribuisce all’output. injectMapping scrive nella pipe .context.inject del consumatore (mutazione lato chiamante). pipeline[].with fornisce il payload args del plugin Wasm. Le tre superfici sono ortogonali — una FeatureRecipe usa abitualmente tutte e tre insieme, con locals: che porta le stringhe derivate condivise a cui fanno riferimento le altre due.
Il blocco assertions:
FeatureRecipe.spec.assertions: è una mappa opzionale di regole con nome che esprimono invarianti di implementazione della FeatureRecipe — regole tra campi che valgono data la specifica pipeline di plugin Wasm, il chart o il meccanismo su cui la FeatureRecipe è costruita. Ogni chiave è un identificatore di regola che compare nel messaggio di errore; ogni valore è un corpo di template Go. Come le asserzioni della Recipe, le asserzioni della FeatureRecipe sono proprietà dell’implementazione specifica; le regole di contratto a livello di Feature si applicano indipendentemente in una fase precedente della pipeline.
spec: implements: core/referenced-secret:^1.0.0 pipeline: - id: fetch_secret plugin: pipeline-step/aws-secrets-manager:1.2.0 function: step assertions: # aws-secrets-manager plugin 1.x requires an explicit region when none is # implied through the Aggregate's infra block. region-supplied-for-secrets-manager: | {{- if not .values.region -}} {{- if not .infra.aws.region -}} {{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}} {{- end -}} {{- end -}}La regola sopra è specifica del plugin aws-secrets-manager 1.x; non si applica se viene associata una FeatureRecipe core/referenced-secret diversa. Le regole di contratto a livello di Feature dalla definizione della Feature continuano ad applicarsi in parallelo.
Le asserzioni della FeatureRecipe vengono valutate dopo il binding della FeatureRecipe e prima della generazione delle risorse. Il contesto di template per le FR con ambito di componente rispecchia il contesto delle asserzioni della Recipe (campi dell’istanza dell’entità più .provides, .locals, .recipe.metadata, .recipe.source); per le FR con ambito di confine (executionScope: boundary), le asserzioni vengono valutate rispetto alla vista con ambito di confine (campi .boundary.* disponibili; campi per componente no). Per la grammatica di authoring completa ed esempi svolti, vedi templates/assertions-block.md.
Il campo omits: — escludere documenti renderizzati da una sorgente
La maggior parte delle FeatureRecipes non ne ha mai bisogno. Serve a una FeatureRecipe il cui source: è un chart che prendi così com’è — molto spesso uno recuperato da un registry — che renderizza un documento che il collegamento non deve emettere: un Secret che il chart genera da capo a ogni rendering, o un oggetto che il componente host o l’operatore fornisce già. omits: esclude un documento di questo tipo da ciò che la FeatureRecipe genera — oppure, per un file compose che la FeatureRecipe usa come sorgente, un servizio, un volume o una config che il collegamento non deve contribuire, e per un template CloudFormation che usa come sorgente, una risorsa.
spec: capability: helm implements: core/observability/collector:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/collector version: "0.9.1" omits: # The collector chart ships its own ServiceAccount; the host supplies one. - kind: ServiceAccount name: collector - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: collector-dashboardsLa chiave si scrive in modo identico su una Recipe, e Recipe → Il campo omits: ne è il riferimento completo: cosa seleziona ogni campo di una voce, che when: viene valutato per primo e uno falso scarta la voce, che ogni voce che si applica deve escludere qualcosa altrimenti la build si interrompe indicandola, che la sorgente viene comunque renderizzata per intero e solo il suo output viene filtrato, e quali provider rispettano la chiave. Su una FeatureRecipe cambia soltanto dove vengono valutati i template:
- I template di ogni voce vengono valutati rispetto al contesto in cui viene valutato il
valuesMapping:di questa FeatureRecipe, all’ambito selezionato dal suoexecutionScope. Le voci di una FeatureRecipe con ambito di componente vengono valutate una volta per collegamento, rispetto a.valuese.infradi quel collegamento; quelle di una con ambito di confine una volta per confine, rispetto alla vista con ambito di confine e a.infradel collegamento di confine. Le regole su ciò che i template di un collegamento possono leggere si applicano alle voci come al suovaluesMapping:. - Viene filtrato solo ciò che renderizza il
source:di questa FeatureRecipe. Il suoworkload:e i suoiartifacts:no, e nemmeno l’output del componente host: le voci di un collegamento raggiungono il suo chart, il suo file compose o il suo template CloudFormation, e nient’altro — un servizio compose che l’host dichiara con la stessa chiave neldocker-compose.yamlin cui entrambi confluiscono non viene toccato, così come una risorsa che l’host dichiara con lo stesso ID logico nello stack in cui entrambi confluiscono. Per modificare un documento che l’host renderizza, la Recipe dell’host dichiara la voce, oppure uno steppipeline:lo modifica tramite patch.
Un’interruzione su una voce indica il nodo, il provider, questa FeatureRecipe e la posizione della voce nella sua lista omits:; per una FeatureRecipe con ambito di confine, la riga sopra il messaggio indica il collegamento e il suo confine.
Per un esempio svolto della chiave, scritta su una Recipe — il Secret generato di un chart recuperato escluso, e le interruzioni senza la voce e con una voce che non corrisponde a nulla — vedi ai-gateway-own-webhook-certificate.