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

Modello delle credenziali

Un’unica famiglia di attachment

In Aggrega una credenziale è una Feature. Si collega sulla stessa superficie, con la stessa parola chiave e nella stessa forma di qualsiasi altra Feature. Qui lo sviluppatore collega la credenziale del database nell’Aggregate, scrivendone il localizzatore in values:

# the Aggregate — its parameters and the components' own values left out
spec:
components:
api:
type: core/compute/server
db:
type: core/datastore/mariadb
features:
root_password: # a credential Feature
type: core/secret-value:1.0.0
values:
key: MARIADB_ROOT_PASSWORD
origin: "{{ .parameters.db_root_pass }}"

e l’operatore collega al server un target di scraping delle metriche nella Release, perché ogni input che core/prometheus-exporter accetta — la porta, il percorso e l’intervallo dello scraping — è operativo, quindi si scrive in infra:

# the Release — the api's own infra and the db's entry left out
spec:
components:
api:
features:
metrics: # an operational Feature
type: core/prometheus-exporter:1.0.0
infra:
port: http # the named port of the api's Service

Esiste una sola parola chiave di attachment (features:), una sola forma del contesto di rendering (.features.<name>, e la stessa forma sotto una connessione, .context.uses.<alias>.features.<slot>, per un attachment scritto su una connessione), un solo ordine di esecuzione e un solo insieme di coordinate di output — per un attachment su un componente, il componente a cui è collegato e poi il nome con cui è collegato, che il layout del target riporti queste due informazioni come directory <component>--<instance>/ accanto a quella del componente o come prefisso del nome file <component>--<instance>--. Ciò che varia tra gli attachment è ciò che producono — un valore iniettato, una risorsa referenziabile, un sidecar, un’identità cloud — non la superficie su cui sono dichiarati.

Una Feature di credenziale porta l’etichetta feature.aggrega.ai/kind: secret sulla propria entità di catalogo. Quell’etichetta è metadato descrittivo: dice a un lettore, a un sito di catalogo e a un selettore di etichette a cosa serve la Feature. Nessun ramo del compilatore la legge e nessun comportamento dipende da essa. Il comportamento deriva dalla FeatureRecipe a cui un operatore associa il tipo di Feature.

Il modello mentale in una frase: esiste un solo tipo di attachment; ciò che varia è ciò che produce.

Slot e attachment liberi

Un Component o una Feature può dichiarare slot in featuresSchema:

spec:
featuresSchema:
root_password:
required: true
inject: [] # blackbox — the Recipe delivers it
selector: "feature.aggrega.ai/kind=secret"
user_password:
inject: [env, file] # transparent — the developer may dictate delivery

Un attachment il cui nome di istanza corrisponde a uno slot dichiarato riempie quello slot. Un attachment con qualsiasi altro nome è un attachment libero: l’entità non l’ha richiesto, e viene renderizzato insieme a tutto ciò che l’entità ha richiesto. Lo schema generato per uno slot dichiarato resta aperto, quindi dichiarare uno slot non chiude mai il blocco agli attachment liberi. Una sola forma arresta la build invece di essere renderizzata: un attachment scritto sul componente stesso la cui Feature soddisfa il selector di uno slot che nulla vincola lì, che è un riempimento scritto con il nome sbagliato anziché un attachment libero.

Due cose che uno slot può vincolare:

  • inject — i meccanismi di consegna che un Workload può selezionare per ciò che riempie lo slot. Una lista vuota indica uno slot blackbox: lo consegna l’infrastruttura interna della Recipe stessa (ad esempio l’opzione existingSecret di un chart), e un Workload non può farvi riferimento da un container.
  • selector — una stringa di selettore di etichette che le etichette della Feature che riempie lo slot devono soddisfare. È qui che l’etichetta kind=secret si rende utile: l’autore di un’entità che vuole uno slot riempito solo da una credenziale lo dice con un selettore, e il controllo è una valutazione su un insieme di etichette che il compilatore esegue durante l’analisi statica.

Una terza cosa che uno slot può fare è richiedere di risultare vincolato. required: true rende obbligatorio il nome dello slot: il compilatore si arresta durante l’analisi statica quando nulla lo vincola, con una diagnostica che nomina lo slot e il tipo di componente che lo ha dichiarato. La richiesta si valuta sull’insieme di attachment che il componente ottiene dopo la cascata di tutti gli scope, quindi un attachment fornito sopra il componente vincola lo slot esattamente come un riempimento scritto sul componente.

Una seconda superficie esprime una richiesta diversa. L’annotazione ripetibile del Component features.aggrega.ai/requiredType.<label> dichiara un obbligo di presenza: almeno un attachment deve portare il tipo di Feature che l’annotazione nomina, con qualsiasi nome e a qualsiasi scope, e un obbligo che nulla soddisfa arresta la build durante la stessa analisi statica con una propria diagnostica. Le due non rispondono mai l’una per l’altra — uno slot chiede se un punto di vincolo con nome è vincolato, un obbligo se qualche attachment porta un tipo con nome — quindi un’entità che ha bisogno che la propria Recipe legga ciò che è stato collegato dichiara uno slot, mentre una il cui contratto richiede semplicemente la presenza di una capacità dichiara un obbligo.

Cosa il compilatore garantisce e cosa no

