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

数据分类与组合

统一数据分类与组合规则

为了建立可预测的模式并消除认知摩擦,平台只使用五个通用易懂的关键字,并采用严格基于映射(字典)的 YAML 结构,在结构根部使用映射而不是嵌套数组。

1. 五关键字映射标准与模式的完全对称

直接的结构化词汇: 模式设计的一条基本规则是:根数据结构必须是单一的结构化关键字。使用口语化的英文短语(如 depends_on 或 runs_within)虽然能让 YAML DSL 对开发者读起来更自然,但在把这些键映射到程序化的 Go 模板时会引入结构上的复杂性。为了保持直接的 1:1 变量映射并防止领域特定语言(DSL)碎片化,核心目录实体(Component、Feature)的 JSON 模式呈现出近乎完全的结构对称,由编写的实例槽位中通用的同一组核心结构化关键字驱动。凭据 Features(标记为 feature.aggrega.ai/kind: secret)采用完全相同的范式——密钥没有单独的模式。

  • parameters(全局环境契约)
    • 作用范围: 在 Aggregate 的根部定义;由 Release(CI/CD)在 parameters: 下内联提供,或通过指向外部参数文件的 parameters: { $import: <path> } 提供。
    • 含义: 在不同环境间动态改变应用认知或逻辑状态的外部参数(例如把 workers: 2 改为 workers: 10)。支持在插值之前进行校验的类型化契约(完整的类型化契约语法见 data-pillars)。对于把参数值保存在单独文件中的 GitOps 工作流,Release 使用 $import: 形式;编译器加载该文件的内容并替换内联的 parameters: 映射。多文件分层通过 Release 的 extends: 链表达。
  • values(认知意图——由开发者负责)
    • 作用范围: 在 Aggregate 内的 components 及其 features 附件中统一使用,包括凭据 Features。
    • 含义: 核心认知状态、业务逻辑和运维配置。对 Go 编译器不透明,但由目录统一的 schema: 声明(紧凑形式或 JSON Schema 2020-12)严格校验。
  • uses(结构拓扑——声明式状态)
    • 作用范围: 在 Aggregate 内的 components 及其 features 附件中统一使用,包括凭据 Features。
    • 含义: 定义网络边和依赖关系的声明式事实陈述(例如“这个代理使用这个数据库”)。由 Go 编译器原生解析,用于绘制中间表示(IR)图。由目录统一的 usesSchema 声明校验,以确保跨节点的类型安全。
  • infra(物理现实——由运维负责)
    • 作用范围: 在 Release 内某个边界的 components 及其 features 附件中统一使用。
    • 含义: 在后期绑定期间注入的物理占用和机械规格(例如 cpu_limit: "4"、port: 5432)。Aggregate 的组件实例及其 features 附件不包含 infra 字段,并且结合 additionalProperties: false,在模式校验时拒绝 infra。由目录统一的 schema: 声明校验。
  • inject(交付契约——命令式指令)
    • 作用范围: 用于组件实例上、uses 中的显式目标定义内以及附加的 features 上,包括凭据 Features。
    • 含义: 一条显式的命令式指令,规定交付的意图(例如“编译器,把这个映射值作为环境变量注入”)。它为物理输出、已解析的端点或获取到的凭据建立抽象契约(env、file、arg 或自定义机制),而该挂载究竟如何执行的物理机制则完全委托给底层的运维 Recipe。每种机制都是一个条目列表([{ in: API_HOST, from: "host" }]),每个条目用 in: 命名其本地标识符,并且恰好携带 from: 或 value: 之一。
  • .context(通用元数据管道)
    • 作用范围: 由编译器静默注入运维 Recipe 模板。
    • 含义: 承载编译器从图的其余部分为该节点汇集的内容(如 .context.uses),直接传递给运维模板引擎。

1:1 映射的现实

通过用严格的基础设施关键字取代口语化的介词,实现了直接的 1:1 映射。运维工程师无需转换语法,只需引用开发者编写的确切键。

