Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

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ânciaComponent do catálogoo que é aqui
memorycore/datastore/cogneeo 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
llmcore/ai-model/openaium modelo alojado, etiquetado component.aggrega.ai/hosting: managed; alcançado como referência, pelo que nada é executado para ele no cluster
embeddingscore/ai-model/teiText 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:

releaseAggregateo que mostra
release-matched.yamlaggregate-matched.yamlas duas ligações escritas pelo programador, as duas pontas da ligação de embeddings a ler um único parâmetro
release-mismatched.yamlaggregate-mismatched.yamlo 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.yamlaggregate-operator-wired.yamla 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:

Terminal window
aggrega scaffold --example connection-credentials

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd connection-credentials

Compilação

Compile-se uma release por execução:

Terminal window
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:

Terminal window
aggrega pull --release release-matched.yaml # resolve, then build normally
aggrega build --release release-matched.yaml --auto-pull # or resolve during the build

O 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>/dist

As 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.yaml

Um 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 credential em cada um dos seus dois sockets de modelo; o Component do servidor de embeddings declara api_key em 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-mini

As 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-key

O 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-key

e no do repositório, de dist/matched/helm/memory-statefulset.yaml:

- name: EMBEDDING_API_KEY
valueFrom:
secretKeyRef:
name: embedding-server-key
key: api-key

O 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: 443

A 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.0

k8s-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:

dist/matched/helm/memory-statefulset.yaml
metadata:
name: memory
namespace: memory
# dist/matched/helm/embeddings-statefulset.yaml
metadata:
name: embeddings
namespace: memory

Assim, 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-key

Uma 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: value

A 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-key

Uma 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:

Terminal window
aggrega lint --release release-mismatched.yaml
release-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:

Terminal window
aggrega lint --release release-matched.yaml
conventions 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:

Terminal window
aggrega build --release release-matched.yaml --verify-determinism

Recompilar 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_key e embeddings.credential pelo nome a k8s-external-secret e satisfazer embedding_key_secret com 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 com unauthenticated: true nos seus values.

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.