Questa è la sezione portante. Aggrega è un compilatore ahead-of-time, e le sue garanzie sono più ristrette di quanto la parola «secret» induca un lettore a supporre.

Il compilatore non risolve mai una credenziale. Non si autentica presso un’API cloud, non legge un vault e non recupera materiale durante aggrega build. I values e l’infra di un attachment di credenziale attraversano il grafo ed entrano nel contesto di rendering come scalari opachi, e una FeatureRecipe li renderizza in qualunque artefatto si aspetti la piattaforma di destinazione. La risoluzione avviene dopo, nel cluster o nel gestore di stato IaC, rispetto a ciò a cui punta l’artefatto renderizzato.

Il compilatore non sa distinguere un puntatore da un valore materiale. È agnostico rispetto al significato di uno scalare (vedi 05-invariants.md). Un attachment di credenziale il cui localizzatore porta una coordinata di store (path, key, un ARN) renderizza un riferimento a quella coordinata; un attachment di credenziale il cui localizzatore porta il materiale stesso renderizza il materiale, alla lettera, nel file di output. Entrambi sono legittimi, e il compilatore li tratta in modo identico perché non ha modo di distinguerli.

Quindi l’enunciato onesto della garanzia è:

Aggrega garantisce che il compilatore non esegue alcuna risoluzione. Non garantisce che l’output renderizzato non contenga materiale — ciò dipende interamente da quale Feature di credenziale è collegata e da cosa vi ha messo il suo autore, lo sviluppatore in values o l’operatore in infra.

Due conseguenze da interiorizzare:

  • Un albero di artefatti renderizzato è sensibile quanto il suo attachment che porta più materiale. Tratta dist/ di conseguenza: se un qualsiasi attachment porta materiale inline, l’albero contiene materiale.
  • Le famiglie core/secret-value e core/referenced-secret del catalogo stesso includono forme che accettano direttamente un valore. Esistono perché i deployment reali hanno bisogno di un percorso per lo sviluppo locale, e lo dichiarano apertamente: gli esempi distribuiti usano segnaposto evidenti (dev-root-pw-change-me) proprio perché il materiale in un esempio renderizzato non sia visibilmente una credenziale reale. Per un deployment che non deve portare materiale, collega una Feature di credenziale basata su uno store la cui FeatureRecipe emette una risorsa di recupero (un ExternalSecret, una risorsa personalizzata di recupero da vault, un riferimento a un secret nativo del provider) anziché una che emette dati.

La convenzione della libreria standard è che una credenziale si richiede come attachment anziché scriverla in un blocco values, in modo che sostituire un riempimento per lo sviluppo locale con uno basato su uno store sia una modifica al Manifest anziché una modifica all’intento dello sviluppatore. È una convenzione che il catalogo segue, non una regola che il compilatore impone.

Sensibilità dichiarata

Il compilatore non sa distinguere un puntatore da un valore materiale, come dice la sezione precedente — ma un autore sì, e può dichiararlo. In Aggrega la sensibilità è un’annotazione su una dichiarazione: l’autore di un’entità di catalogo afferma cosa porta materiale segreto, e il compilatore deriva il resto da quell’affermazione più il cablaggio che ha già costruito. Nulla viene dedotto da un valore e nulla viene indovinato dal nome di un campo.

Si scrive esattamente in due punti, che esprimono affermazioni realmente diverse.

Su una foglia di schema — questo dato è materiale segreto. Una foglia di values, infra o provides dichiara sensitive: true:

spec:
schema:
values:
origin:
type: string
required: true
sensitive: true # the material
key:
type: string
default: value # a data key — a locator, not material

Su uno slot di attachment — qualunque cosa vincoli questo punto gestisce materiale segreto. Uno slot di featuresSchema dichiara sensitive: true:

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

I due livelli non sono un duplicato di comodo l’uno dell’altro, e la forma della credenziale referenziabile è il caso concreto che mostra perché. Una credenziale referenziabile pubblica provides.name e provides.key — il localizzatore della risorsa e la chiave dei dati al suo interno — e nessuno dei due è sensibile: il nome di un Secret Kubernetes è pubblico, e lo è anche la chiave al suo interno. Entrambi sono renderizzati in chiaro nel manifest del consumatore come secretKeyRef. Eppure lo slot che quella credenziale riempie gestisce indubbiamente materiale segreto. Un solo livello non può esprimere entrambi i fatti: marcare i localizzatori pubblicati per far risultare sensibile lo slot affermerebbe qualcosa di falso su di essi e porterebbe quell’errore ovunque la dichiarazione venga letta.

Da queste due dichiarazioni il compilatore deriva, per ogni attachment, se l’attachment gestisce materiale dichiarato sensibile — vero quando la Feature collegata dichiara una foglia sensibile, o quando lo slot che vincola ne dichiara una, bastando l’una o l’altra da sola. Lo deriva dall’attachment così com’è dopo che tutti gli scope di authoring sono stati ripiegati, quindi una dichiarazione di scope più ampio che un riempimento più ristretto ha sostituito non persiste, e la richiesta di uno slot si applica al riempimento che ha effettivamente prevalso. Una Feature di credenziale che non dichiara alcuna foglia sensibile — perché il motore di destinazione possiede il materiale e l’autore non scrive nulla — produce comunque un attachment sensibile quando vincola uno slot sensibile.