结构形态:根部用映射,载荷中用数组。 根拓扑块——components、features、aggregates、subsystems、boundaries——是 YAML 映射,其由用户编写的键作为稳定的实例 ID。这些位置不允许使用数组;映射键是编译器用于交叉引用(target: my-db)、图节点构建和 Manifest 解析的标识。在不透明的载荷块(values、infra、parameters)内部,完全允许使用数组——开发者可以在 Component 的 values 中写 tools_allowed: ["sql", "web"] 或 hostnames: ["stripe.com", "twilio.com"]。Aggregate 模式把这些载荷块声明为 additionalProperties: true,因此它们对 Go 编译器不透明,完全由目录内嵌的 schema: 声明校验。这样就把框架的易变性(新的 AI API 形态、新的云原生载荷格式)放在可以独立演进的目录领域内,而 Go 编译器在结构根部只处理可寻址的键。

2. 信息流:谁、何时、为何?

为防止模板命名空间冲突,以及物理基础设施配置意外泄漏到认知层应用逻辑中,该架构将数据明确划分为六条独立的数据流:

  • 流 1:环境注入(parameters): CI/CD 流水线注入部署现实。编译器根据带类型的 parameters: 契约校验 Release 提供的每个值,然后在执行下游 values: schema 校验之前插值已解析的 Go 模板变量。
    • 推荐用法: parameters 保留给随环境变化的认知层应用逻辑(例如 LOG_LEVEL=debug、ENABLE_BETA=true)。运维规模和物理基础设施方面的关注点——副本数、CPU 限制、AWS ARN、入口主机名——通过 Release 的 infra 块和边界覆盖层传递,使开发者的 Aggregate 专注于应用意图。
    • 务实的逃生舱口: 对于小型团队、快速原型开发,或无法实现严格分离的遗留 CI/CD 集成,parameters 可以在整个栈中承载全局环境配置。编译器接受任何通过 schema 校验的内容;上述建议是一种社会契约,而非编译器规则。
  • 流 2:认知层应用意图(Components 中的 values): 定义应用的内在逻辑。该 Component 的 schema: 声明(紧凑形式或 JSON Schema 2020-12)为该负载提供严格的类型检查和校验,为开发者提供即时的“左移”反馈,并确保所请求的配置与底层基础设施 API 相匹配。
  • 流 3:运维层 Feature 意图(Features 中的 values): 在 Aggregate 中,开发者请求那些行为属于应用意图的基础设施能力,并查询严格类型化的凭据,而无需修改内部代码。输入全部属于运维层的 Feature 不携带开发者 values:运维在 Release 中挂载它,并附带其 infra(流 4)。
  • 流 4:物理基础设施规格(infra): 物理 infra 规格完全绕过开发者,从特定于环境的 Release 直接显式投射到局部作用域的 Components 及其挂载的 Features 上,凭据 Features 也包括在内。为避免原样广播字典导致封闭 schema 校验冲突,infra 规格严格局限于显式指向它的那个组件。这使计算限制、副本数和机械资源需求保留在运维领域。
  • 流 5:级联注解(上下文元数据): 宽泛的上下文数据(如运维域、命名空间或计费代码)通过级联注解处理,从而避免 infra 广播污染。这些注解按来源被隔离到不同的桶中,下文每个桶的预期用途是一项社会契约:Recipe 模板可以读取全部三个桶,编译器并不强制执行这种隔离(参见 labels-and-annotations):
    • .context.annotations.release(领域 4 边界): 专门用于管理物理现实。运维通过 Go 模板将这些注解明确路由到严格的局部 infra 字段中(例如将区域命名空间映射到计算组件)。
    • .context.annotations.aggregate(领域 1 子系统): 专门用于管理认知和运维逻辑。这些注解被明确路由到组件的 values 负载中(例如将团队计费代码向下级联到应用配置)。
    • .context.annotations.catalog(领域 2 目录): 由架构师编写的不可变内在特征,主要用于以编程方式进行 Wasm 策略评估。
  • 流 6:元数据管道(.context): 将全局企业要求(SOC2 标签)直接应用到物理基础设施模板上。

