Condividere una credenziale — per consumatore, condivisa, ed entrambe insieme
Due agenti CrewAI dietro un unico gateway compatibile con OpenAI. Il socket model di ciascun agente dichiara uno slot credential, quindi la chiave che un agente presenta al modello che raggiunge viene associata su quella connessione. Questo workspace riempie lo slot in tre modi senza modificare una sola entità di catalogo: una chiave per connessione, un unico Secret a cui fanno riferimento tutte le connessioni, e un default condiviso che una connessione sovrascrive.
Il punto sono i due consumatori. Le tre forme sono indistinguibili con un solo consumatore — la differenza è quale Secret finisce per indicare ciascun consumatore, e quella domanda non ha contenuto finché non c’è più di un consumatore.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example model-api-key-sharingPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd model-api-key-sharingBuild
Tre release, una per forma. Esegui il build di una per esecuzione:
aggrega build --release release-per-consumer.yaml --auto-pull # → dist/per-consumer/aggrega build --release release-shared.yaml --auto-pull # → dist/shared/aggrega build --release release-composed.yaml --auto-pull # → dist/composed/Ogni release scrive nella propria directory, quindi tutti e tre gli alberi renderizzati coesistono e possono essere confrontati tra loro con un diff.
Una release ha bisogno del proprio lockfile prima di eseguire il build. Su un checkout nuovo, risolvine prima uno — come step a sé oppure lasciando che sia il build a riempirlo:
aggrega pull --release release-shared.yaml # resolve, then build normallyaggrega build --release release-shared.yaml --auto-pull # or resolve during the buildLe release risolvono le proprie entità di catalogo dal catalogo configurato, quindi non serve alcun flag --catalog.
Tutte e tre eseguono il build sulla destinazione helm, deliberatamente. L’elemento osservabile che distingue le tre forme è il nome del Secret a cui fa riferimento il container di ciascun agente, e helm è dove una credenziale è un Secret Kubernetes con nome a cui un container fa riferimento per nome. Due Manifests legano la credenziale: manifest.yaml a k8s-secret-from-parameter, che renderizza un Secret dal valore che porta l’associazione, per la release per consumatore; e manifest-existing-secret.yaml a k8s-existing-secret, che non renderizza nulla e fa puntare ciascun consumatore a un Secret già presente nel namespace, per le release condivisa e composta.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `model-api-key-sharing`, chiama una volta lo strumento `scaffold` con `example` impostato su `model-api-key-sharing` e senza `dir`: scrive l’esempio in una nuova cartella `model-api-key-sharing`. Poi chiama lo strumento `build` una volta per ogni Release, in questo ordine — `release-per-consumer.yaml`, `release-shared.yaml` e `release-composed.yaml` — ogni volta con `workspace_root` impostato su `model-api-key-sharing`, `release` impostato su quel file, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto ciascuna build; si trovano in `model-api-key-sharing/dist/`.Per consumatore — ciascuna connessione detiene la propria chiave
aggregate-per-consumer.yaml riempie lo slot sulla connessione di ciascun agente, con un origin diverso per agente:
researcher: type: core/ai-agent/crewai uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: researcher-key-change-meUn’associazione su una connessione diventa una delle associazioni proprie dell’agente, con il nome della connessione e dello slot — qui gateway.credential — quindi vengono emessi due Secret, uno per agente, ciascuno con il materiale proprio di quell’agente:
[… omitted: the apiVersion and the Secret kind]metadata: name: researcher-gateway.credential [… omitted: the labels and annotations every rendered document carries]stringData: OPENAI_API_KEY: "researcher-key-change-me"
# dist/per-consumer/helm/writer--gateway-zdcredential--writer-secret-writer-gateway-credential.yaml[… omitted: the apiVersion and the Secret kind]metadata: name: writer-gateway.credential [… omitted: the labels and annotations every rendered document carries]stringData: OPENAI_API_KEY: "writer-key-change-me"e ciascun Deployment fa riferimento al proprio:
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: researcher-gateway.credential key: OPENAI_API_KEY
# dist/per-consumer/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: writer-gateway.credential key: OPENAI_API_KEYRevocare la chiave di un agente lascia l’altro in esecuzione.
Condivisa — un unico Secret, referenziato da ciascuna connessione
Una credenziale su una connessione viene scritta su quella connessione: nulla di associato altrove la riempie. Quindi più consumatori condividono una credenziale tramite l’authoring: la credenziale di ciascuna connessione legge lo stesso valore, e quel valore nomina un unico Secret.
aggregate-shared.yaml dichiara un parametro e lo legge su entrambe le connessioni:
parameters: team_model_key: type: string default: team-model-keycomponents: researcher: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: "{{ .parameters.team_model_key }}" writer: { ... } # the same credential, reading the same parameterLa release lega la credenziale a k8s-existing-secret, che legge origin come il nome di un Secret che esiste già nel namespace. Non renderizza alcun Secret — vengono scritti solo il Service del gateway e i due Deployment — ed entrambi i Deployment fanno riferimento all’unico Secret che il parametro nomina:
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEY
# dist/shared/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEYSi tratta esattamente di un unico Secret fisico, creato al di fuori della Release da chi la distribuisce, e letto da ogni consumatore. Il materiale della chiave non passa mai attraverso un file scritto dall’autore né un artefatto renderizzato.
Ciò che il parametro porta segue la realizzazione che il Manifest lega. Con k8s-existing-secret è il nome di un Secret. Se invece il legame è con k8s-secret-from-parameter, le stesse due connessioni che leggono un unico parametro porterebbero la chiave stessa, e il build renderizzerebbe un Secret per consumatore, ciascuno con lo stesso materiale: il rendering avviene per componente, e quella realizzazione nomina il Secret che renderizza in base al componente consumatore e alla connessione. L’unico parametro è ciò che impedisce ai consumatori di divergere; quale realizzazione lo legge decide se condividono una risorsa. Una credenziale generata nel cluster si condivide allo stesso modo — una richiesta e molti riferimenti; vedi Modello delle credenziali.
Composta — default condiviso, una connessione che lo sovrascrive
aggregate-composed.yaml mantiene il parametro condiviso come default e lascia che una connessione nomini un Secret proprio:
researcher: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: researcher-model-key # this connection's own Secretwriter: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: "{{ .parameters.team_model_key }}" # the shared defaultLa sovrascrittura è ciò che quella connessione scrive; nulla vi si propaga a cascata, e writer mantiene intatto il Secret condiviso:
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: researcher-model-key key: OPENAI_API_KEY
# dist/composed/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEYLa credenziale di una connessione è un’associazione intera a sé stante, quindi una sovrascrittura ridichiara ogni campo di cui ha bisogno — qui il tipo di Feature, key e origin — e non ne eredita nessuno dal default.
Che cosa offre lo slot
core/ai-agent/crewai dichiara lo slot una volta, sul suo socket model, e le tre forme sono tutte scelte fatte nell’Aggregate:
usesSchema: model: selector: "component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api" required: true inject: [env, file] featuresSchema: credential: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]Lo slot è facoltativo, quindi una quarta forma consiste nel non associare nulla: togli il blocco features: da entrambe le connessioni e l’albero renderizzato perde ogni voce env OPENAI_API_KEY, lasciando i due Deployment e il Service del gateway. Nulla viene inventato per colmare il vuoto. L’entità di catalogo è identica in ogni caso; decide l’autore.
Il build va a buon fine perché il gateway qui, core/ai-model/openai-compatible, non porta alcuna etichetta component.aggrega.ai/hosting. Una connessione che raggiunge una destinazione che il catalogo etichetta managed — core/ai-model/openai, per esempio — senza alcuna credenziale arresta il build sull’asserzione propria dell’agente, a meno che la connessione non dichiari nei suoi values che la destinazione non ne richiede alcuna, unauthenticated: true.
Lo slot è inoltre agnostico rispetto alla famiglia (feature.aggrega.ai/kind=secret ammette l’una o l’altra famiglia di credenziali), ed è ciò che consente allo stesso agente di accettare un Secret referenziabile su helm e una credenziale a valore iniettato su compose. Consegna delle credenziali — secretKeyRef dall’inizio alla fine illustra questa suddivisione tra provider, e la sua release negativa mostra che cosa succede quando a una credenziale non referenziabile viene chiesto di soddisfare un riferimento.
Determinismo
Tutte e tre le release eseguono il build con --verify-determinism, che renderizza ogni nodo due volte e confronta i byte emessi:
aggrega build --release release-shared.yaml --auto-pull --verify-determinismRicostruire una qualsiasi delle tre da un albero pulito ne riproduce l’output renderizzato byte per byte.