Il limite, detto chiaramente

La parola «sensibile» induce un lettore ad aspettarsi un meccanismo di riservatezza. Non lo è, e la garanzia è più ristretta di quanto il nome suggerisca in cinque modi specifici:

  • Non cifra. Nulla viene incapsulato, sigillato o trasformato.
  • Non cambia il verdetto della build, con un’eccezione. Nessuna build si arresta perché manca una dichiarazione, e un catalogo le cui entità di credenziale non portano alcuna dichiarazione viene compilato con successo. Nessun valore è accettato o rifiutato perché esiste una dichiarazione, tranne dove il valuesMapping di una Recipe o di una FeatureRecipe CloudFormation legge un valore dichiarato sensibile per riempire i parametri di un template sorgente: lì ogni letterale che la mappatura vincola viene rifiutato, quindi aggiungere una dichiarazione può trasformare una build riuscita in una che si arresta — vedi A secret bound to a CloudFormation parameter would be written into the template (Un secret vincolato a un parametro CloudFormation verrebbe scritto nel template). Ovunque altrove, aggiungere dichiarazioni a un catalogo esistente lascia riuscire ogni build che riusciva.
  • Non garantisce che l’output renderizzato sia privo di materiale. La garanzia enunciata sopra resta invariata: se un artefatto porta materiale dipende da quale riempimento è stato collegato e da cosa vi ha messo il suo autore. Un valore dichiarato sensibile fornito inline viene renderizzato esattamente come uno non dichiarato ovunque la build lo renderizzi — il rifiuto CloudFormation descritto sopra blocca un letterale anziché renderizzarlo, e una funzione intrinseca viene scritta così come è data, testo incluso — e dist/ resta sensibile quanto il suo attachment che porta più materiale.
  • Non impone un meccanismo di consegna. Una dichiarazione non può convertire un valore inline in un riferimento a uno store, e non restringe ciò che l’allowlist inject di uno slot consente. Imporre la consegna significherebbe emettere una risorsa che l’autore non ha mai dichiarato, che è esattamente ciò che l’invariante di assenza di infrastruttura fantasma vieta — vedi 05-invariants.md.
  • Non cambia alcun byte renderizzato sulla maggior parte dei target, e su quelli non lo farà mai. Due percorsi di rendering distribuiti agiscono sulla dichiarazione in ciò che producono (anche i provider Helm, Helm-Chart e Compose la leggono, solo per tenere un valore marcato fuori dal testo di un errore): il provider Terraform marca l’input di un modulo vendorizzato che porta materiale dichiarato sensibile con l’attributo di sensibilità proprio di Terraform — vedi language-reference/providers/terraform.md «Input di modulo dichiarati sensibili»; dove il valuesMapping di una Recipe, o quello della FeatureRecipe di una Feature collegata a un componente, inventa i nomi degli input, nessun input può portare l’attributo e la build stampa un avviso che lo segnala, vedi A declared-sensitive value reaches the target through a values mapping (Un valore dichiarato sensibile raggiunge il target tramite una mappatura dei valori) — e il provider CloudFormation rifiuta i vincoli letterali descritti sopra, il che arresta una build anziché cambiarne i byte. Ovunque altrove, aggiungere dichiarazioni in un catalogo esistente lascia identico ogni artefatto renderizzato. Il limite oltre questo è strutturale e non dipende da ciò che è stato costruito: una dichiarazione può raggiungere un artefatto renderizzato solo su una piattaforma di destinazione il cui linguaggio abbia una nozione di sensibilità — una dichiarazione che quella piattaforma comprende, che regola come visualizza un valore anziché come lo memorizza. Su un target privo di tale nozione non c’è nulla in cui una dichiarazione possa trasformarsi, quindi un input identico viene renderizzato in modo identico con o senza di essa, in modo permanente.

Una cosa che una dichiarazione cambia è ciò che la CLI stampa perché un essere umano lo legga. Un valore dichiarato sensibile viene sostituito da un segnaposto fisso nella traccia per passata e nei layout di inspect, mantenendo la chiave e nascondendo solo il valore. È una scelta di visualizzazione su superfici che nessuno distribuisce, e gli artefatti renderizzati sono emessi alla lettera perché sono ciò che si distribuisce.

Dove il compilatore può identificare il valore per chiave — una foglia dichiarata, o una chiave di consegna che porta materiale da una chiave provides dichiarata — la sostituzione è esatta. Un valore che un template ha già scritto in un altro documento non porta alcuna chiave a cui sostituirlo, perché un documento renderizzato non registra nulla su quale dichiarazione abbia prodotto ciascun carattere, e ricostruirlo significherebbe ispezionare il contenuto. Così la traccia mostra un tale documento valutando lo stesso template una seconda volta rispetto a un contesto i cui dati dichiarati sensibili si leggono già come segnaposto, ed etichetta il risultato come un nuovo rendering anziché come ciò che è stato renderizzato: un template che si dirama in base al contenuto di un valore viene renderizzato diversamente con un segnaposto, e un dato che nessuna dichiarazione nomina passa invariato. Le superfici, questa etichettatura e i suoi limiti sono in language-reference/vocabulary/compact-form-authoring.md «Dichiarare sensibile una foglia».

