跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

provides、inject、uses

注入契约与预解析映射

由于 Aggrega 是一个预先编译(AOT)的静态编译器,编译期间不会有任何数据从实际运行的基础设施反向流入。编译器在机制上不可能主动获取物理凭据(例如 AWS 密钥)并将其“回传”给开发者的容器环境。

相反,平台依赖于真正的控制反转。当开发者编写 inject: { env: [{ in: ORACLE_PASSWORD, from: "password" }] } 时,他们并不是在发起数据获取,而是在向基础设施规定一份严格的契约。

  1. 意图(领域 1): 开发者声明一个抽象接口:“我需要一个密钥。我不知道它存放在哪里。只需将它作为 ORACLE_PASSWORD 注入我的环境,并映射到目录的 password 键。”
  2. 编译器传递(渲染时): Go 编译器接收条目 { in: ORACLE_PASSWORD, from: "password" } 并将其交给 Ops Recipe。不会获取任何物理密钥。
  3. Plugin 输出(领域 3): 凭据 FeatureRecipe 的 Wasm 流水线生成目标基础设施所需的、精确且相互配合的制品。例如,在 Kubernetes 中,它输出 ExternalSecret CRD(指示集群获取 vault 数据),并且对目标 Pod 执行 JSONPatch,将生成的本地 K8s Secret 专门映射到开发者请求的 "ORACLE_PASSWORD" 环境变量。
  4. 运行时实际情况: 在运行时,集群中的 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 契约,并采用三个不同的验证层:

  1. 凭据 Feature Schema(标记为 feature.aggrega.ai/kind: secret): 仅验证 vault 查询(path、key)。它与容器如何使用这些数据完全无关。
  2. Component Schema(spec.inject 允许列表): 通过 spec.inject 字段执行黑盒/白盒规则。如果存在 spec.inject(例如 inject: ["env", "file"]),开发者可以使用这些交付机制进行组件级自注入。如果省略 spec.inject,编译器在结构上禁止自注入——黑盒组件完全依赖 Recipe 的 valuesMapping 进行内部连接。构建在解析 Aggregate 时强制执行这一点,拒绝该组件的 inject: 块并指出相应机制,这不同于 schema: 下按支柱进行的内容验证。
  3. 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 中的三个位置:

  1. **组件级自注入:**作为组件实例上 values: 的直接同级项。将组件自身的字面值或其自身的 provides 键注入交付管道。仅当 Component 目录声明了带有相应机制的 spec.inject 时才允许。
  2. **Uses 级交叉注入:**位于 uses: 块中的显式目标定义内。将依赖目标的 provides 键注入交付管道。
  3. **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 provides

APP_VERSION 的 value: 中的模板以 {{"{{"}} 而不是 {{ 开头:在自注入解析运行之前,Aggregate 的全部文本会作为模板读取一次,用于参数插值,而此时 .values 尚不存在,因此该转义会把 {{ 放回,留待自注入解析求值。参见自带双花括号的文本。

**Provider 特定说明(compose)。**当 uses: 边在以 compose 为目标的节点之间解析时,compose provider 会从这些边派生 depends_on 条目。这些条目始终使用 service_started 语义,与任何目标的 health: 块无关;尚未实现基于目标健康状态进行门控。完整的推断规则参见 providers/compose.md。

注入键冲突规则: 开发者从两个不同来源请求同一个交付键(例如同一个环境变量名)属于致命错误,而不是合并。编译器会检测到冲突并中止构建:

来源 A来源 B结果
component.injectuses[].inject❌ 致命中止——交付键重复
uses[target_A].injectuses[target_B].inject❌ 致命中止——交付键重复
component.injectfeatures[<name>].inject❌ 致命中止——交付键重复
uses[].injectfeatures[<name>].inject❌ 致命中止——交付键重复
features[A].injectfeatures[B].inject❌ 致命中止——交付键重复
component.inject(同一键出现两次)—❌ 致命中止——交付键重复
features[A] 的 FeatureRecipe injectMappingfeatures[B] 的 FeatureRecipe injectMapping❌ 致命中止——两个附件之间交付键重复
features[A].injectfeatures[B] 的 FeatureRecipe injectMapping❌ 致命中止——两个附件之间交付键重复
component.inject 或 uses[].injectFeatureRecipe 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 引用)解析为最终字符串值,随后应用了 FeatureRecipe injectMapping 拦截。

双状态注入上下文(空值安全与意图纯度) 在为修饰器(绑定到任意附件的 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-manager
    values:
    path: /prod/ai/openai
    key: "api_token"
    inject:
    file:
    - in: "/etc/secrets/openai.json" # Local path
    from: "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-ingress
    inject:
    arg:
    - in: "--callback-url=" # Local flag
    from: "hostname" # The attachment's provides key
  • 运维实现: 主机名是环境对该组件的命名,因此由运维人员在 Release 中该组件条目上此附件的 infra 里写入 api.enterprise.com。该 Feature 的 Wasm 插件通过注入契约接收解析后的公共 URL,并生成一个 JSONPatch,动态追加 Kubernetes args 数组:["/app/binary", "--callback-url=https://api.enterprise.com"],完全绕过该 Component 的基础 Recipe。