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

Compartilhando uma credencial — por consumidor, compartilhada e as duas ao mesmo tempo

Dois agentes CrewAI atrás de um único gateway compatível com a OpenAI. O socket model de cada agente declara um slot credential, então a chave que um agente apresenta ao modelo que ele alcança é vinculada nessa conexão. Este espaço de trabalho preenche o slot de três maneiras sem alterar uma única entidade de catálogo: uma chave por conexão, um único Secret que toda conexão referencia, e um padrão compartilhado que uma conexão sobrescreve.

Dois consumidores são o ponto principal. As três formas são indistinguíveis com um único consumidor — a diferença é para qual Secret cada consumidor acaba apontando, e essa pergunta não tem conteúdo até que haja mais de um consumidor.

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:

Terminal window
aggrega scaffold --example model-api-key-sharing

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd model-api-key-sharing

Build

Três releases, uma por forma. Faça o build de uma por execução:

Terminal window
aggrega build --release release-per-consumer.yaml --auto-pull # → dist/per-consumer/
aggrega build --release release-shared.yaml --auto-pull # → dist/shared/
aggrega build --release release-composed.yaml --auto-pull # → dist/composed/

Cada release 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 arquivo de bloqueio antes de fazer o build. Em um checkout novo, resolva um primeiro — seja como etapa própria, seja deixando o build preenchê-lo:

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

As releases resolvem as suas entidades de catálogo a partir do catálogo configurado, então nenhuma flag --catalog é necessária.

As três fazem o build no destino helm, deliberadamente. O elemento observável que separa as três formas é o nome do Secret que o contêiner de cada agente referencia, e o helm é onde uma credencial é um Secret do Kubernetes com nome que um contêiner referencia pelo nome. Dois Manifests associam a credencial: manifest.yaml a k8s-secret-from-parameter, que renderiza um Secret a partir do valor que a vinculação traz, para a release por consumidor; e manifest-existing-secret.yaml a k8s-existing-secret, que não renderiza nada e faz cada consumidor apontar para um Secret já presente no namespace, para as releases compartilhada e composta.

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 você mesmo. Se a pasta do workspace ainda não contiver uma pasta `model-api-key-sharing`, chame a ferramenta `scaffold` uma vez com `example` definido como `model-api-key-sharing` e sem `dir`: ela grava o exemplo em uma nova pasta `model-api-key-sharing`. Depois chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-per-consumer.yaml`, `release-shared.yaml` e `release-composed.yaml` —, cada vez com `workspace_root` definido como `model-api-key-sharing`, `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 `model-api-key-sharing/dist/`.

Por consumidor — cada conexão mantém a sua própria chave

aggregate-per-consumer.yaml preenche o slot na conexão de cada agente, com um origin diferente por agente:

researcher:
type: core/ai-agent/crewai
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: researcher-key-change-me

Uma vinculação em uma conexão se torna uma das vinculações próprias do agente, nomeada a partir da conexão e do slot — aqui gateway.credential — então dois Secrets são emitidos, um por agente, cada um com o material próprio desse agente:

dist/per-consumer/helm/researcher--gateway-zdcredential--researcher-secret-researcher-gateway-credential.yaml
[… omitted: the apiVersion and the Secret kind]
metadata:
name: researcher-gateway.credential
[… omitted: the labels and annotations every rendered document carries]
stringData:
OPENAI_API_KEY: "researcher-key-change-me"
# dist/per-consumer/helm/writer--gateway-zdcredential--writer-secret-writer-gateway-credential.yaml
[… omitted: the apiVersion and the Secret kind]
metadata:
name: writer-gateway.credential
[… omitted: the labels and annotations every rendered document carries]
stringData:
OPENAI_API_KEY: "writer-key-change-me"

e cada Deployment referencia o seu próprio:

dist/per-consumer/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: researcher-gateway.credential
key: OPENAI_API_KEY
# dist/per-consumer/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: writer-gateway.credential
key: OPENAI_API_KEY

Revogar a chave de um agente deixa o outro em execução.

Compartilhada — um único Secret, referenciado a partir de cada conexão