Quindi l’enunciato onesto di ciò che questo asse offre:

Una dichiarazione di sensibilità è un’affermazione dell’intento dell’autore che viaggia con l’entità, così che strumenti e policy possano ragionare su ciò che un deployment gestisce. Non è un meccanismo che lo protegge.

Proteggere il materiale resta compito del secret store, del cluster e della pipeline che gestisce l’albero renderizzato — come dice il resto di questo capitolo.

Come una credenziale raggiunge un container

Due forme di consegna, scelte dalla FeatureRecipe dell’attachment anziché dallo sviluppatore:

Valore iniettato. La FeatureRecipe dichiara un injectMapping e nessuna risorsa. Il suo output viene unito in profondità nella pipe di consegna del componente consumatore prima che la Recipe di base esegua il rendering, quindi una Recipe che legge .context.inject.env.<KEY> riceve il valore. Non viene emesso nulla di autonomo.

Due credenziali consegnate sotto una stessa chiave arrestano la build, nominando entrambi gli allegati: una mappatura che scrive una chiave già consegnata da un’altra Feature allegata — tramite la mappatura propria di quella Feature o il suo blocco inject: — viene rifiutata anziché unita, così che una credenziale non venga mai presentata al posto di un’altra. La regola è la stessa per ogni allegato, ovunque sia stato allegato e sia che riempia uno slot sul componente o su una connessione. Una mappatura che sostituisce una chiave consegnata dal blocco inject: del componente stesso o da una delle sue connessioni è l’intercettazione su cui si basano le Features di instradamento, e resta lecita.

Risorsa referenziabile. La FeatureRecipe dichiara source, workload, artifacts e/o valuesMapping, quindi emette una risorsa — tipicamente un Secret nativo della piattaforma. Pubblica l’identità di quella risorsa tramite i propri provides, e un consumatore la rilegge come .features.<name>.provides.name / .provides.key. Il nome stesso della risorsa deriva dagli stessi provides pubblicati, quindi il nome che il consumatore legge e il nome che la risorsa porta sono un’unica stringa valutata anziché due derivazioni che potrebbero divergere.

Il Workload di una Recipe consuma un riempimento referenziabile tramite la mappa attachments: di un container:

workload: |
containers:
main:
attachments:
DB_PASSWORD:
from: root_password # a slot the Component declares
as: env

Il sintetizzatore risolve il riferimento dai provides pubblicati dello slot — un secretKeyRef Kubernetes per as: env, un volume basato su secret per as: file. L’autore della Recipe scrive solo il nome dello slot e il meccanismo.

Una FeatureRecipe può fare entrambe le cose: riscrivere la pipe di consegna ed emettere una risorsa. Può anche dichiarare una pipeline di passi Wasm, che vengono eseguiti allo stesso modo per ogni famiglia di attachment — un attachment di credenziale può trasformare i documenti renderizzati del componente ospite su invito esattamente come può farlo un attachment operativo.

Chi dà il nome alla credenziale

Il localizzatore di una credenziale — il nome del secret, la voce dello store da recuperare, il valore da consegnare — è scritto da chi lo conosce, e non sempre è lo sviluppatore. Una connessione che la Release cabla non ha alcuna voce nell’Aggregate, e la Release non scrive values da nessuna parte, quindi una credenziale che prendesse il proprio localizzatore solo da values non potrebbe mai essere nominata su una tale connessione, né su alcun attachment creato dalla Release.

Perciò ogni Feature di credenziale della libreria standard che porta il localizzatore di un chiamante — core/referenced-secret, core/referenced-secret-set, core/secret-value e core/secret-provided — lo accetta da entrambi gli autori: lo sviluppatore nei values dell’attachment, nell’Aggregate, o l’operatore nella sua infra, nella Release. La foglia ha un solo nome, una sola forma e una sola dichiarazione sensitive: true in entrambi i pilastri, e ogni realizzazione legge il pilastro che la porta. Il divieto di values: nella Release resta intatto: il localizzatore dell’operatore è infra. Le Features che non accettano un localizzatore — core/random-password, core/generated-secret — non sono interessate.

Esattamente uno, garantito dalla Feature. Un attachment porta il localizzatore in un solo pilastro, mai in entrambi e mai in nessuno. Lo schema di nessun pilastro può esprimerlo, perché ogni pilastro è validato a sé; lo fa il blocco assertions di ciascuna Feature, e un attachment che lo viola arresta la build nominando la Feature, l’attachment e il componente. È il contratto dell’entità di catalogo, rispettato come ogni asserzione di Feature: il compilatore valuta il template scritto dall’autore della Feature e non ha alcuna regola propria su credenziali, pilastri o localizzatori.

Cosa resta dov’era. Ogni altro campo mantiene il proprio pilastro — la chiave dei dati di una credenziale referenziabile si scrive ancora in values, quindi un attachment creato dalla sola Release ne legge il valore predefinito — e core/secret-provided consegna ancora solo tramite il blocco inject: dell’attachment stesso, che solo l’Aggregate scrive e che l’attachment di una connessione non porta mai.

Condividere una credenziale tra più consumatori

