provides、inject、uses
注入契约与预解析映射
由于 Aggrega 是一个预先编译(AOT)的静态编译器,编译期间不会有任何数据从实际运行的基础设施反向流入。编译器在机制上不可能主动获取物理凭据(例如 AWS 密钥)并将其“回传”给开发者的容器环境。
相反,平台依赖于真正的控制反转。当开发者编写 inject: { env: [{ in: ORACLE_PASSWORD, from: "password" }] } 时,他们并不是在发起数据获取,而是在向基础设施规定一份严格的契约。
- 意图(领域 1): 开发者声明一个抽象接口:“我需要一个密钥。我不知道它存放在哪里。只需将它作为
ORACLE_PASSWORD注入我的环境,并映射到目录的password键。” - 编译器传递(渲染时): Go 编译器接收条目
{ in: ORACLE_PASSWORD, from: "password" }并将其交给 Ops Recipe。不会获取任何物理密钥。 - Plugin 输出(领域 3): 凭据 FeatureRecipe 的 Wasm 流水线生成目标基础设施所需的、精确且相互配合的制品。例如,在 Kubernetes 中,它输出
ExternalSecretCRD(指示集群获取 vault 数据),并且对目标 Pod 执行 JSONPatch,将生成的本地 K8s Secret 专门映射到开发者请求的"ORACLE_PASSWORD"环境变量。 - 运行时实际情况: 在运行时,集群中的 operator 只需执行这些生成的制品——获取凭据并将其物理挂载到容器中——从而将物理安全机制与 AOT 编译器完全解耦。
为了在不违反关注点分离的前提下将这一物理现实交付给应用,Aggrega 使用注入契约。不过,该契约严格区分自定义应用代码与商用现成(COTS)基础设施:
- 白盒(自定义代码): 该组件是一个通用的工作单元(例如自定义 Python 代理)。Go 编译器和 Ops Recipe 完全不知道开发者的自定义脚本需要哪些变量。因此,凡是代码读取的名称不在其 Recipe 默认交付范围内,开发者都通过
inject:块规定交付方式——既包括跨组件依赖(通过uses[].inject,其中from:引用目标的provides),也包括组件自身的值(通过组件级inject,使用value:字面量或引用自身provides的from:)。允许哪些机制按接入面分别声明,且两种声明彼此独立:组件自身的值受spec.inject允许列表约束(例如inject: ["env", "file"]),而uses:边受其所经由的插槽上的允许列表约束,即spec.usesSchema.<socket>.inject。在任一接入面上,规定约束该处的允许列表未列出的机制都会使构建中止。 - 黑盒(封装计算): 该组件是一个封闭系统(例如 Redis、托管的 API Gateway)。Ops Recipe 已经确切知道该系统如何使用其数据。因此,Component 目录实体省略允许列表,这会彻底禁止规定交付方式,而不是缩小其范围——省略
spec.inject会禁止组件级自注入,而声明时没有inject:允许列表的插槽会禁止经由它连接的边上出现任何inject:块。开发者只需通过uses提供依赖目标,平台会通过 Recipe 的valuesMapping原生处理内部连接。
确定性寻址规则(内部网络物理)
Aggrega 的 .context.uses 管道在编译时将目标字符串动态注入容器。由于核心 Go 编译器与物理网络完全无关,什么才算有效的地址字符串完全取决于由 Platform Ops 维护的社会契约,而非编译器的功能——编译器会将 Ops Recipe 产生的任何确定性指针字符串不加解释地传入下游模板上下文。
规则:Ops Recipe 必须导出一个确定、稳定的地址指针。 provider 不计算 IP。相反,目标的 Ops Recipe 应当构造一个可预测的字符串,并通过其 provides: 契约公开它(例如在 Kubernetes 中发布 provides.internal_host: "http://agent-b.namespace.svc.cluster.local",或在 Terraform 中发布类似 "${module.db.endpoint}" 的插值字符串,其中该模块为该值声明了相应的 output)。
依赖编译器获取资源创建后的动态 IP,直接违反了 AOT 执行模型。由于编译器在云端创建任何实际计算资源之前就对拓扑进行求值,它在物理上无法获取尚不存在的数据。如果某个服务需要一个仅在计算资源启动后才生成的随机 IP,编译器在物理上无法获取它。编译器唯一的职责是将 Ops Recipe 提供的确定性指针字符串原样传入调用方容器的环境变量,最终解析交由集群的 DNS 或运行中的 IaC 状态管理器完成。
强制使用确定性寻址可从根本上解决循环依赖(例如 Agent A 委托给 Agent B,而 Agent B 又委托回 Agent A)。由于稳定的 URL 或 IaC 指针在任一容器实际启动之前即可作为字符串计算出来,编译器可以安全地将两个代理连接在一起,而不会引入时序竞争条件。
(注:此规则同样适用于外部入口。如果某个架构公开了一个公共 API Gateway,并需要将该 URL 反向注入内部容器,Go 编译器无法获取云端随机生成的 URL(例如 xyz123.execute-api.aws.com),因为它在编译时并不存在。Ops 必须编写其 Recipe,要么映射一个确定的自定义域名(例如 api.enterprise.com),要么导出原生 IaC 插值字符串,以确保 AOT 编译器拥有一个已知引用可供安全注入)。
实现机制(目录即 API 契约) 为了在实现这一点时不让开发者与 Ops 紧密耦合,Aggrega 将平台目录(领域 2)用作严格的 API 契约,并采用三个不同的验证层:
- 凭据 Feature Schema(标记为
feature.aggrega.ai/kind: secret): 仅验证 vault 查询(path、key)。它与容器如何使用这些数据完全无关。 ComponentSchema(spec.inject允许列表): 通过spec.inject字段执行黑盒/白盒规则。如果存在spec.inject(例如inject: ["env", "file"]),开发者可以使用这些交付机制进行组件级自注入。如果省略spec.inject,编译器在结构上禁止自注入——黑盒组件完全依赖 Recipe 的valuesMapping进行内部连接。构建在解析 Aggregate 时强制执行这一点,拒绝该组件的inject:块并指出相应机制,这不同于schema:下按支柱进行的内容验证。featuresSchema映射:它在 Component 目录中定义,明确声明开发者必须(或可以)使用的凭据槽位。每个条目指定required(默认为false)、inject允许列表([]= 黑盒,[env, file]= 透明)以及description。由于这些键是稳定的且由契约保证,Ops 工程师可以直接依赖它们,在其 Go 模板中可靠地规定确定性目标(例如helm目标上的existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}"),并通过.locals显式导出名称的后缀——local 无法读取.context.rendered_name——这样下游凭据 FeatureRecipe 会将这两部分拼接起来,在不违反 AOT 执行顺序的情况下满足该需求。完整的featuresSchema设计参见entities/component.md。
严格放置规则: inject: 机制可用于开发者 Aggregate 中的三个位置:
- **组件级自注入:**作为组件实例上
values:的直接同级项。将组件自身的字面值或其自身的provides键注入交付管道。仅当 Component 目录声明了带有相应机制的spec.inject时才允许。 - **Uses 级交叉注入:**位于
uses:块中的显式目标定义内。将依赖目标的provides键注入交付管道。 - **Feature/Secret 级注入:**在附加 feature 和 secret 时,作为
values:的同级项。将附件自身已解析的provides键(secret 的已解析凭据,或 feature 提供的值)注入交付管道。
这三种形式都填充同一个 .context.inject 管道。无论有多少来源向其贡献内容,Recipe 读取的都是单一、统一的管道。
inject schema 为工具定义了标准枚举(env、file、arg),但将 additionalProperties 保持开放,因此可以命名自定义机制(例如用于 AWS Systems Manager Parameter Store 的 ssm_param)。有一个名称已被占用:all 是 Recipe 在 .context.inject.all 读取的所有机制的合并视图,因此将某个机制命名为 all 的 inject 块会在文档信封处中止构建,并说明这一点。
注入条目语法:在 inject 块下,每种交付机制——env、file、arg 或自定义机制——都是一个条目列表,且每个位置都使用相同的条目形态。决定条目字符串含义的是条目所带的关键字,而不是条目所在的位置,因此无论条目出现在哪里,其读法都相同。如果某个机制写成映射而不是列表,或某个条目同时带有两个关键字,构建会在 Aggregate 的文档信封处中止,并指出 Aggregate 中形态错误的路径。
条目关键字(from: 和 value:):每个条目使用 in 关键字表示本地标识符——环境变量名、文件路径、参数标志——外加 from:(provides 键引用)或 value:(字面字符串)中的恰好一个。from: 针对其所在位置所指节点的 provides 进行解析:在 component.inject 中是组件自身的,在 uses[target].inject 中是目标的,在 features[<name>].inject 中是附件自身的:
| 关键字 | 含义 | 在 component.inject 中是否允许 | 在 uses[].inject 中是否允许 | 在 features[<name>].inject 中允许 |
|---|---|---|---|---|
from: | 针对 provides 解析 | ✅ 自身节点的 provides | ✅ 目标节点的 provides | ✅ 附件自身的 provides |
value: | 字面字符串(支持 Go 模板) | ✅ | ❌(value: 在 uses[].inject 中无效;自注入请使用组件级 inject) | ❌ (value: 在附件的 inject 中会中止构建;自注入请使用组件级 inject) |
示例:
# Component-level self-inject (White-Box custom code)components: my-worker: type: core/python-worker:1.0.0 values: app_token: "xyz" inject: env: - in: MY_TOKEN value: "xyz" # Literal value - in: LOG_LEVEL value: "debug" # Literal value - in: CALLBACK_HOST from: "host" # From own provides (already evaluated) - in: APP_VERSION value: '{{"{{"}} .values.app_token }}' # Go template expanding own values uses: databases: my_db: target: postgres-db inject: env: - in: DB_HOST from: "host" # Provides key from target - in: DB_PORT from: "port" # Provides key from target - in: DB_URL from: "dsn" # From target's providesAPP_VERSION 的 value: 中的模板以 {{"{{"}} 而不是 {{ 开头:在自注入解析运行之前,Aggregate 的全部文本会作为模板读取一次,用于参数插值,而此时 .values 尚不存在,因此该转义会把 {{ 放回,留待自注入解析求值。参见自带双花括号的文本。
**Provider 特定说明(compose)。**当 uses: 边在以 compose 为目标的节点之间解析时,compose provider 会从这些边派生 depends_on 条目。这些条目始终使用 service_started 语义,与任何目标的 health: 块无关;尚未实现基于目标健康状态进行门控。完整的推断规则参见 providers/compose.md。
注入键冲突规则: 开发者从两个不同来源请求同一个交付键(例如同一个环境变量名)属于致命错误,而不是合并。编译器会检测到冲突并中止构建:
| 来源 A | 来源 B | 结果 |
|---|---|---|
component.inject | uses[].inject | ❌ 致命中止——交付键重复 |
uses[target_A].inject | uses[target_B].inject | ❌ 致命中止——交付键重复 |
component.inject | features[<name>].inject | ❌ 致命中止——交付键重复 |
uses[].inject | features[<name>].inject | ❌ 致命中止——交付键重复 |
features[A].inject | features[B].inject | ❌ 致命中止——交付键重复 |
component.inject(同一键出现两次) | — | ❌ 致命中止——交付键重复 |
features[A] 的 FeatureRecipe injectMapping | features[B] 的 FeatureRecipe injectMapping | ❌ 致命中止——两个附件之间交付键重复 |
features[A].inject | features[B] 的 FeatureRecipe injectMapping | ❌ 致命中止——两个附件之间交付键重复 |
component.inject 或 uses[].inject | FeatureRecipe injectMapping | ✅ 合法——设计上的拦截:映射的值替换该条目 |
该表以相同方式对待每个附加的 Feature,无论它附加在何处——在组件上、在子系统或 Release 边界上、通过注解展开,或在连接上。FeatureRecipe 的 injectMapping 在每个 inject: 块完成交付之后才渲染,因此它始终是两个声明中较晚的一个:它可以改写组件或其某个连接交付的内容,也可以改写其自身附件的 inject: 块交付的内容,但若某个键已由另一个附加的 Feature 交付,则构建中止,并指出双方。
附加到 Release 边界、且其 FeatureRecipe 针对该边界只渲染一次(executionScope: boundary)的 Feature,会通过同一途径到达该边界所含的组件:其 injectMapping 针对其中每个组件、在该组件的上下文中各运行一次,并像任何其他映射一样受上表各行约束。compose 桥接改写消费者的主机变量,使其经由网关到达目标,就是这样一种映射,因此若另一个附加的 Feature 交付了同一变量,构建将中止,并指出双方。
为避免 Recipes 中出现 Go 模板样板代码,编译器同时提供:
.context.uses:经过丰富的拓扑边映射(用于复杂逻辑、secret 引用和来源追踪)。.context.inject:预解析的扁平字典,编译器已将所有注入来源(自注入字面值、自注入 provides 引用和跨组件 provides 引用)解析为最终字符串值,随后应用了 FeatureRecipeinjectMapping拦截。
双状态注入上下文(空值安全与意图纯度) 在为修饰器(绑定到任意附件的 FeatureRecipe,无论是否为凭据)生成配置时,编译器必须在 Go 模板的空指针安全、动态网络路由以及保持与能力无关的图之间取得平衡。为此,编译器向模板提供双状态上下文:
.inject_raw(不可变意图):表示组件自身的inject:块,与开发者在领域 1 中编写的完全一致。它是不可变的。如果开发者省略了该块,其值为null。运维专门将其用于逻辑检查(例如用{{ if not .inject_raw }}应用回退行为)。由于它不可变,即使路由 feature 拦截并修改了物理交付管道,它也能保护运维模板免受误判。.context.inject(预填充且经拦截的管道):一个并行的、由编译器生成的结构,表示物理交付的实际状态。它起初是一个预填充的映射(例如将API_HOST映射到目标的基础字符串"backend-instance")。关键在于,该管道被设计为可由 Features(例如网络路由)通过injectMapping块拦截并深度合并。到 Base Recipe 渲染时,该管道已包含完整格式化、物理上正确的字符串(例如完整正确的网络名称"backend-instance.backend-zone.svc.cluster.local")。其内容按env、file、arg(以及 Component 的注入允许列表所允许的任何自定义交付机制)组织,并附带一个预合并的.all字典,汇总所有机制,便于整体序列化管道。.context.self_inject(每个名称交付哪个自有值): 从与.inject_raw相同的组件级inject:块读取,其形态与.context.uses.<alias>.inject给出连接名称的形态相同:按每种机制,开发者写下的每个名称都映射到其条目所交付的组件自有键——对于from:条目是provides.<key>;对于恰好只读取组件自有值中的一个、不读取其他任何内容的value:模板是values.<key>;其他任何情况(一个字面量、两个值、读取值以外的任何内容)则为空字符串。它让运行开发者自有镜像的 Recipe 能将其自身的变量名视为默认值——仅当没有任何条目已映射到values.<key>时,才以默认名称交付一个自有值,因此重命名某个值的开发者会保留其他所有默认值。这是标准库目录的约定,而不是编译器规则;企业目录可以按自己选择的任何方式交付其组件的自有值。
运维仅将 .context.inject 结构用于安全序列化(例如 {{ toJson .context.inject.all }})和路由生成,从而确保物理基础设施收到完全解析的坐标,而开发者的原始意图在 .inject_raw 中保持完好。
开发者 YAML 示例(细粒度映射):
uses: databases: my-postgres-cluster: target: db-main inject: ssm_param: # Agnostic injection paradigm (AWS Systems Manager) - in: MY_DB_HOST # Local identifier from: "host" # Target provides key编译器在编译时解析这些内容(映射为静态字符串或内部 DNS 名称),并将这两个对象传递给 Recipe:
"context": { "uses": { ... raw graph ... }, "inject": { "all": { "MY_DB_HOST": "db-main.internal" }, "ssm_param": { "MY_DB_HOST": "db-main.internal" } }}连接级配置(values 和 infra)。 除了通过 inject 传递目标的 provides 之外,一条边还可以携带自己的配置——即消费方 Recipe 从增强拓扑管道中读取的每连接设置:
.context.uses.<alias>.values—— 由开发者编写,在 Aggregate 的详细uses条目中声明,并依据插槽的valueSchema进行校验。.context.uses.<alias>.infra—— 由运维人员编写,在 Release 中声明,并依据插槽的infraSchema进行校验。
插槽(usesSchema[<socket>])是架构师的契约,规定了哪些连接是可能的以及它们可以携带什么配置;values 和 infra 按编写领域拆分该配置,与组件上的 values/infra 拆分相对应。因此一条边有两位作者:开发者在 Aggregate 中连接拓扑并用 values 对其调优,而运维人员在 Release 中、在架构师声明的插槽范围内设置每连接的 infra。Release 还可以将一个已声明但未绑定的插槽连接到一个现有组件;但不能更改开发者声明的边的目标——参见 entities/release.md §“Per-edge connection configuration”。
每条边的配置作用于消费方:它只出现在编写该边的节点(即连接的源)的上下文中,绝不出现在目标的上下文中。因此,目标自身的渲染输出不随连接到它的消费方而变化。附加到目标上的 Feature 是唯一能看到这些连接的地方:其 FeatureRecipe 在 .context.used_by 读取哪些组件使用该目标——每个组件的标识、插槽、发布的 provides、所在的命名空间和边界,以及(对于声明要读取它们的 FeatureRecipe)其 provider 报告的渲染事实——但绝不读取连接自身的 values 或 infra。附加到消费方的 Feature 以同样方式,在该连接的条目 .context.uses.<alias>.render_facts 上读取其各个目标的渲染所报告的内容,前提是其 FeatureRecipe 声明要读取它们。
连接附件(features)。 一个连接还可以携带自己的附件——例如消费方向该连接所到达的组件出示的凭据——位于其条目的 features: 下,以插槽在其 featuresSchema 中声明的槽位为键。同样由两位作者分担:开发者在 Aggregate 的连接条目上用 type 和 values 进行附加,运维人员在 Release 的条目上用 infra 为该附件确定规格,或用 type 和 infra 附加自己的附件。连接上的附件不带自己的 inject 块,这就是它不出现在上述放置规则中的原因:它不是开发者指定传递方式的位置之一。
每个附件都成为消费方组件的一个名为 <alias>.<slot> 的附件,因此它与每条边的配置一样作用于消费方:其 FeatureRecipe 在消费方一侧渲染,目标的输出不会因它而改变。它不包含在消费方 Recipe 的 .features 中,后者只保存组件自身块所声明的附件;Recipe 改为在其连接下读取它,位于 .context.uses.<alias>.features.<slot>。由 Feature 附件引出的连接不携带附件。参见 entities/aggregate.md §“A connection’s own attachments”和 entities/component.md §“Topology Sockets”。
A. 环境变量(env)与动态目标解析
现代云原生应用的标准传递机制。对于显式的拓扑边(例如 Agent 与数据库通信),Aggrega 使用 .context.uses 注入环境变量映射。
- 用例: 接收确定性的内部 DNS 名称、基础设施即代码插值字符串(例如
${module.db.endpoint})或静态 Vault 指针。编译器以 AOT 方式连接这些静态引用,以便运行时基础设施或 GitOps 控制器解析实际值。
B. 文件挂载(file)
许多企业级 AI 框架期望在磁盘的特定路径上存在结构化的 config.json 或 .pem 证书,而不是依赖环境变量。
-
用例: 注入复杂的 JSON 配置,或满足从磁盘读取的旧版 SDK。
-
开发意图:
features:openai_key:type: core/aws-secrets-managervalues:path: /prod/ai/openaikey: "api_token"inject:file:- in: "/etc/secrets/openai.json" # Local pathfrom: "api_token" # The attachment's provides key -
运维实现: 运维 Recipe 动态生成所需的 Kubernetes
Volume、VolumeMount和ExternalSecret,以安全地拉取 vault 数据并将其挂载到/etc/secrets/openai.json。
C. 命令行参数(arg)
预编译的二进制文件(如 Rust 或 Go 工作节点)通常完全绕过环境变量,期望值以运行时标志的形式传入其执行命令。
-
用例: 将物理实际值追加到容器的启动命令中。
-
开发意图:
features:public-ingress:type: core/external-ingressinject:arg:- in: "--callback-url=" # Local flagfrom: "hostname" # The attachment's provides key -
运维实现: 主机名是环境对该组件的命名,因此由运维人员在 Release 中该组件条目上此附件的
infra里写入api.enterprise.com。该 Feature 的 Wasm 插件通过注入契约接收解析后的公共 URL,并生成一个 JSONPatch,动态追加 Kubernetesargs数组:["/app/binary", "--callback-url=https://api.enterprise.com"],完全绕过该 Component 的基础 Recipe。