Partager une information d’identification — par consommateur, partagée, et les deux à la fois
Deux agents CrewAI derrière une seule passerelle compatible avec OpenAI. Le socket model de chaque agent déclare un slot credential, si bien que la clé qu’un agent présente au modèle qu’il atteint est rattachée sur cette connexion. Cet espace de travail remplit le slot de trois façons sans modifier une seule entité de catalogue : une clé par connexion, un seul Secret référencé par toutes les connexions, et une valeur par défaut partagée qu’une connexion remplace.
Deux consommateurs, c’est tout l’enjeu. Les trois formes sont indiscernables avec un seul consommateur — la différence est quel Secret chaque consommateur finit par désigner, et cette question n’a pas de contenu tant qu’il n’y a pas plus d’un consommateur.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example model-api-key-sharingElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd model-api-key-sharingBuild
Trois releases, une par forme. Construisez-en une par exécution :
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/Chaque release écrit dans son propre répertoire, si bien que les trois arborescences rendues coexistent et peuvent être comparées entre elles avec un diff.
Une release a besoin de son fichier de verrouillage avant de se construire. Sur un checkout récent, résolvez-en d’abord un — soit comme étape à part, soit en laissant le build le remplir :
aggrega pull --release release-shared.yaml # resolve, then build normallyaggrega build --release release-shared.yaml --auto-pull # or resolve during the buildLes releases résolvent leurs entités de catalogue depuis le catalogue configuré, si bien qu’aucun flag --catalog n’est nécessaire.
Les trois se construisent sur la cible helm, délibérément. L’élément observable qui distingue les trois formes est le nom du Secret que référence le conteneur de chaque agent, et helm est l’endroit où une information d’identification est un Secret Kubernetes nommé qu’un conteneur référence par son nom. Deux Manifests lient l’information d’identification : manifest.yaml à k8s-secret-from-parameter, qui rend un Secret à partir de la valeur que porte le rattachement, pour la release par consommateur ; et manifest-existing-secret.yaml à k8s-existing-secret, qui ne rend rien et fait pointer chaque consommateur vers un Secret déjà présent dans le namespace, pour les releases partagée et composée.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `model-api-key-sharing`, appelez une fois l’outil `scaffold` avec `example` défini sur `model-api-key-sharing` et sans `dir` : il écrit l’exemple dans un nouveau dossier `model-api-key-sharing`. Appelez ensuite l’outil `build` une fois pour chaque Release, dans cet ordre — `release-per-consumer.yaml`, `release-shared.yaml` et `release-composed.yaml` —, chaque fois avec `workspace_root` défini sur `model-api-key-sharing`, `release` défini sur ce fichier, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers chaque build a écrits ; ils se trouvent sous `model-api-key-sharing/dist/`.Par consommateur — chaque connexion détient sa propre clé
aggregate-per-consumer.yaml remplit le slot sur la connexion de chaque agent, avec un origin différent par agent :
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 rattachement sur une connexion devient l’un des rattachements propres de l’agent, nommé d’après la connexion et le slot — ici gateway.credential — si bien que deux Secrets sont émis, un par agent, chacun portant le matériel propre à cet agent :
[… 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"et chaque Deployment référence le sien :
- 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_KEYRévoquer la clé d’un agent laisse l’autre en fonctionnement.
Partagée — un seul Secret, référencé depuis chaque connexion
Une information d’identification sur une connexion s’écrit sur cette connexion : rien de rattaché ailleurs ne la remplit. Plusieurs consommateurs partagent donc une information d’identification par la rédaction : l’information d’identification de chaque connexion lit la même valeur, et cette valeur nomme un seul Secret.
aggregate-shared.yaml déclare un paramètre et le lit sur les deux connexions :
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 lie l’information d’identification à k8s-existing-secret, qui lit origin comme le nom d’un Secret qui existe déjà dans le namespace. Elle ne rend aucun Secret — seuls le Service de la passerelle et les deux Deployments sont écrits — et les deux Deployments référencent l’unique Secret que nomme le paramètre :
- 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_KEYIl s’agit d’exactement un Secret physique, créé en dehors de la Release par celui qui la déploie, et lu par chaque consommateur. Le matériel de la clé ne passe jamais par un fichier rédigé ni par un artefact rendu.
Ce que porte le paramètre suit la réalisation que lie le Manifest. Sous k8s-existing-secret, c’est le nom d’un Secret. Si l’information d’identification était plutôt liée à k8s-secret-from-parameter, les deux mêmes connexions lisant un seul paramètre porteraient la clé elle-même, et le build rendrait un Secret par consommateur, chacun contenant le même matériel : le rendu s’effectue par composant, et cette réalisation nomme le Secret qu’elle rend d’après le composant consommateur et la connexion. C’est le paramètre unique qui empêche les consommateurs de diverger ; la réalisation qui le lit décide s’ils partagent une ressource. Une information d’identification générée dans le cluster se partage de la même façon — une demande et de nombreuses références ; voir Modèle des informations d’identification.
Composée — valeur par défaut partagée, une connexion qui la remplace
aggregate-composed.yaml garde le paramètre partagé comme valeur par défaut et laisse une connexion nommer un Secret qui lui est propre :
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 defaultLe remplacement est ce que rédige cette seule connexion ; rien ne se propage en cascade sur elle, et writer garde le Secret partagé intact :
- 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_KEYL’information d’identification d’une connexion est un rattachement entier à part, si bien qu’un remplacement redéclare chaque champ dont il a besoin — ici le type de Feature, key et origin — et n’en hérite aucun de la valeur par défaut.
Ce que le slot apporte
core/ai-agent/crewai déclare le slot une seule fois, sur son socket model, et les trois formes sont toutes des choix faits dans l’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]Le slot est facultatif, si bien qu’une quatrième forme consiste à ne rien rattacher du tout : retirez le bloc features: des deux connexions et l’arborescence rendue perd chaque entrée env OPENAI_API_KEY, en laissant les deux Deployments et le Service de la passerelle. Rien n’est inventé pour combler le manque. L’entité de catalogue est identique dans tous les cas ; c’est l’auteur qui décide.
Cela se construit parce que la passerelle ici, core/ai-model/openai-compatible, ne porte aucun label component.aggrega.ai/hosting. Une connexion atteignant une cible que le catalogue étiquette managed — core/ai-model/openai, par exemple — sans information d’identification arrête le build sur l’assertion propre de l’agent, à moins que la connexion n’indique dans ses values que la cible n’en demande aucune, unauthenticated: true.
Le slot est également agnostique vis-à-vis de la famille (feature.aggrega.ai/kind=secret admet l’une ou l’autre famille d’informations d’identification), ce qui permet au même agent d’accepter un Secret référençable sur helm et une information d’identification à valeur injectée sur compose. Livraison des informations d’identification — secretKeyRef de bout en bout détaille cette répartition par fournisseur, et sa release négative montre ce qui se passe quand on demande à une information d’identification non référençable de satisfaire une référence.
Déterminisme
Les trois releases se construisent sous --verify-determinism, qui rend chaque nœud deux fois et compare les octets émis :
aggrega build --release release-shared.yaml --auto-pull --verify-determinismReconstruire n’importe laquelle des trois à partir d’une arborescence propre reproduit sa sortie rendue octet pour octet.