Il consumatore può detenere la credenziale. Uno slot appartiene a qualunque entità abbia bisogno della credenziale, e spesso si tratta del chiamante anziché di ciò che viene chiamato: un componente che presenta una chiave quando contatta un servizio dichiara lo slot per quella chiave sulla propria entità di catalogo, sul socket attraverso cui lo contatta, così che la chiave sia detenuta sulla connessione su cui viene presentata — e nulla in un arco uses obbliga il target a fornirne una. core/ai-agent/crewai è la forma fornita — il suo socket model dichiara uno slot credential opzionale con il selettore feature.aggrega.ai/kind=secret, inject: [env] e sensitive: true, e un Aggregate lo riempie sotto la connessione, in uses.model.<alias>.features.credential. Ciò che i componenti modello della libreria standard pubblicano perché un consumatore lo legga è un indirizzo di servizio e un nome di modello, non una credenziale, quindi la chiave che l’agente presenta quando chiama quell’endpoint è dichiarata dall’agente e detenuta sulla sua connessione. Lo slot è opzionale, ma una connessione che raggiunge un modello che il suo catalogo etichetta component.aggrega.ai/hosting: managed e che non porta alcuna credenziale arresta la build, a meno che i suoi values non dicano che il modello non ne richiede alcuna, unauthenticated: true — un’asserzione che l’entità di catalogo dell’agente porta con sé e che il compilatore valuta come valuta qualsiasi asserzione, leggendo l’etichetta come una stringa. Il componente modello a cui si connette può detenere una chiave propria per i suoi propri chiamanti — core/ai-model/vllm dichiara uno slot api_key esattamente a questo scopo — e i due sono punti di binding separati: un allegato vincola uno slot per nome dove questo è dichiarato, sul componente o sulla connessione, quindi riempirne uno non dice nulla dell’altro.

È questa collocazione a rendere le due forme seguenti delle vere scelte di deployment: con lo slot sul consumatore, una build può dare a ciascun consumatore la propria chiave e un’altra può dare a tutti la stessa, senza che alcuna entità di catalogo cambi tra le due.

La stessa entità di catalogo serve entrambe le forme, ed è l’autore a scegliere quale:

  • Per consumatore. Ogni consumatore riempie il proprio slot con il proprio allegato di credenziale — sul componente, o sulla sua connessione dove lo slot è quello di un socket. Ciascuno ottiene la propria risorsa renderizzata.
  • Condivisa. Per uno slot dichiarato da un componente, una credenziale viene allegata una sola volta in un ambito condiviso — un sottosistema nell’Aggregate, un boundary nella Release — e si propaga a cascata a ogni componente in quell’ambito. Uno slot dichiarato da un socket si riempie per connessione, e nulla si propaga a cascata dentro una connessione, quindi lì la forma condivisa si scrive su ciascuna connessione: la credenziale di ogni connessione legge un unico parametro. Dove i consumatori devono fare riferimento a un’unica risorsa fisica, quel parametro la nomina — core/referenced-secret vincolato alla realizzazione existing-Secret punta ogni connessione a un unico Secret per nome, e una credenziale generata è una richiesta e molti riferimenti, come più sotto.

Va detto con precisione come viene renderizzata la forma condivisa, perché è facile supporre il contrario: un allegato condiviso renderizza una risorsa per consumatore, ciascuna con lo stesso materiale proveniente dall’unica dichiarazione. Il rendering avviene per componente, e un nome di risorsa derivato da {{ .context.instance_id }}-{{ .attachment_name }} differisce quindi per consumatore. Ciò che è condiviso è la singola dichiarazione; le risorse emesse non vengono deduplicate in una sola. Un parametro letto su ogni connessione si renderizza allo stesso modo sotto una realizzazione che renderizza una risorsa — una per connessione, dove il nome dell’allegato è l’alias della connessione, un punto e lo slot.

Se un deployment ha bisogno esattamente di un unico Secret fisico letto da più consumatori, lo si esprime con una Feature di credenziale la cui FeatureRecipe viene eseguita nell’ambito del boundary (executionScope: boundary), che renderizza una volta per il boundary anziché una volta per componente.

Una chiave detenuta da entrambe le estremità di una connessione

Un server che verifica una chiave e il componente che lo chiama detengono ciascuno quella chiave, ognuno dal proprio lato. Il server detiene la chiave che verifica in uno slot del proprio Component — core/ai-model/vllm, core/ai-model/tei e core/ai-model/tgi dichiarano ciascuno api_key, come fanno il modello e il gateway LiteLLM per la chiave che LiteLLM chiama master key — e la sua Recipe consegna ciò che riempie lo slot come la variabile che il server legge. Il chiamante detiene la chiave che presenta dal proprio lato: sulla connessione su cui la presenta, in uno slot dichiarato dal suo socket — come il socket model di core/ai-agent/crewai dichiara credential — oppure, dove il suo Component dichiara la chiave su sé stesso, in quello slot, per ogni connessione che effettua. Nessuna delle due estremità vede gli allegati dell’altra: un allegato su una connessione ricade solo sul chiamante, e l’output renderizzato di un server è lo stesso qualunque cosa portino le connessioni che lo raggiungono. Il server non sa mai quale chiave detiene un chiamante, e il chiamante legge solo ciò che il server pubblica — un indirizzo e un nome di modello. Le due estremità concordano perché l’Aggregate le alimenta entrambe da un unico parametro:

spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
router:
type: local/gateway/model-router # its `models` socket declares a `credential` slot
uses:
models:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Che si tratti di un secret o di due dipende da dove le due estremità risolvono i secret. Un provider risolve un secret per riferimento all’interno di un ambito dei secret: un namespace Kubernetes su helm, un progetto Compose su compose, la configurazione radice di un boundary su terraform e, su cloudformation, uno stack, nell’account e nella regione AWS in cui viene distribuito. Dove entrambe le estremità si trovano in un unico ambito, fanno riferimento a un’unica risorsa secret. Dove si trovano in ambiti diversi, ciascuna estremità detiene una propria risorsa secret, realizzata dalla stessa voce dello store. Il Manifest sceglie la realizzazione di ciascuna estremità — per tipo di Feature o, per un singolo allegato, per il suo nome, che per l’allegato di una connessione è <alias>.<slot> (local.credential sopra). Poiché un unico parametro le alimenta entrambe, le due realizzazioni leggono origin come lo stesso tipo di localizzatore: entrambe il nome di un Secret, entrambe la chiave di una voce dello store, o entrambe il valore stesso.

Su helm, con entrambe le estremità in un unico namespace, vincolare core/referenced-secret a helm/k8s-existing-secret e soddisfare il parametro con il nome di un Secret presente in quel namespace, model-keys, fa sì che entrambe le estremità vi facciano riferimento per nome e non renderizza alcun Secret. Il container del server porta:

- name: VLLM_API_KEY
valueFrom:
secretKeyRef:
name: model-keys
key: api-key

e la Recipe del router legge lo stesso nome e la stessa chiave dalla sua connessione, in .context.uses.local.features.credential.provides. Con le due estremità in namespace diversi, vincolarlo a helm/k8s-external-secret e soddisfare il parametro con la chiave di una voce dello store dà a ciascuna estremità un proprio ExternalSecret, nel proprio namespace, ed entrambi recuperano quella stessa voce. Su compose, entrambe le estremità portano lo stesso riferimento ${VAR}, che Docker Compose sostituisce a partire dall’ambiente con cui viene avviato l’unico progetto. Questa collocazione è una convenzione seguita dal catalogo della libreria standard; il compilatore non confronta nulla tra le due estremità.

Una chiave serve ogni chiamante. vLLM, TEI e TGI verificano ciascuno una sola chiave, quindi ogni chiamante presenta la stessa chiave e il server non può distinguere un chiamante da un altro, per quante connessioni lo raggiungano. Questo è un limite del server stesso. TGI confronta la propria chiave senza tenere conto di maiuscole e minuscole, quindi due chiavi che differiscono solo per le maiuscole sono per esso una sola chiave. Il modello e il gateway LiteLLM accettano anche le chiavi che emettono essi stessi, finché il loro database di contabilità è allegato.

Una credenziale generata dal target

Dove una Release non fornisce alcuna credenziale, un’entità di catalogo ripiega spesso su un valore predefinito di sviluppo — un valore inline in una Recipe, un default sul parametro di un modulo. Quel valore è lo stesso per ogni lettore del catalogo, il che è accettabile per la valutazione e per nient’altro. core/random-password ne elimina la necessità: nessuno scrive la credenziale, perché la genera il target.

La build non può essere il luogo in cui si crea la password. Il suo output è una funzione pura del suo input e non porta mai il valore di un secret, quindi una password estratta al momento della build cambierebbe a ogni build e si troverebbe nei file renderizzati. La FeatureRecipe renderizza invece una richiesta — una risorsa generatore che nomina la risorsa secret che riempie — e il target estrae il valore al momento del deploy:

  • su helm, un controller nel cluster: il generatore di password dell’External Secrets Operator, riconciliato tramite un ExternalSecret, oppure il controller kubernetes-secret-generator, che riconcilia uno StringSecret;
  • su terraform, il random_password del provider random, estratto quando la configurazione viene applicata;
  • su cloudformation, un secret di Secrets Manager che genera la propria stringa quando lo stack lo crea.

In ogni caso l’output renderizzato nomina il generatore e la risorsa secret e non porta alcun valore. È una proprietà di ciò che la build possiede, non una protezione che aggiunge: il valore non esiste finché il target non lo crea. Dove il target lo conservi in seguito è affare del target — Terraform lo conserva nel piano e nello stato, un cluster in un Secret.

Cosa deve essere in esecuzione sul target. Una richiesta viene soddisfatta solo dove qualcosa la soddisfa. Su helm è il controller, e il compilatore non può ispezionare il cluster per sapere se ne è in esecuzione uno, quindi le FeatureRecipes helm arrestano la build a meno che la Release non affermi il prerequisito con infra.control_plane_present: true sull’allegato. Su terraform e cloudformation l’apply o lo stack genera il valore da sé e nulla deve essere in esecuzione prima.

Dove non può essere usata. Compose non esegue alcun controller e non ha alcuna risorsa che generi un valore, quindi nessuna FeatureRecipe realizza core/random-password lì, e una build che lo vincola su compose si arresta per mancanza di una. Una Release che ha come target compose fornisce la propria credenziale tramite core/secret-value, tipicamente come riferimento a una variabile che Docker Compose sostituisce all’avvio dello stack.

