Credenciais em conexões — uma chave por conexão, e uma única chave nas duas pontas
Um repositório de memória semântica que alcança dois modelos e apresenta uma chave diferente a cada um, compilado para manifestos do Kubernetes. Ele lê o material ingerido com um modelo hospedado e o codifica com um servidor de embeddings executado ao lado dele no cluster. A chave que ele apresenta ao modelo hospedado é obtida de um repositório de segredos do cluster. O servidor de embeddings verifica uma chave própria, e o repositório apresenta essa mesma chave — as duas pontas a leem de um único parâmetro, então as duas não podem ser escritas de forma diferente.
Este espaço de trabalho não escreve nenhuma entidade de catálogo própria. Cada Component, Feature e Recipe que ele nomeia vem no catálogo da biblioteca padrão; os arquivos aqui — três Aggregates, um Manifest e três Releases — são tudo o que alguém escreve.
O que ele constrói
┌── 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)| instância | Component do catálogo | o que é aqui |
|---|---|---|
memory | core/datastore/cognee | o chamador: um repositório de memória semântica cujos dois sockets de modelo declaram cada um um slot credential para a chave que ele apresenta nessa conexão |
llm | core/ai-model/openai | um modelo hospedado, rotulado component.aggrega.ai/hosting: managed; alcançado como referência, então nada é executado para ele no cluster |
embeddings | core/ai-model/tei | Text Embeddings Inference no cluster, rotulado self-hosted; ele exige uma chave de cada chamador e a mantém no seu próprio slot api_key |
Três releases compartilham um único Manifest, manifest.yaml, e cada uma tem um Aggregate próprio:
| release | Aggregate | o que mostra |
|---|---|---|
release-matched.yaml | aggregate-matched.yaml | as duas conexões escritas pelo desenvolvedor, as duas pontas da conexão de embeddings lendo um único parâmetro |
release-mismatched.yaml | aggregate-mismatched.yaml | o mesmo com as duas pontas lendo dois parâmetros: o build é concluído, e a verificação de convenções emite um aviso |
release-operator-wired.yaml | aggregate-operator-wired.yaml | a conexão de extração deixada ao operador: a Release a liga e nomeia a sua chave em infra |
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example connection-credentialsEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd connection-credentialsBuild
Faça o build de uma release por execução:
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 escreve no seu próprio diretório, então as três árvores renderizadas coexistem e podem ser comparadas entre si com um diff.
Uma release precisa do seu lockfile antes do build, e os lockfiles são gerados em vez de distribuídos com o exemplo. Resolva um primeiro, ou deixe o build preenchê-lo:
aggrega pull --release release-matched.yaml # resolve, then build normallyaggrega build --release release-matched.yaml --auto-pull # or resolve during the buildO espaço de trabalho resolve as suas entidades a partir do registro padrão que .aggrega-config.yaml nomeia, então nenhuma flag --catalog é necessária.
O 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)e o build, com <workspace> representando a pasta deste exemplo:
[… 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>/distAs outras duas releases imprimem as mesmas linhas, cada comando pull nomeando o seu próprio lockfile e cada build escrevendo oito arquivos. A linha notice: diz respeito à Feature de credenciais que toda vinculação aqui usa: core/referenced-secret aceita o nome do seu segredo, origin, tanto dos values do desenvolvedor quanto da infra do operador, e o aviso informa que uma folha está declarada nos dois pilares. Ele não muda nenhum veredito nem nenhum byte renderizado; Features de credenciais explica por que a folha fica nos dois.
Onde esta página imprime o que um build produziu, o bloco é copiado de uma execução real — veja Lendo a saída nestas páginas para a convenção e a marca que ela usa para as linhas omitidas.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use somente as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do espaço de trabalho ainda não contém uma pasta `connection-credentials`, chame uma vez a ferramenta `scaffold` com `example` definido como `connection-credentials` e sem `dir`: ela grava o exemplo em uma nova pasta `connection-credentials`. Em seguida, chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-matched.yaml`, `release-mismatched.yaml`, `release-operator-wired.yaml` — cada vez com `workspace_root` definido como `connection-credentials`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam em `connection-credentials/dist/`.A árvore renderizada
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.yamlUm arquivo foi trazido por uma vinculação em vez da própria Recipe de um componente: o ExternalSecret que obtém a chave que o repositório apresenta ao modelo hospedado. O seu nome de arquivo traz o componente que recebe a vinculação, memory, e o nome da vinculação, llm.credential, escrito llm-zdcredential porque o ponto compartilha uma única string com o próprio nome do arquivo; veja Nomeando um recurso renderizado. Nenhum arquivo traz a chave de embeddings: ela fica em um Secret que o namespace já mantém, como mostram as seções abaixo.
Qual documento escreveu o quê
- O catálogo declara os pontos de vínculo. O Component do repositório declara um slot
credentialem cada um dos seus dois sockets de modelo; o Component do servidor de embeddings declaraapi_keyem si mesmo; cada Recipe decide a variável em que uma chave é entregue. - O Aggregate — o desenvolvedor — escreve quais modelos o repositório alcança, a credencial em cada conexão, a chave que o servidor verifica e o único parâmetro que as duas pontas da conexão de embeddings leem.
- O Manifest — o roteamento do operador para este destino — decide o que cada credencial se torna no Kubernetes: uma referência a um Secret que o namespace já mantém para toda vinculação
core/referenced-secret, exceto a da conexão com o modelo hospedado, que é obtida de um repositório de segredos do cluster. - A Release — o documento do operador para um ambiente — preenche os parâmetros, coloca a fronteira em um namespace e, na release ligada pelo operador, liga a conexão de extração e nomeia a chave apresentada nela.
Uma chave por conexão
O repositório alcança dois modelos por meio de dois sockets que a sua entidade de catálogo declara, extraction_model e embedding_model, e cada socket declara um slot credential. Assim, a chave que o repositório apresenta fica na conexão em que é apresentada, e cada conexão traz a sua. 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 }}"Uma vinculação escrita em uma conexão se torna uma das vinculações próprias do repositório, nomeada a partir do alias da conexão, de um ponto e do slot: llm.credential e embeddings.credential. Aqui estão as duas primeiras e as quatro últimas entradas do env do contêiner do repositório, 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-miniAs duas primeiras são as chaves, cada uma da credencial na sua própria conexão, sob a variável que a Recipe do repositório dá a esse lado — LLM_API_KEY para a extração, EMBEDDING_API_KEY para o embedding. Ambas são referências, não valores, e o provedor helm escreve as entradas que lê de um Secret antes das simples. As últimas quatro vieram das duas conexões: cada modelo publica o seu endereço e o seu nome de modelo, e a Recipe do repositório os lê por socket.
O Component do repositório também declara um slot de chave em si mesmo, model_api_key. A sua Recipe lê esse slot apenas para um socket deixado sem ligação, em que o repositório alcança um provedor no próprio endereço do provedor e não há conexão para trazer uma chave. Os dois sockets estão ligados aqui, então ele não é lido.
Uma única chave nas duas pontas
O servidor de embeddings verifica uma chave. Ele mantém essa chave em um slot do seu próprio Component, api_key, e a sua Recipe entrega o que quer que preencha o slot como API_KEY, a variável que o Text Embeddings Inference lê na inicialização. 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 }}"Essa é uma vinculação no servidor. A chave que o repositório apresenta é outra, na conexão do repositório, mostrada acima. Preencher o slot de uma ponta não preenche nada na outra, então declarar a chave nas duas pontas é o mínimo, e não uma duplicata. O que mantém as duas como uma única chave é que ambas leem um único parâmetro, embedding_key_secret, que o Aggregate declara e a Release preenche:
parameters: provider_key_entry: ai/openai-api-key embedding_key_secret: embedding-server-keyO Manifest vincula core/referenced-secret a k8s-existing-secret, que lê origin como o nome de um Secret que o namespace já mantém e não renderiza nada. Então as duas pontas referenciam esse único Secret. No env do contêiner do servidor, de dist/matched/helm/embeddings-statefulset.yaml:
- name: API_KEY valueFrom: secretKeyRef: name: embedding-server-key key: api-keye no do repositório, de dist/matched/helm/memory-statefulset.yaml:
- name: EMBEDDING_API_KEY valueFrom: secretKeyRef: name: embedding-server-key key: api-keyO Secret é criado fora da Release, por quem a implanta, então o material da chave nunca passa por um arquivo escrito nem por um artefato renderizado.
Por que o servidor nunca vê as chaves dos seus chamadores
Uma vinculação em uma conexão vai parar apenas no chamador. As duas credenciais do repositório são vinculações do repositório: o que elas renderizam fica ao lado do repositório, e o contêiner do repositório o referencia. Nada delas chega ao componente para o qual uma conexão aponta, então um destino é renderizado da mesma forma, seja o que for que as conexões que o alcançam tragam.
O modelo hospedado mostra isso claramente. Ele renderiza um arquivo, um Service que mapeia um nome interno do cluster para o host do provedor — o spec inteiro de dist/matched/helm/llm-service.yaml:
spec: type: ExternalName externalName: api.openai.com ports: - port: 443A chave que o repositório apresenta a ele é obtida ao lado do repositório, como mostra a próxima seção. O servidor de embeddings mostra isso por comparação: a release divergente abaixo muda a chave na conexão de embeddings do repositório e deixa a do servidor intacta, e os três arquivos do servidor em dist/mismatched/ diferem dos de dist/matched/ apenas no rótulo aggrega.ai/aggregate-name, que nomeia o Aggregate a partir do qual cada um foi compilado.
Então nada na configuração do servidor nomeia uma chave que um chamador detém. Em tempo de execução, uma requisição traz a chave do chamador e o servidor a compara com a que detém; o chamador, por sua vez, lê apenas o que o servidor publica: um endereço e um nome de modelo.
Uma chave por servidor
O Text Embeddings Inference verifica uma única chave. Todo chamador apresenta a mesma chave, um chamador que apresente qualquer outra é recusado, e o servidor não consegue distinguir um chamador de outro, então retirar o acesso de um chamador significa mudar a chave que todo chamador apresenta. Não importa quantas conexões o alcancem, o seu slot api_key contém uma única chave. Esse limite é do próprio servidor, e core/ai-model/vllm e core/ai-model/tgi do catálogo o compartilham. Não é um limite da conexão: um chamador que alcança vários servidores detém uma chave por conexão, como o repositório aqui detém duas.
A chave de uma conexão a partir de um repositório de segredos
O Manifest vincula toda vinculação core/referenced-secret pelo seu tipo, e uma delas pelo seu nome. 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 lê origin como a entrada do repositório de segredos a obter. O origin da conexão é o parâmetro provider_key_entry, preenchido como ai/openai-api-key, então a vinculação renderiza um ExternalSecret que um operador de repositório de segredos no cluster reconcilia em um Secret. O spec inteiro 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"O Secret que ele preenche, memory-llm.credential, é nomeado a partir do repositório e da conexão, e é o nome que o LLM_API_KEY do repositório referencia acima. A realização lê de um ClusterSecretStore chamado platform-secret-store.
O que um parâmetro traz decorre da realização que o lê: uma entrada do repositório de segredos para a chave do modelo hospedado, o nome de um Secret para a chave de embeddings. A chave de uma conexão recebe uma realização própria enquanto toda outra vinculação do mesmo tipo mantém a do tipo.
Onde as duas pontas resolvem um segredo
Uma plataforma de destino resolve um segredo por referência dentro de um escopo de segredos: a fronteira dentro da qual um recurso pode nomear outro. Onde as duas pontas de uma conexão ficam em um mesmo escopo, ambas referenciam um único recurso de segredo. Onde ficam em escopos diferentes, cada ponta mantém um recurso de segredo próprio, realizado a partir da mesma entrada do repositório de segredos. O Manifest escolhe a realização de cada ponta — por tipo de Feature para toda vinculação desse tipo, ou para uma única vinculação pelo seu nome.
Cada destino traça o escopo nos seus próprios termos. No Kubernetes, para o qual este espaço de trabalho faz o build, é o namespace: uma carga de trabalho referencia um Secret apenas no seu próprio. Cada release aqui coloca a sua única fronteira em um único namespace, aggrega.ai/namespace: memory, e todo documento renderizado o traz — o cabeçalho dos dois StatefulSets:
metadata: name: memory namespace: memory
# dist/matched/helm/embeddings-statefulset.yamlmetadata: name: embeddings namespace: memoryEntão as duas pontas referenciam o único Secret acima. Com o servidor de embeddings em um namespace próprio, o Manifest vincula as credenciais das duas pontas pelo nome — api_key e embeddings.credential — a k8s-external-secret, a Release preenche o parâmetro com a entrada do repositório de segredos, e cada ponta mantém um ExternalSecret no seu próprio namespace, ambos obtendo essa mesma entrada. O repositório então alcança o servidor entre namespaces, o que cross-boundary-networking aborda. Nos outros destinos, o escopo é um projeto do Compose, uma configuração raiz do Terraform e uma stack do CloudFormation; o Modelo de credenciais descreve cada um.
O operador liga uma conexão
aggregate-operator-wired.yaml escreve a conexão de embeddings e deixa sem vínculo o socket extraction_model do repositório: a entidade de catálogo do repositório o declara, e o desenvolvedor o deixa para o operador. A Release o liga ao modelo hospedado que o Aggregate declara. 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-keyUma Release pode ligar uma conexão a um socket que a entidade de catálogo declara e que o Aggregate deixa sem vínculo, apontando para um componente que o Aggregate declara. Ela não adiciona nenhum componente, e nunca muda o destino de uma conexão que o Aggregate escreveu. Ela não escreve nenhum values, então a credencial nessa conexão nomeia o seu segredo em infra: core/referenced-secret recebe origin dos values do desenvolvedor ou da infra do operador, exatamente de um dos dois, e o build é interrompido em uma vinculação que traga os dois ou nenhum.
A vinculação se chama llm.credential exatamente como na release correspondente, então o nível de nomes do Manifest a vincula da mesma forma. Além do rótulo que nomeia o Aggregate, duas linhas diferem entre dist/operator-wired/ e dist/matched/. O data do ExternalSecret:
data: - secretKey: value remoteRef: key: "ai/openai-api-key"e a referência do repositório ao Secret que ele preenche, em dist/operator-wired/helm/memory-statefulset.yaml:
- name: LLM_API_KEY valueFrom: secretKeyRef: name: memory-llm.credential key: valueA chave de dados é value em vez de api-key porque key é uma folha de values, que só o Aggregate escreve, então uma vinculação que só a Release faz lê o valor padrão da Feature. A realização publica essa chave e o repositório a lê do que foi publicado, então os dois continuam de acordo.
O modelo hospedado é rotulado managed, então uma conexão que o alcança traz uma credencial ou diz nos seus próprios values que o modelo não exige nenhuma, unauthenticated: true. Isso vale seja qual for o documento que escreveu a conexão. Remova o bloco features: da conexão da Release e o build é interrompido. A interrupção é E0033, uma asserção com falha do Component do repositório, e a sua mensagem termina com a frase da própria regra: 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 (a conexão extraction_model llm de “memory” alcança “llm”, cujo rótulo component.aggrega.ai/hosting é managed, sem nenhuma credencial: vincule uma em credential nessa conexão, ou defina unauthenticated: true nos seus values).
Quando as duas pontas divergem
aggregate-mismatched.yaml dá à chave do servidor e à chave do repositório dois 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.A api_key do servidor lê embedding_key_secret e a conexão do repositório lê memory_embedding_key_secret, que a Release preenche com dois Secrets diferentes. O build é concluído e escreve oito arquivos: o compilador avalia cada vinculação que recebe e não compara nada entre as duas pontas. O servidor ainda referencia embedding-server-key, e o repositório agora apresenta outro, de dist/mismatched/helm/memory-statefulset.yaml:
- name: EMBEDDING_API_KEY valueFrom: secretKeyRef: name: embedding-client-key key: api-keyUma vez implantado, o servidor só aceita as requisições do repositório se esses dois Secrets por acaso contiverem a mesma chave.
A verificação de convenções de publicação de uma Release é onde isso é detectado:
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)A mesma verificação sobre a release correspondente não informa nada:
aggrega lint --release release-matched.yamlconventions checked: 10 entities, 0 advisory finding(s)e sobre a release ligada pelo operador, também nada.
A regra encontra as duas pontas pelos nomes que o catálogo padrão lhes dá — a api_key do destino e a credential da conexão — e compara o origin que cada ponta escreve, tal como está escrito: duas pontas que leem um mesmo parâmetro são consideradas iguais, e nada é resolvido. Ela nunca cita nenhum dos dois, já que o que está escrito ali pode ser o próprio segredo. Ela não julga um destino rotulado managed, cuja api_key, onde ele declara uma, é a chave apresentada ao seu fornecedor, e não uma que os seus chamadores apresentam; então a conexão com llm não gera nada em nenhuma das três releases. A constatação é uma recomendação: aggrega lint termina com 0, e um espaço de trabalho cujas duas pontas diferem deliberadamente se exclui com allow_connection_credential_mismatches. Um editor que faz a mesma pergunta ao daemon, aggrega/lint nomeando a Release, recebe a mesma constatação sob o código connection-credential-matches-target-key e o código curto E0329. A regra e o que ela lê são descritos em As regras de disciplina.
Determinismo
As três releases fazem o build com --verify-determinism, que renderiza cada nó duas vezes e compara os bytes emitidos:
aggrega build --release release-matched.yaml --verify-determinismRefazer o build de qualquer uma das três a partir de uma árvore limpa reproduz a sua saída renderizada byte a byte.
Adaptando-o
- Adicione um segundo chamador do servidor de embeddings. A credencial da conexão dele também lê
embedding_key_secret. O servidor mantém uma única chave para todos os chamadores, então o segundo chamador apresenta a mesma chave. - Obtenha também a chave de embeddings do repositório de segredos. Vincule
api_keyeembeddings.credentialpelo nome ak8s-external-secrete preenchaembedding_key_secretcom uma entrada do repositório de segredos em vez do nome de um Secret. As duas pontas mudam juntas porque ambas leem o parâmetro. - Alcance um modelo que não verifica nenhuma chave. Deixe a credencial fora da conexão. Onde o destino for rotulado
managed, diga isso na conexão comunauthenticated: truenos seusvalues.
Para compartilhar uma chave entre as conexões de vários chamadores, veja model-api-key-sharing. Para um router que mantém as chaves dos provedores em nome dos seus chamadores, veja ai-agent-and-model-router. O modelo por trás de tudo isso é o Modelo de credenciais.