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

WorkloadLibrary

WorkloadLibrary 是一种目录实体,用于存放可复用的 Workload 模板片段。部署相同 workload 形态(例如暴露指标的服务器、批处理作业、sidecar 对)的 Recipes 和 FeatureRecipes 只需在库中声明一次该形态,并在使用时通过 workload: { $import: ... } 指令引用它。该库实体属于第 3 层:供需要跨 Recipe 复用 workload 的目录按需启用。如果目录中的各个 Recipes 各自带有不同的 workload 形态,则无需任何 WorkloadLibrary。

WorkloadLibrary 的作用

平台架构师编写 WorkloadLibraries,用于集中管理在目录的 Recipes 和 FeatureRecipes 中反复出现的 Workload 内容。库不是可部署的构建指令,而是一个定义命名空间。Recipe 和 FeatureRecipe 的作者通过 $import: 指令引用库条目:条目只编写一次,凡是导入能够解析的地方都可以使用。

“库”与“使用方”的划分是有意为之。Recipes 编码构建指令(source、valuesMapping、artifacts)。FeatureRecipes 编码行为附加。WorkloadLibraries 只编码 Workload 内容——即 provider 合成为 provider 原生清单的 workload 形态。让这三种角色保持分离,使每种实体类型都能按自己的节奏演进;不需要共享 workload 内容的作者永远不会接触到这种库实体。

实体信封

WorkloadLibrary 实体带有标准的目录信封。apiVersion: aggrega.ai/v1beta1 和 kind: WorkloadLibrary 标记实体类型;metadata.name 是 PascalCase 标识符;metadata.version 遵循严格的语义化版本。两者都是必需的。metadata.description、metadata.labels 和 metadata.annotations 是可选的——labels 和 annotations 是作者声明的不透明元数据,携带它们是为了让读取该库的任何内容据以匹配,编译器不解释它们的值。库的内容位于 spec.workloads 之下,这是一个必需的映射,必须至少声明一个条目。

信封在全部三个层级上都是封闭的——文档根、metadata 和 spec 都会拒绝 schema 未声明的键。

apiVersion: aggrega.ai/v1beta1
kind: WorkloadLibrary
metadata:
name: BaseWorkloads
version: 1.0.0
spec:
workloads:
SimpleServer: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
app:
image: "{{ .values.image }}"
ports:
web: {{ optional .values `port` 8080 }}
services:
http:
type: ClusterIP
ports:
web: {{ optional .values `port` 8080 }}

编写 Workload 条目

每个条目都是以 YAML 字符串编写的 Go 模板片段。条目的渲染输出是一个完整的 Workload 文档——它自带 apiVersion: aggrega.ai/v1beta1 和 kind: Workload——因为 Recipe 的 workload: 字段接受一个完整的 Workload,而不是拼接进外围文档的片段,并且导入会替换整个字段。MappingLibrary 条目同样是完整的:导入一个条目会替换 Recipe 的整个 valuesMapping:。

条目主体对实体信封是不透明的。编译器在加载 WorkloadLibrary 时原样存储该字符串,并不在此时解析模板;模板解析器在消费时运行,即 Recipe 或 FeatureRecipe 导入该条目时。原样存储片段可在重新输出时保持编写的保真度,也意味着模板错误会在条目被消费、其支柱上下文已知的位置暴露,而不是在库中暴露。

由于 Workload 文档是多行的,条目使用 YAML 的字面量风格标量(|),以便换行和缩进在往返过程中得以保留:

spec:
workloads:
BatchJob: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]

条目的值必须是字符串标量。在主体位置写入映射或序列会被拒绝——条目主体是模板文本,而不是编译器遍历的结构化 YAML。

条目内部可以使用 Go 模板的全部组合词汇:{{ define "name" }}...{{ end }} 在单个库内声明可复用的块,{{ template "name" . }} 调用这些块,管道和函数遵循标准 Go text/template 包。条目可读取的支柱上下文——.values、.infra、.locals、.context、.features——与任何 Workload 模板读取的上下文相同,并在 Workload 页面的模板求值部分中说明。

目标 provider 必须支持 workload 合成。如果某个 Recipe 导入了库条目,却绑定到无法合成 Workload 的 provider,它会在渲染时显式中止,而不是输出降级的形态;标准库目录在支持该功能的 provider 上声明 workloadSchema,作为文档化的契约。

单一编写模式

WorkloadLibrary 只提供一种编写模式:Go 模板。spec 在库级别不接受并行的编写界面,也不提供表达能力方面的逃生舱口。

原因在于消费界面的一致性。Recipes 和 FeatureRecipes 全程使用 Go 模板,它们自身的内容通过解析导入片段的同一个 Go 模板引擎求值。并行的编写界面会迫使作者在单个 Recipe 的渲染过程中切换求值模型:Recipe 自身的内容使用一种模型,任何导入的库条目使用另一种模型。保持界面一致意味着作者只需学习一种求值模型,并在所有地方应用它。

需要超出 Go 模板组合词汇的表达能力时,作者应在更高层级进行组合——使用 Components 或 Features 包装库条目,并加入它们自身的实质性变化——而不是在库内部升级到第二种编写语言。

命名约定

