Credenciales en las conexiones — una clave por conexión, y una sola clave en ambos extremos
Un almacén de memoria semántica que llega a dos modelos y presenta una clave distinta a cada uno, compilado a manifiestos de Kubernetes. Lee el material ingerido con un modelo alojado y lo codifica con un servidor de embeddings que se ejecuta a su lado en el clúster. La clave que presenta al modelo alojado se obtiene de un almacén de secretos del clúster. El servidor de embeddings comprueba una clave propia, y el almacén presenta esa misma clave — ambos extremos la leen de un único parámetro, así que no se pueden escribir distintas.
Este espacio de trabajo no escribe ninguna entidad de catálogo propia. Cada Component, Feature y Recipe que nombra se incluye en el catálogo de la biblioteca estándar; los archivos de aquí — tres Aggregates, un Manifest y tres Releases — son todo lo que alguien escribe.
Lo que construye
┌── extraction_model ──► llm a hosted model API │ key on the connection, fetched from a secret store memory ───┤ │ └── embedding_model ──► embeddings an embedding server that checks a key key on the connection ═══ the server's own api_key (both read one parameter)| instancia | Component del catálogo | qué es aquí |
|---|---|---|
memory | core/datastore/cognee | el llamador: un almacén de memoria semántica cuyos dos sockets de modelo declaran cada uno un slot credential para la clave que presenta en esa conexión |
llm | core/ai-model/openai | un modelo alojado, etiquetado component.aggrega.ai/hosting: managed; alcanzado como referencia, así que nada se ejecuta para él en el clúster |
embeddings | core/ai-model/tei | Text Embeddings Inference en el clúster, etiquetado self-hosted; exige una clave a cada llamador y la guarda en su propio slot api_key |
Tres releases comparten un único Manifest, manifest.yaml, y cada una tiene un Aggregate propio:
| release | Aggregate | qué muestra |
|---|---|---|
release-matched.yaml | aggregate-matched.yaml | ambas conexiones escritas por el desarrollador, los dos extremos de la conexión de embeddings leyendo un único parámetro |
release-mismatched.yaml | aggregate-mismatched.yaml | lo mismo con los dos extremos leyendo dos parámetros: la compilación tiene éxito, y la comprobación de convenciones emite un aviso |
release-operator-wired.yaml | aggregate-operator-wired.yaml | la conexión de extracción dejada al operador: la Release la conecta y nombra su clave en infra |
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 connection-credentialsDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd connection-credentialsCompilación
Compila una release por ejecución:
aggrega build --release release-matched.yaml --auto-pull # → dist/matched/aggrega build --release release-mismatched.yaml --auto-pull # → dist/mismatched/aggrega build --release release-operator-wired.yaml --auto-pull # → dist/operator-wired/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 lockfile antes de compilarse, y los lockfiles se generan en lugar de incluirse. Resuelve uno primero, o deja que la compilación lo rellene:
aggrega pull --release release-matched.yaml # resolve, then build normallyaggrega build --release release-matched.yaml --auto-pull # or resolve during the buildEl espacio de trabajo resuelve sus entidades desde el registro predeterminado que nombra .aggrega-config.yaml, así que no hace falta ningún flag --catalog.
El comando pull imprime:
[… omitted: a warning that the declared-sensitive origin of llm.credential reaches the target with no per-key sensitivity marking, because its realization maps it through a valuesMapping]Pull complete: release-matched.lock (entities=15, source_artifacts=0, external_inputs=0)y la compilación, con <workspace> en lugar de la carpeta de este ejemplo:
[… omitted: the same warning about llm.credential the pull printed] notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: a total build time, which differs per run]Build completed: 8 files written to <workspace>/distLas otras dos releases imprimen las mismas líneas, cada comando pull nombrando su propio lockfile y cada compilación escribiendo ocho archivos. La línea notice: trata de la Feature de credenciales que usa cada vinculación aquí: core/referenced-secret acepta el nombre de su secreto, origin, tanto de los values del desarrollador como de la infra del operador, y el aviso informa de que una hoja está declarada en ambos pilares. No cambia ningún veredicto ni ningún byte renderizado; Features de credenciales explica por qué la hoja está en ambos.
Donde esta página imprime lo que produjo una compilación, el bloque está copiado de una ejecución real — consulta Leer la salida en estas páginas para la convención y la marca que usa para las líneas omitidas.
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 ninguna carpeta por tu cuenta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `connection-credentials`, llama una vez a la herramienta `scaffold` con `example` establecido en `connection-credentials` y sin `dir`: escribe el ejemplo en una nueva carpeta `connection-credentials`. Después llama a la herramienta `build` una vez por cada Release, en este orden — `release-matched.yaml`, `release-mismatched.yaml`, `release-operator-wired.yaml` — cada vez con `workspace_root` establecido en `connection-credentials`, `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 `connection-credentials/dist/`.El árbol renderizado
dist/matched/helm/├── embeddings-default-service.yaml├── embeddings-headless-service.yaml├── embeddings-statefulset.yaml├── llm-service.yaml├── memory--llm-zdcredential--memory-externalsecret-memory-memory-llm-credential.yaml├── memory-default-service.yaml├── memory-headless-service.yaml└── memory-statefulset.yamlUn archivo lo aportó una vinculación en lugar de la propia Recipe de un componente: el ExternalSecret que obtiene la clave que el almacén presenta al modelo alojado. Su nombre de archivo lleva el componente que lleva la vinculación, memory, y el nombre de la vinculación, llm.credential, escrito llm-zdcredential porque el punto comparte una sola cadena con el nombre propio del archivo; consulta Nombrar un recurso renderizado. Ningún archivo lleva la clave de embeddings: está en un Secret que el namespace ya tiene, como muestran las secciones siguientes.
Qué documento escribió qué
- El catálogo declara los puntos de enlace. El Component del almacén declara un slot
credentialen cada uno de sus dos sockets de modelo; el Component del servidor de embeddings declaraapi_keyen sí mismo; cada Recipe decide la variable con la que se entrega una clave. - El Aggregate — el desarrollador — escribe qué modelos alcanza el almacén, la credencial de cada conexión, la clave que verifica el servidor y el único parámetro que leen ambos extremos de la conexión de embeddings.
- El Manifest — el enrutamiento del operador para este destino — decide en qué se convierte cada credencial en Kubernetes: una referencia a un Secret que el namespace ya tiene para cada vinculación
core/referenced-secret, excepto la de la conexión al modelo alojado, que se obtiene de un almacén de secretos del clúster. - La Release — el documento del operador para un entorno — cumple los parámetros, coloca el límite en un namespace y, en la release conectada por el operador, conecta la conexión de extracción y nombra la clave que se presenta en ella.
Una clave por conexión
El almacén llega a dos modelos a través de dos sockets que declara su entidad de catálogo, extraction_model y embedding_model, y cada socket declara un slot credential. Así que la clave que presenta el almacén está en la conexión en la que se presenta, y cada conexión lleva la suya. De aggregate-matched.yaml:
memory: type: core/datastore/cognee values: # The width of the vectors the embedding model above returns. embedding_dimensions: 384 uses: extraction_model: llm: target: llm features: credential: # the key presented to the hosted model type: core/referenced-secret values: key: api-key origin: "{{ .parameters.provider_key_entry }}" embedding_model: embeddings: target: embeddings features: credential: # the key presented to the embedding server type: core/referenced-secret values: key: api-key origin: "{{ .parameters.embedding_key_secret }}"Una vinculación escrita en una conexión se convierte en una de las vinculaciones propias del almacén, con el nombre del alias de la conexión, un punto y el slot: llm.credential y embeddings.credential. Estas son las dos primeras y las cuatro últimas entradas del env del contenedor del almacén, de dist/matched/helm/memory-statefulset.yaml:
- name: LLM_API_KEY valueFrom: secretKeyRef: name: memory-llm.credential key: api-key- name: EMBEDDING_API_KEY valueFrom: secretKeyRef: name: embedding-server-key key: api-key[… omitted: the store's own settings, HTTP_PORT to EMBEDDING_DIMENSIONS]- name: EMBEDDING_ENDPOINT value: http://embeddings-default:8080/v1- name: EMBEDDING_MODEL value: BAAI/bge-small-en-v1.5- name: LLM_ENDPOINT value: https://api.openai.com/v1- name: LLM_MODEL value: gpt-4o-miniLas dos primeras son las claves, cada una de la credencial de su propia conexión, bajo la variable que la Recipe del almacén da a ese lado — LLM_API_KEY para la extracción, EMBEDDING_API_KEY para el embedding. Ambas son referencias, no valores, y el proveedor helm escribe las entradas que lee de un Secret antes que las simples. Las cuatro últimas proceden de las dos conexiones: cada modelo publica su dirección y su nombre de modelo, y la Recipe del almacén los lee por socket.
El Component del almacén también declara un slot de clave en sí mismo, model_api_key. Su Recipe lee ese slot solo para un socket que se deja sin conectar, donde el almacén llega a un proveedor en la dirección propia del proveedor y no hay ninguna conexión que lleve una clave. Aquí ambos sockets están conectados, así que no se lee.
Una sola clave en ambos extremos
El servidor de embeddings comprueba una clave. Guarda esa clave en un slot de su propio Component, api_key, y su Recipe entrega lo que llene el slot como API_KEY, la variable que Text Embeddings Inference lee al arrancar. De aggregate-matched.yaml:
embeddings: type: core/ai-model/tei values: model: BAAI/bge-small-en-v1.5 features: api_key: # the key the server verifies type: core/referenced-secret values: key: api-key origin: "{{ .parameters.embedding_key_secret }}"Esa es una vinculación en el servidor. La clave que presenta el almacén es otra, en la conexión del almacén, mostrada arriba. Llenar el slot de un extremo no llena nada en el otro, así que declarar la clave en ambos extremos es el mínimo y no un duplicado. Lo que hace de las dos una sola clave es que ambas leen un único parámetro, embedding_key_secret, que el Aggregate declara y la Release cumple:
parameters: provider_key_entry: ai/openai-api-key embedding_key_secret: embedding-server-keyEl Manifest enlaza core/referenced-secret con k8s-existing-secret, que lee origin como el nombre de un Secret que el namespace ya tiene y no renderiza nada. Así que ambos extremos referencian ese único Secret. En el env del contenedor del servidor, de dist/matched/helm/embeddings-statefulset.yaml:
- name: API_KEY valueFrom: secretKeyRef: name: embedding-server-key key: api-keyy en el del almacén, de dist/matched/helm/memory-statefulset.yaml:
- name: EMBEDDING_API_KEY valueFrom: secretKeyRef: name: embedding-server-key key: api-keyEl Secret se crea fuera de la Release, por quien la despliegue, así que el material de la clave nunca pasa por un archivo escrito ni por un artefacto renderizado.
Por qué el servidor nunca ve las claves de sus llamadores
Una vinculación en una conexión va a parar solo al llamador. Las dos credenciales del almacén son vinculaciones del almacén: lo que renderizan está junto al almacén, y el contenedor del almacén lo referencia. Nada de ellas llega al componente al que apunta una conexión, así que un destino se renderiza igual lleven lo que lleven las conexiones que llegan a él.
El modelo alojado lo muestra claramente. Renderiza un archivo, un Service que asigna un nombre interno del clúster al host del proveedor — el spec completo de dist/matched/helm/llm-service.yaml:
spec: type: ExternalName externalName: api.openai.com ports: - port: 443La clave que le presenta el almacén se obtiene junto al almacén, como muestra la sección siguiente. El servidor de embeddings lo muestra por comparación: la release discordante de más abajo cambia la clave en la conexión de embeddings del almacén y deja intacta la del servidor, y los tres archivos del servidor en dist/mismatched/ difieren de los de dist/matched/ solo en la etiqueta aggrega.ai/aggregate-name, que nombra el Aggregate a partir del que se compiló cada uno.
Así que nada en la configuración del servidor nombra una clave que tenga un llamador. En tiempo de ejecución, una solicitud lleva la clave del llamador y el servidor la compara con la que tiene; el llamador, por su parte, solo lee lo que publica el servidor: una dirección y un nombre de modelo.
Una clave por servidor
Text Embeddings Inference comprueba una sola clave. Todo llamador presenta la misma clave, un llamador que presente otra se rechaza, y el servidor no puede distinguir un llamador de otro, así que retirar el acceso a un llamador significa cambiar la clave que presentan todos los llamadores. Lleguen a él cuantas conexiones lleguen, su slot api_key contiene una sola clave. Ese límite es propio del servidor, y core/ai-model/vllm y core/ai-model/tgi del catálogo lo comparten. No es un límite de la conexión: un llamador que llega a varios servidores tiene una clave por conexión, como el almacén de aquí tiene dos.
La clave de una conexión desde un almacén de secretos
El Manifest enlaza cada vinculación core/referenced-secret por su tipo, y una de ellas por su nombre. De manifest.yaml:
features: # One realization for every core/referenced-secret attachment: the Secret # already exists in the namespace, and origin is its name. type: core/referenced-secret:1.0.0: helm/k8s-existing-secret:1.0.0 # One attachment bound differently, by its name. An attachment written on # a connection is named for the connection's alias, a dot and the slot, # so the memory store's credential on its llm connection is # llm.credential. That key is fetched from the store, and origin is the # store entry to fetch. name: llm.credential: helm/k8s-external-secret:1.0.0k8s-external-secret lee origin como la entrada del almacén de secretos que hay que obtener. El origin de la conexión es el parámetro provider_key_entry, cumplido como ai/openai-api-key, así que la vinculación renderiza un ExternalSecret que un operador del almacén de secretos en el clúster reconcilia en un Secret. El spec completo de dist/matched/helm/memory--llm-zdcredential--memory-externalsecret-memory-memory-llm-credential.yaml:
spec: refreshInterval: "1h" secretStoreRef: name: platform-secret-store kind: ClusterSecretStore target: name: memory-llm.credential creationPolicy: Owner data: - secretKey: api-key remoteRef: key: "ai/openai-api-key"El Secret que rellena, memory-llm.credential, lleva el nombre del almacén y de la conexión, y es el nombre que referencia más arriba el LLM_API_KEY del almacén. La realización lee de un ClusterSecretStore llamado platform-secret-store.
Lo que lleva un parámetro se deriva de la realización que lo lee: una entrada del almacén de secretos para la clave del modelo alojado, el nombre de un Secret para la clave de embeddings. La clave de una conexión recibe una realización propia mientras todas las demás vinculaciones del mismo tipo conservan la del tipo.
Dónde resuelven un secreto los dos extremos
Una plataforma de destino resuelve un secreto por referencia dentro de un ámbito de secretos: el límite dentro del cual un recurso puede nombrar a otro. Donde ambos extremos de una conexión están en un mismo ámbito, ambos referencian un único recurso de secreto. Donde están en ámbitos distintos, cada extremo tiene un recurso de secreto propio, realizado a partir de la misma entrada del almacén de secretos. El Manifest elige la realización de cada extremo — por tipo de Feature para cada vinculación de ese tipo, o para una sola vinculación por su nombre.
Cada destino traza el ámbito en sus propios términos. En Kubernetes, para el que compila este espacio de trabajo, es el namespace: una carga de trabajo referencia un Secret solo en el suyo. Cada release de aquí coloca su único límite en un único namespace, aggrega.ai/namespace: memory, y cada documento renderizado lo lleva — la cabecera de ambos StatefulSets:
metadata: name: memory namespace: memory
# dist/matched/helm/embeddings-statefulset.yamlmetadata: name: embeddings namespace: memoryAsí que ambos extremos referencian el único Secret de arriba. Con el servidor de embeddings en un namespace propio, el Manifest enlaza las credenciales de ambos extremos por nombre — api_key y embeddings.credential — con k8s-external-secret, la Release cumple el parámetro con la entrada del almacén de secretos, y cada extremo tiene un ExternalSecret en su propio namespace, y ambos obtienen esa única entrada. El almacén llega entonces al servidor a través de namespaces, lo que trata cross-boundary-networking. En los demás destinos, el ámbito es un proyecto de Compose, una configuración raíz de Terraform y un stack de CloudFormation; el Modelo de credenciales describe cada uno.
El operador establece una conexión
aggregate-operator-wired.yaml escribe la conexión de embeddings y deja sin enlazar el socket extraction_model del almacén: la entidad de catálogo del almacén lo declara, y el desarrollador lo deja al operador. La Release lo conecta al modelo alojado que declara el Aggregate. De release-operator-wired.yaml:
memory: uses: # A connection the Aggregate does not write, into a socket the # store's catalog entity declares, to a component the Aggregate # declares. A Release writes no values, so the credential on it # names its secret in infra. extraction_model: llm: target: llm features: credential: type: core/referenced-secret infra: origin: ai/openai-api-keyUna Release puede establecer una conexión en un socket que la entidad de catálogo declara y el Aggregate deja sin enlazar, hacia un componente que el Aggregate declara. No añade ningún componente, y nunca cambia el destino de una conexión que escribió el Aggregate. No escribe ningún values, así que la credencial de esa conexión nombra su secreto en infra: core/referenced-secret toma origin de los values del desarrollador o de la infra del operador, exactamente de uno de los dos, y la compilación se detiene ante una vinculación que lleve ambos o ninguno.
La vinculación se llama llm.credential exactamente como en la release concordante, así que el nivel de nombres del Manifest la enlaza de la misma manera. Aparte de la etiqueta que nombra el Aggregate, dos líneas difieren entre dist/operator-wired/ y dist/matched/. El data del ExternalSecret:
data: - secretKey: value remoteRef: key: "ai/openai-api-key"y la referencia del almacén al Secret que rellena, en dist/operator-wired/helm/memory-statefulset.yaml:
- name: LLM_API_KEY valueFrom: secretKeyRef: name: memory-llm.credential key: valueLa clave de datos es value en lugar de api-key porque key es una hoja de values, que solo escribe el Aggregate, así que una vinculación que hace solo la Release lee el valor predeterminado de la Feature. La realización publica esa clave y el almacén la lee de lo publicado, así que los dos siguen coincidiendo.
El modelo alojado está etiquetado managed, así que una conexión que llega a él lleva una credencial o indica en sus propios values que el modelo no requiere ninguna, unauthenticated: true. Eso se cumple sea cual sea el documento que escribió la conexión. Quita el bloque features: de la conexión de la Release y la compilación se detiene. La detención es E0033, una aserción fallida del Component del almacén, y su mensaje termina con la frase propia de la regla: the extraction_model connection llm of “memory” reaches “llm”, whose component.aggrega.ai/hosting label is managed, with no credential: attach one under credential on that connection, or set unauthenticated: true in its values (la conexión extraction_model llm de «memory» llega a «llm», cuya etiqueta component.aggrega.ai/hosting es managed, sin ninguna credencial: vincula una bajo credential en esa conexión, o establece unauthenticated: true en sus values).
Cuando los dos extremos no coinciden
aggregate-mismatched.yaml da a la clave del servidor y a la clave del almacén dos parámetros:
parameters: provider_key_entry: type: string description: > The store entry holding the key the memory store presents to the hosted model provider. embedding_key_secret: type: string description: The Secret holding the key the embedding server verifies. # The fault: a second parameter for what is meant to be the same key. memory_embedding_key_secret: type: string description: The Secret holding the key the memory store presents to the embedding server.La api_key del servidor lee embedding_key_secret y la conexión del almacén lee memory_embedding_key_secret, que la Release cumple con dos Secrets distintos. La compilación tiene éxito y escribe ocho archivos: el compilador evalúa cada vinculación que recibe y no compara nada entre los dos extremos. El servidor sigue referenciando embedding-server-key, y el almacén ahora presenta otro, de dist/mismatched/helm/memory-statefulset.yaml:
- name: EMBEDDING_API_KEY valueFrom: secretKeyRef: name: embedding-client-key key: api-keyUna vez desplegado, el servidor solo acepta las solicitudes del almacén si esos dos Secrets resultan contener la misma clave.
La comprobación de convenciones de publicación de una Release es donde se detecta esto:
aggrega lint --release release-mismatched.yamlrelease-mismatched.yaml:warn: E0329 connection-credential-matches-target-key: connection "embeddings" on socket "embedding_model" of component "memory" carries a credential in its credential slot and its target "embeddings" holds a key in its api_key slot, but the two ends write their secret's locator differently, so they may name different secrets and the target would refuse the key this caller presents. The locators are compared as written, and neither is shown here. Reading one parameter at both ends keeps them one key; that agreement is the standard-catalog convention, and the build does not check it.conventions checked: 10 entities, 1 advisory finding(s)La misma comprobación sobre la release concordante no informa de nada:
aggrega lint --release release-matched.yamlconventions checked: 10 entities, 0 advisory finding(s)y sobre la release conectada por el operador, tampoco.
La regla encuentra los dos extremos por los nombres que les da el catálogo estándar — la api_key del destino y la credential de la conexión — y compara el origin que escribe cada extremo, tal como está escrito: dos extremos que leen un mismo parámetro resultan iguales, y no se resuelve nada. Nunca cita ninguno de los dos, ya que lo que hay escrito ahí puede ser el propio secreto. No juzga un destino etiquetado managed, cuya api_key, donde declara una, es la clave que se presenta a su proveedor y no una que presentan sus llamadores; así que la conexión a llm no genera nada en ninguna de las tres releases. El hallazgo es una recomendación: aggrega lint termina con 0, y un espacio de trabajo cuyos dos extremos difieren deliberadamente se excluye con allow_connection_credential_mismatches. Un editor que hace al daemon la misma pregunta, aggrega/lint nombrando la Release, recibe el mismo hallazgo bajo el código connection-credential-matches-target-key y el código corto E0329. La regla y lo que lee se describen en Las reglas de disciplina.
Determinismo
Las tres releases se compilan con --verify-determinism, que renderiza cada nodo dos veces y compara los bytes emitidos:
aggrega build --release release-matched.yaml --verify-determinismRecompilar cualquiera de las tres desde un árbol limpio reproduce su salida renderizada byte a byte.
Adaptarlo
- Añade un segundo llamador del servidor de embeddings. La credencial de su conexión también lee
embedding_key_secret. El servidor tiene una sola clave para todos los llamadores, así que el segundo llamador presenta la misma clave. - Obtén también la clave de embeddings del almacén de secretos. Enlaza
api_keyyembeddings.credentialpor nombre conk8s-external-secrety cumpleembedding_key_secretcon una entrada del almacén de secretos en lugar del nombre de un Secret. Ambos extremos cambian a la vez porque ambos leen el parámetro. - Llega a un modelo que no comprueba ninguna clave. Deja la credencial fuera de la conexión. Donde el destino esté etiquetado
managed, indícalo en la conexión conunauthenticated: trueen susvalues.
Para compartir una clave entre las conexiones de varios llamadores, consulta model-api-key-sharing. Para un router que tiene las claves de los proveedores en nombre de sus llamadores, consulta ai-agent-and-model-router. El modelo detrás de todo ello es el Modelo de credenciales.