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

Features di credenziali

Questa pagina spiega un’unica idea, le Features di credenziali della libreria standard e il modo in cui un Manifest sceglie che cosa realizza ciascuna di esse, e non è uno spazio di lavoro eseguibile. Un solo intento dello sviluppatore, due forme di consegna delle credenziali esegue il build di un Aggregate con due realizzazioni della stessa credenziale; scrivilo in una cartella tua con:

Terminal window
aggrega scaffold --example credential-shape-per-target

Poi stampa i prossimi comandi da eseguire:

Terminal window
cd credential-shape-per-target
aggrega build --release release-local.yaml --auto-pull
aggrega build --release release-store.yaml --auto-pull

Una credenziale riempie uno slot che un Component dichiara nel proprio featuresSchema (vedi entities/component.md); lo slot, la Feature che lo riempie e la FeatureRecipe che il Manifest vincola formano l’intero percorso dall’associazione di un autore fino a un carico di lavoro in esecuzione.

La famiglia di Feature di credenziali

Una Feature di credenziali porta l’etichetta feature.aggrega.ai/kind: secret. L’etichetta è un metadato del catalogo che descrive ciò che l’associazione produce; nessun ramo del compilatore la legge, e una Feature di credenziali si associa sotto features: come qualsiasi altra Feature, dallo sviluppatore nell’Aggregate o dall’operatore nella Release.

La libreria standard suddivide le Features di credenziali in base a ciò che la realizzazione fa con il secret:

  • core/secret-value consegna un valore nel canale di iniezione del componente, dove la sua Recipe lo legge — un valore del chart, una variabile d’ambiente.
  • core/secret-provided produce anch’essa un valore, ma lo pubblica invece come chiave provides, così è il blocco inject: proprio dell’associazione, su uno slot trasparente, a dire dove va.
  • core/referenced-secret nomina una risorsa secret — un Secret Kubernetes, un secret di AWS Secrets Manager, una voce di Vault — che la sua realizzazione crea o che esiste già, e pubblica name e key di quella risorsa, che un consumatore legge come .features.<slot>.provides.name e .features.<slot>.provides.key.
  • core/referenced-secret-set materializza una di queste risorse, che contiene un insieme di chiavi dei dati fornito dall’autore, e ne pubblica solo il localizzatore, per un consumatore la cui destinazione fissa già i nomi delle chiavi che legge. Docker Compose non ha una risorsa di questo tipo, quindi lì la sua realizzazione consegna invece le chiavi come valori, come descritto più avanti. MariaDB (chart Bitnami) — un unico Secret di credenziali con più chiavi la usa.
  • core/generated-secret non produce nulla: il motore di destinazione genera e gestisce da sé la credenziale, come fa un database gestito con la propria password di amministratore. L’operatore la associa nella Release, perché il fatto che sia il motore a possedere la credenziale dipende dalla Recipe che il Manifest sceglie; Terraform RDS (artefatto HCL inline) vincola in questo modo uno slot obbligatorio.
  • core/random-password renderizza una richiesta alla destinazione di generare una password in una risorsa secret, e pubblica il localizzatore di quella risorsa come fa core/referenced-secret. Nessuno scrive la credenziale e l’output renderizzato non ne porta alcuna.

Sono alla pari — stessa etichetta, stessa superficie di associazione, stesso slot — quindi uno slot è sempre riempito, e ciò che cambia tra le Releases è ciò che lo riempie. Una Feature di credenziali che dichiara un contratto provides obbliga ogni FeatureRecipe che la implementa a pubblicare quelle chiavi, e il build si arresta se una non lo fa; è questo che rende sicura la lettura del consumatore.

core/random-password ha bisogno di qualcosa sulla destinazione che generi il valore, perché il build non lo fa mai: su Kubernetes un controller (External Secrets Operator, o kubernetes-secret-generator) la cui presenza la Release attesta con infra.control_plane_present: true; su Terraform una risorsa random_password; su CloudFormation un secret di Secrets Manager che genera la propria stringa. Per Docker Compose non viene fornita alcuna realizzazione, quindi un build che la vincola lì si arresta. Ogni richiesta genera il proprio valore, quindi due componenti condividono una sola password generata associandola una volta, con name fissato, e leggendola altrove tramite core/referenced-secret vincolata a helm/k8s-existing-secret.

Chi nomina la credenziale: values o infra, esattamente uno

core/secret-value, core/secret-provided, core/referenced-secret e core/referenced-secret-set accettano il localizzatore della credenziale da entrambi gli autori: lo sviluppatore lo scrive nei values dell’associazione nell’Aggregate, l’operatore nell’infra dell’associazione nella Release. La foglia è la stessa in entrambi — origin, o entries per l’insieme — e ogni realizzazione legge il pilastro che la porta, qualunque esso sia.

La forma dell’operatore è ciò che rende utilizzabile una credenziale dove lo sviluppatore non può scriverne una: su una connessione che la Release cabla, e su un’associazione che fa soltanto la Release, poiché una Release non scrive values da nessuna parte.