3. 网络抽象:“零端口”约定

  • 最佳实践: 开发者应在 Aggregate 中省略端口。Ops Recipe 会动态处理内部路由。
  • 逃生舱口: 如果应用的内部代码无法修改,平台架构师会在 schema: 声明中显式暴露一个 port 字段。架构说明: “零端口”约定是平台更广泛的关注点分离最突出的例子。完全相同的理念——将物理机制从开发者面前抽象掉——同样适用于 CPU 请求、内存限制、运维域和磁盘规格。每当物理基础设施约束必须泄漏到开发者的应用负载中(由于遗留代码或严格的硬件要求),都必须由架构师 schema: 声明中显式的“逃生舱口”加以管控,开发者的负载正是依据该声明进行校验的。

“零端口”这个名称代表该约定;该原则可推广到遗留应用硬编码的任何物理基础设施约束。下面的 schema 以 tcp_keepalive_seconds 作为示例——这是应用在套接字层期望的一项内核/网络计时参数——因为它明确处于基础设施泄漏这一维度。

Schema(领域 2):

values:
image: { type: string, required: true }
# The architect explicitly allows the developer to declare a hardcoded constraint
tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }

开发者 YAML(领域 1):

components:
legacy-payment-engine:
type: core/java-tomcat:1.0.0
values:
image: "corp/payments:v4"
tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versa

编译器行为: Go 编译器将 tcp_keepalive_seconds: 120 传入 IR 图。随后 Ops Recipe 读取 {{ .values.tcp_keepalive_seconds }} 来配置 Kubernetes pod spec 或云提供商负载均衡器的空闲超时,从而在不违反 schema 的前提下成功弥合遗留差距。

4. 注入契约与预解析映射

在五个结构关键字中,inject 的形态与其他几个不同。parameters、values、uses 和 infra 是声明式状态——开发者陈述应用是什么以及它依赖什么的事实。inject 是命令式指令——开发者规定值如何交付给运行中的容器,将抽象数据源(目标的 provides 键、组件自身的 values、凭据 Feature 的 vault 响应)映射到具体的交付机制上(env、file、arg,或该 Component 声明的自定义机制)。

这种解耦是结构性的。开发者的 Aggregate 声明“将数据库主机作为环境变量 DB_HOST 注入”,而无需指明数据库的物理地址、密钥存储的 vault 路径或云提供商的主机名格式。Ops Recipe 通过 .context.inject 接收已解析的字符串并直接使用,无需编写查找链。

预解析映射。 渲染期间,编译器会解析每一个注入源——自注入字面量和针对组件自身 provides 的 from: 引用、通过 uses[].inject 的跨组件引用、FeatureRecipe 的 injectMapping 拦截——并将其合并为位于 .context.inject 的单一扁平字典。当基础 Recipe 的 valuesMapping 模板运行时,每个注入键都已携带其最终字符串值。Recipes 直接遍历该映射({{ range $k, $v := .context.inject.env }}),无需遍历解析链。

开发者为组件自身的值所取的名称。 当 Component 声明了 spec.inject 时,开发者自己的 inject: 块会选择组件自身的值和 provides 进入交付管道时所用的名称。编译器在 .context.self_inject 处告诉 Recipe 每个条目的模板所读取的那一个自身值——按机制,每个名称映射到 provides.<key>;对于恰好只读取一个自身值、不读取其他任何内容的模板,映射到 values.<key>;否则映射到空字符串——其形态与连接的名称在 .context.uses.<alias>.inject 处的形态相同。对于运行开发者镜像的 Recipe,标准库目录的约定是:将它原本会为组件自身的值选择的名称视为默认值,仅当尚无任何条目映射到某个自身值时,才以其默认名称传递该值。这是目录的约定,而不是编译器的规则:企业目录可以按自己选择的任何方式传递其组件自身的值。编译器从开发者编写的文本中读取该映射,不赋予这些名称任何含义。

完整的注入契约规范——双态上下文语义、键冲突规则、FeatureRecipe 拦截模型以及完整示例——见 topology-triad。

5. 模板引擎(Ops DX)

