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

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:

Terminal window
aggrega scaffold --example model-api-key-sharing

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd model-api-key-sharing

Build

Tre release, una per forma. Esegui il build di una per esecuzione:

Terminal window
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:

Terminal window
aggrega pull --release release-shared.yaml # resolve, then build normally
aggrega build --release release-shared.yaml --auto-pull # or resolve during the build

Le 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-me

Un’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:

dist/per-consumer/helm/researcher--gateway-zdcredential--researcher-secret-researcher-gateway-credential.yaml
[… 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:

dist/per-consumer/helm/researcher-deployment.yaml
- 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_KEY

Revocare 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-key
components:
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 parameter

La 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:

dist/shared/helm/researcher-deployment.yaml
- 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_KEY

Si 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 Secret
writer:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: "{{ .parameters.team_model_key }}" # the shared default

La sovrascrittura è ciò che quella connessione scrive; nulla vi si propaga a cascata, e writer mantiene intatto il Secret condiviso:

dist/composed/helm/researcher-deployment.yaml
- 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_KEY

La 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:

Terminal window
aggrega build --release release-shared.yaml --auto-pull --verify-determinism

Ricostruire una qualsiasi delle tre da un albero pulito ne riproduce l’output renderizzato byte per byte.