Uma credencial em uma conexão é escrita nessa conexão: nada vinculado em outro lugar a preenche. Então vários consumidores compartilham uma credencial por autoria: a credencial de cada conexão lê o mesmo valor, e esse valor nomeia um único Secret.

aggregate-shared.yaml declara um parâmetro e o lê nas duas conexões:

parameters:
team_model_key:
type: string
default: team-model-key
components:
researcher:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: "{{ .parameters.team_model_key }}"
writer: { ... } # the same credential, reading the same parameter

A release associa a credencial a k8s-existing-secret, que lê origin como o nome de um Secret que já existe no namespace. Ela não renderiza nenhum Secret — apenas o Service do gateway e os dois Deployments são escritos — e os dois Deployments referenciam o único Secret que o parâmetro nomeia:

dist/shared/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY
# dist/shared/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY

Isso é exatamente um Secret físico, criado fora da Release por quem a implanta, e lido por cada consumidor. O material da chave nunca passa por um arquivo escrito pelo autor nem por um artefato renderizado.

O que o parâmetro traz segue a realização que o Manifest associa. Com k8s-existing-secret, é o nome de um Secret. Se a credencial fosse associada a k8s-secret-from-parameter, as mesmas duas conexões que leem um único parâmetro trariam a própria chave, e o build renderizaria um Secret por consumidor, cada um com o mesmo material: a renderização ocorre por componente, e essa realização nomeia o Secret que renderiza a partir do componente consumidor e da conexão. O parâmetro único é o que impede que os consumidores divirjam; qual realização o lê decide se eles compartilham um recurso. Uma credencial gerada no cluster é compartilhada da mesma forma — uma solicitação e muitas referências; veja Modelo de credenciais.

Composta — padrão compartilhado, uma conexão sobrescrevendo

aggregate-composed.yaml mantém o parâmetro compartilhado como padrão e deixa uma conexão nomear um Secret próprio:

researcher:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: researcher-model-key # this connection's own Secret
writer:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: "{{ .parameters.team_model_key }}" # the shared default

A sobrescrita é o que essa única conexão escreve; nada se propaga em cascata para ela, e writer mantém o Secret compartilhado intacto:

dist/composed/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: researcher-model-key
key: OPENAI_API_KEY
# dist/composed/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY

A credencial de uma conexão é uma vinculação inteira própria, então uma sobrescrita declara novamente cada campo de que precisa — aqui o tipo de Feature, key e origin — e não herda nenhum do padrão.

O que o slot oferece

core/ai-agent/crewai declara o slot uma vez, no seu socket model, e as três formas são todas escolhas feitas no Aggregate:

usesSchema:
model:
selector: "component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api"
required: true
inject: [env, file]
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

O slot é opcional, então uma quarta forma é não vincular nada: remova o bloco features: das duas conexões e a árvore renderizada perde cada entrada env OPENAI_API_KEY, restando os dois Deployments e o Service do gateway. Nada é inventado para preencher a lacuna. A entidade de catálogo é idêntica em todos os casos; quem decide é o autor.

Isso faz o build porque o gateway aqui, core/ai-model/openai-compatible, não traz nenhum rótulo component.aggrega.ai/hosting. Uma conexão que alcança um destino que o catálogo rotula como managed — core/ai-model/openai, por exemplo — sem nenhuma credencial interrompe o build na asserção do próprio agente, a menos que a conexão diga nos seus values que o destino não exige nenhuma, unauthenticated: true.

O slot também é agnóstico em relação à família (feature.aggrega.ai/kind=secret admite qualquer uma das duas famílias de credenciais), e é isso que permite ao mesmo agente aceitar um Secret referenciável no helm e uma credencial de valor injetado no compose. Entrega de credenciais — secretKeyRef de ponta a ponta trabalha essa divisão por provedor, e a sua release negativa mostra o que acontece quando se pede a uma credencial não referenciável que satisfaça uma referência.

Determinismo

As três releases fazem o build com --verify-determinism, que renderiza cada nó duas vezes e compara os bytes emitidos:

Terminal window
aggrega build --release release-shared.yaml --auto-pull --verify-determinism

Refazer o build de qualquer uma das três a partir de uma árvore limpa reproduz a sua saída renderizada byte a byte.