密钥
本页只讲解一个概念,即凭据如何到达需要它的组件,它并不是一个可运行的工作区。高级平台——多边界 Kubernetes 平台 在你自行构建的工作区中展示了两种交付模型;用以下命令将其写入你自己的文件夹:
aggrega scaffold --example advanced-platform然后它会打印接下来要运行的命令:
cd advanced-platformaggrega pull --release release.yamlaggrega build --release release.yaml密钥交付检查清单
凭据在到达运行中的容器之前要经过六个界面。以下是接入新凭据时需要检查的接触点:
| 步骤 | 界面 | 操作 |
|---|---|---|
| 1 | Component featuresSchema: | 声明凭据槽位:其名称、是否为 required,以及其 inject: 允许列表——附件可以指定的交付机制,透明槽位为 [env] 或 [env, file],不透明槽位为 []。 |
| 2 | 凭据 Feature schema: | 定义作者提供的内容:标准库的凭据 Features 带有 feature.aggrega.ai/kind: secret 标签,并将凭据的定位符作为 origin、将数据键作为 key 接收。 |
| 3 | Aggregate features: | 请求凭据,使用与其他任何 Feature 相同的 features: 关键字:其 type、其 values,以及仅在透明槽位上提供的一个 inject: 块,用于说明应用程序如何读取它。 |
| 4 | FeatureRecipe | 针对目标实现凭据:将值写入组件读取它的位置,渲染一个保存该值的资源,或渲染一个从机密存储中获取该值的资源。 |
| 5 | Manifest mappings.features.type | 将凭据 Feature 绑定到其 FeatureRecipe,与其他所有 Feature 位于同一层级。 |
| 6 | Recipe | 在不透明槽位上读取凭据:组件的 Recipe 读取凭据发布的定位符 .features.<slot>.provides.name,并将其交给产品自身的机制,例如 chart 的 existingSecret。 |
透明槽位使用前五项;不透明槽位使用全部六项,这是打包基础设施(例如供应商的 chart)的常见情况。
透明槽位与不透明槽位
透明槽位让开发者决定应用程序如何读取凭据。不透明槽位将交付交由 Recipe 处理,在其上编写 inject: 块的附件会使构建停止。在本示例中,core/datastore/mariadb 各声明了一个,Aggregate 填充了这两个槽位,以下摘自 aggregate.yaml,省略了其中的注释:
db: type: core/datastore/mariadb features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: dev-root-pw-change-me user_password: type: core/secret-provided values: origin: dev-app-pw-change-me inject: env: - in: MARIADB_PASSWORD from: valueroot_password 是不透明的:core/secret-value 将值交付到附件指定的键下,由数据库的 Recipe 在那里读取。user_password 是透明的:core/secret-provided 将值发布为 value,由附件自己的 inject: 块将其交付到 MARIADB_PASSWORD。如果 inject: 块指定了槽位未列出的机制,构建会停止;指定了没有任何内容发布或读取的键时,也同样如此。
对于由可引用凭据填充的不透明槽位,组件的 Recipe 读取已发布的定位符,而不是推导名称:existingSecret: "{{ .features.root_password.provides.name }}",因此 FeatureRecipe 生成的 Secret 与对它的引用是同一个字符串。MariaDB(Bitnami chart)——一个多键凭据 Secret 针对供应商的 chart 构建了这一流程。
实现凭据:一个资源,或一个两步流水线
标准库的 Kubernetes 实现从 FeatureRecipe 旁边的一个小型 chart 渲染凭据的资源:helm/k8s-secret-from-parameter 渲染一个保存作者所提供值的 Secret,helm/k8s-external-secret 渲染一个由 External Secrets Operator 从机密存储中协调的 ExternalSecret。凭据 Features 逐一进行了讲解。
FeatureRecipe 也可以改用由两个步骤组成的 pipeline: 来实现凭据,每个步骤都是一个插件。第一步是获取器,它写入特定于存储的资源(例如一个 ExternalSecret),并指定附件的值所给出的存储条目。第二步是注入器,它修补组件渲染出的工作负载,将生成的 Secret 挂载到其容器中,挂载位置是附件的 inject: 块所指定的变量或文件,该步骤在 .inject 处读取它们。迁移到另一个机密存储时替换获取器;注入器保持不变。步骤将其添加的资源作为副作用返回,将其对渲染文档的更改作为补丁返回;Wasm 插件契约 定义了两者的形状。
Feature 自身的凭据
Feature 可能需要自己的凭据:例如向上游服务认证的护栏代理,或带有摄取令牌的日志传送器。Feature 在其自身的 featuresSchema 中声明该槽位,方式与 Component 完全相同;绑定到它的 FeatureRecipe 在渲染该 Feature 的工作负载时读取填充该槽位的内容。
**附件不能嵌套。**凭据附加在 Feature 旁边,位于同一个组件上,使用 Feature 的槽位所声明的名称;槽位名称正是将两者关联起来的纽带。下面的防护 Feature 和组件是工作区自己的实体;core/referenced-secret 则属于标准库。
# The Feature declares the slotkind: Featuremetadata: name: local/guardspec: appliesTo: "component.aggrega.ai/type in (server, worker)" featuresSchema: guard_api_key: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]---# The Aggregate fills it beside the Featurespec: components: finance-agent: type: local/compute/guarded-worker features: ai-guard: type: local/guard guard_api_key: type: core/referenced-secret values: origin: dev-guard-key-change-me key: api-key防护的 FeatureRecipe 渲染一个工作负载,其容器引用该槽位:attachments: { GUARD_API_KEY: { from: guard_api_key, as: env } },因此该引用只落在防护的容器上,不会落在其他任何容器上。宿主组件的 Recipe 无法引用该槽位,因为该槽位属于 Feature:试图使用它的工作负载会使构建停止,并指出该槽位。指定了无任何内容填充的槽位的工作负载条目同样会使构建停止,因为没有可解析的已发布定位符。
Feature 发起的连接也是如此:Feature 自身 uses: 块中的连接不携带附件,因此这类连接所需的凭据是 Feature 声明的一个槽位,在 Feature 旁边填充。
连接自身的凭据
一个访问两个模型的网关可能向每个模型出示不同的密钥,或者向其中一个出示密钥,另一个则不出示。网关上的槽位为整个组件保存一个凭据,因此凭据改为放在连接上:网关的插座声明经由它的每个连接都可以填充的槽位,每个连接各自决定是否填充它。
spec: components: router: type: core/gateway/litellm uses: models: gpt: target: gpt features: credential: # a slot the models socket declares type: core/referenced-secret values: key: api-key网关的 Recipe 从其连接中读取附件,位置为 .context.uses.gpt.features.credential,因此访问多个模型的网关会读取每个模型自己的密钥;core/gateway/litellm 将每个密钥作为各自独立的变量交付,该变量由连接在其路由表中的条目指定。如果附件使用的名称在插座上没有声明对应的槽位,构建会停止,并列出插座已声明的槽位。Manifest 可以以不同于其他连接的方式实现某一个连接的凭据,在其按实例层级中以 <connection>.credential 为键。连接上的凭据——每个连接一个密钥,以及两端共用一个密钥 构建了这一点;Release 也可以接入这样的连接,并在附件的 infra 中指定该机密,如 凭据 Features 所述。