Come la legge un consumatore. core/random-password pubblica gli stessi provides.name e provides.key di core/referenced-secret e porta la stessa etichetta feature.aggrega.ai/kind: secret, quindi uno slot che seleziona la famiglia delle credenziali la ammette e un consumatore legge una credenziale generata esattamente come ne legge una già esistente.

Come la condividono più consumatori. Un generatore estrae un nuovo valore per ogni richiesta, quindi la regola di condivisione della sezione precedente si applica in modo più netto: una credenziale generata allegata in un ambito condiviso — o su ciascun consumatore — renderizza una richiesta per consumatore, e ogni richiesta estrae una password diversa, che un database e i suoi client non possono usare. Un’unica credenziale generata condivisa da più consumatori si esprime come una richiesta e molti riferimenti: core/random-password su un componente, con il suo valore name che fissa il Secret che riempie, e core/referenced-secret sugli altri, vincolato alla realizzazione existing-Secret e puntato a quello stesso nome. Scritti a partire da un unico parametro, i due non possono divergere, e il render porta esattamente una richiesta a cui ogni consumatore fa riferimento.

core/random-password non è core/generated-secret. Quella Feature consegna una credenziale a un motore che ne possiede già l’intero ciclo di vita — un database gestito, un controller di database — e non renderizza nulla. core/random-password renderizza la richiesta stessa, per un workload la cui Recipe si aspetta che le venga consegnata una credenziale.

Precedenza degli allegati

Un allegato può essere dichiarato in più ambiti contemporaneamente. La titolarità di un campo conteso si risolve con tre regole, applicate in quest’ordine:

  1. Origine. Un campo scritto esplicitamente prevale su uno fornito dall’espansione guidata dalle annotazioni, da qualunque ambito provenga ciascuno dei due.
  2. Autorità di composizione. Una dichiarazione nell’Aggregate che stai distribuendo prevale su una all’interno di un Aggregate che esso compone, anche quando il documento composto l’ha dichiarata nell’ambito più ristretto.
  3. Specificità. All’interno di uno stesso livello di authoring, l’ambito più ristretto raffina quello più ampio campo per campo: un riempimento a livello di componente sovrascrive un allegato a livello di sottosistema o di boundary con lo stesso nome di istanza solo per i campi che menziona, e i campi che omette mantengono i valori dell’ambito più ampio.

Il lato sviluppatore fornisce values e il lato operatore fornisce infra, quindi i due non si contendono mai lo stesso campo. Una Feature di credenziale che prende il proprio localizzatore da entrambi i lati lo dichiara come due campi, uno per pilastro, e la sua stessa asserzione rifiuta un allegato che li porti entrambi, quindi nemmeno lì la precedenza ha un pareggio da risolvere. La precedenza governa solo i valori dei campi; non riordina la valutazione, che segue la sequenza di cascata in 10-compilation-pipeline.md.

Chart legacy che richiedono una stringa formattata

Un chart a volte vuole una singola stringa di connessione con il materiale incorporato — oracle://admin:PASSWORD@HOST:1521/DB. Un compilatore ahead-of-time non può costruire quella stringa da una coordinata dello store, perché non detiene mai il materiale. Due percorsi supportati:

Templating lato cluster. La FeatureRecipe della credenziale emette una risorsa che formatta la stringa nel cluster, usando il templating proprio dell’operatore del vault. L’applicazione fa poi riferimento per nome al Secret di piattaforma risultante, e il compilatore ha collegato la relazione senza mai detenere il materiale:

{
"apiVersion": "external-secrets.io/v1beta1",
"kind": "ExternalSecret",
"metadata": { "name": "oracle-dsn-secret" },
"spec": {
"target": {
"name": "oracle-formatted-dsn",
"template": {
"engineVersion": "v2",
"data": { "ORACLE_DSN": "oracle://admin:{{ .password }}@10.0.5.55:1521/PROD_DB" }
}
},
"data": [
{ "secretKey": "password", "remoteRef": { "key": "arn:aws:secretsmanager:prod/oracle" } }
]
}
}

Hoisting dei parametri. L’Aggregate dichiara un parametro tipizzato e la pipeline CI circostante fornisce il valore al momento della build tramite i parameters: della Release — per esempio un file che la pipeline scrive e che la Release importa con parameters: { $import: ./ci-parameters.yaml }. Questa è la via d’uscita esplicita, e rende visibile il compromesso: il materiale ora passa attraverso la build, quindi l’output renderizzato lo porta e va gestito di conseguenza.

Sviluppo locale

Il percorso di riferimento per lo sviluppo locale mantiene invariato l’intento dello sviluppatore e sostituisce il binding. L’Aggregate continua ad allegare lo stesso tipo di Feature di credenziale; il Manifest locale mappa quel tipo a una FeatureRecipe locale anziché a quella basata sullo store. Il compilatore continua a non recuperare nulla — la FeatureRecipe locale consegna semplicemente la sintassi nativa del provider che il runtime locale risolve: per Compose, un riferimento a una variabile come ${SECRET_NAME} scritto nell’ambiente del servizio, che Docker Compose sostituisce a partire dall’ambiente della shell o da un file .env all’avvio dello stack. Cambiare ambiente è una modifica del Manifest.

Governance dei dati attorno alle credenziali

