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

Provider 架构

provider 将 Recipe 的输入类型渲染为 provider 原生的 manifest 文件。当 Recipe 声明 capability: helm、capability: compose 或任何其他 provider 名称时,编译器会将渲染分派给提供该名称的 provider。本章介绍 provider 如何以 provider-rendering Plugin 的形式实现、分派如何工作,以及将编译器与每个 provider 绑定在一起的 plugin-socket 契约。

本章不涉及的内容:Recipe 用于生成其输出的三种输入类型组合模型(source: + valuesMapping:、workload:、artifacts:——每种都接受内联内容或 $import:)。该模型横跨所有 provider,详见 ../../architecture/16-recipe-input-composition.md,其中包括列出每个 provider 支持哪些输入类型的 Provider Capability Matrix。

provider 渲染 Plugin

Provider 渲染由带有 pluginType: provider 的 Plugin 提供。该提供者渲染 Plugin:

  • 服务一个或多个 provider 名称——在 spec.provider.capabilities 中声明。Recipe 所指定的 provider 名称(spec.capability: helm)绑定到其 spec.provider.capabilities 列表包含该名称的 provider 渲染 Plugin。当多个 Plugin 服务同一目标时,工作区通过 .aggrega-config.yaml 中的 provider 绑定在它们之间进行选择,该绑定在 aggrega pull 时解析并记录在锁文件中;没有绑定且恰好只有一个候选时,使用该候选;没有绑定且有多个候选时,构建会显式中止,并列出候选插件的名称。
  • 在同一代码块中携带其 provider 插槽元数据——spec.provider 包含上述能力列表以及该 provider 的其余声明。spec.provider.workloadSchema 是一个 JSON Schema 2020-12 声明,记录平台所拥有的 Workload 类型如何转换为该 provider 的原生输出;标准库目录在执行合成的 provider 上声明它,作为有文档记录的转换契约。spec.provider.wellKnownAnnotations 列举该 provider 读取的 aggrega.ai/ 边界注解。对合成输入(workload:)的支持是 provider 的一项属性,在渲染时强制执行——并不由 workloadSchema 是否存在来决定。

有关 Plugin 实体完整的字段级编写接口(包括 spec.provider 块),请参阅 ../entities/plugin.md。

按 provider 分派

每个 Recipe 在其 spec 顶部声明且仅声明一个 capability:。编译器读取该字段,并将渲染分派给提供该名称的 provider。一个 Recipe 不能同时面向多个 provider。多 provider 组合发生在 Release 层面:一个边界可以容纳混合 provider 的组件,边界求值后的组装路径上每个 provider 的贡献者各自独立组装——每个 (path, provider) 元组对应一次组装。

单个节点的分派路径:

  1. 编译器在目标 provider 的映射段下,通过 Manifest 的三级查找解析该节点的 Recipe URI。正是 Manifest 按 provider 轴的分组,使“同一个 Component,不同 provider 使用不同 Recipes”成为一种自然的模式。
  2. 解析得到的 Recipe 的 spec.capability 指明要分派到的 provider 名称。
  3. 编译器为该名称绑定 provider:它解析其 spec.provider.capabilities 列表包含该名称的 provider 渲染 Plugin,并通过该 Plugin 的 guest 进行渲染。渲染仅通过 Wasm 进行——不存在可回退的宿主内渲染器,因此若某个 provider 名称解析不到任何提供它的 Plugin,构建会在路由阶段明确报错并中止。
  4. 调用 provider 时传入按节点的渲染上下文(支柱值、.context.* 投影、该 Recipe 的输入种类)。
  5. provider 返回渲染输出。编译器将渲染出的文件路由到按 (path, provider) 划分的组装器,其键为边界求值后的 directory: 与按组件的 subDirectory: 拼接而成的路径。在同一 provider 下求值为相同路径的两个边界共享一个组装器——典型模式是一个父边界加两个使用 directory: "{{ .parent_boundary.directory }}" 的子边界,合并为一次组装。

Manifest 按 provider 轴的分派结构参见 ../entities/manifest.md,Recipe 一侧的单 provider 声明参见 ../entities/recipe.md。按 (path, provider) 的组装模型,以及控制求值路径的路径模板变量允许列表,记录在 ../path-template-variables.md 中。

Wasm 插件契约

Provider 渲染在 WebAssembly 沙箱内运行。Go 编译器是宿主;provider-rendering Plugin 是客体。对于每个节点,编译器将该节点的渲染上下文交给插件,插件返回它渲染出的文件。这一契约对每个 provider 都是统一的:

  • 双向采用规范的二进制编码。 编译器将渲染上下文——节点的值和附件、解析后的 .workload、求值后的 artifact 条目、已解析 .source 的仅含名称的列表,以及边界元数据——编码为规范 CBOR(RFC 8949 §4.2.1),并交给插件。插件以相同的编码返回它渲染出的文件列表——每项为一个相对于节点输出根目录的路径以及要写入该处的确切字节,可选地附带文件所采用的格式——以及任何诊断信息。从渲染单个节点到组装边界、连接跨边界链接,插槽的每个导出在两个方向上都承载这种编码,每种语言的插件开发工具包都会为插件解码和编码它。不符合该导出在此编码下的输出结构的应答会使构建中止。插件契约记录了每个导出的载荷。
  • 无文件系统访问。 Plugins 无法从宿主文件系统读取任意文件。Recipe 指定的源(registry 中的 chart、仓库中的模块)会在插件运行之前由编译器解析;插件收到该源的仅含名称的清单,并通过一个宿主函数向编译器请求它选中的文件,该宿主函数只响应该节点源之下的文件。
  • 无网络访问。 Plugins 是确定性且封闭的,不会自行建立任何连接。插件在渲染期间需要的外部输入(例如 chart 的 values 所引用的远程 schema)通过编译器的外部输入宿主函数请求,该函数从工作区为该引用固定的内容中作答。
  • 确定性输出。 给定相同的输入和相同的插件版本,插件必须产生逐字节相同的输出。正是这一契约使编译器的逐字节相同输出保证能够端到端地贯穿插件层。使用 --verify-determinism 运行的构建会将每个节点渲染两次,并在某个节点的两次渲染结果不同时中止。

