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

Partilhar uma credencial — por consumidor, partilhada e ambas 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, pelo que a chave que um agente apresenta ao modelo que alcança é anexada nessa ligação. Este espaço de trabalho preenche o slot de três formas sem alterar uma única entidade de catálogo: uma chave por ligação, um Secret que todas as ligações referenciam e uma predefinição partilhada que uma ligação substitui.

Dois consumidores são o essencial. As três formas são indistinguíveis com um único consumidor — a diferença é qual Secret cada consumidor acaba por referenciar, e essa pergunta não tem conteúdo enquanto não houver mais de um consumidor.

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 model-api-key-sharing

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

Terminal window
cd model-api-key-sharing

Compilação

Três releases, uma por forma. Compile-se 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, pelo que as três árvores renderizadas coexistem e podem ser comparadas entre si com um diff.

Uma release precisa do seu ficheiro de bloqueio antes de compilar. Num checkout novo, resolva-se primeiro um — seja como passo próprio, seja deixando que a compilação o preencha:

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, pelo que não é necessária nenhuma flag --catalog.

As três compilam no destino helm, deliberadamente. O elemento observável que distingue as três formas é o nome do Secret que o contentor de cada agente referencia, e o helm é onde uma credencial é um Secret do Kubernetes com nome que um contentor referencia pelo nome. Dois Manifests associam a credencial: manifest.yaml a k8s-secret-from-parameter, que renderiza um Secret a partir do valor que o anexo 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 partilhada e composta.

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 conta própria. Se a pasta da área de trabalho ainda não contiver uma pasta `model-api-key-sharing`, chame uma vez a ferramenta `scaffold` com `example` definido como `model-api-key-sharing` e sem `dir`: esta escreve o exemplo numa nova pasta `model-api-key-sharing`. Em seguida, chame a ferramenta `build` uma vez para cada Release, por esta ordem — `release-per-consumer.yaml`, `release-shared.yaml` e `release-composed.yaml` —, de cada vez com `workspace_root` definido como `model-api-key-sharing`, `release` definido como esse ficheiro, `auto_pull` definido como true e `write` definido como true. Indique quais os ficheiros que cada compilação escreveu; encontram-se em `model-api-key-sharing/dist/`.

Por consumidor — cada ligação detém a sua própria chave

aggregate-per-consumer.yaml preenche o slot na ligaçã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

Um anexo numa ligação torna-se um dos anexos próprios do agente, nomeado a partir da ligação e do slot — aqui gateway.credential — pelo que são emitidos dois Secrets, 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:

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.

Partilhada — um único Secret, referenciado a partir de cada ligação

Uma credencial numa ligação é escrita nessa ligação: nada anexado noutro lugar a preenche. Assim, vários consumidores partilham uma credencial por autoria: a credencial de cada ligação lê o mesmo valor, e esse valor nomeia um único Secret.

aggregate-shared.yaml declara um parâmetro e lê-o nas duas ligaçõ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. 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

Isto é exatamente um Secret físico, criado fora da Release por quem a implementa, e lido por cada consumidor. O material da chave nunca passa por um ficheiro escrito pelo autor nem por um artefacto 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 antes associada a k8s-secret-from-parameter, as mesmas duas ligações que leem um único parâmetro trariam a própria chave, e a compilação 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 ligação. O parâmetro único é o que impede os consumidores de divergirem; a realização que o lê decide se partilham um recurso. Uma credencial gerada no cluster é partilhada da mesma forma — um pedido e muitas referências; veja-se Modelo de credenciais.

Composta — predefinição partilhada, uma ligação a substituí-la

aggregate-composed.yaml mantém o parâmetro partilhado como predefinição e deixa uma ligaçã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 substituição é o que essa única ligação escreve; nada se propaga em cascata para ela, e writer mantém o Secret partilhado 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 ligação é um anexo inteiro próprio, pelo que uma substituição volta a declarar cada campo de que precisa — aqui o tipo de Feature, key e origin — e não herda nenhum da predefiniçã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, pelo que uma quarta forma é não anexar nada: retire-se o bloco features: das duas ligações e a árvore renderizada perde todas as entradas 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 compila porque o gateway aqui, core/ai-model/openai-compatible, não traz nenhuma etiqueta component.aggrega.ai/hosting. Uma ligação que alcance um destino que o catálogo etiqueta como managed — core/ai-model/openai, por exemplo — sem nenhuma credencial interrompe a compilação na asserção do próprio agente, a menos que a ligação indique 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 fornecedor, 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 compilam 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

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