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

Aggrega 基础设施基座(Recipe)schema

自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。

Schema id:https://aggrega.ai/schemas/recipe-v1beta1.schema.json

由运维编写的指针与映射层,将开发意图连接到特定的基础设施 provider。与一个物理 provider 及一个目录 component 严格一一对应。

关于编写 Recipe 实体的说明性指导,请参阅 Recipe 编写参考;本页记录该参考所描述的结构化 schema。

顶层类型: object

属性

属性类型必需描述
apiVersionconst “aggrega.ai/v1beta1”是常量:"aggrega.ai/v1beta1"
kindconst “Recipe”是常量:"Recipe"
metadataobject是
specobject是Recipe 的 provider 绑定、源、值映射和流水线。支持通过叠加组合的三种输入类型:sourced(source 加 valuesMapping 覆盖层)、synthesized(workload)和 artifacts(具名输出文件)。除此之外,Recipe 还可以在 ‘boundary’ 下,向其渲染所在 boundary 的共享输出贡献文件。

不允许其他属性。

recipe.metadata

属性类型必需描述
namestring是长度至少为 1 个字符。
versionstring是实现 recipe 的严格语义化版本(例如 2.1.0)。模式:^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$。
descriptionstring否说明该实体是什么、用于什么,面向正在决定是否使用它的人。先用一句话点明它是什么,再补充读者为正确选择和使用它所需了解的内容——它对部署它的 Release 有什么期望,以及它的行为中任何出人意料之处。通常写一个简短的段落即可。
maintainersobject[]否拥有此实体的维护者列表。
licensestring否此实体所描述软件的许可证 SPDX 标识符,例如 MIT 或 AGPL-3.0。它记录的是该软件的条款,而不是此文件的条款。
repositorystring否源文件所在 Git 仓库的 URL。
homestring否此实体的主页、wiki 或文档的 URL。
keywordsstring[]否用于提升 UI 可发现性的描述性关键字列表。

不允许其他属性。

recipe.metadata.maintainers[]
属性类型必需描述
namestring是
emailstring否
urlstring否

不允许其他属性。

recipe.spec

Recipe 的 provider 绑定、源、值映射和流水线。支持通过叠加组合的三种输入类型:sourced(source 加 valuesMapping 覆盖层)、synthesized(workload)和 artifacts(具名输出文件)。除此之外,Recipe 还可以在 ‘boundary’ 下,向其渲染所在 boundary 的共享输出贡献文件。

