本页面由机器翻译。阅读英文原文。
Aggrega 目录(Feature)schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/feature-v1beta1.schema.json
一种模块化的运维功能,可动态绑定到组件。
有关编写 Feature 实体的文字指导,请参阅 Feature 编写参考;本页记录该参考所描述的结构化 schema。
顶层类型: object
属性
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | 是 | 常量:"aggrega.ai/v1beta1" |
kind | const “Feature” | 是 | 常量:"Feature" |
metadata | object | 是 | |
spec | object | 是 | 目录 Feature 的验证、定位与互操作契约:通过 schema 编写的自由形态支柱(values、infra、provides)、固定形态支柱(usesSchema 依赖插槽、featuresSchema 挂接槽位)、组件定位(appliesTo 和 appliesToAnyOf),以及互操作控制。 |
不允许其他属性。
feature.metadata
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 长度至少为 1 个字符。 |
version | string | 是 | 该 feature 的严格语义化版本(例如 1.0.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 可发现性的描述性关键字列表。 |
labels | object | 否 | 该 Feature 的鸭子类型标签。值为 ‘secret’ 的保留标签 ‘feature.aggrega.ai/kind’ 会向作者及展示它的工具将其标记为凭据 Feature。凭据 Feature 与普通 Feature 的挂接方式相同,位于同一挂接界面下;挂接产生什么,由 Manifest 将其类型映射到的 FeatureRecipe 决定,而不是由该标签决定。 |
annotations | map of string | 否 | 由平台架构师在领域 2 中编写的不可变的、固有的 feature 特征。向下级联到 .context.annotations.catalog 存储桶。 |
不允许其他属性。
feature.metadata.maintainers[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | |
email | string | 否 | |
url | string | 否 |
不允许其他属性。
feature.metadata.labels
该 Feature 的鸭子类型标签。值为 ‘secret’ 的保留标签 ‘feature.aggrega.ai/kind’ 会向作者及展示它的工具将其标记为凭据 Feature。凭据 Feature 与普通 Feature 的挂接方式相同,位于同一挂接界面下;挂接产生什么,由 Manifest 将其类型映射到的 FeatureRecipe 决定,而不是由该标签决定。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
feature.aggrega.ai/kind | string(枚举) | 否 | Feature 类别标签。值 ‘secret’ 将其标记为凭据 Feature。允许的值:"secret" |
feature.spec
目录 Feature 的验证、定位与互操作契约:通过 schema 编写的自由形态支柱(values、infra、provides)、固定形态支柱(usesSchema 依赖插槽、featuresSchema 挂接槽位)、组件定位(appliesTo 和 appliesToAnyOf),以及互操作控制。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
extends | string | 否 | 对该 Feature 所继承的基础 Feature 的引用。它按基础 Feature 的 metadata.name 来命名,而不是按该 Feature 发布时所用的注册表坐标,并且接受每个目录引用都接受的三种版本形式:裸形式(core/queue)表示可用的最高 release,精确形式(core/queue:1.0.0),或脱字符范围(core/queue:^1.0.0)。继承的不只是 metadata:基础 Feature 的 metadata.labels 和 metadata.annotations、其 appliesTo 和 appliesToAnyOf 选择器、其 interoperability 块、其 usesSchema 和其 featuresSchema 都会向下合并,其在 schema 上的 JSON Schema 2020-12 声明会自动合并。在共享的键上以子级自身的值为准,标识字段从不继承。 |
featuresSchema | map of object | 否 | 声明式附加槽定义:该 Feature 期望附加另一个 Feature 的具名绑定点。槽约束哪些填充可以绑定它(selector),以及填充的内容可以如何交付(inject);填充自身的 Feature 拥有其 values 和 infra 契约。声明槽从不会封闭附加块——作者可以用任何槽都未声明的名称附加 Feature。槽是绑定点,而不是依赖插座:usesSchema 声明的是独立的拓扑面。 |
appliesTo | string | 否 | 匹配 Components 的 Kubernetes 风格标签选择器字符串。以逗号分隔的各项要求必须全部成立(AND)。支持的形式:key=value、key!=value、key in (v1, v2)、key notin (v1, v2)、裸 key(标签存在)、!key(标签不存在)。示例:“tier in (critical, production), !legacy”。空的或缺省的选择器不声明任何约束。每次评估该 Feature 的附加时,都会按这些形式读取选择器,超出这些形式的要求会使构建停止,并指出该要求:空要求(开头、结尾或重复的逗号),或包含空白或 = ! ( ) 及逗号中任一字符的 key——因此 “!tier=frontend” 会被拒绝,排除某个值应写作 tier!=frontend。值是其运算符之后的文本,无论其中包含什么字符。该字段上的模式只在评估任何附加之前拒绝少数几种格式错误的形式。模式:^(?:[^()]*[()][\s\S]*|[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?(?:,[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?)*)$。 |
appliesToAnyOf | string 或 string[] 的 map | 否 | 选择器列表;只要任一项匹配,该 Feature 即适用(OR 逻辑)。每一项要么是标签选择器字符串(语法与 appliesTo 相同;字符串内的各项要求以 AND 组合),要么是扁平的键值 map,其中每一对都必须匹配(仅限相等)。 |
interoperability | object | 否 | 高级运行安全与互操作性控制。 |
usesSchema | map of object | 否 | 该实体声明的依赖插座,以插座名称为键;通过某个插座建立的每个连接都会对照该插座的声明进行检查——其选择器以及它允许的 inject 机制。键:一个或多个字母、数字、下划线或连字符。不允许使用点。模式:^[a-zA-Z0-9_-]+$。 |
schema | object | 否 | 涵盖自由形态支柱的 JSON Schema 2020-12 内容:values(Developer 的领域——Developer 在 Aggregate 中为每个 Feature 附加配置的应用形态参数);infra(Operator 的领域——由 Release 提供的物理规格调节项);以及 provides(该 Feature 通过拓扑管道向使用方公开的下游上下文键)。通过按内容形态分派接受三种编写模式:(1) 内联内容(一个 YAML map,承载紧凑形式、JSON Schema YAML 或二者混合);(2) 通过 {$import: |
assertions | map of string | 否 | 构建时跨字段验证。每个条目是一个具名断言:键是在错误消息中显示的稳定规则标识符;值是具有 {{ fail "message" }} 停止语义的 Go 模板字符串。每个实体的多个具名断言按实例、按作者声明的顺序评估;第一个失败的断言会停止构建。Feature 断言在解析和静态分析之后、渲染之前评估,用于表达契约的架构不变量。模板上下文:.values / .infra / .uses / .features / .metadata。评估器使用 missingkey=error:引用未定义的键会以 no-such-key 诊断停止。由于裸引用在任何回退得以运行之前就会停止,在此处单纯的 default 无法为可选字段提供回退——请用 hasKey 守护该引用,或使用直接执行存在性检查的 optional 辅助函数。通过 index 读取该键同样无法提供回退:index 遇到 map 中不存在的键时会停止,并指出该键。 |
不允许其他属性。
feature.spec.interoperability
高级运行安全与互操作性控制。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
conflictsWith | string[] | 否 | 该 Feature 不能与之同时到达同一组件的 Features 的名称,每个名称的写法与附加的 type 命名 Feature 的写法相同。当某个组件最终同时带有该 Feature 和此处列出的某个 Feature 时,构建会在渲染前停止——无论各自是附加在该组件上、附加在包含它的子系统或边界上、附加在 Release 的组件条目上,还是通过注解驱动的展开附加的。一方声明即可:停止并不需要另一个 Feature 也列出此 Feature。比较名称时会去除任何版本,因此一个条目会匹配其所指 Feature 的每个版本。附加到不共享任何组件的同级边界上的两个 Features 永远不会相遇,也不会导致停止。 |
不允许其他属性。