Aggrega Release 模式
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
模式 ID:https://aggrega.ai/schemas/release-v1beta1.schema.json
有关编写 Release 实体的说明性指导,请参阅 Release 编写参考;本页记录该参考所描述的结构模式。
顶层类型: object
属性
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | 是 | 常量:"aggrega.ai/v1beta1" |
kind | const “Release” | 是 | 常量:"Release" |
metadata | object | 是 | |
spec | object | 是 | 该 Release 所绑定和路由的内容:它所部署的 Aggregate 和 Manifest(或一个 extends 基础),特定于环境的参数填充,以及其组件被路由进入的边界。 |
不允许其他属性。
release.metadata
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 长度至少为 1 个字符。 |
environment | string | 是 | |
version | string | 是 | release 的严格语义化版本(例如 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 | 否 | 说明该实体是什么、用于什么,面向正在决定是否使用它的人。先用一句话点明它是什么,再补充读者正确选择和使用它所需的信息——它对其部署到的平台有什么要求,以及它的行为中任何出人意料之处。通常写一小段即可。 |
maintainers | object[] | 否 | 拥有此实体的维护者列表。 |
license | string | 否 | 此实体所描述软件的许可证 SPDX 标识符,例如 MIT 或 AGPL-3.0。它记录的是该软件的条款,而不是此文件的条款。 |
repository | string | 否 | 源文件所在 Git 仓库的 URL。 |
home | string | 否 | 此实体的主页、wiki 或文档的 URL。 |
keywords | string[] | 否 | 用于提升 UI 可发现性的描述性关键字列表。 |
不允许其他属性。
release.metadata.maintainers[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | |
email | string | 否 | |
url | string | 否 |
不允许其他属性。
release.spec
该 Release 所绑定和路由的内容:它所部署的 Aggregate 和 Manifest(或一个 extends 基础),特定于环境的参数填充,以及其组件被路由进入的边界。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
aggregate | string | 否 | 对此 release 所部署的 Aggregate(开发者意图)的引用。裸标记按身份解析——即被引用 Aggregate 的 metadata.name,先在该 Release 自身所在目录中查找,再在目录库(catalog)中查找。以 ’./’ 或 ’../’ 开头的值是显式的本地文件,相对于该 Release 解析(例如 ’../shared/app.yaml’,用于在子目录中的多个 release 变体之间共享同一个 Aggregate)。 |
manifest | string | 否 | 对 Manifest 的引用,该 Manifest 解析此 release 部署时所针对的抽象接口。裸标记按身份解析——即被引用 Manifest 的 metadata.name,在该 Release 自身所在目录中查找。以 ’./’ 或 ’../’ 开头的值是显式的本地文件,相对于该 Release 解析。Manifest 属于部署侧,不被目录库索引,因此只能从 Release 所在目录或显式路径解析。 |
extends | string | 否 | 对一个基础 Release 的引用,此 Release 继承其编写面——其边界树以及其下各组件的 infra 和 Feature 挂载、其 parameters、其 annotations 以及其 Manifest 指针。该值是指向此 Release 旁边某个文件的路径,以 ’./’ 或 ’../’ 开头;裸名称和注册表坐标都会被拒绝,因为 Release 属于部署侧,不被目录库索引。继承的内容可以逐键替换,直到第一个不可分割的值——标量、列表、模板——该值会被整体替换;写为 null 的键会移除继承的内容。metadata 字段均不会被继承,因此子级自带其名称、版本和环境。本 schema 拒绝同时声明 ‘aggregate’ 和 ‘extends’,因此子级部署与其基础相同的开发者意图;‘manifest’ 仍为可选,并可被覆盖以替换依赖锁文件。 |
parameters | object | 否 | 特定于环境的变量填充契约,通过内容形状分派支持两种编写模式。模式 1(内联):直接携带结构化嵌套参数值的 YAML 映射。模式 2(文件导入):仅含一个键 $import: ./relative/path.yaml 的 YAML 映射,指向提供参数值的单个本地文件。此处仅支持单一来源——多文件分层由 Release 的 extends: 链负责(父 Release 提供基础参数;子级进行扩展和覆盖)。 |
boundaries | boundary 映射 | 否 | Aggregate 的组件被路由到的根逻辑框。键:一个或多个字母、数字、下划线或连字符。不允许使用点。模式:^[a-zA-Z0-9_-]+$。 |
components | boundary_component 映射 | 否 | 携带各组件运维 infra 的顶层组件实例,用于没有命名边界的单作用域 Release。与 boundaries 互斥:扁平 Release 声明 components,多目标路由声明 boundaries,二者不可同时声明。使用 components 时,编译器会合成一个容纳这些组件的 default 边界,并将其产物扁平地输出到 dist/。键:一个或多个字母、数字、下划线或连字符。不允许使用点。模式:^[a-zA-Z0-9_-]+$。 |
不允许其他属性。
定义
boundary_component
路由到某个边界中的组件实例,可附带物理规格设置和特性附加项。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
description | string | 否 | 可选文档,描述该组件在该 Release 的此边界中的角色。 |
subDirectory | string | 否 | Component 级别的子路径覆盖,追加到父 boundary 的目录之后。如果 boundary 和 component 上均省略或为空,则默认为 ’{{ .capability }}‘;在此处写入空字符串视同省略。设置为 ’.’,或设置为求值结果为空字符串的模板,即可禁用子目录生成。 |
annotations | string、object 或 null 的映射 | 否 | Component 专属的 Operator 注解,为该 component 覆盖 boundary 级别的注解。深度合并到 boundary 注解之上(键冲突时 component 优先;结构化值与结构化父值按子键合并)。值可以是字符串、结构化对象或 null。用于按 component 覆盖 provider 的知名注解(例如 helm provider 上的 aggrega.ai/namespace)。对从父 boundary 继承的键显式写入 null,会从该 component 中移除继承的绑定(注解驱动的 Feature 退出);同级 component 仍保留继承的绑定。 |
infra | object | 否 | 严格局限于该组件的物理规格(例如副本数、磁盘 IOPS)。 |
features | map of object | 否 | 通过 Release 附加到该组件的 Features。对于同样在 Aggregate 中声明的特性,只提供 infra(值来自 Aggregate)。对于仅在 Release 中出现的特性(由 Operator 注入),type 为必填。键为特性实例名,可包含完整的特性类型 URI(允许点和斜杠)。Release 不得为特性提供 values——这属于 Developer 的领域。键:一个或多个字母、数字、下划线、点、斜杠或连字符。模式:^[a-zA-Z0-9_./-]+$。 |
uses | release_uses_block | 否 | Operator 边配置面。在 Architect 声明的 socket 范围内,Release 可以将已声明但未绑定的 socket 连接到现有组件(target),和/或提供每条边的 infra。不允许 values(Release 的 values: 禁令仍然适用),也不允许创建计算资源;重新指定开发者声明的边的目标会在构建时中止。 |
不允许其他属性。
release_uses_block
由 Release 编写的每条边的 uses 配置面,先以 socket 为键,再以别名为键(与 Aggregate 的 uses 拓扑结构一致)。每个连接可以任意组合设置 target(在已声明但未绑定的 socket 中创建一条指向现有组件的边)、infra(每条边的 operator 配置,在解析 Release 时依据 socket 的 infraSchema 校验)和 features(填充 socket 所声明槽位的附加项)。禁止使用 values(Release 的 values: 禁令);重新指定开发者声明的边的目标会在构建时触发明确的防护报错。
键: 一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。
值为 map of object。
不允许使用其他任何键。
release_connection_attachment
Release 连接条目携带的一个附加项:填充该连接的 socket 所声明槽位的 Feature,以及 operator 为其设定的规格。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
type | string | 否 | 该 Feature 的 URI。对于仅由 Release 做出的附加项为必填。如果两者都声明了,必须与 Aggregate 的 type 一致。 |
description | string | 否 | 可选文档,说明 Operator 为何将此特性附加到该连接。 |
infra | object | 否 | 该附加项的运维规格,依据 Feature 的 schema 声明进行校验。 |
不允许其他属性。
aggregate_routing
将嵌套 Aggregate 子模块的内部组件路由到此边界。与边界的 component/aggregate 结构相对应,用于递归组合。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
components | boundary_component 映射 | 否 | Component 实例,位于嵌套聚合中,要路由到此边界。键是每个组件在该子模块内部使用的本地名称:边界自身的 components 映射以 ‘data.main-db’ 寻址的组件,其键为 ‘main-db’,因为这是它在该子模块中唯一的名称。键:一个或多个字母、数字、下划线或连字符。不允许使用点。模式:^[a-zA-Z0-9_-]+$。 |
aggregates | map of aggregate_routing | 否 | 此子 aggregate 内更深层的嵌套 aggregate(用于深度嵌套的模块组合)。键:一个或多个字母、数字、下划线或连字符。不允许使用点。模式:^[a-zA-Z0-9_-]+$。 |
不允许其他属性。
boundary
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
description | string | 否 | 可选文档,描述此边界的用途和物理目标(例如 ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’)。 |
directory | string | 否 | 用于生成 GitOps 制品的物理输出路径。支持 Go 模板变量({{ .capability }}、{{ .boundary_name }}、{{ .parameters.X }})。与 subDirectory 按路径拼接,生成最终的制品路径。 |
subDirectory | string | 否 | 追加到 directory 之后的边界级子路径。如果在边界和组件上均省略或为空,则默认为 ’{{ .capability }}‘,用于 CI/CD 自动分区;在此处写入空字符串视同省略。设置为 ’.’,或设置为求值结果为空字符串的模板,即可禁用。 |
syncWave | integer | 否 | 可选的按边界部署波次(有符号整数,默认为 0)。此边界中的每个组件都会将边界的波次继承到其节点中。允许负值(在其他所有内容之前运行);较大的值在较小的值之后运行。在 K8s 和 Helm 上,波次决定部署顺序:它会成为 argocd.argoproj.io/sync-wave 注解;对于 chart 已标记为 Helm hook 的资源,它还会成为该 hook 的 helm.sh/hook-weight。在 compose 上,波次既会记录为服务标签,也会通过服务之间的 depends_on 对其渲染所在文件中的服务进行排序——因此它作用于该文件中的每个服务,而不会影响文件之外的任何内容。在 cloudformation 上,波次决定边界所组装进的 stack 的资源配置顺序:一个波次中的每个资源都被声明为依赖于前一个波次的资源,从而确定资源的创建顺序,以及相反的删除顺序。这仅是创建和删除顺序——stack 模板无法表达资源就绪的概念,因此不会等待任何资源变为可用。在 terraform 上,波次决定边界所组装进的根配置中 module 块的顺序:一个波次中的每个 module 都被声明为依赖于前一个波次的 module,从而确定引擎执行操作的顺序。这仅是操作顺序——配置无法表达资源就绪的概念,因此不会等待任何资源变为可用——该值还会随节点的构建来源信息一起记录。编译器会将同一个值作为每个节点的 sync_wave 带到边界中的每个节点上,在那里会从节点的角度再次说明各目标的行为。嵌套边界不会隐式继承——每个嵌套边界各自声明自己的波次。 |
annotations | string、object 或 null 的映射 | 否 | 边界范围的 Operator 注解,向下级联到 .context.annotations.release 存储桶。值可以是字符串、结构化对象或 null。结构化值携带按子键的配置,与结构化的父级进行深度合并(按子键合并,子级优先),并参与注解驱动的 Feature 展开;只有标量值会出现在渲染上下文中。对从父边界继承的键显式设置 null,会从此边界的有效注解集中移除继承的绑定(注解驱动的 Feature 退出),并传播到路由到此边界的每个组件,除非更深层的覆盖重新引入该绑定。 |
features | map of object | 否 | 应用于所有嵌套组件的边界范围 feature(例如默认的安全网格)。feature 的 uses 块会投射到边界中的每个组件,从而在边界上一次性声明共享依赖,而不必在每个组件上重复声明。键为 feature 实例名称,可以携带完整的 feature 类型 URI(允许使用点和斜杠)。键:一个或多个字母、数字、下划线、点、斜杠或连字符。模式:^[a-zA-Z0-9_./-]+$。 |
boundaries | boundary 映射 | 否 | 嵌套的逻辑边界(例如集群内的命名空间)。键:一个或多个字母、数字、下划线或连字符。不允许使用点。模式:^[a-zA-Z0-9_-]+$。 |
components | boundary_component 映射 | 否 | Aggregate 中哪些组件放置在此边界中。键为组件实例名称;子 aggregate 的组件通过其限定的点分路径寻址(例如 ‘data.main-db’——aggregate 实例名称、一个点、组件名称)。键:一个或多个字母、数字、下划线、点或连字符。模式:^[a-zA-Z0-9_.-]+$。 |
aggregates | map of aggregate_routing | 否 | 将嵌套 Aggregate 子模块的组件路由到此边界。键为 aggregate 实例名称,与 Aggregate 的 spec.aggregates 映射相匹配。如果定义了边界,则所有 aggregate 实例都必须恰好放置在一个边界中。键:一个或多个字母、数字、下划线或连字符。不允许使用点。模式:^[a-zA-Z0-9_-]+$。 |
不允许其他属性。
uses_block
结构拓扑——由开发者负责。声明逻辑网络边和依赖关系。
键: 一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。
值为 string[] or map of object。
不允许使用其他任何键。
inject_block
连接上的不可知注入路由。将本地变量映射到目标的 provides 键。每种交付机制(env、file、arg 或 custom)都编写为 {in, from} 条目的数组——provides 引用使用显式的 ‘from’。自定义机制可以使用除 all 之外的任何名称:模板会在 .context.inject.all 读取合并为一个视图的所有机制,因此同名的机制会被该视图遮蔽,命名这样的机制会使构建中止。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
env | inject_delivery | 否 | 单个交付机制,编写为条目数组。每个条目携带一个 ‘in’(本地标识符——环境变量名、文件路径、参数标志或自定义机制专用的键),外加 ‘from’(要解析的 provides 键)与 ‘value’ 中的恰好一个。在 Release 上,每个条目都位于某个连接上,因此 ‘from’ 针对目标的 provides 进行解析,携带 ‘value’ 的条目会被拒绝。 |
file | inject_delivery | 否 | 单个交付机制,编写为条目数组。每个条目携带一个 ‘in’(本地标识符——环境变量名、文件路径、参数标志或自定义机制专用的键),外加 ‘from’(要解析的 provides 键)与 ‘value’ 中的恰好一个。在 Release 上,每个条目都位于某个连接上,因此 ‘from’ 针对目标的 provides 进行解析,携带 ‘value’ 的条目会被拒绝。 |
arg | inject_delivery | 否 | 单个交付机制,编写为条目数组。每个条目携带一个 ‘in’(本地标识符——环境变量名、文件路径、参数标志或自定义机制专用的键),外加 ‘from’(要解析的 provides 键)与 ‘value’ 中的恰好一个。在 Release 上,每个条目都位于某个连接上,因此 ‘from’ 针对目标的 provides 进行解析,携带 ‘value’ 的条目会被拒绝。 |
inject_delivery
单个交付机制,编写为条目数组。每个条目携带一个 ‘in’(本地标识符——环境变量名、文件路径、参数标志或自定义机制专用的键),外加 ‘from’(要解析的 provides 键)与 ‘value’ 中的恰好一个。在 Release 上,每个条目都位于某个连接上,因此 ‘from’ 针对目标的 provides 进行解析,携带 ‘value’ 的条目会被拒绝。
类型: object[]