Aggrega non modella gli schemi dei dati — righe, colonne, file sono questioni dell’applicazione. Modella l’identità di governance dei dati con le etichette, e la convenzione della libreria standard è:

  • I dati risiedono in componenti la cui etichetta di ontologia li contrassegna come stateful o simili a risorse (component.aggrega.ai/type: stateful-server, resource). Anche un message broker che conserva payload in coda è uno di questi: porta stateful-server quando possiede il proprio disco e resource quando la Release ne collega uno ospitato, e lo scaffale messaging sotto cui viene sfogliato è l’asse separato component.aggrega.ai/category.
  • compliance.aggrega.ai/data-class (public, internal, restricted) dà a quei dati un’identità semantica. La convenzione fissa la chiave e i suoi valori, non quali componenti la portano: nessun Component della libreria standard la porta, perché la classe dei dati che un componente conserva è un’affermazione su come un’organizzazione usa il componente anziché una proprietà del prodotto, quindi un’organizzazione la dichiara sui propri Components. È un’etichetta ordinaria: i selettori di etichette la valutano, e un plugin di governance allegato da un operatore può leggerla e rifiutare una build. Il compilatore stesso non la interpreta e non pone alcuna classe al di sopra di un’altra — quali classi esistano e come si ordinino è materia delle impostazioni della policy allegata, come in ../language-reference/examples/policy-data-class-route/.

data-class e sensitive sono due assi, e fonderli fa perdere informazioni. Stanno l’uno accanto all’altro ed è facile scambiarli per un’unica superficie, quindi tieni presente la distinzione:

compliance.aggrega.ai/data-classsensitive
Formagraduata — public / internal / restrictedbooleana
Granularitàun intero nodouna foglia di schema, o uno slot di allegato
Dicequale identità di governance hanno i dati che un componente conservache questo dato è materiale segreto, o che questo punto di binding lo gestisce
Scritta comeun’etichetta in metadata.labelsuna parola chiave su una dichiarazione

Nessuno dei due sostituisce l’altro: forzare la sensibilità nell’etichetta graduata imporrebbe un ordinamento a un fatto che non ne ha, e forzare una classe di dati su una foglia imporrebbe una granularità che la classificazione non ha. Un’entità può portarli entrambi, e un componente che conserva dati restricted il cui slot di credenziale è dichiarato sensitive afferma due cose vere distinte. Le parole chiave per foglia e per slot sono spiegate in ../language-reference/vocabulary/compact-form-authoring.md «Dichiarare sensibile una foglia» e in ../language-reference/entities/component.md «Dichiarare sensibile uno slot».

La cifratura a riposo è deliberatamente al di fuori dell’intento dello sviluppatore e al di fuori del compilatore. Appartiene alla Recipe Ops del componente stateful e al plugin di rendering che legge le etichette del nodo ed emette la configurazione di storage cifrato. Questa collocazione è un’indicazione di progettazione su dove appartiene la questione — il compilatore non verifica che una qualsiasi Recipe la rispetti.

Che cosa è distintivo qui, e che cosa non lo è

Il posizionamento pubblico merita di essere enunciato in modo semplice e circoscritto, perché il lettore possa calibrarsi.

Distintivo: il contratto del socket è pubblicato, non dichiarato inline. Il contratto che una credenziale deve soddisfare — lo slot, la sua allowlist di consegna, il suo selettore di etichette — è scritto sull’entità di catalogo da chi l’ha pubblicata, e vive in un catalogo mantenuto da terzi. Un consumatore non descrive il contratto inline nella propria configurazione; riempie un contratto pubblicato da qualcun altro, e il compilatore verifica il riempimento rispetto a quella dichiarazione pubblicata. Il consumatore e l’autore del contratto sono persone diverse, che lavorano in repository diversi, con cadenze di rilascio diverse.

Distintivo: il riempimento è vincolato da un selettore di etichette. Uno slot può dire che tipo di cosa può riempirlo (selector: "feature.aggrega.ai/kind=secret") anziché nominare un’implementazione specifica. Il controllo è una valutazione di un insieme di etichette, quindi un’entità può accettare una famiglia di riempimenti di cui non ha mai sentito parlare, e un nuovo riempimento diventa idoneo portando le etichette giuste.

Non distintivo: la mappatura di iniezione. Mappare «questo nome di variabile d’ambiente locale riceve quel valore prodotto» è un pattern noto; diversi strumenti di configurazione e di deployment esprimono la stessa idea con la propria sintassi. La versione di Aggrega è una mappatura valutata in anticipo e fusa in una pipe di consegna, ma l’idea è dell’ecosistema, non nostra.

Non distintivo: la generazione statica anticipata. Generare staticamente artefatti di deployment da una descrizione di livello più alto, senza accesso a un cluster attivo al momento della generazione, non è un’invenzione di Aggrega. Altri strumenti lo fanno, e lo facevano prima che Aggrega esistesse. Ciò che Aggrega aggiunge è il livello di contratti pubblicati che vi sta sopra, non la generazione statica in sé.

Non è un confine di sicurezza. Nulla in questo capitolo è un meccanismo di riservatezza. Il modello delle credenziali è un modello di cablaggio: decide da dove proviene un puntatore o un valore, chi può vincolarlo e come raggiunge un container. Proteggere il materiale è compito del secret store, del cluster e della pipeline che gestisce l’albero renderizzato.

Riferimenti incrociati