属性类型必需描述
capabilitystring是此 recipe 绑定的显式 provider 能力(例如 ‘helm’、‘terraform’、‘compose’),即渲染它的 provider 类型。可接受可选的版本锁定,形式与 ‘implements’ 相同的三种:不带版本(‘helm’)、精确版本(‘helm:1.0.0’)或主版本兼容范围(‘helm:^1.0.0’)。裸名称选择 provider 类型;锁定存在时,选择由提供该能力的 provider 渲染插件的哪个版本来渲染此 recipe:未锁定时取最高可用版本,精确锁定时取该精确版本,脱字符锁定时取范围内最高版本。若没有任何提供该能力的插件版本满足锁定,构建会明确地中止。provider 选择之后的一切(输出分组、路径段、流水线兼容性和编解码器选择)都以裸能力为键,因此两个锁定同一能力不同插件版本的 recipe 可以在同一次构建中共存。
implementsstring是声明此 recipe 能够实现的目录 component 类型(精确版本 ‘core/api-server:1.0.0’、主版本兼容范围 ‘core/api-server:^1.0.0’,或不带版本 ‘core/api-server’)。编译器用它来校验 Manifest 映射,并在诊断和编辑器补全中建议候选项;它从不决定构建的解析。aggrega lint 也会读取它,以定位一个 Component,将 Recipe 发布的键与该 Component 声明的 provides 契约进行比较。Manifest 映射是用户对实现的显式选择,锁定在该 Release 的 lockfile 中。
sourcestring 或 object否基础设施代码的位置。可接受 URI 字符串,或一个开放的结构化对象,其由 provider 定义的键以 ‘.source.*’ 的形式暴露给 Recipe 的模板。
localsmap of string否私有 Ops 状态。内部计算结果,在此 Recipe 的模板中以 ‘.locals.*’ 的形式可用。每个条目本身是一个 Go 模板,针对一个自包含的节点本地上下文求值:‘.context.instance_id’、‘.values’、‘.infra’,以及本块中已解析的条目。条目按书写顺序解析,条目可以读取定义在其上方的同级条目,得到的是该同级条目解析后的值,而不是其模板文本。凡是一个条目读取另一个条目,书写顺序就是契约的一部分:将定义移到读取者下方会破坏构建,且本块从不为使引用得以解析而重新排序。对本块稍后才定义的条目的 ‘.locals.’ 引用会中止并指出顺序错误;引用本块根本未声明的键会中止并指出该键。这两项检查读取的是引用最终解析到的路径,而不是字面写法,因此同样覆盖直接形式、’{{ with .locals }}’ 块内的读取、通过直接绑定到 ‘.locals’ 的变量进行的读取,以及在括号中从块上读取的键,即 ‘(.locals).’ 或 ’($.locals).’。有一种写法不在覆盖范围内:路径不由模板文本决定的引用,即通过函数到达的引用,例如 ‘index .locals’ 或 ‘(default dict .locals).’,或通过其流水线应用了函数的 ‘with’ 块或变量绑定到达的引用,因为这类流水线的结果在求值时才决定,而不是由其文本决定。这种写法不会被分析,以这种方式到达的缺失键不会中止:它会渲染字面文本 '',而不是什么都不输出。唯一的例外是 ‘index’ 本身:在每个模板表面上,当它读取的 map 不包含所请求的键时,它都会中止并指出该键,因此通过 ‘index .locals’ 到达的缺失键会中止。local 不能读取 ‘.provides’:该支柱不属于此上下文,试图访问它的条目会中止。解析后的值可用于 provides、source、valuesMapping、workload、artifacts、assertions 和 pipeline[].with(以及 pipeline[].when)。此 Recipe 的 locals 先于其 provides 解析,因此 provides 模板可以读取 ‘.locals’ 并得到解析后的值,而引用本块未声明的键的 provides 模板会中止。用于为下游 Wasm 插件导出物理实际信息(例如目标容器、JSON 路径)。从不暴露给调用方;公共 API 请使用 provides。
providesstring、number 或 boolean 的 map否公共开发者 API。契约化的输出变量,供下游 Caller 的 inject 解析使用。编译器针对一个自包含的上下文对 provides 模板求值,彼此之间顺序任意:任何 provides 条目都不读取另一个条目。节点的 locals 在 locals 前导阶段解析,先于其 provides,因此 provides 模板可以读取 ‘.locals’ 并得到解析后的值;引用 locals 块未声明的键会中止。调用方在 inject 注水时根据这些值解析 inject 键。值为标量:管道原样传递它们,并在注入边界处确定性地字符串化。
valuesMappingstring 或 object否值映射内容,通过内容形态分派支持三种编写模式。模式 1(内联):一个 Go 模板字符串标量(通常是块标量 YAML |),根据 Aggrega 上下文(.values、.features、.infra)生成 provider 所期望的值格式。模式 2(文件导入):恰好只有一个键的 YAML map,$import: ./relative/path.tmpl,指向本地 Go 模板文件。模式 3(库导入):恰好只有一个键的 YAML map,$import: <Library>#/mappings/<entry>,按裸名称标识引用 MappingLibrary 条目(版本由每个 Release 的 lockfile 提供;引用中不出现注册表主机)。在对象形式中,$import 不得匹配 ^oci://;匹配的值会被拒绝。
workloadstring 或 object否Workload YAML 生成器,通过内容形态分派支持三种编写模式。模式 1(内联):一个 Go 模板字符串标量,其输出可解析为 ‘aggrega.ai/v1beta1 Workload’。模式 2(文件导入):仅含一个键的 YAML 映射 $import: ./relative/path.yaml,指向一个本地 Go 模板文件。模式 3(库导入):仅含一个键的 YAML 映射 $import: <Library>#/workloads/<entry>,按裸名称标识引用一个 WorkloadLibrary 条目(版本由每个 Release 的锁文件提供;引用中不出现注册表主机)。目标 Provider 必须支持 workload 合成;标准库目录在此类 provider 上声明 workloadSchema,作为有文档的契约。绑定到无法合成的 provider 的 workload: Recipe 会在渲染时显式中止。在对象形式中,$import 不得匹配 ^oci://;匹配的值会被拒绝。
artifactsstring 或 object 的 map否条目名称到 artifact 内容编写的映射。每个条目的值通过内容形态分派采用三种模式之一。模式 1(内联):一个 Go 模板字符串标量,其输出即 artifact 正文。模式 2(文件导入):仅含一个键的 YAML 映射 $import: ./relative/path.yaml,指向一个本地 Go 模板文件。模式 3(库导入):仅含一个键的 YAML 映射 $import: <Library>#/artifacts/<entry>,按裸名称标识引用一个 ArtifactLibrary 包(版本由每个 Release 的锁文件提供;引用中不出现注册表主机)。一个包按文件展开为多个输出,每个输出以 <key>/<filename> 的形式嵌套在条目的键下。键为条目的输出命名:模式 1 或模式 2 条目的键即其输出文件名,按原样使用;模式 2 条目导入的文件只提供内容,不为输出命名,因此两个条目导入同名的不同文件时,是两个不同的输出。artifact 条目、包文件、source 输出与 workload 合成之间的冲突会在节点渲染时中止构建。artifacts 块在 Recipe 和 FeatureRecipe 上的编写方式完全相同——同样的三种模式、同样的键到输出规则以及同样的冲突行为——因此这部分描述在两种类型上读起来一样;为其中一种编写的示例无需修改即可用于另一种。在对象形式中,$import 不得匹配 ^oci://;匹配的值会被拒绝。键:键为条目的输出命名,因此限定为单个文件名:以字母或数字开头,后接字母、数字、点、连字符或下划线。首字符之后的点用于保留 artifact 键所带的扩展名(main.tf、template.yaml、serviceaccount.yaml)。/ 会使一个键命名路径而非文件,而开头的 . 会允许 ..,它指向输出目录之外的位置——首字符类同时拒绝这两者。对于库导入,键命名包文件所嵌套的目录,因此适用同样的限制。模式:^[A-Za-z0-9][A-Za-z0-9._-]*$。
omitsobject[]否从该 Recipe 的 source 渲染结果中省去的内容——适用于按原样采用、却会渲染出 Release 不得发布之物的 source:所获取的 chart 渲染出的文档,例如保存着 chart 每次渲染都重新生成的密钥的 Secret;所获取的 compose 文件捆绑的 service、volume 或 config;或所获取的 CloudFormation 模板声明的资源。大多数 Recipes 从不需要它。每个条目按种类、名称以及(条目给出时的)命名空间和其来源的 subchart 指定 source 渲染的一个单元,均使用渲染该 source 的 provider 的词汇——对于 chart,是按文档自身的 kind 和 metadata.name 指定的文档;对于 compose 文件,是按其在 services:、volumes: 或 configs: 下的键指定的 service、volume 或 config;对于 CloudFormation 模板,是按其 Type 和逻辑 ID 指定的资源。该 provider 会省去条目匹配的每个单元;条目匹配什么、provider 因条目而拒绝什么,均属于该 provider 自身有文档的契约。无法省去任何内容的 provider 会在渲染任何内容之前拒绝声明此键的 Recipe。只有 source: 渲染的内容会被过滤——workload: 或 artifacts: 条目永远不会——因此该键要求 source。每个值都是模板,针对 valuesMapping 所用的同一上下文求值。条目的 when 最先求值,when 渲染为假值的条目会被丢弃。每个保持激活的条目都必须省去某些内容:未匹配到 source 渲染的任何内容的激活条目会中止构建,并指出该条目。source 仍会完整渲染——chart 的每个模板仍会运行,因此失败的模板仍会导致构建失败——只有其输出被省去。至少 1 个条目。
boundaryobject否该 Recipe 向其渲染所在 boundary 的共享输出贡献的内容,而非向其自身 component 的输出贡献的内容。大多数 Recipes 从不需要它:它用于目标在整个 boundary 中只读取一次的文件——例如 Terraform provider 配置,Terraform 只在 boundary 的根配置中接受它,从不接受出现在某个 component 的模块内。provider 仅在其契约声明了 boundaryArtifacts 时才接受此类文件;为未声明的 provider 声明此块的 Recipe 会在渲染任何内容之前被拒绝。FeatureRecipe 不带此类块。
outputLabelsmap of string否由 Recipe 作者声明的标签,盖印到该 recipe 渲染输出产生的每个对象上,并由 provider 转换到各 provider 的标签载体上(helm 合成、source 渲染和 artifacts 使用 Kubernetes metadata.labels;Compose 使用 service labels;Terraform .tf.json artifact 正文使用按资源的 tags)。它们与固定的来源标签走同一通道,但归作者所有而非编译器所有。aggrega.ai/ 和 app.kubernetes.io/ 命名空间保留给平台原生来源信息,会在加载时被拒绝。对目标 provider 而言无效的标签键或值由 recipe 作者负责;除保留命名空间规则外,核心不检查标签字符集。
outputComponentLabelsstring[]否此 recipe 提升到其渲染输出上的 Component 身份标签键。每个条目指定一个标签键;其值取自此 recipe 所渲染的组件实例的标签,因此盖印的标签携带该组件声明的值,而不是在此处重复的值。被提升的标签到达与 outputLabels 相同的标签面,而 outputLabels 携带的是就地编写的字面键值对。在两个块中都声明的键会在加载时被拒绝,因此每个盖印的键只有单一来源。aggrega.ai/ 和 app.kubernetes.io/ 命名空间保留给平台原生的来源标签,会在加载时被拒绝;诸如 component.aggrega.ai/hosting 这样的作用域键位于这些保留根之外,可以被提升。
pipelineobject[]否在渲染之后对渲染出的文档集依次运行的 Wasm 流水线步骤列表,每个步骤返回 RFC 6902 补丁和副作用。
assertionsmap of string否构建时的跨字段校验。每个条目是一个具名断言:键是一个稳定的规则标识符,会出现在错误消息中;值是一个 Go 模板字符串,采用 {{ fail "message" }} 的中止语义。每个实体的多个具名断言按作者声明的顺序逐实例求值;第一个失败的断言会中止构建。Recipe 断言在 recipe 绑定之后、provides 求值之后、渲染之前求值,用于表达该 Recipe 所引用的特定 chart 或模块的实现不变量。模板上下文:.values / .infra / .uses / .features / .metadata,以及 .provides / .locals / .recipe。求值器使用 missingkey=error:引用未定义的键会以 no-such-key 诊断中止。由于裸引用在任何回退逻辑运行之前就会中止,在此处普通的 default 无法为可选字段提供回退——请用 hasKey 保护该引用,或使用 optional 辅助函数,它直接执行存在性检查。通过 index 读取该键同样无法提供回退:index 遇到映射中不存在的键时会中止,并指出该键。