平台运维工程师编写转换模板,需要标准基础设施模板的全部能力,而无需使用专有的模板语言。Aggrega 的模板是 Go text/template:

  • 没有“魔法”字符串: 编译器保留开发者原样的映射键。运维通过标准的 Go 映射索引安全地访问 feature:{{ (index .features "public-route").infra.hostname }}。
  • Sprig 库: 编译器原生注册 Helm 标准的 Sprig 库,可直接使用 | default、| quote 和 | toYaml 等管道。
  • MappingLibrary 片段: 多个 Recipes 复用的映射片段存放在 MappingLibrary 中,并通过 $import: 引入每个 Recipe。Helm 的 chart 模板辅助函数(include、tpl、required、warn)未被注册;已注册的函数列于 sprig-functions。

6. 组合规则:Aggregates、子系统与 Components

  • 逻辑分组(subsystems 数组): 开发者可以使用 subsystems 同时为数十个组件应用逻辑元数据(团队归属、合规标签)和横切 feature。子系统在逻辑/意图平面上充当递归文件夹,将 annotations 向下级联到 .context.annotations.aggregate 存储桶中,并将 feature 附加到其包含的所有组件,而不规定物理边界。子系统级 feature 与组件级 feature 遵循相同的 schema(支持 type、values、uses、inject),因为它们属于领域 1(开发者意图)。编译器在图最终确定时将子系统 feature 展平到其包含的每个组件的 feature 列表中,在执行顺序上位于组件自身的 feature 之后、任何 Release 附加的 feature 之前。
aggregate.yaml
subsystems:
finance-module:
annotations:
"billing.corp.com/team": "payments"
features:
audit-logging:
type: core/audit-logger:1.0.0
values: { log_level: "verbose" }
components:
ledger-api:
type: core/python-worker:1.0.0
ledger-db:
type: core/postgres:1.0.0
  • 支持复合 Aggregates(模块模式): Aggregates 既可作为 Release 所构建的根 Aggregate,也可作为可复用模块。父 Aggregate 可以像声明组件一样声明子 Aggregate,并将 parameters 向下传入。为避免紧耦合,子 Aggregates 暴露一个 exportedComponents: 契约,建立稳定的公共接口名称。父级只能通过该接口访问模块的组件:uses: 目标指定模块及其导出的某个别名,编译器将边连接到该别名所指的内部组件;而以任何其他名称深入模块的目标会中止构建,并指出该模块及其导出的别名。模块本身可以以自己的接口名称重新导出嵌套模块已导出的组件(可选择重命名),编译器会以传递方式将这种重新导出链解析到底层内部节点,因此模块可以组合到任意深度,而父级无需知道目标嵌套得有多深。无法解析到任何内部节点的目标仍会明确地中止,而闭合回自身的重新导出链会被拒绝,而不是被无限跟随。
child-database-module.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
components:
internal-pg-primary:
type: core/postgres:1.0.0
exportedComponents:
# The Public Contract (Written once by the module author)
primary_db: "internal-pg-primary"
parent-app.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
aggregates:
finance-db-subsystem:
type: my-catalog/child-database-module:1.0.0
components:
billing-api:
type: core/python-worker:1.0.0
uses:
databases:
- finance-db-subsystem.primary_db
  • Components 不能包含子组件: Components 是原子构建块。组合发生在 Aggregate 层级,通过子系统和子 aggregate 实现。如果应用需要多个物理容器(例如 API + sidecar),这种物理嵌套位于运维 Recipe 模板内部,而不在 Component 定义中。

  • 每个 Component 一个连贯服务——单工作负载边界: 一个 Component 建模一个连贯的服务——单个对外暴露的服务,或一个服务的工作负载及其仅供内部使用的辅助工作负载。其 component.aggrega.ai/type 标签指明该服务的运行形态。当单个 Component 内的多个物理工作负载构成一个连贯的产品、且没有可独立使用的部分时,这样做是可以的:一个 chart 运行控制器、webhook 和注入器的服务仍然是一个 Component。判断标准不是多工作负载,而是可独立使用性。

    边界划在这样的位置:一个捆绑包中包含另一个组件可以有意义地单独 use 的东西——尤其是 Aggrega 已将其建模为独立 Component 的外部基础设施,例如数据库、缓存或消息代理。这样的捆绑包不是一个 Component,而是一个子 aggregate 模块——即上文所示的 spec.aggregates + exportedComponents 模式——为每个服务组合一个 Component,使每个服务都是可寻址的节点,拥有自己的类型、自己的边,以及自己的策略和扩缩容面。

    该启发式方法可以表述为一条明确的规则:该 chart 是否包含另一个组件可以有意义地单独使用的东西,或者 Aggrega 已有对应 Component 的东西?如果是,就将其建模为一个栈——一个组合按服务划分的 Components 的子 aggregate 模块。如果它只为这一个服务提供支持,就将其建模为一个 Component。

    将整个多服务产品包装成单个不透明的 Component 是一种有文档记载的反模式。编译器不预设立场,会接受这种做法——它会渲染任何通过 schema 验证的内容——但标准库会将按服务划分的 Components 组合成一个模块,因为整体式包装会对拓扑、选择器以及按服务的策略和扩缩容隐藏那些可独立建模的服务。这种粒度规范是一种社会契约——参见 ../language-reference/vocabulary/social-contracts.md(Component 粒度)。

