Compartir una credencial — por consumidor, compartida, y ambas a la vez
Dos agentes de CrewAI detrás de un único gateway compatible con OpenAI. El socket model de cada agente declara un slot credential, así que la clave que un agente presenta al modelo al que llega se vincula en esa conexión. Este espacio de trabajo rellena el slot de tres maneras sin cambiar ni una sola entidad de catálogo: una clave por conexión, un único Secret al que hacen referencia todas las conexiones, y un valor predeterminado compartido que una conexión sobrescribe.
Lo esencial son los dos consumidores. Las tres formas son indistinguibles con un solo consumidor — la diferencia es a qué Secret acaba apuntando cada consumidor, y esa pregunta no tiene contenido hasta que hay más de un consumidor.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example model-api-key-sharingDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd model-api-key-sharingCompilación
Tres releases, una por forma. Compila una por ejecución:
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/Cada release escribe en su propio directorio, así que los tres árboles renderizados coexisten y se pueden comparar entre sí con un diff.
Una release necesita su archivo de bloqueo antes de compilarse. En un checkout nuevo, resuelve uno primero — ya sea como paso propio o dejando que la compilación lo rellene:
aggrega pull --release release-shared.yaml # resolve, then build normallyaggrega build --release release-shared.yaml --auto-pull # or resolve during the buildLas releases resuelven sus entidades de catálogo desde el catálogo configurado, así que no hace falta ningún flag --catalog.
Las tres se compilan en el destino helm, deliberadamente. Lo observable que distingue las tres formas es el nombre del Secret al que hace referencia el contenedor de cada agente, y helm es donde una credencial es un Secret de Kubernetes con nombre al que un contenedor hace referencia por su nombre. Dos Manifests enlazan la credencial: manifest.yaml con k8s-secret-from-parameter, que renderiza un Secret a partir del valor que lleva la vinculación, para la release por consumidor; y manifest-existing-secret.yaml con k8s-existing-secret, que no renderiza nada y hace apuntar a cada consumidor a un Secret que ya está en el namespace, para las releases compartida y compuesta.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees tú ninguna carpeta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `model-api-key-sharing`, llama una vez a la herramienta `scaffold` con `example` establecido en `model-api-key-sharing` y sin `dir`: escribe el ejemplo en una nueva carpeta `model-api-key-sharing`. Después llama a la herramienta `build` una vez por cada Release, en este orden — `release-per-consumer.yaml`, `release-shared.yaml` y `release-composed.yaml` —, cada vez con `workspace_root` establecido en `model-api-key-sharing`, `release` establecido en ese archivo, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió cada compilación; están en `model-api-key-sharing/dist/`.Por consumidor — cada conexión tiene su propia clave
aggregate-per-consumer.yaml rellena el slot en la conexión de cada agente, con un origin distinto por 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-meUna vinculación en una conexión se convierte en una de las vinculaciones propias del agente, con el nombre de la conexión y del slot — aquí gateway.credential — así que se emiten dos Secrets, uno por agente, cada uno con el material propio de ese 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"y cada Deployment referencia el suyo:
- 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_KEYRevocar la clave de un agente deja al otro en funcionamiento.
Compartida — un único Secret, referenciado desde cada conexión
Una credencial en una conexión se escribe en esa conexión: nada vinculado en otro lugar la rellena. Así que varios consumidores comparten una credencial mediante la autoría: la credencial de cada conexión lee el mismo valor, y ese valor nombra un único Secret.
aggregate-shared.yaml declara un parámetro y lo lee en ambas conexiones:
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 enlaza la credencial con k8s-existing-secret, que lee origin como el nombre de un Secret que ya existe en el namespace. No renderiza ningún Secret — solo se escriben el Service del gateway y los dos Deployments — y ambos Deployments referencian el único Secret que nombra el parámetro:
- 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_KEYEso es exactamente un Secret físico, creado fuera de la Release por quien la despliega, y leído por cada consumidor. El material de la clave nunca pasa por un archivo escrito por el autor ni por un artefacto renderizado.
Lo que lleva el parámetro sigue la realización que enlaza el Manifest. Con k8s-existing-secret es el nombre de un Secret. Si la credencial se enlazara en cambio con k8s-secret-from-parameter, las mismas dos conexiones que leen un único parámetro llevarían la clave misma, y la compilación renderizaría un Secret por consumidor, cada uno con el mismo material: el renderizado se hace por componente, y esa realización nombra el Secret que renderiza según el componente consumidor y la conexión. El parámetro único es lo que evita que los consumidores se desvíen entre sí; qué realización lo lee decide si comparten un recurso. Una credencial generada en el clúster se comparte de la misma manera — una solicitud y muchas referencias; consulta Modelo de credenciales.
Compuesta — valor predeterminado compartido, una conexión que lo sobrescribe
aggregate-composed.yaml mantiene el parámetro compartido como valor predeterminado y deja que una conexión nombre un Secret propio:
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 sobrescritura es lo que escribe esa única conexión; nada se propaga en cascada hacia ella, y writer conserva intacto el Secret compartido:
- 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 credencial de una conexión es una vinculación completa propia, así que una sobrescritura vuelve a declarar cada campo que necesita — aquí el tipo de Feature, key y origin — y no hereda ninguno del valor predeterminado.
Lo que aporta el slot
core/ai-agent/crewai declara el slot una vez, en su socket model, y las tres formas son todas elecciones hechas en el 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]El slot es opcional, así que una cuarta forma es no vincular nada en absoluto: quita el bloque features: de ambas conexiones y el árbol renderizado pierde cada entrada env OPENAI_API_KEY, y quedan los dos Deployments y el Service del gateway. No se inventa nada para llenar el hueco. La entidad de catálogo es idéntica en todos los casos; decide el autor.
Eso se compila porque el gateway de aquí, core/ai-model/openai-compatible, no lleva ninguna etiqueta component.aggrega.ai/hosting. Una conexión que llega a un destino que el catálogo etiqueta managed — core/ai-model/openai, por ejemplo — sin ninguna credencial detiene la compilación en la aserción propia del agente, a menos que la conexión indique en sus values que el destino no requiere ninguna, unauthenticated: true.
El slot es además agnóstico respecto a la familia (feature.aggrega.ai/kind=secret admite cualquiera de las dos familias de credenciales), que es lo que permite al mismo agente aceptar un Secret referenciable en helm y una credencial de valor inyectado en compose. Entrega de credenciales — secretKeyRef de extremo a extremo desarrolla esa división por proveedor, y su release negativa muestra qué ocurre cuando se pide a una credencial no referenciable que satisfaga una referencia.
Determinismo
Las tres releases se compilan con --verify-determinism, que renderiza cada nodo dos veces y compara los bytes emitidos:
aggrega build --release release-shared.yaml --auto-pull --verify-determinismRecompilar cualquiera de las tres desde un árbol limpio reproduce su salida renderizada byte a byte.