共享凭据——按消费者、共享,以及两者兼用
两个 CrewAI 代理位于同一个 OpenAI 兼容网关之后。每个代理的 model
socket 声明了一个 credential 槽位,因此代理向其所连接模型出示的密钥
附加在该连接上。本工作区以三种方式填充该槽位,而无需修改任何目录实体:每个连接一个密钥、所有连接都指向的一个 Secret,
以及由一个连接覆盖的共享默认值。
关键在于有两个消费者。 只有一个消费者时,这三种形式无法区分——区别在于每个消费者最终指向哪个 Secret, 而在消费者多于一个之前,这个问题没有实际内容。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example model-api-key-sharing然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd model-api-key-sharing构建
三个 release,每种形式一个。每次运行构建一个:
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/每个 release 写入各自的目录,因此三棵渲染树可以共存, 并可以相互比较差异。
release 在构建前需要其锁文件。在全新检出的代码上,先解析一个锁文件 ——可以作为单独的步骤,也可以让构建来填充:
aggrega pull --release release-shared.yaml # resolve, then build normallyaggrega build --release release-shared.yaml --auto-pull # or resolve during the build这些 release 从已配置的目录中解析其目录实体,因此无需 --catalog 标志。
三者都有意在 helm 目标上构建。区分三种形式的可观察项是每个代理的容器所引用的 Secret 的名称,
而在 helm 中,凭据是一个命名的 Kubernetes Secret,容器按名称引用它。两个 Manifests 绑定该凭据:manifest.yaml 绑定到
k8s-secret-from-parameter,它根据附件携带的值渲染一个 Secret,用于按消费者的 release;
manifest-existing-secret.yaml 绑定到 k8s-existing-secret,它不渲染任何内容,
而是让每个消费者指向命名空间中已存在的 Secret,用于共享和组合的 release。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `model-api-key-sharing` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `model-api-key-sharing`,不设 `dir`:它会把示例写入一个新的 `model-api-key-sharing` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-per-consumer.yaml`、`release-shared.yaml` 和 `release-composed.yaml`——每次都将 `workspace_root` 设为 `model-api-key-sharing`、`release` 设为该文件、`auto_pull` 设为 true、`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `model-api-key-sharing/dist/` 下。按消费者——每个连接持有自己的密钥
aggregate-per-consumer.yaml 在每个代理的连接上填充该槽位,
每个代理使用不同的 origin:
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连接上的附件会成为代理自身的附件之一,以连接和槽位命名
——此处为 gateway.credential——因此会生成两个 Secret,
每个代理一个,各自携带该代理自己的密钥材料:
[… 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"并且每个 Deployment 引用各自的 Secret:
- 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吊销一个代理的密钥不会影响另一个代理的运行。
共享——一个 Secret,由每个连接引用
连接上的凭据写在该连接上:其他地方附加的内容不会填充它。因此多个消费者通过编写共享一个凭据: 每个连接的凭据读取同一个值,而该值指定一个 Secret。
aggregate-shared.yaml 声明一个参数,并在两个连接上读取它:
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 parameter该 release 将凭据绑定到 k8s-existing-secret,它将 origin
读取为命名空间中已存在的 Secret 的名称。它完全不渲染
Secret——只写入网关的 Service 和两个 Deployment——
两个 Deployment 都引用该参数所指定的那个 Secret:
- 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这恰好是一个物理 Secret,由部署者在 Release 之外创建, 并被每个消费者读取。密钥材料从不经过编写的文件或渲染的制品。
参数携带的内容取决于 Manifest 绑定的实现。 在
k8s-existing-secret 下,它是 Secret 的名称。若改为绑定到
k8s-secret-from-parameter,读取同一参数的两个连接将携带密钥本身,
构建会为每个消费者渲染一个 Secret,各自持有相同的材料:渲染按组件运行,
而该实现以消费组件和连接来命名其渲染的 Secret。这一个参数使消费者不会相互偏离;
由哪个实现读取它决定了它们是否共享资源。在集群中生成的凭据也以同样方式共享——一个请求,多个
引用;参见 凭据模型。
组合——共享默认值,一个连接覆盖
aggregate-composed.yaml 保留共享参数作为默认值,并让一个
连接指定自己的 Secret:
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 default覆盖是该连接自己编写的内容;不会有任何内容级联到它上面,
writer 保持共享 Secret 不变:
- 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连接的凭据是其自身的完整附件,因此覆盖需要重新声明它所需的每个字段
——此处为 Feature 类型、key 和 origin——
不会从默认值继承任何字段。
槽位带来了什么
core/ai-agent/crewai 在其 model socket 上声明一次该槽位,
三种形式都是在 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]该槽位是可选的,因此第四种形态是完全不附加任何内容:从两个连接中删除
features: 块,渲染树将失去所有
OPENAI_API_KEY env 条目,只剩下两个 Deployment 和网关 Service。
不会凭空生成任何内容来填补空缺。目录实体在每种情况下都相同;
由作者决定。
之所以能构建,是因为此处的网关 core/ai-model/openai-compatible 不带
component.aggrega.ai/hosting 标签。如果某个连接到达目录标记为 managed 的目标
——例如 core/ai-model/openai——且没有凭据,代理自身的断言会使构建中止,
除非该连接在其 values 中声明目标不需要凭据,即 unauthenticated: true。
该槽位还与凭据族无关(feature.aggrega.ai/kind=secret 接受任一
凭据族),正因如此,同一个代理可以在 helm 上接受可引用的
Secret,在 compose 上接受注入值凭据。
凭据交付——secretKeyRef 端到端
演示了这种 provider 划分,其负面 release 展示了当要求不可引用的凭据满足引用时会发生什么。
确定性
三个 release 都在 --verify-determinism 下构建,它会将每个节点渲染两次
并比较生成的字节:
aggrega build --release release-shared.yaml --auto-pull --verify-determinism从干净的树重新构建三者中的任何一个,都会逐字节重现其渲染输出。