库名称和 workload 条目键采用 PascalCase。实体信封的 JSON Schema 通过模式约束在两个位置强制执行该约定:

  • metadata.name 匹配 ^[A-Z][A-Za-z0-9]*$。
  • spec.workloads 的映射键通过 propertyNames 匹配同一模式。

若一个 WorkloadLibrary 在 spec.workloads 中含有非 PascalCase 的键,则会在加载工作区时无法通过信封校验。这一强制执行至关重要:workload 条目键会出现在 #/workloads/<name> 引用片段中,因此非 PascalCase 的键会传播到每一个导入该条目的使用方。

命名的统一使 #/workloads/<name> 片段清晰易读:#/workloads/BatchJob 一目了然。

引用库条目

Recipe 和 FeatureRecipe 的作者在 workload: { $import: ... } 块中通过裸名称标识引用 workload 条目:

# Inside a Recipe's spec:
spec:
workload:
$import: "BaseWorkloads#/workloads/SimpleServer"

#/workloads/<name> 片段用于选择条目,并将 workload 引用与 MappingLibrary 的 #/mappings/<name> 和 SchemaLibrary 的 #/schemas/<name> 区分开来。该引用不包含注册表主机;带主机的 oci://… 形式会同时被信封 schema 和使用位置拒绝,因此物理注册表位置永远不会进入编写的源代码。作者可以用 <Library>:<version>#/workloads/<name> 声明一个可选的最低版本下限——版本分隔符为 :,与 recipe/feature 映射及 lockfile 锁定保持一致;如果改写为 @,则会被拒绝,并给出指明更正后引用的诊断。解析出的版本由每个 Release 的 lockfile 提供,该文件按名称、版本和内容摘要锁定每个被使用的库;物理位置在解析时绑定。

同一个 workload: 字段还接受另外两种形式:内联 Go 模板字符串,以及对相对于 Recipe 目录的本地文件路径的 $import:。这三种形式按内容的形态区分,并且都会生成相同的解析后 Workload。关于 workload: 如何与 Recipe 的其他输入类型组合,请参阅 Recipe;关于更广泛的 $ref: / $import: 区别,请参阅 vocabulary/cross-document-ref。

跨库组合

WorkloadLibrary 条目可以是一个字段根 $import: 重定向:其主体的第一个标记是 $import: <Library>#/workloads/<entry>,它用被引用条目的内容替换整个条目——这是按标识复用,而不是原地模板化。该重定向在使用时解析,而不是在 WorkloadLibrary 加载时解析,并且以递归方式解析,因此被导入的条目本身也可以是字段根 $import:。回环到自身的链会停止,并给出指明该循环的诊断。$import: 只作用于整个条目;它不是片段中间使用的模板函数。要在单个条目内部组合模板文本,请使用 Go 模板的 define / template。

# In library A — alias an entry to a shared entry in another library:
spec:
workloads:
StandardServer: |
$import: PlatformWorkloads#/workloads/MetricsServer

未知的库名,以及在能够解析的库中不存在的条目名,会作为不同的诊断报告,因此作者可以区分缺失的依赖与拼写错误的条目。

层级定位

在实体层级文档模型中,WorkloadLibrary 属于第 3 层——供需要跨 Recipe 复用 workload 的目录选择性启用。若目录中的 Recipes 各自携带不同的 workload 内容,则无需任何 WorkloadLibrary 实体即可发布;层级标记表示的是“高级内容;不需要可跳过”,用于文档导航,而非表示能力。编译器对 WorkloadLibrary 的处理与其他目录实体类型一致:在工作区加载时执行相同的信封校验,在发布时使用相同的 OCI 发布流水线,在 lockfile 中同样按名称、版本和内容摘要进行锁定。

该库类型是目录层面一组库中的一种——SchemaLibrary 存放可复用的 schema 定义,MappingLibrary 存放可复用的映射片段,ArtifactLibrary 存放可复用的制品包,WorkloadLibrary 存放可复用的 workload 内容。每一种都可独立选择启用;目录只发布所需的那些,其余一概不包含。

WorkloadLibrary 不是什么

以下是几个值得提前澄清的常见误解:

  • 不是内联 workload: 的替代品。 大多数 Recipes 携带的工作负载内容足够具体,适合内联编写,作者可以将其与 Recipe 的其余部分一起阅读。当同一种工作负载形态出现在许多 Recipes 中时,WorkloadLibrary 才有帮助;对于一次性内容,内联编写才是正确的选择。

  • 不是存放局部片段的地方。 一个条目渲染为一份完整的 Workload 文档。Recipe 的 values 文档属于 MappingLibrary,一组辅助文件属于 ArtifactLibrary,schema 定义属于 SchemaLibrary。各库类型按内容类型划分,而不是按复用模式划分。

  • 不是可独立部署的实体。 库条目是 Workload 内容,而 Workload 内容从不能被单独寻址——它作为 Recipe 或 FeatureRecipe 所使用的输入而存在。发布 WorkloadLibrary 会使其条目可被导入,但不会使它们可被部署。

  • 不提供超出 Go 模板机制的参数化复用。 需要参数化变化的作者可以在库条目中使用 Go 模板的 {{ define }} + {{ template }} 机制,或使用引用它的 Recipe 所提供的支柱上下文。库实体本身不附带任何参数化辅助机制。