更宏观的可扩展性层面的插件插槽架构,包括编译流水线中的其他 Wasm 插槽(治理插槽的 transform 和 verdict 角色),参见 ../../architecture/14-extensibility.md。

Aggrega 的标准库 provider

helm、helm-chart、compose、terraform 和 cloudformation 这几个 provider 共同构成标准库 provider 集。它们覆盖常见的部署目标,企业团队无需自行编写 provider。

helm 支持全部三种输入类型:sourced(通过 Helm SDK 获取上游 Helm chart,并以 Recipe 的 valuesMapping 输出作为该 chart 的覆盖值)、synthesized(扁平的 Kubernetes YAML——由 Workload 的 form 选定的控制器对象(Deployment、StatefulSet、DaemonSet、Job 或 CronJob),加上 Service 和 PVC——由解析后的 Workload 生成)以及 artifacts(与 chart 输出并存的独立 YAML 文件)。它接受这三种类型中的哪些,参见 ../../architecture/16-recipe-input-composition.md 中的 Provider Capability Matrix。

helm-chart 支持 sourced 模式(umbrella chart 组合:每个边界一个 chart,每个 component 一个 sub-chart),以及与之并存的 artifacts:,两种编写形式均支持。通过 $import: 加载的 artifacts: 条目先由 Aggrega 进行 Go 模板渲染,然后在渲染前注入 chart 的 templates/ 目录;内联内容的 artifacts: 条目以同样方式求值,并放置在 sub-chart 根目录下,不合并任何来源信息,由 chart 自身的模板通过 Helm 的 .Files.Get / .Files.Glob 读取。独立的仅含 artifacts 的 Recipe 不在它声明的类型之列,synthesized 类型也不在其中:umbrella 负责编排 sub-chart,而 Workload 类型是一个叶子概念,属于每个 sub-chart 内部(即 helm provider 的领域)。

compose 支持 sourced(加载一个 compose 文件并深度合并 valuesMapping 叠加层)、synthesized(针对 stateless 和 stateful 形式,由解析后的 Workload 生成 compose 的 services: + volumes: + networks:,对 persistentTemplate 的卷处理有所降级——每个副本的 PVC 合并为单个共享的命名卷并发出警告;daemon、scheduled 和 task 形式没有 compose 映射,会明确报错并停止)以及 artifacts(compose 片段,其顶层键 services: / networks: / volumes: / configs: 合并进每个边界的组合 docker-compose.yaml)。Artifacts 可以与另外两种类型中的任一种并存;独立的仅含 artifacts 的 Recipe——有 artifacts: 而没有 source: 和 workload:——也是该 provider 声明的一种类型:其片段按相同规则合并,因此该节点恰好贡献它所声明的内容,无需用 Workload 来代替它并不具备的计算资源。

terraform 支持 sourced(原样内置一个 Terraform 模块,并将 valuesMapping 输出作为边界根配置中该 component 的 module 块的参数)和 artifacts(按模板求值的结果输出编写好的 HCL 或 .tf.json 内容,不对其进行改写)。它不提供 synthesized 输入类型——平台的 Workload 类型无法忠实地映射到任意 Terraform 资源。该 provider 只生成配置,从不运行 Terraform;依赖运行时的值保留为 ${ ... } 插值字符串,由 Terraform 运行时在 apply 时解析。

cloudformation 将一个边界渲染为一个 AWS CloudFormation 栈模板:把其 component 编写的资源片段组装为单个纯 JSON 模板,将每个 component 的 provides 暴露为栈的 Outputs,并将 uses 边在栈内连接为 Fn::GetAtt、跨栈连接为 Fn::ImportValue / Fn::GetStackOutput。它支持 sourced 和 artifacts 输入,只生成配置而从不运行 CloudFormation;仅在运行时可知的值保留为 CloudFormation 内置函数。

provider 参考索引可引导你前往每个 provider 各自的参考页面;每个 provider 接受哪些输入类型,参见 ../../architecture/16-recipe-input-composition.md 中的能力矩阵。

自定义 provider

编写自有 provider 的企业团队遵循与标准库相同的模式:编写一个 provider 渲染 Plugin(pluginType: provider),在 spec.provider.capabilities 中声明它所服务的 provider 名称,并附上其余的 spec.provider 元数据,然后发布实现上述渲染契约的 Wasm 制品。编译器对自定义 provider 与标准库 provider 一视同仁;按 provider 分派依据的是 Recipe 所声明的 provider 名称。

编写 provider 的方法已有文档说明,而非留待以后。编写 provider 从头到尾构建一个可运行的 provider guest——describe() 自我报告、构建、Plugin 实体、挂载,以及一次你可以阅读其输出的渲染。Wasm 插件开发者指南是关于该实体及发布生命周期的参考,插件契约则记录了每个插槽的载荷与结果结构。Guest 使用 Go、Rust 或 TypeScript 基于插件开发工具包编写。