本页面由机器翻译。阅读英文原文。
Aggrega 基础设施基础(FeatureRecipe)schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/featurerecipe-v1beta1.schema.json
由运维编写的定义,将一个抽象的目录 Feature 映射到针对某一 provider 能力的具体的、带版本的实现。与物理 provider 和目录 feature 严格一一对应。
有关编写 FeatureRecipe 实体的说明性指导,请参阅 FeatureRecipe 编写参考;本页记录该参考所描述的结构化 schema。
顶层类型: object
属性
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | 是 | 常量:"aggrega.ai/v1beta1" |
kind | const “FeatureRecipe” | 是 | 常量:"FeatureRecipe" |
metadata | object | 是 | |
spec | object | 是 | FeatureRecipe 的 provider 能力绑定、映射、流水线和注入映射。携带与 Recipe 相同的三种输入类型(sourced、synthesized、artifacts),外加 FeatureRecipe 独有的 injectMapping;仅声明 capability 和 implements 的纯连线 FeatureRecipe 是有效的,且不渲染任何内容。 |
不允许其他属性。
featurerecipe.metadata
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 长度至少为 1 个字符。 |
version | string | 是 | 该 FeatureRecipe 的严格语义化版本(例如 1.2.5)。模式:^(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 可发现性的描述性关键字列表。 |
不允许其他属性。
featurerecipe.metadata.maintainers[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | |
email | string | 否 | |
url | string | 否 |
不允许其他属性。
featurerecipe.spec
FeatureRecipe 的 provider 能力绑定、映射、流水线和注入映射。携带与 Recipe 相同的三种输入类型(sourced、synthesized、artifacts),外加 FeatureRecipe 独有的 injectMapping;仅声明 capability 和 implements 的纯连线 FeatureRecipe 是有效的,且不渲染任何内容。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
capability | string | 是 | 该 recipe 所绑定的显式 provider 能力(例如 ‘helm’、‘terraform’、‘compose’),即渲染它的 provider 类型。 |
implements | string | 是 | 声明该 recipe 能够实现哪种目录 Feature 类型(包括标记为 feature.aggrega.ai/kind: secret 的凭据 Features;可为精确版本、主版本兼容范围 ’^’ 或不带版本)。编译器用它来验证 Manifest 映射,并在诊断和编辑器补全中提供候选项;它从不决定构建。Manifest 映射是用户对实现的显式选择,固定在该 Release 的 lockfile 中。 |
locals | map of string | 否 | 私有 Ops 状态。内部计算结果,仅在该 FeatureRecipe 的模板中以 ‘.locals.*’ 形式可用。每个条目本身都是一个 Go 模板,针对一个自包含的上下文求值:‘.context.instance_id’(该 attachment 正在为其解析的宿主 COMPONENT,这也是该引用在每个模板表面上所指代的对象)、‘.attachment_name’(正在解析的 attachment 实例,也是从 local 获取该名称的唯一途径)、attachment 自身的 ‘.values’ 和 ‘.infra’,以及同一块中迄今已解析的条目。条目按书写顺序解析,一个条目可以读取定义在它上方的同级条目,得到的是该同级条目解析后的值,而不是其模板文本。只要一个条目读取另一个条目,作者书写的顺序就是契约的一部分:把某个定义移到读取它的条目下方会破坏构建,而且该块永远不会为了让引用得以解析而重新排序。引用该块稍后才定义的条目的 ‘.locals. |
provides | map of string | 否 | 公共 Developer API。可供下游调用方进行 inject 解析的契约输出变量。当 executionScope 为 boundary 时,provides 针对边界 attachment 只求值一次,使用边界作用域的模板上下文;该 attachment 所到达的每个组件都在 ‘.features. |
source | string 或 object | 否 | 可选的基础设施代码路径。接受 URI 字符串或开放的结构化对象。如果与 valuesMapping 一同提供,编译器会渲染它,渲染出的文档会在该 FeatureRecipe 的流水线步骤运行之前并入其输出。 |
valuesMapping | string 或 object | 否 | values 映射内容,通过内容形状分派支持三种编写模式。模式 1(内联):一个 Go 模板字符串标量,生成 provider 所期望的 values 格式。模式 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 map,$import: ./relative/path.yaml,指向本地 Go 模板文件。模式 3(库导入):仅含一个键的 YAML map,$import: <Library>#/workloads/<entry>,按裸名称标识引用一个 WorkloadLibrary 条目(版本由每个 Release 的 lockfile 提供;引用中不出现注册表主机)。目标 Provider 必须支持 workload 合成;标准库目录在此类 provider 上声明 workloadSchema,作为有文档记载的契约。绑定到无法合成的 provider 的 workload: FeatureRecipe 会在渲染时明确停止。合成的 FeatureRecipe workload 会在该 feature 的输出目录下生成其 provider 原生清单。在对象形式中,$import 不得匹配 ^oci://;匹配的值会被拒绝。 |
artifacts | string 或 object 的 map | 否 | 条目名称到 artifact 内容编写的映射。每个条目的值通过内容形态分派采用三种模式之一。模式 1(内联):一个 Go 模板字符串标量,其输出即 artifact 正文。模式 2(文件导入):一个只有一个键的 YAML map,$import: ./relative/path.yaml,指向本地 Go 模板文件。模式 3(库导入):一个只有一个键的 YAML map,$import: <Library>#/artifacts/<entry>,按裸名称标识引用一个 ArtifactLibrary bundle(版本由每个 Release 的 lockfile 提供;引用中不出现 registry 主机)。一个 bundle 展开为每个文件一个输出,每个输出都以 <key>/<filename> 的形式嵌套在该条目的键下。键为条目的输出命名:模式 1 或模式 2 条目的键就是其输出文件名,按原样使用;模式 2 条目导入的文件提供内容但不为输出命名,因此两个导入同名不同文件的条目是两个不同的输出。生成资源的 FeatureRecipe 所输出的辅助资源(ConfigMap、ServiceMonitor、NetworkPolicy、ExternalSecret CRD 等)都具有 artifact 形态;artifacts: 是主要的资源生成机制。artifact 条目、bundle 文件、source 输出和 workload 合成之间的冲突会在节点渲染时使构建中止。artifacts 块在 Recipe 和 FeatureRecipe 上的编写方式完全相同——相同的三种模式、相同的键到输出规则以及相同的冲突行为——因此本描述的这一部分在两种类型上内容一致;为其中一种编写的示例可原样用于另一种。在对象形式中,$import 不得匹配 ^oci://;匹配的值会被拒绝。键:键为条目的输出命名,因此限定为单个文件名:以字母或数字开头,后接字母、数字、点、连字符或下划线。首字符之后的点保留 artifact 键所带的扩展名(main.tf、template.yaml、serviceaccount.yaml)。/ 会使一个键命名的是路径而非文件,而开头的 . 会允许 ..,它指向输出目录之外的位置——首字符类同时拒绝这两者。对于库导入,键命名 bundle 文件所嵌套的目录,因此同样的限制适用。模式:^[A-Za-z0-9][A-Za-z0-9._-]*$。 |
omits | object[] | 否 | 从此 FeatureRecipe 的 source 渲染结果中排除哪些内容——适用于按原样采用、却会渲染出 Release 不得发布之内容的 source:获取的 chart 渲染出的文档,例如保存 chart 每次渲染都重新生成的密钥的 Secret;获取的 compose 文件捆绑的 service、volume 或 config;或获取的 CloudFormation 模板声明的资源。大多数 FeatureRecipes 从不需要它。每个条目按种类、名称以及(条目给出时的)命名空间和其来源子 chart 指定 source 渲染的一个单元,均使用渲染该 source 的 provider 的词汇——对于 chart,按文档自身的 kind 和 metadata.name 指定文档;对于 compose 文件,按 services:、volumes: 或 configs: 下的键指定 service、volume 或 config;对于 CloudFormation 模板,按 Type 和逻辑 ID 指定资源。该 provider 会排除条目匹配的每个单元;条目匹配什么、provider 因条目而拒绝什么,都由该 provider 自己的文档化契约决定。无法排除任何内容的 provider 会在渲染任何内容之前拒绝声明此键的 FeatureRecipe。只有 source: 渲染的内容会被过滤——workload: 或 artifacts: 条目从不被过滤——因此该键要求 source。每个值都是模板,在与 valuesMapping 相同的上下文中求值。条目的 when 最先求值,when 渲染为假值的条目会被丢弃。每个保持激活的条目都必须排除某些内容:未匹配到 source 任何渲染结果的激活条目会使构建中止,并指出该条目。source 仍会完整渲染——chart 的每个模板仍会运行,因此失败的模板仍会使构建失败——只是其输出被排除。该键在 Recipe 和 FeatureRecipe 上的编写方式完全相同。至少 1 个条目。 |
injectMapping | string | 否 | 可选的内联 Go 模板,在 Pre-Render Interception 阶段求值,对挂载所触及的每个组件各求值一次,基于该组件的模板上下文:无论 executionScope 如何设置,它都读取该组件的 ‘.context’、‘.features’ 以及挂载的 ‘.attachment_name’、‘.values’、‘.infra’ 和 ‘.locals’;引用 ‘.boundary’(任何组件的上下文都不携带它)会中止构建。输出一个 JSON/YAML 字典,由 Go 编译器原生深度合并到 Caller 的 ‘.context.inject’ 内存管道上。用于在不使用 Wasm 的情况下对环境变量和交付契约进行 Caller 端修改。 |
pipeline | object[] | 否 | 在渲染之后对渲染出的文档集依次运行的 Wasm 流水线步骤列表,每个步骤返回 RFC 6902 补丁和副作用。 |
executionScope | string(枚举) | 否 | 此 FeatureRecipe 的 Resource Generation 是按组件运行(默认),还是按每个边界挂载运行一次。边界作用域的 FeatureRecipes 按 (boundary_path, FeatureRecipe 实例) 去重,并且除 injectMapping 外的每个模板都读取边界作用域的模板上下文:使用 .boundary.* 支柱,而非按组件的 .context.* 支柱,引用后者会中止构建。无论 executionScope 如何,injectMapping 都对挂载所触及的每个组件各运行一次,因此它读取该组件的上下文,从不读取 .boundary。允许的值:"component"、"boundary" 默认值:"component" |
readsCallerRenderFacts | 布尔值 | 否 | 声明此 FeatureRecipe 的模板会读取连接到其所挂载 Component 的那些 Components 的渲染结果:这些调用方各自的 provider 就其自身输出报告的渲染事实。当其为 true 且该 FeatureRecipe 按组件渲染时,它的每个挂载都会在构建中所有 Component 渲染完成之后渲染,而不是紧接在其所挂载的 Component 之后,从而保证在求值该挂载之前每个调用方的渲染均已完成。当其为 false 或缺省时,‘.context.used_by’ 上的调用方条目都不携带渲染事实,除非 readsTargetRenderFacts 为 true,否则该挂载紧接其 Component 之后渲染;若此 FeatureRecipe 中内联编写的模板读取 ‘.context.used_by’ 下调用方的渲染事实,构建会中止。默认值:false |
readsTargetRenderFacts | 布尔值 | 否 | 声明此 FeatureRecipe 的模板会读取其所挂载 Component 所连接的那些 Components 的渲染结果:这些目标各自的 provider 就其自身输出报告的渲染事实,位于 ‘.context.uses’ 的每个条目上。当其为 true 且该 FeatureRecipe 按组件渲染时,它的每个挂载都会在构建中所有 Component 渲染完成之后渲染,而不是紧接在其所挂载的 Component 之后,从而保证在求值该挂载之前每个目标的渲染均已完成。这与 readsCallerRenderFacts 引起的延后渲染相同,因此设置其中任一键或两者都设置,都会使挂载在那时渲染。当其为 false 或缺省时,‘.context.uses’ 上的条目都不携带渲染事实,除非 readsCallerRenderFacts 为 true,否则该挂载紧接其 Component 之后渲染;若此 FeatureRecipe 中内联编写的模板读取 ‘.context.uses’ 下目标的渲染事实,构建会中止。默认值:false |
assertions | map of string | 否 | 构建时跨字段校验。每个条目是一个具名断言:键是在错误消息中显示的稳定规则标识符;值是具有 {{ fail "message" }} 中止语义的 Go 模板字符串。每个实体的多个具名断言按实例、按作者声明的顺序求值;第一个失败的断言会中止构建。FeatureRecipe 断言在 recipe 绑定之后、provides 求值之后、渲染之前求值,用于表达该 FeatureRecipe 所引用的特定 chart 或模块的实现不变量。模板上下文:.values / .infra / .uses / .features / .metadata 以及 .provides / .locals / .recipe。求值器使用 missingkey=error:引用未定义的键会以 no-such-key 诊断中止。由于裸引用会在任何回退运行之前中止,在此处普通的 default 无法为可选字段提供回退——请用 hasKey 保护该引用,或使用 optional 辅助函数,它直接执行存在性检查。通过 index 读取该键同样无法提供回退:index 遇到 map 中不存在的键会中止,并指出该键。 |
不允许其他属性。
featurerecipe.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 会中止构建。 |
不允许其他属性。
featurerecipe.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 相互独立:一个步骤可以同时声明两者。 |
不允许其他属性。