不允许其他属性。

recipe.spec.omits[]
属性类型必需描述
kindstring是要省略的单元的 kind,使用渲染该 source 的 provider 的词汇:对于 chart,是渲染出的文档自身的 kind,例如 Secret;对于 compose 文件,是 service、volume 或 config;对于 CloudFormation 模板,是资源的 Type,例如 AWS::S3::Bucket。它指定的是 source 渲染出的 kind,与结构化 source: 所携带的 kind: 无关。这是一个模板。
namestring是要省略的单元的名称,使用渲染该 source 的 provider 的词汇:对于 chart,是渲染出的文档自身的 metadata.name;对于 compose 文件,是该单元在 services:、volumes: 或 configs: 下的键;对于 CloudFormation 模板,是资源的逻辑 ID,即它在 Resources 下的键。这是一个模板。
namespacestring否要省略的单元所在的 namespace,用于该条目只应匹配该 namespace 中的单元的情况——适用于输出带有 namespace 的 provider,例如 chart 渲染出的文档。若不设置,或渲染为空字符串,该条目匹配具有其 kind 和名称的单元,无论其 namespace 为何。compose 文件和 CloudFormation 模板没有 namespace,它们的 provider 会拒绝指定了 namespace 的条目。这是一个模板。
subchartstring否要排除的单元所来自的子 chart,用于条目只应匹配某一个子 chart 所渲染副本的情况——适用于由嵌套 source 组装而成的 source,就像 chart 由其子 chart 组装而成。对于 chart,为子 chart 自身的名称,或其父 chart 的依赖为其指定的别名,嵌套子 chart 的名称从最外层起用 / 连接:operator 或 operator/webhooks。此时条目匹配从该子 chart 自身的 templates/ 或 crds/ 渲染出的文档,既不匹配 chart 自身渲染的文档,也不匹配嵌套在该子 chart 内的子 chart 渲染的文档。缺省或渲染为空字符串时,条目匹配其种类和名称对应的单元,无论其来源。未渲染该名称子 chart 的 chart 会使构建停止,并指出该条目。compose 文件和 CloudFormation 模板没有子 chart,其 provider 会拒绝指定子 chart 的条目。一个模板。
whenstring否内联 Go 模板,在该条目的其他字段之前求值。当它渲染为假值时,该条目被丢弃:其他字段不会被求值,不会因它而省略任何内容,也不要求它必须匹配。when 为空或不设置时保留该条目。真值判断遵循类布尔模板输出的标准约定:字符串 true/True/TRUE、任何非零数字以及任何其他非空字符串为真,而 false/False/FALSE、空字符串和零为假。渲染失败的 when 会中止构建。

