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:
aggrega scaffold --example model-api-key-sharingEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd model-api-key-sharingBuild
Três releases, uma por forma. Faça o build de uma por execução:
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:
aggrega pull --release release-shared.yaml # resolve, then build normallyaggrega build --release release-shared.yaml --auto-pull # or resolve during the buildAs 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-meUma 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:
[… 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:
- 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_KEYRevogar 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-keycomponents: 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 parameterA 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:
- 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_KEYIsso é 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 Secretwriter: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: "{{ .parameters.team_model_key }}" # the shared defaultA sobrescrita é o que essa única conexão escreve; nada se propaga em cascata para ela, e writer mantém o Secret compartilhado intacto:
- 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_KEYA 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:
aggrega build --release release-shared.yaml --auto-pull --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.