Credenciais em ligações — uma chave por ligaçã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 em manifestos do Kubernetes. Lê o material ingerido com um modelo alojado e codifica-o com um servidor de embeddings executado ao seu lado no cluster. A chave que apresenta ao modelo alojado é obtida a partir 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 leem-na de um único parâmetro, pelo que 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 nomeia vem no catálogo da biblioteca standard; os ficheiros aqui — três Aggregates, um Manifest e três Releases — são tudo o que alguém escreve.
O que 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 apresenta nessa ligação |
llm | core/ai-model/openai | um modelo alojado, etiquetado component.aggrega.ai/hosting: managed; alcançado como referência, pelo que nada é executado para ele no cluster |
embeddings | core/ai-model/tei | Text Embeddings Inference no cluster, etiquetado self-hosted; exige uma chave a cada chamador e guarda-a no seu próprio slot api_key |
Três releases partilham 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 ligações escritas pelo programador, as duas pontas da ligação de embeddings a ler um único parâmetro |
release-mismatched.yaml | aggregate-mismatched.yaml | o mesmo com as duas pontas a ler dois parâmetros: a compilação é bem-sucedida, e a verificação de convenções emite um aviso |
release-operator-wired.yaml | aggregate-operator-wired.yaml | a ligação de extração deixada ao operador: a Release liga-a e nomeia a sua chave em infra |
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example connection-credentialsDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd connection-credentialsCompilação
Compile-se 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, pelo que as três árvores renderizadas coexistem e podem ser comparadas entre si com um diff.
Uma release precisa do seu lockfile antes de ser compilada, e os lockfiles são gerados em vez de incluídos. Resolva-se um primeiro, ou deixe-se a compilação 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 registo predefinido que .aggrega-config.yaml nomeia, pelo que não é necessária nenhuma flag --catalog.
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 a compilação, com <workspace> a representar 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 a nomear o seu próprio lockfile e cada compilação a escrever oito ficheiros. A linha notice: diz respeito à Feature de credenciais que todos os anexos aqui usam: core/referenced-secret aceita o nome do seu segredo, origin, tanto dos values do programador como da infra do operador, e o aviso indica que uma folha está declarada nos dois pilares. Não altera nenhum veredicto nem nenhum byte renderizado; Features de credenciais explica porque é que a folha está nos dois.
Onde esta página imprime o que uma compilação produziu, o bloco é copiado de uma execução real — veja-se Ler a saída nestas páginas para a convenção e a marca que esta 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-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta da área de trabalho ainda não contiver uma pasta `connection-credentials`, chame uma vez a ferramenta `scaffold` com `example` definido como `connection-credentials` e sem `dir`: esta escreve o exemplo numa nova pasta `connection-credentials`. Em seguida, chame a ferramenta `build` uma vez para cada Release, por esta ordem — `release-matched.yaml`, `release-mismatched.yaml`, `release-operator-wired.yaml` — de cada vez com `workspace_root` definido como `connection-credentials`, `release` definido como esse ficheiro, `auto_pull` definido como true e `write` definido como true. Indique-me que ficheiros cada build escreveu; encontram-se 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 ficheiro foi trazido por um anexo em vez da própria Recipe de um componente: o ExternalSecret que obtém a chave que o repositório apresenta ao modelo alojado. O seu nome de ficheiro traz o componente que recebe o anexo, memory, e o nome do anexo, llm.credential, escrito llm-zdcredential porque o ponto partilha uma única string com o próprio nome do ficheiro; veja-se Nomear um recurso renderizado. Nenhum ficheiro traz a chave de embeddings: está num Secret que o namespace já detém, como mostram as secções abaixo.
Que 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 próprio; cada Recipe decide a variável em que uma chave é entregue. - O Aggregate — o programador — escreve que modelos o repositório alcança, a credencial em cada ligação, a chave que o servidor verifica e o único parâmetro que as duas pontas da ligação de embeddings leem.
- O Manifest — o encaminhamento do operador para este destino — decide aquilo em que cada credencial se torna no Kubernetes: uma referência a um Secret que o namespace já detém para cada anexo
core/referenced-secret, exceto o da ligação ao modelo alojado, que é obtido a partir de um repositório de segredos do cluster. - A Release — o documento do operador para um ambiente — satisfaz os parâmetros, coloca a fronteira num namespace e, na release em que é o operador a ligar, estabelece a ligação de extração e nomeia a chave nela apresentada.
Uma chave por ligação
O repositório alcança dois modelos através 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 ligação em que é apresentada, e cada ligaçã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 }}"Um anexo escrito numa ligação torna-se um dos anexos próprios do repositório, com o nome formado pelo alias da ligação, um ponto e o slot: llm.credential e embeddings.credential. Eis as duas primeiras e as quatro últimas entradas do env do contentor 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 ligação, sob a variável que a Recipe do repositório atribui 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 fornecedor helm escreve as entradas que lê de um Secret antes das simples. As últimas quatro vieram das duas ligações: cada modelo publica o seu endereço e o seu nome de modelo, e a Recipe do repositório lê-os por socket.
O Component do repositório também declara um slot de chave em si próprio, model_api_key. A sua Recipe só lê esse slot para um socket deixado sem ligação, em que o repositório alcança um fornecedor no próprio endereço do fornecedor e não há ligação que transporte uma chave. Os dois sockets estão ligados aqui, pelo que não é lido.
Uma única chave nas duas pontas
O servidor de embeddings verifica uma chave. Guarda essa chave num 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ê no arranque. 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 }}"Esse é um anexo no servidor. A chave que o repositório apresenta vem de outro anexo, na ligação do repositório, mostrado acima. Preencher o slot de uma ponta não preenche nada na outra, pelo que declarar a chave nas duas pontas é o mínimo, e não um duplicado. 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 satisfaz:
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á detém e não renderiza nada. Assim, as duas pontas referenciam esse único Secret. No env do contentor 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 implementa, pelo que o material da chave nunca passa por um ficheiro escrito nem por um artefacto renderizado.
Porque é que o servidor nunca vê as chaves dos seus chamadores
Um anexo numa ligação fica apenas no chamador. As duas credenciais do repositório são anexos do repositório: o que renderizam fica ao lado do repositório, e o contentor do repositório referencia-o. Nada delas chega ao componente para o qual uma ligação aponta, pelo que um destino é renderizado da mesma forma, seja o que for que as ligações que o alcançam transportem.
O modelo alojado mostra-o claramente. Renderiza um único ficheiro, um Service que mapeia um nome interno do cluster para o anfitrião do fornecedor — o spec completo de dist/matched/helm/llm-service.yaml:
spec: type: ExternalName externalName: api.openai.com ports: - port: 443A chave que o repositório lhe apresenta é obtida ao lado do repositório, como mostra a secção seguinte. O servidor de embeddings mostra-o por comparação: a release divergente abaixo muda a chave na ligação de embeddings do repositório e deixa a do servidor intacta, e os três ficheiros do servidor em dist/mismatched/ diferem dos de dist/matched/ apenas na etiqueta aggrega.ai/aggregate-name, que nomeia o Aggregate a partir do qual cada um foi compilado.
Assim, nada na configuração do servidor nomeia uma chave que um chamador detenha. Em tempo de execução, um pedido traz a chave do chamador e o servidor compara-a com a que detém; o chamador, por seu lado, 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. Todos os chamadores apresentam a mesma chave, um chamador que apresente qualquer outra é recusado, e o servidor não consegue distinguir um chamador de outro, pelo que retirar o acesso a um chamador significa mudar a chave que todos os chamadores apresentam. Por muitas ligações que 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 partilham-no. Não é um limite da ligação: um chamador que alcança vários servidores detém uma chave por ligação, tal como o repositório aqui detém duas.
A chave de uma ligação a partir de um repositório de segredos
O Manifest vincula cada anexo core/referenced-secret pelo seu tipo, e um deles 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 ligação é o parâmetro provider_key_entry, satisfeito como ai/openai-api-key, pelo que o anexo renderiza um ExternalSecret que um operador de repositório de segredos no cluster reconcilia num Secret. O 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"O Secret que preenche, memory-llm.credential, tem o nome do repositório e da ligação, e é o nome que o LLM_API_KEY do repositório referencia acima. A realização lê a partir 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 alojado, o nome de um Secret para a chave de embeddings. A chave de uma ligação recebe uma realização própria, enquanto todos os outros anexos 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 âmbito de segredos: a fronteira dentro da qual um recurso pode nomear outro. Onde as duas pontas de uma ligação se encontram num mesmo âmbito, ambas referenciam um único recurso de segredo. Onde se encontram em âmbitos diferentes, cada ponta deté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 todos os anexos desse tipo, ou para um único anexo pelo seu nome.
Cada destino traça o âmbito nos seus próprios termos. No Kubernetes, para o qual este espaço de trabalho compila, é o namespace: uma carga de trabalho só referencia um Secret no seu próprio. Cada release aqui coloca a sua única fronteira num único namespace, aggrega.ai/namespace: memory, e todos os documentos renderizados o trazem — o cabeçalho dos dois StatefulSets:
metadata: name: memory namespace: memory
# dist/matched/helm/embeddings-statefulset.yamlmetadata: name: embeddings namespace: memoryAssim, as duas pontas referenciam o único Secret acima. Com o servidor de embeddings num namespace próprio, o Manifest vincula as credenciais das duas pontas pelo nome — api_key e embeddings.credential — a k8s-external-secret, a Release satisfaz o parâmetro com a entrada do repositório de segredos, e cada ponta detém um ExternalSecret no seu próprio namespace, ambos a obter essa mesma entrada. O repositório alcança então o servidor entre namespaces, o que cross-boundary-networking aborda. Nos outros destinos, o âmbito é um projeto do Compose, uma configuração raiz do Terraform e uma stack do CloudFormation; o Modelo de credenciais descreve cada um.
O operador estabelece uma ligação
aggregate-operator-wired.yaml escreve a ligação de embeddings e deixa sem vínculo o socket extraction_model do repositório: a entidade de catálogo do repositório declara-o, e o programador deixa-o ao operador. A Release liga-o ao modelo alojado 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 estabelecer uma ligação num socket que a entidade de catálogo declara e que o Aggregate deixa sem vínculo, para um componente que o Aggregate declara. Não acrescenta nenhum componente, e nunca muda o destino de uma ligação que o Aggregate escreveu. Não escreve nenhum values, pelo que a credencial nessa ligação nomeia o seu segredo em infra: core/referenced-secret recebe origin dos values do programador ou da infra do operador, exatamente de um dos dois, e a compilação é interrompida num anexo que traga ambos ou nenhum.
O anexo chama-se llm.credential exatamente como na release concordante, pelo que o nível de nomes do Manifest o vincula da mesma forma. Além da etiqueta 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 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, pelo que um anexo que só a Release faz lê o valor predefinido da Feature. A realização publica essa chave e o repositório lê-a a partir do que foi publicado, pelo que os dois continuam de acordo.
O modelo alojado está etiquetado managed, pelo que uma ligação que o alcance traz uma credencial ou indica nos seus próprios values que o modelo não exige nenhuma, unauthenticated: true. Isto aplica-se seja qual for o documento que escreveu a ligação. Retire-se o bloco features: da ligação da Release e a compilação é interrompida. A interrupção é E0033, uma asserção falhada 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 ligação extraction_model llm de «memory» alcança «llm», cuja etiqueta component.aggrega.ai/hosting é managed, sem nenhuma credencial: anexe-se uma em credential nessa ligação, ou defina-se unauthenticated: true nos seus values).
Quando as duas pontas divergem
aggregate-mismatched.yaml atribui à 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 ligação do repositório lê memory_embedding_key_secret, que a Release satisfaz com dois Secrets diferentes. A compilação é bem-sucedida e escreve oito ficheiros: o compilador avalia cada anexo que recebe e não compara nada entre as duas pontas. O servidor continua a referenciar embedding-server-key, e o repositório apresenta agora outro, de dist/mismatched/helm/memory-statefulset.yaml:
- name: EMBEDDING_API_KEY valueFrom: secretKeyRef: name: embedding-client-key key: api-keyUma vez implementado, o servidor só aceita os pedidos 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 isto é detetado:
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 concordante não reporta nada:
aggrega lint --release release-matched.yamlconventions checked: 10 entities, 0 advisory finding(s)e sobre a release em que é o operador a ligar, também nada.
A regra encontra as duas pontas pelos nomes que o catálogo standard lhes dá — a api_key do destino e a credential da ligaçã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. Nunca cita nenhum dos dois, já que o que lá está escrito pode ser o próprio segredo. Não julga um destino etiquetado managed, cuja api_key, quando declara uma, é a chave apresentada ao seu fornecedor, e não uma que os seus chamadores apresentam; assim, a ligação a 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 exclui-se com allow_connection_credential_mismatches. Um editor que faça a mesma pergunta ao daemon, aggrega/lint a nomear 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 aquilo que lê são descritos em As regras de disciplina.
Determinismo
As três releases compilam com --verify-determinism, que renderiza cada nó duas vezes e compara os bytes emitidos:
aggrega build --release release-matched.yaml --verify-determinismRecompilar qualquer uma das três a partir de uma árvore limpa reproduz a sua saída renderizada byte a byte.
Adaptá-lo
- Acrescentar um segundo chamador do servidor de embeddings. A credencial da sua ligação também lê
embedding_key_secret. O servidor detém uma única chave para todos os chamadores, pelo que o segundo chamador apresenta a mesma chave. - Obter também a chave de embeddings a partir do repositório de segredos. Vincular
api_keyeembeddings.credentialpelo nome ak8s-external-secrete satisfazerembedding_key_secretcom uma entrada do repositório de segredos em vez do nome de um Secret. As duas pontas mudam em conjunto porque ambas leem o parâmetro. - Alcançar um modelo que não verifica nenhuma chave. Deixar a credencial fora da ligação. Quando o destino está etiquetado
managed, indicá-lo na ligação comunauthenticated: truenos seusvalues.
Para partilhar uma chave entre as ligações de vários chamadores, veja-se model-api-key-sharing. Para um router que detém as chaves dos fornecedores em nome dos seus chamadores, veja-se ai-agent-and-model-router. O modelo por detrás de tudo isto é o Modelo de credenciais.