# Release: the operator wires the connection and names the secret.
spec:
components:
router:
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a

Esattamente uno dei due. Ciascun pilastro viene validato per conto proprio, quindi nessuno dei due schemi può richiedere il localizzatore; sono invece le assertions proprie di ciascuna Feature a contenere la regola, e un’associazione che porta il localizzatore in entrambi i pilastri, o in nessuno, arresta il build (E0033) nominando la Feature, l’associazione e il componente. Questo è il contratto delle entità del catalogo: il compilatore valuta la loro asserzione come valuta quella di qualsiasi Feature.

Tutto il resto mantiene il proprio pilastro. key resta una foglia di values, quindi un’associazione che fa soltanto la Release legge la chiave dei dati predefinita, value. Dichiarare origin in entrambi i pilastri è esattamente ciò che cerca l’avviso di sovrapposizione dei pilastri, quindi il caricamento di queste Features lo segnala — LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars. Qui la sovrapposizione è il contratto; l’avviso non cambia alcun verdetto né alcun byte renderizzato.

Il Manifest sceglie la realizzazione

Più FeatureRecipes possono implementare una Feature per la stessa destinazione, e il Manifest sceglie. core/referenced-secret ne ha tre su Kubernetes, e a decidere tra di esse è dove si trova la credenziale:

  • helm/k8s-secret-from-parameter scrive il valore fornito da un autore in un Secret che emette, quindi il materiale si trova nell’output renderizzato: per la valutazione e il lavoro locale.
  • helm/k8s-external-secret renderizza un ExternalSecret che nomina una voce in un archivio di secret, che External Secrets Operator nel cluster riconcilia in un Secret.
  • helm/k8s-existing-secret non emette nulla: legge origin come il nome di un Secret che esiste già e lo pubblica così come è scritto.

Le prime due ricavano il nome del Secret allo stesso modo, dal nome renderizzato dell’host e da quello dello slot, quindi un consumatore legge lo stesso localizzatore da entrambe e il suo riferimento renderizzato non cambia; è ciò che mostra l’esempio. La terza pubblica il nome proprio del Secret esistente, quindi vincolarla cambia di proposito il riferimento del consumatore.

core/secret-value è realizzata su Docker Compose da compose/dotenv-secret, che scrive il valore nell’ambiente del servizio esattamente come l’autore lo ha scritto: un origin scritto come ${DB_PASSWORD} vi arriva come quel riferimento, che Docker Compose riempie dalla tua shell o da un file .env all’avvio dello stack. Su Kubernetes, helm/env-secret consegna il valore nel canale di iniezione, e helm/k8s-secret-from-value lo scrive anche in un Secret e ne pubblica il localizzatore, per un consumatore che legge la credenziale per riferimento. Nessuna delle due realizzazioni Kubernetes accetta un riferimento a una variabile di Compose, che lì nulla riempirebbe.

core/referenced-secret è realizzata su Docker Compose da compose/dotenv-referenced-secret. Compose non ha una risorsa secret a cui fare riferimento, quindi origin è la credenziale stessa anziché il nome di un Secret: viene consegnata nella pipe di inject sotto la key del collegamento, e una Recipe di Compose che legge lo slot la scrive nel file emesso esattamente come l’autore l’ha scritta, così un origin scritto come ${DB_PASSWORD} arriva come quel riferimento. Non crea alcuna risorsa, quindi il nome che pubblica è vuoto e la chiave che pubblica è values.key.

core/referenced-secret-set è realizzata su Docker Compose da compose/dotenv-secret-set, che consegna ogni voce nella pipe di inject come una variabile che prende il nome dalla sua chiave, scritta nell’ambiente del servizio esattamente come l’autore l’ha scritta, così una voce il cui valore è ${GITHUB_TOKEN} arriva come quel riferimento. Non crea alcuna risorsa, quindi il localizzatore che pubblica è vuoto: un consumatore su Compose legge le voci dalla propria pipe di inject anziché fare riferimento a un Secret per nome, come fanno compose/mcp e compose/mcp-stdio-bridge dalla 1.1.0 per il server_env di un server Model Context Protocol.

Un nome di FeatureRecipe distribuito per più di una destinazione, come provided-secret, si indica nel Manifest insieme alla sua destinazione, compose/provided-secret:1.0.0, poiché il nome semplice corrisponde a entrambe.

Un solo nome, pubblicato una volta

La Recipe di un consumatore non ricava mai il nome del Secret che una credenziale produce: legge il localizzatore che la credenziale pubblica, existingSecret: "{{ .features.root_password.provides.name }}". Il nome viene scritto una sola volta, nel provides della FeatureRecipe, quindi cambiare il modo in cui è composto è una modifica soltanto lì. Consegna delle credenziali — secretKeyRef end-to-end costruisce il percorso referenziabile su Kubernetes e quello iniettato su Docker Compose, e Condividere una credenziale — per consumatore, condivisa ed entrambe insieme mostra diversi consumatori che hanno ciascuno la propria chiave o ne condividono una.