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

Aggrega 基础设施基础(FeatureRecipe)schema

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

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

由运维编写的定义,将一个抽象的目录 Feature 映射到针对某一 provider 能力的具体的、带版本的实现。与物理 provider 和目录 feature 严格一一对应。

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

顶层类型: object

属性

属性类型必需描述
apiVersionconst “aggrega.ai/v1beta1”是常量:"aggrega.ai/v1beta1"
kindconst “FeatureRecipe”是常量:"FeatureRecipe"
metadataobject是
specobject是FeatureRecipe 的 provider 能力绑定、映射、流水线和注入映射。携带与 Recipe 相同的三种输入类型(sourced、synthesized、artifacts),外加 FeatureRecipe 独有的 injectMapping;仅声明 capability 和 implements 的纯连线 FeatureRecipe 是有效的,且不渲染任何内容。

不允许其他属性。

featurerecipe.metadata

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

不允许其他属性。

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

不允许其他属性。

featurerecipe.spec

FeatureRecipe 的 provider 能力绑定、映射、流水线和注入映射。携带与 Recipe 相同的三种输入类型(sourced、synthesized、artifacts),外加 FeatureRecipe 独有的 injectMapping;仅声明 capability 和 implements 的纯连线 FeatureRecipe 是有效的,且不渲染任何内容。

属性类型必需描述
capabilitystring是该 recipe 所绑定的显式 provider 能力(例如 ‘helm’、‘terraform’、‘compose’),即渲染它的 provider 类型。
implementsstring是声明该 recipe 能够实现哪种目录 Feature 类型(包括标记为 feature.aggrega.ai/kind: secret 的凭据 Features;可为精确版本、主版本兼容范围 ’^’ 或不带版本)。编译器用它来验证 Manifest 映射,并在诊断和编辑器补全中提供候选项;它从不决定构建。Manifest 映射是用户对实现的显式选择,固定在该 Release 的 lockfile 中。
localsmap of string否私有 Ops 状态。内部计算结果,仅在该 FeatureRecipe 的模板中以 ‘.locals.*’ 形式可用。每个条目本身都是一个 Go 模板,针对一个自包含的上下文求值:‘.context.instance_id’(该 attachment 正在为其解析的宿主 COMPONENT,这也是该引用在每个模板表面上所指代的对象)、‘.attachment_name’(正在解析的 attachment 实例,也是从 local 获取该名称的唯一途径)、attachment 自身的 ‘.values’ 和 ‘.infra’,以及同一块中迄今已解析的条目。条目按书写顺序解析,一个条目可以读取定义在它上方的同级条目,得到的是该同级条目解析后的值,而不是其模板文本。只要一个条目读取另一个条目,作者书写的顺序就是契约的一部分:把某个定义移到读取它的条目下方会破坏构建,而且该块永远不会为了让引用得以解析而重新排序。引用该块稍后才定义的条目的 ‘.locals.’ 会停止构建,并指出顺序错误;引用该块根本未声明的键则会停止构建,并指出该键。这两项检查读取的是引用所解析到的路径,而不是按键输入的文本,因此同样覆盖直接形式、’{{ with .locals }}’ 块内的读取、通过直接绑定到 ‘.locals’ 的变量进行的读取,以及在括号中从块上读取的键,即 ‘(.locals).’ 或 ’($.locals).’。有一种写法它们不覆盖:模板文本无法确定其路径的引用,即通过函数(如 ‘index .locals’ 或 ‘(default dict .locals).’)到达的引用,或通过其流水线应用了函数的 ‘with’ 块或变量绑定到达的引用,因为这类流水线产生什么是在求值时决定的,而不是由其文本决定。这种写法不会被分析,以这种方式到达的缺失键不会停止构建:它会渲染字面文本 '',而不是什么都不渲染。唯一的例外是 ‘index’ 本身:在每个模板表面上,当它读取的 map 中没有所请求的键时,它会停止构建并指出该键,因此通过 ‘index .locals’ 到达的缺失键会停止构建。该 FeatureRecipe 的 locals 在其 provides 之前解析,因此 provides 模板可以读取 ‘.locals’ 并得到解析后的值,而引用该块未声明的键的 provides 模板会停止构建。这些规则与 Recipe 的 locals 块所遵循的规则相同。当 executionScope 为 boundary 时,该块针对边界 attachment 只求值一次,所用的是边界作用域的模板上下文而不是某个组件的上下文,并且该 attachment 所到达的每个组件都读取这些已解析的条目,包括其 injectMapping 所读取的 ‘.locals’。用于为下游 Wasm 插件导出物理实际信息(例如目标容器、JSON 路径)。永远不会暴露给调用方,公共 API 请使用 provides。
providesmap of string否公共 Developer API。可供下游调用方进行 inject 解析的契约输出变量。当 executionScope 为 boundary 时,provides 针对边界 attachment 只求值一次,使用边界作用域的模板上下文;该 attachment 所到达的每个组件都在 ‘.features..provides’ 处读取这一次求值的结果,该 attachment 所携带的连接也是如此;所实现的 Feature 声明的 provides 契约只在这次求值上检查一次,并指出该边界 attachment。
sourcestring 或 object否可选的基础设施代码路径。接受 URI 字符串或开放的结构化对象。如果与 valuesMapping 一同提供,编译器会渲染它,渲染出的文档会在该 FeatureRecipe 的流水线步骤运行之前并入其输出。
valuesMappingstring 或 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://;匹配的值会被拒绝。
workloadstring 或 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://;匹配的值会被拒绝。
artifactsstring 或 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._-]*$。
omitsobject[]否从此 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 个条目。
injectMappingstring否可选的内联 Go 模板,在 Pre-Render Interception 阶段求值,对挂载所触及的每个组件各求值一次,基于该组件的模板上下文:无论 executionScope 如何设置,它都读取该组件的 ‘.context’、‘.features’ 以及挂载的 ‘.attachment_name’、‘.values’、‘.infra’ 和 ‘.locals’;引用 ‘.boundary’(任何组件的上下文都不携带它)会中止构建。输出一个 JSON/YAML 字典,由 Go 编译器原生深度合并到 Caller 的 ‘.context.inject’ 内存管道上。用于在不使用 Wasm 的情况下对环境变量和交付契约进行 Caller 端修改。
pipelineobject[]否在渲染之后对渲染出的文档集依次运行的 Wasm 流水线步骤列表,每个步骤返回 RFC 6902 补丁和副作用。
executionScopestring(枚举)否此 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
assertionsmap 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[]
属性类型必需描述
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 会中止构建。

不允许其他属性。

featurerecipe.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 相互独立:一个步骤可以同时声明两者。

不允许其他属性。