不允许其他属性。

recipe.spec.boundary

该 Recipe 向其渲染所在 boundary 的共享输出贡献的内容,而非向其自身 component 的输出贡献的内容。大多数 Recipes 从不需要它:它用于目标在整个 boundary 中只读取一次的文件——例如 Terraform provider 配置,Terraform 只在 boundary 的根配置中接受它,从不接受出现在某个 component 的模块内。provider 仅在其契约声明了 boundaryArtifacts 时才接受此类文件;为未声明的 provider 声明此块的 Recipe 会在渲染任何内容之前被拒绝。FeatureRecipe 不带此类块。

属性类型必需描述
artifactsstring 或 object 的 map是从文件名到文件内容编写的映射,其形式与该 Recipe 自身的 artifacts 完全相同:同样的三种模式——内联 Go 模板字符串、对本地 Go 模板文件的 $import:,或对 ArtifactLibrary 包的 $import:(其文件以 <key>/<filename> 的形式嵌套在条目的键下)——同样的键到文件名规则,以及同样的模板上下文,因此条目可以像 artifacts 条目一样读取 .values、.infra、.locals 等。不同之处在于每个文件的写入位置:只写入一次,写在存放该边界汇总输出的目录中,与 provider 自身汇总写入该目录的文件并列,而不是写在该 component 自己的目录中。对于该 Recipe 在边界内渲染的每个 component,每个条目都会求值一次,这些求值产生的文件按名称合并:多个 component 或多个 Recipes 将同一名称求值为相同字节时,视为同一个文件;而同一名称求值为不同字节时会中止构建,并指出该文件及所有贡献者,provider 自身汇总已写入的名称也同样如此。此类文件中不会写入任何标记来说明是哪个 component 写入的,因为它属于声明了它的每个 component。模板渲染为空的条目不会写入文件。这些条目不会交给 provider,provider 在不读取它们的情况下写入边界输出的其余部分。在对象形式中,$import 不得匹配 ^oci://;匹配的值会被拒绝。键:键用于命名文件,因此限定为单个文件名,遵循 artifacts 键的规则:以字母或数字开头,后接字母、数字、点、连字符或下划线。/ 会使一个键命名一个路径而非文件,而开头的 . 会允许 ..,它指向边界输出目录之外的位置——首字符类会同时拒绝这两者。对于库导入,键命名的是包内文件所嵌套的目录,因此同样的限制适用。模式:^[A-Za-z0-9][A-Za-z0-9._-]*$。至少 1 个条目。

