实体分类
Aggrega 的架构分为四个领域,每个领域归属于不同的角色并容纳特定的实体类型,此外还有一个第 3 层库层——即语言参考中实体层级模型的第三层——用于存放可复用的模式、映射、工作负载和制品内容。下面的概览展示了四个领域与第 3 层库之间的相互关系;随后的每一节都以一张展示本节实体的图开头,图中来自其他领域的实体以虚线轮廓绘制。每个实体的详细编写界面(字段、模式、示例)见语言参考实体目录。
graph TD
Intent["<b>Domain 1: Developer Intent</b><br/><i>Developer</i>"]
Catalog["<b>Domain 2: Platform Catalog</b><br/><i>Platform Architect</i>"]
Routing["<b>Domain 4: Routing & Policy</b><br/><i>Platform Operator / DevOps</i>"]
Infra["<b>Domain 3: Infrastructure Base</b><br/><i>Infrastructure Engineer / Ops</i>"]
Libs["<b>Tier 3: Libraries</b>"]
Intent -->|"requests, attaches"| Catalog
Intent -->|"binds via"| Routing
Routing -->|"attaches"| Catalog
Catalog -->|"resolved to"| Infra
Routing -->|"resolves, renders via"| Infra
Catalog -.->|"$ref"| Libs
Infra -.->|"$import"| Libs
整个语料涵盖四个领域以及第 3 层库层:
| # | 实体 | 领域 | 角色 |
|---|---|---|---|
| 1 | Aggregate | 领域 1 — 开发者意图 | 应用拓扑蓝图 |
| 2 | Component | 领域 2 — 平台目录 | 抽象计算节点接口 |
| 3 | Feature | 领域 2 — 平台目录 | 运维特征(包括凭据 Features) |
| 4 | Recipe | 领域 3 — 基础设施底座 | 按提供方的 Component 实现 |
| 5 | FeatureRecipe | 领域 3 — 基础设施底座 | 按提供方的 Feature 实现 |
| 6 | Plugin | 领域 3 — 基础设施底座 | 按内容寻址的 WebAssembly 插件(提供方渲染、管道步骤、lint 检查) |
| 7 | Manifest | 领域 4 — 路由与策略 | 将接口映射到 Recipes 的依赖锁文件 |
| 8 | Release | 领域 4 — 路由与策略 | 将 Aggregate 绑定到 Manifest 的部署路由器 |
| 9 | SchemaLibrary | 第 3 层 — 库 | 可复用的 JSON Schema 2020-12 定义 |
| 10 | MappingLibrary | 第 3 层 — 库 | 可复用的 Go 模板片段 |
| 11 | WorkloadLibrary | 第 3 层 — 库 | 可复用的 Workload 模板片段 |
| 12 | ArtifactLibrary | 第 3 层 — 库 | 可复用的具名制品包 |
该表就是全部的编写实体类型,即作者在 kind: 字段中声明的类型。Workload 类型是嵌入在 Recipe 合成输入中、归平台所有的内容,而不是独立的目录实体(参见第 16 章),因此有意未列入上表。
Plugin 是一等编写实体,拥有自己的类型、JSON Schema 和目录目录,归领域 3 中的平台运维(Platform Ops)所有。一个 Plugin 是对 WebAssembly 制品的按内容寻址的引用,并声明它所实现的唯一一种插槽类型。该分类共有七个成员:provider(将 IR 节点渲染为提供方原生制品)、linter(对编写的内容发出诊断)、pipeline-step(feature-recipe-pipeline 中的一个步骤)、governance(承担治理角色:转换标签或注解,或对 IR 图或渲染出的制品给出接受/拒绝的裁决)、cli(提供一个由运维人员在命令行调用的 aggrega 子命令)、parser(将外部源文本转换为规范的结构化树)以及 importer(将外部基础设施或智能体定义源转换为 Aggrega 编写文件草稿)。提供方渲染 Plugin(pluginType: provider)是承担提供方渲染的单元:它在 spec.provider.capabilities 中声明其渲染的提供方名称,并在同一个 spec.provider 块中携带其余的提供方插槽元数据。编译器负责固定并路由该引用;WebAssembly 运行时执行其字节码;编译器并不解释插件做什么——插件是承载存在于 WebAssembly 中的领域特定智能的载体。其编写与元数据界面记录在 language-reference/entities/plugin.md。
领域 1:开发者意图(“做什么”)
graph LR
classDef ext stroke-dasharray:5 4;
A["Aggregate<br/>The 'What'"]
CC["Component"]:::ext
CapC["Feature"]:::ext
EB["Release"]:::ext
A -.->|"Requests"| CC
A -.->|"Attaches"| CapC
A -->|"Binds via"| EB
- 角色:开发人员。只专注于 AI 架构、认知循环和应用的存续要求。他们无需了解 CEL、OPA 或物理端口。
- 1. Aggregate:基于映射的应用拓扑声明式蓝图。无论作为 Release 所构建的根 Aggregate,还是作为参数化、可复用的模块,它都定义逻辑上的
components,并在features下附加那些行为属于应用意图的 Features 及其values;而所有输入都属于运维范畴的 Feature 则由运维人员在 Release 中附加(参见领域 4)。凭据也在同一个features附加入口上申请,通过凭据 Feature 实现——没有单独的块。它通过parameters(以紧凑形式词汇编写的类型化契约)定义抽象的容量要求,并通过values定义载荷状态。Component 实例支持可选的description字段,用于文档和 Studio 中的渲染。它推行“零端口”(Zero-Port)约定(除非已有代码明确要求,否则对网络端口进行抽象),不硬编码任何目标平台或命名空间。
领域 2:平台目录(“接口与智能”)
graph TD
classDef ext stroke-dasharray:5 4;
A["Aggregate"]:::ext
EB["Release"]:::ext
CC["Component<br/>The Compute Interface"]
CapC["Feature<br/>The Operational Trait"]
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
A -.->|"Requests"| CC
A -.->|"Attaches"| CapC
EB -.->|"Attaches"| CapC
CC -.->|"Resolved to"| CD
CapC -.->|"Resolved to"| CapD
- 角色:平台架构师。平台的“程序员”。他们把每个组件放到可运维本体中,编写可编程策略(Wasm 变换器和校验器),并建立语义鸭子类型标签。
- 2. Component:计算节点的抽象接口。它通过可运维的云本体声明其基础形态(例如
component.aggrega.ai/type: server),并通过鸭子类型标签叠加其认知身份(例如model.aggrega.ai/capability: generative)。它通过featuresSchema声明凭据槽位(必需/可选、黑盒/透明),并使用schema:(JSON Schema 2020-12,通常以紧凑形式简写编写)严格校验开发人员不透明的values块。 - 3. Feature:一种模块化的运维特征(例如数据脱敏、DNS 路由、机密管理)。它使用
appliesTo标签选择器动态绑定到特定的语义标签。与 Components 一样,它通过featuresSchema声明凭据槽位,以强制配置 API 密钥。关键在于,它使用metadata.annotations在扁平的 IR 图中显式标记元素,从而告知下游的 Wasm 策略校验器和渲染插件如何处理该 Feature 的配置载荷。- 凭据 Features:平台将凭据管理统一到 Feature 实体中:带有
feature.aggrega.ai/kind: secret标签的 Feature 就是凭据功能——它定义了一个通往机密存储(例如 AWS Secrets Manager、HashiCorp Vault)的查询接口。它与其他任何 Feature 一样附加在features:下,入口相同、形态相同;该标签是目录携带的元数据,用于描述该附加产生什么,编译器中没有任何分支会读取它。不存在单独的机密存储或机密 Recipe 类型:凭据 FeatureRecipe 与其他任何 FeatureRecipe 形态相同,二者的“获取再交付”管道一致,inject交付契约(env、file、arg)也是共享的。一个实体、一个附加关键字、一条贯穿渲染的修饰器执行路径——凭据在 Manifest 中映射到features.type下。
- 凭据 Features:平台将凭据管理统一到 Feature 实体中:带有
以标签表达本体。 可运维的云本体在 metadata.labels["component.aggrega.ai/type"] 中声明,而不是作为顶层的 spec.type 字段。这一选择让编译器的标签选择器引擎能够直接针对本体值——一个 Feature 声明 appliesTo: "component.aggrega.ai/type in (server, worker)",即可动态附加到每个 server 或 worker 组件,而无需在核心编译器中添加任何新的 Go 逻辑。同一套选择器机制适用于每个 Aggrega 标签,因此 Feature、套接字选择器或 Release 的边界映射读取目录自有标签键的方式,与读取这个键完全相同。
component.aggrega.ai/type 是 Aggrega 的键,其取值集合是封闭的:已发布的 Component 模式枚举了这些原语,带有任何其他值的文档在加载时会被拒绝,并由 E0215 指明该标签并列出其接受的值。需要 Aggrega 未定义的分类的目录,会在它旁边添加自己的标签键——Component 模式接受任何值为字符串的额外标签键——因此新增一个维度只需一个你自己的键,而无需编译器发布新版本,同时保留键在任何地方都只有一种含义。正因如此,一个针对 component.aggrega.ai/type in (stateful-server) 编写的 Feature 才能作用于素未谋面的作者所写的 Components。
领域 3:基础设施底座(“实现”)
graph LR
classDef ext stroke-dasharray:5 4;
CC["Component"]:::ext
CapC["Feature"]:::ext
ENV["Manifest"]:::ext
EB["Release"]:::ext
CD["Recipe<br/>The Implementation"]
CapD["FeatureRecipe<br/>The Binding"]
T["Plugin<br/>The Wasm Plugin"]
CC -.->|"Resolved to"| CD
CapC -.->|"Resolved to"| CapD
ENV -->|"Resolves Interfaces to"| CD
ENV -->|"Resolves Interfaces to"| CapD
EB -->|"Renders via"| T
- 角色:基础设施工程师 / 运维。负责物理现实、网络端口分配和模板逻辑。
- 4. Recipe:多提供方的翻译模板(例如 Helm 或 Docker Compose)。它通过
implements关键字与目录组件建立严格的 1:1 API 契约。Recipe 将开发人员的.values映射为物理格式。它硬编码物理网络端口(例如5432),并通过.context.uses管道读取目标的provides,从而在不硬编码数据库名称的情况下满足注入契约。 - 5. FeatureRecipe:通过
implements关键字,将一个Feature显式映射到具体的基础设施实现。它要求在capability中指定目标提供方能力(例如helm、compose)。由于平台将凭据管理统一到 Feature 实体中,FeatureRecipes 既处理运维功能(数据脱敏、DNS 路由、边车注入),也处理凭据功能(生成保险库 CRD、挂载机密卷)。为支持这一完整范围,它支持三种不同的执行块:pipeline:一个按顺序执行的 WebAssembly (Wasm) 插件数组,用于渲染后的 Workload 变换(例如通过 JSONPatch 注入 Envoy 边车,或挂载机密卷)。source与valuesMapping、workload、artifacts:与 Recipe 所携带的相同的三种输入类型,用于资源生成,使运维能够在基础组件旁原生渲染静态模板(例如生成新的HTTPRouteCRD 或ExternalSecretCRD)。injectMapping(渲染前拦截):一个原生 Go 模板块,在基础 Recipe 渲染之前执行。它输出一个 JSON 字典,编译器会将其原生地深度合并到调用方的.context.inject内存管道之上,从而无需 Wasm 即可在调用方一侧修改环境变量和连接字符串。
- 凭据 FeatureRecipe 模式:当某个 FeatureRecipe 实现一个凭据 Feature(标记为
feature.aggrega.ai/kind: secret)时,适用标准的“两段式 Plugin 原则”:pipeline先串联一个 Fetcher 插件(生成特定于保险库的 CRD),再串联一个 Injector 插件(将机密挂载到目标容器)。Fetcher/Injector 的拆分最大化了可复用性——从 AWS Secrets Manager 切换到 HashiCorp Vault 只需替换 Fetcher 插件;Injector 保持不变。
- 6. Plugin:按内容寻址的 WebAssembly 插件。提供方渲染 Plugin(
pluginType: provider)是将 Recipe 的输入类型转换为最终字符串化文件格式的单元:它在spec.provider.capabilities中声明其服务的提供方名称(例如helm),公开一个供编译器分派调用的render_node导出,并在同一个spec.provider块中携带其提供方套接字的其余元数据(workloadSchema、wellKnownAnnotations)。Plugin 可以声明的其他套接字类型有pipeline-step、linter、governance、cli、parser和importer。编译器路由已固定的引用;WebAssembly 运行时执行字节码。
领域 4:路由与策略(“黏合剂”)
graph TD
classDef ext stroke-dasharray:5 4;
A["Aggregate"]:::ext
EB["Release<br/>The Deployment Router"]
ENV["Manifest<br/>The Dependency Lockfile"]
CapC["Feature"]:::ext
T["Plugin"]:::ext
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
A -->|"Binds via"| EB
EB -.->|"Attaches"| CapC
EB -->|"Uses"| ENV
EB -->|"Renders via"| T
ENV -->|"Resolves Interfaces to"| CD
ENV -->|"Resolves Interfaces to"| CapD
- 角色:平台运营者(Platform Operator)/ DevOps。
- 7. Manifest:依赖锁文件。它使用扁平的 URI 映射:
components.type字典将目录组件类型映射到 Recipe URI,features.type字典将 Feature 类型映射到 FeatureRecipe URI。解析是针对锁文件和目录的直接 URI 查找;能力的确定在构建时来自每个已解析 Recipe 的spec.capability字段。解析完成后,每个实体都必须有映射,否则编译器中止。为保持 DRY 的生态系统,Manifests 通过extends关键字支持 Kustomize 风格的组合模式,使特定环境的清单(如本地或预发布环境)能够干净地继承全局基础清单,只声明各自特定的覆盖项。 - 8. Release:路由器。它将一个
aggregate绑定到一个manifest,并把组件映射到物理边界(例如aws-eks-production)。为保持 DRY 的工作流,Releases 通过extends关键字支持继承,使特定环境的发布能够干净地继承全局基础发布。它通过把物理现实严格注入parameters块来履行抽象的 aggregate 契约,并通过并行的infra命名空间注入物理规格(如 CPU 或端口)。为保护 Aggregate 作为单一事实来源的地位,Release 模式在机制上禁止values:块——运维无法从 Release 为任何 Component 或 Feature 声明values。面向开发人员的值的按环境差异通过**参数提升(Parameter Hoisting)**实现:开发人员在 Aggregate 中暴露一个类型化的parameters.*字段,Component 的values模板引用它,再由 Release 为其环境填充该参数。渲染出的值在各环境间不同,而 Aggregate——决定存在哪些值以及它们如何流动的编写界面——始终是单一事实来源。模式层面禁令的明确表述见架构约束与推荐模式下的约束 4“Release 不能覆盖开发人员的值”。关键在于,为防止出现无法追溯的“修改 aggregate”的 Releases,当 Release 使用extends时,声明aggregate会被 Release 模式拒绝(使用extends时,模式约束不允许声明aggregate)。子发布必须对应与其父发布完全相同的开发者意图。不过manifest变为可选,从而解锁“延迟绑定”——运维可以继承整个物理拓扑,同时精确地替换依赖锁文件。- Feature 附加:Release 同样会附加 Features,位于某个边界或某个组件上的
features之下。对于所有输入都属于运维范畴的 Feature,它直接附加,并带上其type和infra;对于由 Aggregate 附加的 Feature,它负责规格设定,在同名下写入该附加的infra。
- Feature 附加:Release 同样会附加 Features,位于某个边界或某个组件上的
为什么把 Manifest 与 Release 分开。 将软件锁文件(Manifest)与部署路由器(Release)分离,可以实现两个实体单独都无法产生的形态:DevOps 将单个应用部署到多个区域部署路由器——不同的 Releases 指向不同的云区域,全部引用同一个 Manifest——而无需在各环境间重复 Recipe 绑定。每个区域性的 Release 携带自己的边界布局和特定于环境的参数,同时使用 Manifest 提供的同一份软件锁文件。多区域扩展源于领域分离,而不是 Manifest 的复制。
第 3 层:库(目录复用)
graph LR
classDef ext stroke-dasharray:5 4;
CC["Component"]:::ext
CapC["Feature"]:::ext
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
SL["SchemaLibrary<br/>JSON Schema definitions"]
ML["MappingLibrary<br/>Go template fragments"]
WL["WorkloadLibrary<br/>Workload template fragments"]
AL["ArtifactLibrary<br/>Named artifact bundles"]
CC -.->|"$ref"| SL
CapC -.->|"$ref"| SL
CD -.->|"valuesMapping $import"| ML
CapD -.->|"$import"| ML
CD -.->|"workload $import"| WL
CD -.->|"artifacts $import"| AL
CapD -.->|"$import"| AL
- 角色:平台架构师(与领域 2 是同一角色),但只有当目录内容大到足以受益于跨 Component 的模式复用,或跨 Recipe 的模板、工作负载形态或制品包复用时,这一角色才会介入。独立作者和小型目录无需任何第 3 层实体即可交付。
- 9. SchemaLibrary:可复用的 JSON Schema 2020-12 定义。库在
spec.schemas:下声明具名模式,并可在spec.templates:下声明参数化辅助项(使用$params:声明和$instantiate:引用实现参数化复用)。目录实体通过标准的 JSON Schema$ref:关键字按标识指向库条目来使用它们——采用不含主机的<library>#/schemas/<name>形式(版本来自锁文件,而非引用本身)。采用 PascalCase 命名,通过 OCI 分发,在锁文件中固定版本。对于需要跨 Component 模式复用的目录,它是可选启用的——PodResources、PersistenceSpec、NodePool、MetricsServiceMonitor等常见形态在每个数据存储 Component 和每个工作负载 Component 中反复出现,而 SchemaLibrary 条目把这种重复从逐个 Component 的编写中提取出来。 - 10. MappingLibrary:可复用的 Go 模板片段。库在
spec.mappings:下声明具名模板。Recipes 和 FeatureRecipes 通过valuesMapping: { $import: <library>#/mappings/<name> }按标识使用库条目。只有一种编写模式(仅 Go 模板);没有并行的 Jsonnet 编写路径。对于需要跨 Recipe 映射复用的目录,它是可选启用的——Bitnami chart 辅助逻辑或共享的 pod 模板模式等常见模式,会在每个面向同一提供方的数据存储 Recipe 中反复出现,而 MappingLibrary 条目把这种重复从逐个 Recipe 的编写中提取出来。 - 11. WorkloadLibrary:可复用的 Workload 模板片段。库在
spec.workloads:下声明具名的工作负载条目。Recipe 通过workload: { $import: <library>#/workloads/<entry> }按标识使用某个条目,导入的内容会像内联的workload:块一样,严格按照平台所有的 Workload 模式进行校验——因此从库导入的工作负载与等效的内联工作负载渲染结果完全相同。只有一种编写模式(仅 Go 模板)。对于需要跨 Recipe 工作负载复用的目录,它是可选启用的,适用于多个 Recipes 共享同一种部署形态、仅取值不同的情况。 - 12. ArtifactLibrary:可复用的具名制品包。库在
spec.artifacts:下声明具名包,每个包将属于同一组的输出文件归在一起——例如一个 CRD、它的 RBAC 和一个 ConfigMap——并作为一个单元导入。Recipes 和 FeatureRecipes 通过artifacts.<name>: { $import: <library>#/artifacts/<name> }按标识使用某个包。只有一种编写模式(仅 Go 模板)。对于需要跨 Recipe 制品复用的目录,它是可选启用的,适用于同一组辅助资源伴随许多 Recipes 的情况。
每个库都通过 OCI 发布,在锁文件中固定版本(schema_libraries:、mapping_libraries:、workload_libraries: 和 artifact_libraries: 部分),并在 Hub 界面中显示,同时可感知其使用方(哪些 Components 引用了哪些库条目;哪些 Recipes 使用了哪些库条目)。