7. 默认作用域——分组的渐进式披露

subsystems(在 Aggregate 中)和 boundaries(在 Release 中)是分组构造,但开发者不必预先声明它们。每个实体提供两种编写形式,且二者互斥:在命名作用域下分组编写组件,或直接在顶层编写组件——绝不能同时使用。同时声明顶层 components 和命名作用域的文档会在加载时因信封错误而停止。

对于扁平(顶层 components)形式,编译器会在加载时合成一个真实的 default 作用域,并将顶层组件折叠进去,从而让每个下游阶段都看到统一的、带作用域的结构。合成的作用域并不是隐藏容器:它是 IR 中一个真实的、带有来源标记的节点,可以与开发者显式命名为 default 的作用域区分开来。它只在作者阅读路径的地方被隐藏——诊断信息和寻址会呈现开发者实际编写的根形式 .spec.components[…]。

  • **扁平 Aggregate(顶层组件):**在 spec.components 下编写组件,不使用 subsystems。编译器在加载时将它们折叠到合成的 default 子系统中。子系统作用域的注解和子系统级 feature 只应用于已声明的子系统;扁平形式不携带这些内容。
  • 扁平 Release(顶层组件):在 spec.components 下编写组件,不使用 boundaries。编译器将它们折叠到合成的 default 边界中,其输出是扁平的——产物直接落在 dist/ 下(按 provider 划分:dist/compose/、dist/helm/、……),没有边界名称这一路径段。这是最简单的情形:对扁平的 Compose 或单集群目标执行 aggrega build,无需命名边界。(开发者声明并命名为 default 的边界是普通的命名边界,在没有自己的 directory: 时,与其他边界一样输出到 dist/boundaries/default/。)
  • **升级路径:**当扁平架构发展到需要分组(不同的命名空间、独立的逻辑分组、多边界部署)时,开发者将顶层组件移入显式的 subsystems,或由 Ops 引入显式的 boundaries。由于两种形式互斥,这是从扁平形式到作用域形式的迁移——而不是两者混用——并且节点标识在迁移过程中保持不变。

其理由是渐进式披露:为简单用例(单服务演示、快速的本地原型)强制要求分组会造成不必要的阻力。“10 分钟从零到可用”的上手测试要求开发者能够编写一个只含一个组件的最小 Aggregate、一个 Manifest 和一个 Release,并在无需先理解子系统或边界的情况下获得可用的输出。默认作用域是入口;声明的作用域是架构在成长过程中的去向。