不允许其他属性。

recipe.spec.pipeline[]
属性类型必需描述
idstring是此步骤的程序化标识符,在此流水线的各步骤中唯一:在其两个步骤上声明同一个 id 的文档会在读取时被拒绝。同一流水线中后续的步骤以 .steps.<id>.outputs 读取此步骤的输出。模式:^[a-zA-Z0-9_]+$。
pluginstring是对此步骤所运行的 Plugin 实体的引用,始终以该插件自身的 socket 类型限定作用域:<pluginType>/<name>,可带可选版本,如 parser/yaml 或 parser/yaml:1.0.0。作用域是必需的,而非多种形式之一——未限定作用域的 name:version 会被拒绝,因为两个 socket 可能持有同名插件,而作用域使该实体可被解析。构建会将实体解析为其按内容寻址的 .wasm 制品(根据插件的身份和所配置的仓库定位,其摘要固定在 lockfile 中)并加载字节。此处不接受裸 .wasm 或制品引用。
functionstring是要调用的导出 Wasm 函数。
withstring否内联 Go 模板,求值结果为严格满足此插件显式输入 schema 的 JSON/YAML 映射。
optional布尔值否为 true 时,此步骤的失败(guest trap、针对文档集中不存在的文档的 patch、格式错误的 patch,或 halt 级别的诊断)会降级为显式警告:恢复步骤前的文档集,丢弃此步骤的输出,流水线继续执行。为 false 或不设置时,任何步骤失败都会在恢复步骤前的文档集后中止构建。
whenstring否内联 Go 模板,在遍历流水线时求值。当它渲染为假值时,跳过该步骤——即直通:文档集原样流向下一步,不产生任何 patch、副作用或步骤记录。when 为空或不设置时始终运行该步骤。真值判断遵循类布尔模板输出的标准约定:字符串 true/True/TRUE、任何非零数字以及任何其他非空字符串为真,而 false/False/FALSE、空字符串和零为假。when 与 optional 相互独立:一个步骤可以同时声明两者。

不允许其他属性。