Segreti
Questa pagina spiega un’unica idea, come una credenziale raggiunge il componente che ne ha bisogno, e non è un workspace eseguibile. Piattaforma avanzata — una piattaforma Kubernetes con più confini mostra entrambi i modelli di consegna in un workspace che costruisci tu; scrivilo in una tua cartella con:
aggrega scaffold --example advanced-platformPoi stampa i prossimi comandi da eseguire:
cd advanced-platformaggrega pull --release release.yamlaggrega build --release release.yamlLa checklist della consegna dei secret
Una credenziale passa attraverso sei superfici prima di raggiungere un container in esecuzione. Questi sono i punti di contatto da verificare quando se ne cabla una nuova:
| Passo | Superficie | Azione |
|---|---|---|
| 1 | featuresSchema: del Component | Dichiarare lo slot della credenziale: il suo nome, se è required, e la sua allowlist inject: — i meccanismi di consegna che un’associazione può nominare, [env] o [env, file] per uno slot trasparente, [] per uno opaco. |
| 2 | schema: della Feature di credenziali | Definire ciò che un autore fornisce: le Features di credenziali della libreria standard portano l’etichetta feature.aggrega.ai/kind: secret e accettano il localizzatore della credenziale come origin e la chiave dei dati come key. |
| 3 | Aggregate features: | Richiedere la credenziale, sotto la stessa parola chiave features: di qualsiasi altra Feature: il suo type, i suoi values e, solo su uno slot trasparente, un blocco inject: che dice come l’applicazione la legge. |
| 4 | FeatureRecipe | Realizzarla per la destinazione: scrivere il valore dove il componente lo legge, renderizzare una risorsa che lo contiene, oppure renderizzarne una che lo recupera da un archivio di segreti. |
| 5 | mappings.features.type del Manifest | Vincolare la Feature di credenziali alla sua FeatureRecipe, nello stesso livello di ogni altra Feature. |
| 6 | Recipe | Leggerla, su uno slot opaco: la Recipe del componente legge il localizzatore che la credenziale pubblica, .features.<slot>.provides.name, e lo passa al meccanismo proprio del prodotto, come existingSecret di un chart. |
Uno slot trasparente usa le prime cinque; uno slot opaco le usa tutte e sei, che è il caso abituale per l’infrastruttura pacchettizzata, come il chart di un fornitore.
Slot trasparenti e opachi
Uno slot trasparente permette allo sviluppatore di dire come l’applicazione legge la credenziale. Uno slot opaco lascia la consegna alla Recipe, e un’associazione che vi scrive un blocco inject: interrompe la build. Nell’esempio, core/datastore/mariadb ne dichiara uno di ciascun tipo, e l’Aggregate li riempie entrambi, da aggregate.yaml senza i suoi commenti:
db: type: core/datastore/mariadb features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: dev-root-pw-change-me user_password: type: core/secret-provided values: origin: dev-app-pw-change-me inject: env: - in: MARIADB_PASSWORD from: valueroot_password è opaco: core/secret-value consegna il valore sotto la chiave che l’associazione nomina, dove la Recipe del database lo legge. user_password è trasparente: core/secret-provided pubblica il valore come value, e il blocco inject: proprio dell’associazione lo consegna in MARIADB_PASSWORD. Un blocco inject: che nomina un meccanismo che lo slot non elenca interrompe la build, così come uno che nomina una chiave che nulla pubblica o legge.
Per uno slot opaco riempito da una credenziale referenziabile, la Recipe del componente legge il localizzatore pubblicato invece di derivare un nome, existingSecret: "{{ .features.root_password.provides.name }}", così il Secret che una FeatureRecipe emette e il riferimento a esso sono un’unica stringa. MariaDB (chart Bitnami) — un unico Secret di credenziali a più chiavi costruisce quel flusso sul chart di un fornitore.
Realizzare una credenziale: una risorsa o una pipeline in due passaggi
Le realizzazioni Kubernetes della libreria standard renderizzano la risorsa della credenziale da un piccolo chart accanto alla FeatureRecipe: helm/k8s-secret-from-parameter un Secret che contiene il valore fornito da un autore, e helm/k8s-external-secret un ExternalSecret che l’External Secrets Operator riconcilia da un archivio di segreti. Features per le credenziali le illustra una per una.
Una FeatureRecipe può invece realizzare una credenziale con una pipeline: di due passaggi, ciascuno un plugin. Il primo, il recuperatore, scrive la risorsa specifica dell’archivio — un ExternalSecret, per esempio — nominando la voce dell’archivio indicata dai valori dell’associazione. Il secondo, l’iniettore, applica una patch al carico di lavoro renderizzato del componente per montare il Secret risultante nel suo container, nelle variabili o nei file che il blocco inject: dell’associazione nomina, e che il passaggio legge in .inject. Passare a un altro archivio di segreti sostituisce il recuperatore; l’iniettore resta. Un passaggio restituisce le risorse che aggiunge come effetti collaterali e le sue modifiche ai documenti renderizzati come patch; il contratto dei plugin Wasm è la forma di entrambi.
La credenziale propria di una Feature
Una Feature può avere bisogno di una credenziale propria: un proxy di guardrail che si autentica presso un servizio a monte, un log shipper con un token di ingestione. La Feature dichiara lo slot nel proprio featuresSchema, esattamente come fa un Component, e la FeatureRecipe vincolata a essa legge ciò che riempie quello slot quando renderizza il carico di lavoro della Feature.
Le associazioni non si annidano. La credenziale è associata accanto alla Feature, sullo stesso componente, sotto il nome che lo slot della Feature dichiara; il nome dello slot è ciò che lega le due. La Feature di guardia e il componente qui sotto sono entità proprie del workspace; core/referenced-secret appartiene alla libreria standard.
# The Feature declares the slotkind: Featuremetadata: name: local/guardspec: appliesTo: "component.aggrega.ai/type in (server, worker)" featuresSchema: guard_api_key: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]---# The Aggregate fills it beside the Featurespec: components: finance-agent: type: local/compute/guarded-worker features: ai-guard: type: local/guard guard_api_key: type: core/referenced-secret values: origin: dev-guard-key-change-me key: api-keyLa FeatureRecipe della guardia renderizza un carico di lavoro il cui container fa riferimento allo slot, attachments: { GUARD_API_KEY: { from: guard_api_key, as: env } }, così il riferimento finisce sul container della guardia e su nessun altro. La Recipe del componente host non può fare riferimento allo slot, perché appartiene alla Feature: un carico di lavoro che tenta di raggiungerlo interrompe la build nominando lo slot. Anche una voce del carico di lavoro che nomina uno slot che nulla riempie interrompe la build, poiché non c’è alcun localizzatore pubblicato da risolvere.
Lo stesso vale per le connessioni che una Feature traccia: una connessione nel blocco uses: proprio della Feature non porta associazioni, quindi una credenziale di cui una tale connessione ha bisogno è uno slot che la Feature dichiara, riempito accanto alla Feature.
La credenziale propria di una connessione
Un gateway che raggiunge due modelli può presentare a ciascuno una chiave diversa, oppure una chiave a uno e nessuna all’altro. Uno slot sul gateway contiene una sola credenziale per l’intero componente, quindi la credenziale va invece sulla connessione: il socket del gateway dichiara lo slot che ogni connessione che lo attraversa può riempire, e ogni connessione lo riempie, o no, per conto proprio.
spec: components: router: type: core/gateway/litellm uses: models: gpt: target: gpt features: credential: # a slot the models socket declares type: core/referenced-secret values: key: api-keyLa Recipe del gateway legge l’associazione dalla propria connessione, in .context.uses.gpt.features.credential, così un gateway che raggiunge più modelli legge la chiave propria di ciascun modello; core/gateway/litellm consegna ciascuna come una variabile a sé, che la voce della connessione nella sua tabella di routing nomina. Un’associazione sotto un nome per cui il socket non dichiara alcuno slot interrompe la build, nominando gli slot che dichiara. Il Manifest può realizzare la credenziale di una connessione diversamente dalle altre, con la chiave <connection>.credential nel suo livello per istanza. Credenziali sulle connessioni — una chiave per connessione e una sola chiave a entrambe le estremità costruisce questo; una Release può anche cablare una connessione del genere e nominare il segreto nell’infra dell’associazione, come descrive Features per le credenziali.