下面的条目包括一个推荐模式和五项约束。schema 强制执行约束 4 和约束 5——Release 没有 values 块,Aggregate 的组件实例没有 labels 键;其余各项是编译器不做检查的约定。

  • 推荐模式:通过模板字符串进行参数提升

    • **示例:**开发者在其 values 块中编写 workers: {{ .parameters.env_workers }},不加引号,使值以其声明的整数类型传入。
    • **原因:**如果 Aggregate 将 env_workers 声明为带类型的参数(type: integer),编译器会先根据契约校验 Release 提供的值。参数契约校验发生在插值之前;插值发生在外层 values: schema 校验之前。这保持了 Aggregate 的可复用性:Ops 通过 Release 的 parameters: 提供整数,编译器根据带类型的 parameters: 声明校验它,将解析后的值代入文档,随后 Component 的 schema: 声明成功校验所得的整数。
  • 约束 1:凭据是附件,而不是值

    • **不推荐的模式:**开发者在组件上编写 values: { password: "123" }。
    • **原因:**标准库的约定是,凭据以 features: 下的附件形式请求,指定一个凭据 Feature type(带有 feature.aggrega.ai/kind: secret 标签的类型),并使用该附件自身的 values 描述对密钥存储的查询。这是一种约定,而不是编译器检查——编译器不解释 values 叶子的含义,会原样携带内联字面量。附件这一接口使规范编写的形式可用且带有类型。
  • 约束 2:与能力无关的 Components

    • **不支持的模式:**架构师在 Component 的 schema: 声明中编写 aws_instance_type: string。
    • **原因:**按照约定,Components 与能力无关。物理硬件目标位于 Ops Recipes 或通用的 .context 注解中,而不在核心的认知应用逻辑内部。
  • 约束 3:基于元数据的条件逻辑

    • **不支持的模式:**Ops 在 Recipe 中编写 {{ if eq .context.labels.gpu "true" }},从根本上改变部署策略。
    • 原因:.context 管道绕过了各支柱的 schema: 校验。在核心基础设施逻辑中依赖未经校验的标签会使平台变得脆弱。.context 对象承载元数据标记(例如计费、SOC2);结构性路由应放在经过 schema 校验的支柱中。
  • 约束 4:Release 不能覆盖开发者的值

    • **不支持的模式:**Ops 试图从 Release 覆盖开发者的认知逻辑(例如将 workers: 4 改为 workers: 10)。
    • 原因:Aggregate 是开发者意图的唯一事实来源。如果某个值在 Aggregate 中硬编码,它在各环境中就不可变。如果某个值必须随环境变化,开发者应使用参数提升。Release schema 通过禁止 values 块来强制执行这一点,将 Ops 限制为履行 parameters 契约和定义物理 infra。
  • 约束 5:Aggregate 上的实例级标签

    • **不支持的模式:**开发者在 Aggregate 内的组件实例上编写 labels: {}。
    • **原因:**标签是由平台架构师编写的、不可变的 Catalog 级特征——即策略引擎和选择器读取的语义标识。Release 通过显式的基于映射的 ID 定位(components: { "my-agent": {} })将组件路由到边界,这样既保留了按组件嵌套 infra 和 feature 覆盖的能力,又不会把标签的编写混入开发者的 Aggregate。

9. 安全边界与显式出站护栏(边界外目标)

没有应用是孤立存在的。编译后的 Aggrega 架构表示一个严格映射的图。然而,现代 AI 系统会不断与这个编译边界之外的实体交互——例如公共 SaaS LLM(Anthropic、OpenAI)、通用公共 API(Stripe、Twilio)或遗留的棕地数据库(本地部署的 Oracle)。

为了安全地集成这些外部系统,Aggrega 严格区分安全边界与执行机制。安全边界由通用 Component 规则和显式出站护栏管控。

1. 通用 Component 规则

如果应用与某个实体交互——无论是本地数据库、托管云资源、SaaS LLM 还是通用公共 API 端点——该实体都必须在 Aggregate 中声明为一个独立的 Component。这条规则是一项约定:编译器看不到应用发起的调用,因此没有任何机制检查它。

通过将外部 SaaS API 和遗留数据库视为中间表示(IR)图中的一等节点,开发者便能将零信任代理配置直接附加到出站调用上。例如,将 Stripe API 建模为独立节点后,开发者可以为其附加 header-injector feature,确保生成的配置使调用方 Agent 无需在自身内存中持有原始 API 令牌。

2. 显式出口护栏(基础设施合规)

