Aggrega 基础设施基座(Recipe)schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/recipe-v1beta1.schema.json
由运维编写的指针与映射层,将开发意图连接到特定的基础设施 provider。与一个物理 provider 及一个目录 component 严格一一对应。
关于编写 Recipe 实体的说明性指导,请参阅 Recipe 编写参考;本页记录该参考所描述的结构化 schema。
顶层类型: object
属性
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | 是 | 常量:"aggrega.ai/v1beta1" |
kind | const “Recipe” | 是 | 常量:"Recipe" |
metadata | object | 是 | |
spec | object | 是 | Recipe 的 provider 绑定、源、值映射和流水线。支持通过叠加组合的三种输入类型:sourced(source 加 valuesMapping 覆盖层)、synthesized(workload)和 artifacts(具名输出文件)。除此之外,Recipe 还可以在 ‘boundary’ 下,向其渲染所在 boundary 的共享输出贡献文件。 |
不允许其他属性。
recipe.metadata
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 长度至少为 1 个字符。 |
version | string | 是 | 实现 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-]+)*))?$。 |
description | string | 否 | 说明该实体是什么、用于什么,面向正在决定是否使用它的人。先用一句话点明它是什么,再补充读者为正确选择和使用它所需了解的内容——它对部署它的 Release 有什么期望,以及它的行为中任何出人意料之处。通常写一个简短的段落即可。 |
maintainers | object[] | 否 | 拥有此实体的维护者列表。 |
license | string | 否 | 此实体所描述软件的许可证 SPDX 标识符,例如 MIT 或 AGPL-3.0。它记录的是该软件的条款,而不是此文件的条款。 |
repository | string | 否 | 源文件所在 Git 仓库的 URL。 |
home | string | 否 | 此实体的主页、wiki 或文档的 URL。 |
keywords | string[] | 否 | 用于提升 UI 可发现性的描述性关键字列表。 |
不允许其他属性。
recipe.metadata.maintainers[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | |
email | string | 否 | |
url | string | 否 |
不允许其他属性。
recipe.spec
Recipe 的 provider 绑定、源、值映射和流水线。支持通过叠加组合的三种输入类型:sourced(source 加 valuesMapping 覆盖层)、synthesized(workload)和 artifacts(具名输出文件)。除此之外,Recipe 还可以在 ‘boundary’ 下,向其渲染所在 boundary 的共享输出贡献文件。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
capability | string | 是 | 此 recipe 绑定的显式 provider 能力(例如 ‘helm’、‘terraform’、‘compose’),即渲染它的 provider 类型。可接受可选的版本锁定,形式与 ‘implements’ 相同的三种:不带版本(‘helm’)、精确版本(‘helm:1.0.0’)或主版本兼容范围(‘helm:^1.0.0’)。裸名称选择 provider 类型;锁定存在时,选择由提供该能力的 provider 渲染插件的哪个版本来渲染此 recipe:未锁定时取最高可用版本,精确锁定时取该精确版本,脱字符锁定时取范围内最高版本。若没有任何提供该能力的插件版本满足锁定,构建会明确地中止。provider 选择之后的一切(输出分组、路径段、流水线兼容性和编解码器选择)都以裸能力为键,因此两个锁定同一能力不同插件版本的 recipe 可以在同一次构建中共存。 |
implements | string | 是 | 声明此 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 中。 |
source | string 或 object | 否 | 基础设施代码的位置。可接受 URI 字符串,或一个开放的结构化对象,其由 provider 定义的键以 ‘.source.*’ 的形式暴露给 Recipe 的模板。 |
locals | map of string | 否 | 私有 Ops 状态。内部计算结果,在此 Recipe 的模板中以 ‘.locals.*’ 的形式可用。每个条目本身是一个 Go 模板,针对一个自包含的节点本地上下文求值:‘.context.instance_id’、‘.values’、‘.infra’,以及本块中已解析的条目。条目按书写顺序解析,条目可以读取定义在其上方的同级条目,得到的是该同级条目解析后的值,而不是其模板文本。凡是一个条目读取另一个条目,书写顺序就是契约的一部分:将定义移到读取者下方会破坏构建,且本块从不为使引用得以解析而重新排序。对本块稍后才定义的条目的 ‘.locals. |
provides | string、number 或 boolean 的 map | 否 | 公共开发者 API。契约化的输出变量,供下游 Caller 的 inject 解析使用。编译器针对一个自包含的上下文对 provides 模板求值,彼此之间顺序任意:任何 provides 条目都不读取另一个条目。节点的 locals 在 locals 前导阶段解析,先于其 provides,因此 provides 模板可以读取 ‘.locals’ 并得到解析后的值;引用 locals 块未声明的键会中止。调用方在 inject 注水时根据这些值解析 inject 键。值为标量:管道原样传递它们,并在注入边界处确定性地字符串化。 |
valuesMapping | string 或 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://;匹配的值会被拒绝。 |
workload | string 或 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://;匹配的值会被拒绝。 |
artifacts | string 或 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._-]*$。 |
omits | object[] | 否 | 从该 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 个条目。 |
boundary | object | 否 | 该 Recipe 向其渲染所在 boundary 的共享输出贡献的内容,而非向其自身 component 的输出贡献的内容。大多数 Recipes 从不需要它:它用于目标在整个 boundary 中只读取一次的文件——例如 Terraform provider 配置,Terraform 只在 boundary 的根配置中接受它,从不接受出现在某个 component 的模块内。provider 仅在其契约声明了 boundaryArtifacts 时才接受此类文件;为未声明的 provider 声明此块的 Recipe 会在渲染任何内容之前被拒绝。FeatureRecipe 不带此类块。 |
outputLabels | map 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 作者负责;除保留命名空间规则外,核心不检查标签字符集。 |
outputComponentLabels | string[] | 否 | 此 recipe 提升到其渲染输出上的 Component 身份标签键。每个条目指定一个标签键;其值取自此 recipe 所渲染的组件实例的标签,因此盖印的标签携带该组件声明的值,而不是在此处重复的值。被提升的标签到达与 outputLabels 相同的标签面,而 outputLabels 携带的是就地编写的字面键值对。在两个块中都声明的键会在加载时被拒绝,因此每个盖印的键只有单一来源。aggrega.ai/ 和 app.kubernetes.io/ 命名空间保留给平台原生的来源标签,会在加载时被拒绝;诸如 component.aggrega.ai/hosting 这样的作用域键位于这些保留根之外,可以被提升。 |
pipeline | object[] | 否 | 在渲染之后对渲染出的文档集依次运行的 Wasm 流水线步骤列表,每个步骤返回 RFC 6902 补丁和副作用。 |
assertions | map 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[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
kind | string | 是 | 要省略的单元的 kind,使用渲染该 source 的 provider 的词汇:对于 chart,是渲染出的文档自身的 kind,例如 Secret;对于 compose 文件,是 service、volume 或 config;对于 CloudFormation 模板,是资源的 Type,例如 AWS::S3::Bucket。它指定的是 source 渲染出的 kind,与结构化 source: 所携带的 kind: 无关。这是一个模板。 |
name | string | 是 | 要省略的单元的名称,使用渲染该 source 的 provider 的词汇:对于 chart,是渲染出的文档自身的 metadata.name;对于 compose 文件,是该单元在 services:、volumes: 或 configs: 下的键;对于 CloudFormation 模板,是资源的逻辑 ID,即它在 Resources 下的键。这是一个模板。 |
namespace | string | 否 | 要省略的单元所在的 namespace,用于该条目只应匹配该 namespace 中的单元的情况——适用于输出带有 namespace 的 provider,例如 chart 渲染出的文档。若不设置,或渲染为空字符串,该条目匹配具有其 kind 和名称的单元,无论其 namespace 为何。compose 文件和 CloudFormation 模板没有 namespace,它们的 provider 会拒绝指定了 namespace 的条目。这是一个模板。 |
subchart | string | 否 | 要排除的单元所来自的子 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 的条目。一个模板。 |
when | string | 否 | 内联 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 不带此类块。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
artifacts | string 或 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[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
id | string | 是 | 此步骤的程序化标识符,在此流水线的各步骤中唯一:在其两个步骤上声明同一个 id 的文档会在读取时被拒绝。同一流水线中后续的步骤以 .steps.<id>.outputs 读取此步骤的输出。模式:^[a-zA-Z0-9_]+$。 |
plugin | string | 是 | 对此步骤所运行的 Plugin 实体的引用,始终以该插件自身的 socket 类型限定作用域:<pluginType>/<name>,可带可选版本,如 parser/yaml 或 parser/yaml:1.0.0。作用域是必需的,而非多种形式之一——未限定作用域的 name:version 会被拒绝,因为两个 socket 可能持有同名插件,而作用域使该实体可被解析。构建会将实体解析为其按内容寻址的 .wasm 制品(根据插件的身份和所配置的仓库定位,其摘要固定在 lockfile 中)并加载字节。此处不接受裸 .wasm 或制品引用。 |
function | string | 是 | 要调用的导出 Wasm 函数。 |
with | string | 否 | 内联 Go 模板,求值结果为严格满足此插件显式输入 schema 的 JSON/YAML 映射。 |
optional | 布尔值 | 否 | 为 true 时,此步骤的失败(guest trap、针对文档集中不存在的文档的 patch、格式错误的 patch,或 halt 级别的诊断)会降级为显式警告:恢复步骤前的文档集,丢弃此步骤的输出,流水线继续执行。为 false 或不设置时,任何步骤失败都会在恢复步骤前的文档集后中止构建。 |
when | string | 否 | 内联 Go 模板,在遍历流水线时求值。当它渲染为假值时,跳过该步骤——即直通:文档集原样流向下一步,不产生任何 patch、副作用或步骤记录。when 为空或不设置时始终运行该步骤。真值判断遵循类布尔模板输出的标准约定:字符串 true/True/TRUE、任何非零数字以及任何其他非空字符串为真,而 false/False/FALSE、空字符串和零为假。when 与 optional 相互独立:一个步骤可以同时声明两者。 |
不允许其他属性。