Aggrega 不依赖硬编码的编译器逻辑来管控网络出口,而是将边界安全完全委托给企业自身与内容无关的策略引擎和 Wasm 渲染插件。这确保生成的配置严格符合显式的出口审批。

  • 目录钩子(领域 2): 当架构师定义一个公共 SaaS 组件(例如 core/external-service)时,会为其附加一个不可变的企业标签(例如 security.enterprise.com/zone: "untrusted-external")。
  • 策略护栏(编译时): 在生成任何配置之前,OPA 或 Kyverno 策略引擎会评估该图。企业编写一条简单规则:“如果内部节点连接到标记为 untrusted-external 的节点,则该目标节点的 ID 必须显式列在环境的 parameters.approved_egress 数组中。” 如果开发者试图将数据路由到未经批准的外部目标,策略引擎会中止构建。
  • 配置生成(渲染时): 如果策略通过,出口规则将根据运维人员挂载的内容渲染。在 Release 中挂载到调用方组件上的 core/egress-allowlist Feature,会在 helm 上为该组件渲染的每个工作负载渲染一个 Kubernetes NetworkPolicy,只允许出口流量到达其自身的 Pod、其 uses 边所指目标的 Pod(限于这些 Pod 声明的端口)、集群的 DNS,以及该挂载为集群未运行的目标(例如公共 SaaS API)列出的地址范围。除非 Release 通过 infra.control_plane_present: true 确认集群的网络插件会执行网络策略,否则构建会中止;对于任何未列出地址范围的此类外部连接,构建也会中止并指出该连接;在没有网络策略的 compose 上,该挂载会中止构建。开发者从不编写防火墙规则。

这通过一个评估已声明拓扑的治理裁决角色,保证显式声明的基础设施符合出口策略,而核心 Go 编译器无需理解“external”的含义。(注意:真正的零信任出口依赖目标集群在运行时运行默认拒绝(Default Deny)的 CNI;生成的配置只是映射已授权的例外。)

每个外部服务一个 Component

每个外部服务都声明为一个独立的组件,而不是合并到一个多目标数组中。如果应用调用五个不同的第三方 API,开发者就声明五个独立的 core/external-service 组件。正是这种按服务的声明,使策略引擎和 Wasm 插件能够单独针对每个出站目标——为每个外部依赖附加不同的出口策略、不同的代理 feature 或不同的可观测性钩子。

将安全与执行解耦(“棕地”场景)

需要特别注意的是,语义标签(例如 untrusted-external)决定的是网络安全策略,而非执行方式。它与 Aggrega 是否渲染用于预配该资源的产物无关。

  • 场景 A(公共 SaaS API): 在目录中标记为 untrusted-external(触发策略出口护栏)。由引用型工作负载实现(不预配计算资源;参见 §10)。
  • 场景 B(内部遗留数据库): 标记为 internal-trusted(绕过出口护栏,留在 VPC 内)。由引用型工作负载实现(不预配计算资源;参见 §10)。
  • 场景 C(自托管数据库): 标记为 internal-trusted。通过 Helm 渲染插件执行(实际预配为 Kubernetes StatefulSet)。

10. 构建不预配的服务:引用型 Workloads

当应用与遗留的本地部署数据库或公共 SaaS API(如 Stripe)交互时,Universal Component Rule(通用 Component 规则)规定,这些外部实体必须在 Aggregate 中声明为独立的组件。然而,Aggrega 不得尝试为它们生成物理的 Kubernetes Pod 或 AWS RDS 实例制品。

实现此类组件的 Recipe 声明一个 form: reference 的 Workload:一个 endpoint(主机或 URL)、可选的 port,且没有容器。编译器将两者作为确定性的指针字符串原样传递,从不解析它们。provider 为引用型 Workload 渲染什么由该 provider 自行决定:helm 生成一个携带端点主机的 ExternalName Service,使集群中的工作负载能够以稳定的集群内名称访问端点为 DNS 名称的服务;compose 不为其渲染任何内容。Kubernetes 将 externalName 视为 DNS 名称,因此以 IP 地址写出的端点是通过使用方收到的地址访问的,而不是经由该 Service。

在这两个 provider 上,该 Recipe 的 provides: 都通过 .context.uses 和 inject 契约到达每个使用方,与已预配组件的完全相同。因此,当目标从预配转为引用时,使用方的连接方式不会改变:改变的只是 Manifest 将该目标映射到的 Recipe。

分步执行流水线

1. 领域 1(Aggregate):开发者意图 开发者请求一个遗留 Oracle 数据库。他们不关心它位于何处,只规定调用方 Agent 期望以环境变量的形式获得连接字符串。由于 IP 是静态的且事先已知,他们通过参数传入。

components:
legacy-oracle:
type: core/legacy-database:1.0.0
values:
host: "{{ .parameters.legacy_oracle_ip }}"
sid: "PROD_DB"
my-agent:
type: core/python-worker:1.0.0
values: {}
uses:
databases:
legacy_db:
target: legacy-oracle
inject:
env:
- in: ORACLE_DSN # Local env var
from: "primary_endpoint" # Target provides key

2. 领域 4(Manifest):路由 运维将遗留数据库类型映射到格式化其连接字符串的 Recipe。Manifest 只指定一个 Recipe,别无其他;所指定的 Recipe 声明一个 form: reference 的 Workload,正是这一形式使该节点不预配计算资源。由于无论目标如何,该映射都只有一种形态,路由始终保持完全扁平且可预测。

spec:
mappings:
components:
type:
"core/legacy-database": "oracle-dsn-formatter:1.0.0"

3. 领域 3(引用型 Recipe):构建交接 运维工程师编写该 Recipe。它在 locals 块中根据开发者的 values 构建 primary_endpoint 连接字符串,将其发布在 provides 下,并声明一个指向数据库主机的引用型 Workload。

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: oracle-dsn-formatter
version: 1.0.0
spec:
capability: helm
implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values
locals:
primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads
provides:
primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
form: reference
endpoint: "{{ .values.host }}"
port: 1521

4. 渲染时的编译器执行(交接)

  1. 编译器对 legacy-oracle 的 Recipe 求值。对于提供 legacy_oracle_ip: "10.0.4.55" 的 Release,其 primary_endpoint 为 oracle://10.0.4.55:1521/PROD_DB。
  2. 在 helm 上,该引用型 Workload 渲染一个 ExternalName Service legacy-oracle,其中 externalName: 10.0.4.55,端口为 1521;在 compose 上,它不渲染任何内容。
  3. 随后编译器渲染 my-agent 的 Recipe。其 .context.uses 管道携带 Oracle 节点的 provides,inject 契约已依据它们解析出 ORACLE_DSN。

5. 领域 3(调用方 Recipe):履行契约 Python worker 的标准 Helm recipe 读取它收到的 inject 映射,与面对构建所预配的数据库时完全相同。

# Inside python-worker-helm (The calling agent's recipe)
env:
# The compiler pre-resolved the target's provides into the inject map
{{- range $key, $value := .context.inject.env }}
- name: {{ $key }} # Renders: ORACLE_DSN
value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB
{{- end }}

11. Schema 桥接跨支柱管道:将意图桥接到基础设施

关于通过子组件安全暴露专用基础设施调节项的 schema 桥接模式,请参阅 inheritance-and-interface——即在 Component 的 schema: 上声明一个面向开发者的 values: 字段,由 Recipe 的 valuesMapping: 模板将其导入渲染后的 infra: 形态输出。

12. 全新环境资源供给(“平台 Aggregates”)

平台工程中一个常见的陷阱,是强迫路由器(即 Release 文件)承担繁重的 Day-0 集群资源供给(例如,先启动一个新的 AWS EKS 集群,再将应用部署到其中)。这会产生冗长且难以阅读的路由文件。

Aggrega 采用“层层皆是乌龟”(Turtles All the Way Down)的原则处理这一问题。Release schema 不包含用于安装基础设施的块;集群资源供给通过 Platform Aggregates 建模。

由于 AWS EKS 集群、Istio 控制平面和 AWS VPC 归根结底只是物理云资源,它们的建模方式与应用组件完全相同。

  1. **Platform Aggregate:**基础设施团队编写一个标准的 Aggregate.yaml,其中的组件为 core/aws-vpc、core/eks-cluster 和 core/istio-base。
  2. **Platform Release:**他们部署这个 aggregate。为这些平台组件绑定的渲染器会输出搭建基础设施所需的制品。
  3. **Application Release:**当应用开发者准备部署其 AI Agent 时,运维团队只需在该应用自己的 Release 文件中用一个边界指向新创建的集群。