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

Release

Release 实体的概念角色(领域 4:将 Aggregate 绑定到 Manifest、并把组件映射到物理边界的部署路由器)见 architecture/04-entity-taxonomy.md。时序编排机制(按边界的 syncWave)、动态寻址 Polyfill 以及参数提升模式见 architecture/12-day-two-lifecycles.md。本页介绍 Release 的编写方式。

Release 的角色

Release 将一个 aggregate 绑定到一个 manifest,并将各组件映射到物理部署边界(例如 aws-eks-production)。它是编译的唯一入口:aggrega build --release release.yaml。

Release 通过严格地将物理现实注入 parameters 块来履行抽象的 aggregate 契约,并通过 infra 并行命名空间注入物理规格(如 CPU 或端口)。

每个 Release 都声明一个 manifest: 字段,指明其 Manifest(除非该 Release 使用 extends:,此时继承父级的 manifest 指针)。aggrega build CLI 直接读取该字段;不存在 --manifest CLI 标志,因此依赖规范与 Release 本身一同提交到 Git,使部署历史可以通过 Release 自身的 Git 历史进行审计。

aggregate: 和 manifest: 字段按标识或按相对路径文件解析,与语言其余部分解析引用的方式相同——绝不会作为相对于 release 的文件名词干解析。./ 或 ../ 值是显式的本地文件,直接相对于 Release 读取。裸标记是一个标识——即被引用实体的 metadata.name。manifest: 标识通过扫描 Release 自身所在目录解析(Manifest 是部署侧的运维配置,因此没有 catalog 或 registry 层级)。aggregate: 标识则通过完整的级联解析——先是 Release 所在目录,然后是 catalog,再是 registry——因此 Release 可以按标识引用已发布的 Aggregate,并且无论同一个已发布模块是 Release 顶层的 spec.aggregate,还是另一个 Aggregate 中的子 aggregate,它都会被解析。这种“标识或路径”模型使一个共享的 Aggregate 可以支撑多个 Release 变体,而无需将引用与文件名耦合,也使已发布的 Aggregate 可以直接按名称部署。

路径必须留在工作区内。 ./ 或 ../ 值指向工作区中的文件,Release 写下的其他所有路径也是如此——即下文的 extends: 和 parameters 的 $import:。按其写法会爬出工作区的路径,或途中被符号链接带出工作区的路径,都会在读取其所指文件的任何内容之前被拒绝。要部署保存在工作区之外的 Aggregate,请按标识引用它,并在工作区配置中将存放它的目录列为 catalog 目录;Manifest、extends: 所指的 Release 以及 parameters 文件都在 Release 旁边读取,从不按名称查找,因此它们应保存在工作区内。你在命令行中指定的、或工作区配置所指定的、位于工作区之外的 Release 自成一个根:它写下的每个路径——以及其 extends: 链所通向的 Release 写下的每个路径——都必须指向存放该 Release 的目录内的文件,爬出该目录或被链接带出该目录的路径同样会被拒绝。请将此类 Release 所引用的内容放在它旁边,或在同时包含两者的工作区中构建它。参见 errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside(对另一文件的引用指向了它必须留在其中的目录之外)”。

Release 决定编译产物的目标位置;provider 分派则属于该 Release 所指向的 Manifest(角色划分参见 Manifest 与 Release:关注点分离)。

环境元数据

每个 Release 的 metadata 块都接受一个 environment: 字段——一个标识该 Release 所部署到的环境的自由格式字符串(典型值:production、staging、dev)。该字段仅供参考:除 type: string 之外,它没有枚举、没有 schema 级模式,也没有跨实体校验。编译器会将其值作为 aggrega.ai/environment 标签,输出到 helm provider 渲染的每个 Kubernetes 清单上,与 Aggrega 其余的来源标签套件一起——若该值是有效的 Kubernetes 标签值,则按原样写入,否则改写为有效的标签值,并以 aggrega.ai/environment 注解携带确切的原值(因此 eu/prod 的标签为 eu-prod);helm-chart provider 会为它放入子 chart 的每个通过 $import: 加载的制品添加相同的标签,而子 chart 自身的模板则保留其作者所写的内容。compose provider 会在其输出的每个服务上,以 aggrega.ai/environment 标签携带同一个值。

编写 environment: 时有五种实用模式:

  1. OTel/FinOps 成本归因。 云成本仪表板(AWS Cost Explorer、Datadog Cloud Cost Management、CloudHealth)按环境对 Kubernetes pod 进行标签过滤。aggrega.ai/environment: production 标签通过 Helm provider 的标签注入流入 pod 标签;成本报告按 aggrega.ai/environment 对支出分组,无需逐个资源手动打标签。

  2. OTel 追踪与日志过滤。 可观测性仪表板(Datadog、New Relic、Honeycomb、Grafana Tempo)按环境标签过滤遥测数据。aggrega.ai/environment: staging 让运维人员可以将日志查询和追踪查找限定在 staging 范围内,而无需依据命名空间约定或 chart 名称过滤——在整个渲染产物中只用一个规范标签。

  3. Kubernetes operator 定位。 GitOps 控制器(ArgoCD、Flux)和策略 operator(Kyverno、OPA Gatekeeper)有时会按环境标签过滤资源,以实施特定于环境的策略(例如,“仅限 production 的资源必须带有 approved-image-source 标签”)。aggrega.ai/environment 标签提供了一个稳定的选择器,有别于命名空间约定或命名模式。

  4. 多区域生产环境区分。 一个团队同时运行 production-us-east Release 和 production-eu-west Release——两者都设置了 metadata.environment: production——会在各区域获得相同的 aggrega.ai/environment: production 标签。结合单独的区域标签,即可实现跨区域成本汇总(“生产环境总支出”)和按区域下钻。

  5. 合规范围界定。 SOC 2、PCI 和 HIPAA 的证据收集按环境界定范围(仅限生产环境的审计等)。合规证据收集工具(Vanta、Drata)使用 aggrega.ai/environment 标签按审计范围过滤资源。

schema 要求每个 Release 都声明 environment:;该值仅供参考,编译器读取它只是为了写入 aggrega.ai/environment 标签。

Schema 级约束

两项结构性保证保护 Aggregate 作为唯一事实来源(Single Source of Truth)的地位:

  • 禁止 values:。 为保护 Aggregate 作为唯一事实来源的地位,Release schema 以机械方式禁止 values: 块——Operator 无法在 Release 中为任何 Component 或 Feature 声明 values。该禁令同样适用于 uses 边:Release 的逐边 uses 条目携带 infra 以及它在连接上写入的附加项,这些附加项同样携带 infra——从不携带 values(面向开发者的逐边 values,以及连接上附加项的 values,都保留在 Aggregate 中)。面向 Developer 的 values 的逐环境差异通过 参数提升(Parameter Hoisting) 实现:Developer 在 Aggregate 中暴露一个带类型的 parameters.* 字段,Component 的 values 模板引用它,再由 Release 为其环境填充该参数。关于明确表述的 schema 级禁令,参见 architecture/06-data-taxonomy-and-composition.md §8 约束 4。Release 的 uses 边接口——它可以配置和连接的内容——记录在下文的逐边连接配置中。
  • 拒绝 extends + aggregate:。 为防止无法追溯的“修改 aggregate”的 Releases,当 Release 使用 extends 时,Release schema 会拒绝声明 aggregate 指针。子 release 必须映射到与其父级完全相同的 Developer 意图。不过,manifest 变为可选,从而解锁“延迟绑定(Late Binding)”——允许 Operator 继承整个物理拓扑,同时精确替换 Manifest。

parameters: 块

Release 履行 Aggregate 声明的类型化参数契约。spec.parameters: 是编写入口:一个 YAML 映射,其键与 Aggregate 的 parameters.* 声明相对应,其值提供每个环境的具体取值。

# Aggregate declares the typed contract
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: my-app
version: 1.0.0
spec:
parameters:
db_size: { type: string, required: true }
timeout_seconds: { type: integer, default: 30 }
region: { type: string, enum: [us-east-1, eu-west-1], required: true }
# Release fulfills the contract for this environment
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
db_size: "100Gi"
timeout_seconds: 60
region: "us-east-1"

每个值都会在参数契约层通过 Aggregate 声明的 schema 检查;当 Release 省略必需参数(E0165,parameter-missing)或提供其槽位契约所拒绝的值(E0164,parameter-contract-violation)时,构建会中止。声明了 default: 的参数在 Release 省略该槽位时取默认值;类型化契约是唯一的编写词汇。

两种编写模式——按内容形态分派。 parameters: 接受内联 YAML 映射(模式 1,如上所示),或指向本地文件的单个 $import: 键(模式 2):

spec:
aggregate: my-app
manifest: prod-manifest
parameters:
$import: ./prod-parameters.yaml

相对的 $import: 路径从写入它的 Release 所在目录解析,无论命令从何处运行,因此命令行和编辑器读取的是同一个文件;绝对路径指明其自身位置。两者都必须指向工作区内的文件;对于工作区之外指定的 Release,则必须指向该 Release 所在目录内的文件。两种模式在此处互斥,并且只能导入单个文件。多文件参数分层属于 Release extends: 链的范畴:父 Release 提供一组基础参数,子 Release 按环境继承并覆盖。该模式参见下文的 Composite Release / extends: 继承。

parameters 与 infra 的边界。 parameters 承载开发者的认知意图,表达为 Aggregate 声明的类型化槽位,由 Release 履行。Release 上的 infra: 承载运维人员的物理规格(副本数、CPU/内存上下限、存储类),附加到特定组件或 Feature 附件上。parameters 通过 .parameters.X 流入 Aggregate 的 values: 模板;infra: 通过 .infra.X 流入 Recipe 的 valuesMapping: 模板。数据支柱分类参见 architecture/06-data-taxonomy-and-composition.md §3,参数在流水线中的生命周期参见 templates/parameters-context.md。

边界与默认作用域

Release 将组件分组到边界中——边界是物理部署单元,每个都有自己的输出目录和注解级联。单边界是常见情形,因此无需任何额外配置。

单一作用域(默认)。 直接在 spec.components: 下编写组件,并省略 boundaries: 块。编译器会将这些组件归入一个合成的 default 边界,其输出是扁平的——产物直接落在 dist/ 下(按 provider 划分,通过下文安全的 subDirectory 默认值:dist/compose/、dist/helm/……),路径中不含边界名称段。这是最简单的部署方式:对扁平的 Compose 或单集群目标执行 aggrega build,无需为边界命名。

spec:
aggregate: aggregate
manifest: manifest
components:
db:
infra:
engine_version: "11.4"
web:
infra:
port: 8080

多个作用域。 当一个 Release 跨越多个物理分组——不同的集群、区域或同步波次——时,在 boundaries: 下声明具名边界。每个边界都有自己的 directory:、注解级联和 syncWave:,组件在其所属边界内寻址。

互斥性。 在 Release 根级,spec.components: 与 spec.boundaries: 互斥——一个 Release 只编写其中之一,绝不同时编写两者。同时声明两者的文档会在加载时因信封错误而终止。顶层 components 接口承载的每组件运维结构与边界的 components 相同(infra:、annotations:、uses:)。

显式声明的名为 default 的边界。 扁平输出是合成的默认边界的属性,而非该名称的属性。在 boundaries: 下显式声明名为 default 的边界的 Release,该边界只是一个普通的具名边界:其输出遵循其 directory:(默认为 dist/boundaries/default/),与其他任何声明的边界完全相同。

有关默认作用域模式,请参阅 architecture/06-data-taxonomy-and-composition.md §7。

空间隔离与输出路径

每个 boundary 为其编译产物声明一个物理输出 directory;boundary 内的组件可通过逐组件的 subDirectory 覆盖它。编译器将两者拼接,计算出最终产物路径,在所有平台上都使用斜杠分隔的形式:Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory)))。

  • 一个目录,一种写法。 求值后的路径只规范化一次,因此 out/a、out//a、./out/a 和 out/a/ 是同一个目录。路径规范化后指向同一目录且通过同一 provider 渲染的 boundary 会被合并组装,与以相同路径书写的 boundary 完全一样。
  • 路径始终位于输出根目录之下。 跳出输出根目录的路径(..、../escape、a/../..)、绝对路径,或根本未指定目录的路径(为空,或规范化后即为输出根目录本身)会在写入任何内容之前终止构建。消息会指出该 Release、该 boundary、出错的字段(directory: 或 subDirectory:)及其求值结果,因为该值往往是模板的结果。
  • 安全默认值。 如果省略 subDirectory 或其为空,编译器会自动应用 subDirectory: "{{ .capability }}":每种渲染能力(Helm、Helm-chart、Compose、Terraform、CloudFormation)的产物都会落在各自的子文件夹中,避免在下游 CI/CD 工具中出现产物混杂的冲突。显式写出的 subDirectory: "" 与省略完全等同,因此同样采用此默认值。
  • 扁平覆盖。 要完全禁用子目录(所有产物直接位于 directory 之下),请设置 subDirectory: "."。求值为空字符串的 subDirectory 模板(例如 "{{ .parameters.sub }}" 且 sub 设为 "")同样会禁用子目录。
  • 模板变量。 directory 求值时可使用 {{ .capability }}、{{ .boundary_name }}、{{ .parameters.X }}、{{ .manifest.recipe_name }},以及用于从外层 boundary 级联数据的 {{ .parent_boundary.* }}。subDirectory 求值时可使用同一组变量,外加 {{ .component_id }}(仅限逐组件覆盖)。编译器以 missingkey=error 对路径模板求值:引用未声明的变量会以精确的诊断信息终止构建。各上下文的变量矩阵及父 boundary 级联规则,请参见路径模板变量。

Boundary 注解向下级联到其包含的每个组件;infra 严格局限于其所针对的组件。递归的 boundaries 映射允许任意嵌套(boundary 套 boundary 再套 boundary),而注解级联与 infra 局部性这两条不变式在每一层级都成立。

完整示例:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: spatial-release
version: 1.0.0
environment: production
spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
# Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`.
annotations:
"aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations
components:
api-server:
infra: { replicas: 5 } # Strictly local
aws-rds:
# Scenario B: Bespoke Enterprise Naming.
subDirectory: provisioning
postgres-db:
# Scenario C: The Flat Directory Override.
subDirectory: "." # not "", which takes the default

通过此机制级联的注解会经由 .context.annotations.release 出现在下游 Recipe 模板中;渲染器如何使用它们,请参见 Recipe 编写和模板展开矩阵。

结构化注解值。 当 Manifest 绑定为一个注解键声明了多条 infra 支柱路由路径时,Release 侧的注解值可以是一个结构化对象,在一次声明中为多个 Feature schema 字段提供值:

boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100
components:
api:
annotations:
feature.myco/db-pool:
max_connections: 200 # closer-level override
# pool_size not listed → inherits 20 from boundary

结构化值按子键深度合并进行级联;更近层级的子键覆盖父级子键。逐子键的 null 可退出单个子键,而同级子键保持不变。Release 侧只生效绑定映射支柱为 infra 的子键;路由到 values 的子键应写在 Aggregate 侧注解中。有关结构化值的完整说明(跨侧组合、逐子键类型校验、宽松默认值原则),请参见 providers/well-known-annotations.md §“Structured annotation values”。

知名注解。 除临时自定义键外,Aggrega 标准库在 aggrega.ai/ 和 feature.aggrega.ai/ 命名空间下定义了一组知名注解,分为放置、网络、安全和可观测性几类。为 Release boundary 添加注解的作者应查阅 providers/well-known-annotations.md,了解完整矩阵及各 provider 的使用规则:该页面说明了哪些 provider 会应用每个知名键,以及该键存在时它们会产生何种行为。

逐边连接配置

边界中的组件可以携带一个 uses: 块,用于在该 Component 的目录 usesSchema 所声明的插槽范围内配置或连接拓扑边。这是运维人员逐连接配置的入口,其范围受到限制,以便开发者保留对自己所编写架构的所有权:

  • 配置已有的边。 在开发者已声明的边上设置逐边 infra。该条目指明开发者的别名并提供 infra;它要么指明与开发者所连接的相同目标,要么省略目标。infra 会依据插槽的 infraSchema 进行校验。
  • 连接未绑定的插槽。 在 Component 的 usesSchema 已声明但开发者未连接的插槽中创建一条边,指向一个已有的组件。所创建的边也可以携带逐边 infra。
  • 在连接上附加。 在条目的 features: 下携带附加项,以插槽在其 featuresSchema 中声明的槽位为键——即开发者的连接条目所填充的那些槽位。每个附加项携带 type、可选的 description 和 infra,从不携带 values。在开发者已于同一连接上填充的槽位下,该条目用于确定该附加项的规格:只写 infra,因为类型和值来自 Aggregate(此处写的 type 必须与 Aggregate 中的一致,否则构建会在此条目处中止,并指出两者)。在开发者留空的槽位下,该附加项属于 Release 自身,且 type 为必需。无论哪种情况,该填充都受槽位的 selector 约束,并计入 required 槽位,与开发者的填充完全相同。

该入口遵循只创建、不重定向:Release 可以向未绑定的插槽添加边,但不能重定向开发者已声明的边。逐边条目若指明与开发者的边不同的目标,构建将中止;指明相同目标(或省略目标)的条目则配置该边。Release 也不能在边上或在其于该处写入的附加项上声明 values(面向开发者的值保留在 Aggregate 中),不能绑定 usesSchema 未声明的插槽,也不能让边指向不存在的组件——每一种都是致命中止。在所有边绘制完成后,若某条目在不存在的连接上设置 infra 或 features,同样会中止,除非消费组件已通过 active: false 关闭。参见 errors/fatal-halts.md §“When building the topology”。

另有三种中止确保连接的附加项留在其连接上:

  • 插槽未声明对应槽位的名称会中止,与在 Aggregate 的连接条目上完全相同,中止发生在 Release 中的此条目处,并列出插槽声明的槽位以及与该名称只差一处编辑的槽位。
  • 仅由 Release 创建且未写 type 的附加项会在连接条目处中止,并指出该槽位。Release 创建的附加项不携带 values,因此适用于其 values 不要求任何内容的 Feature;若其 schema 要求某个值,则会在同一条目处因缺少该值而中止。标准库中携带调用方定位符的凭据 Features 在 values 中不要求任何内容:每一个也都可以在 infra 中接收定位符(见下文)。
  • 在连接以外的任何位置写入组合名称会中止。连接附加项会成为消费组件的一个名为 <alias>.<slot> 的附加项(参见 Aggregate 的连接条目),而组件条目自身的 features: 键和边界的键都允许包含点号。若组件条目写入该名称,或边界写入该名称并使其到达某个连接携带该附加项的组件——放置在该边界或其内嵌边界中的组件,包括被路由子模块中的组件——则会中止并指出两种写法,每到达一个组件报告一次。插槽的槽位在每个连接上填充,绝不会由从更宽作用域级联而来的附加项填充。
spec:
components:
router:
uses:
models:
# Size the attachment the Aggregate declared on the "gpt" connection: infra only.
gpt:
features:
credential:
infra: { rotation: hourly }
# Attach on a connection the developer left without one: the type is required.
plain:
features:
credential:
type: core/generated-secret

Release 所连接的连接上的凭据在 infra 中指明其 secret。 Release 所连接的连接在 Aggregate 中没有条目,因此那里没有任何内容写入凭据的 values,而 Release 在任何地方都不写 values。因此,每个携带调用方定位符的标准库凭据 Feature——core/referenced-secret、core/referenced-secret-set、core/secret-value 和 core/secret-provided——都既在 values 中、也在 infra 中接收定位符:即 origin,对于 core/referenced-secret-set 则为 entries,在两个支柱中具有相同的结构和相同的 sensitive: true 声明。每种实现都会读取携带它的那个支柱。

spec:
components:
router:
uses:
models:
gpt:
target: gpt # wire the socket the developer left unbound
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a # the secret the operator names

每个附加项的定位符只能写在一个支柱中。若某附加项在两处都携带它——同一槽位上 Aggregate 的 values 和 Release 的 infra——或两处都不携带,则会在该 Feature 自身的断言(E0033)处中止,指出该 Feature、附加项和组件,并说明属于哪种情况。该规则属于这些 Features 的目录实体,而非编译器;编译器像评估任何 Feature 的断言一样评估它们的断言。定位符以外的字段保持其支柱:key 仍是 values 叶子,因此仅由 Release 创建的附加项读取该 Feature 的默认数据键 value。values: 禁令不变——运维人员的定位符属于 infra。

core/secret-provided 是唯一不适用于连接的:它发布其值,由附加项自身的 inject: 块交付,而连接的附加项在两份文档中都不携带 inject: 块,因此在连接上没有 inject: 块交付它。在那里请使用 core/referenced-secret 或 core/secret-value。

spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
components:
api-server:
uses:
databases:
# Configure the developer-declared edge "primary": add per-edge infra.
# The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget.
primary:
infra: { storage_class: fast-ssd }
caches:
# Wire an edge into the declared-but-unbound "caches" socket to an existing component.
main:
target: redis-prod
infra: { storage_class: standard }

解析后的逐边 infra 流入消费组件的渲染上下文,位于 .context.uses.<alias>.infra.<key>;它从不出现在目标组件的上下文中,因此目标的渲染输出不随配置指向它的边的消费者而变化。连接上的附加项同样落在消费组件上,作为其附加项之一:其 infra 与同一槽位上 Aggregate 的 values 合并,其 FeatureRecipe 基于两者进行渲染。消费组件的 Recipe 在其连接下读取它,位于 .context.uses.<alias>.features.<slot>,其 Workload 通过在槽位旁指明连接来交付它——参见交付连接所携带的凭据。

aggregates: 字段——将嵌套子模块路由到边界

当 Aggregate 通过 spec.aggregates: 声明嵌套子模块时,Release 通过在目标边界内与 components: 并列声明 aggregates:,决定每个子模块的组件落入哪个边界:

# Aggregate declares two sub-aggregates
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: platform
version: 1.0.0
spec:
aggregates:
finance:
type: finance-module:1.2.0
analytics:
type: analytics-module:2.0.0
components:
gateway:
type: core/ingress
---
# Release routes each sub-aggregate into a specific boundary
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: platform
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
aggregates:
finance: {}
components:
gateway: {}
us-prod:
directory: "deploy/us-prod"
aggregates:
analytics: {}

将 Aggregate.spec.aggregates: 下列出的每个子 aggregate 恰好放入一个边界。

路由放置的是组件。被路由子模块的每个组件都落入路由它的边界,并接受该边界的 directory、subDirectory、syncWave 和注解级联——与直接在 components: 下命名的组件获得的上下文相同,包括标记在生成产物上的 aggrega.ai/boundary-path 来源信息。因此,路由一个子模块,与用限定的点分路径以空主体逐一指定其每个组件,产生完全相同的产物;路由是更简短的写法,也是在不了解子模块内容时唯一的写法。

一个组件只属于一个边界,当文档将某个组件放置两次时,构建会中止——同一子模块被路由到两个边界、一个子模块被路由到一个边界而其某个组件在另一个边界中被命名,或一个组件既被直接命名又通过路由条目放置。诊断信息会给出两处位置,因为保留哪一处由作者决定。将子模块路由到某个边界,同时在同一边界下命名其某个组件,并不构成冲突:路由负责放置该组件,命名条目负责配置它。

**Release 未放置到任何位置的子 aggregate 会中止构建。**放置情况会综合两种写法来判断,因此只有当两种写法都未触及该子模块时构建才会中止:没有边界在 aggregates: 下路由它,也没有边界在 components: 下用限定的点分路径命名它的任何组件。任一写法单独即可放置它,而所有组件都被逐一命名的子模块不需要路由条目。修复应写在导入该子模块的 Aggregate 的 aggregates: 块中——对于直接导入的子模块,是 Release 部署的 Aggregate;对于嵌套的子模块,是执行导入的子模块自身的文档。诊断信息以导入文档所用的键来指出该条目,因此对于嵌套子模块,它显示的是本地名称而不是点分路径。

有两种情况有意不中止。不贡献任何组件的子模块无需放置。active: 开关解析为 false 的子模块从未被组合,因此它没有任何组件需要放置。

部分放置不会触发这条规则:只要子模块的任一组件进入边界,该子模块即视为已放置,因此命名其中一个组件就满足了该子模块。但这并不意味着其余组件可以略去。边界未命名的每个组件此时都没有被任何东西放置,下面的组件规则会在其自身的键处报告它——因此部分放置的子模块会为它遗漏的每个组件各中止一次构建,而不是在子模块处中止。用一行放置整个子模块的两种写法是路由条目和命名每个组件;介于两者之间的写法只放置它所命名的内容。

**Release 未放置到任何位置的组件同样会中止构建,这是更深一层的规则。**上面的规则检查子模块是否进入了边界;这条规则对组合中的每个组件做同样的检查。组件进入边界的方式是:在该边界的 components: 下被命名,或位于某个边界路由进来的子模块中。两者都不满足的组件会在 Release 声明的所有边界之外渲染,其 directory、subDirectory、syncWave、注解级联和逐组件 infra: 都无从获取——因此构建会停止并指出该组件,而不是生成边界配置从未触及的产物。

这两条规则通过考察组件所属的子模块来划分范围,而不仅仅是看组件是否属于某个子模块。Release 完全未放置的子模块中的组件交给子模块规则处理,该规则在 aggregates: 条目处将这一编写错误报告一次,而不是为模块中的每个组件各报告一次。Release 部分放置的子模块中的组件归本规则处理,因为子模块规则将这样的模块视为已放置,不会对其报告——因此边界未命名的每个组件都在此处报告,位置是声明它的文档中它自身的键。因此,部分放置子模块时,被命名的恰好是你想命名的内容,而你未命名的每个组件都会被告知。

**此外,边界条目若命名了所部署 Aggregate 中不存在的组件,也会中止构建。**上面两条规则从组件一侧判断放置——是否有东西放置了它。这条规则从 Release 一侧判断:名称能否解析。解析不到任何内容的条目什么也不放置,因此它的 subDirectory、注解、逐组件 infra: 和 uses: 配置的是一个不存在的组件,构建会停止,而不是生成该条目从未触及的部署。两种写法都会检查:边界 components: 下的名称按组合完成后组件所带的 id 解析,路由条目 components: 下的名称按组件在该子模块内的本地名称解析。诊断信息报告条目所指向的 id,在路由写法下它不是文件中的名称——文件写的是本地部分,前缀由子模块提供。

名称被拒绝只是因为解析不到任何内容,而绝不是因为其形式:点分名称很常见,因为深入一层模块的组件带有该模块的前缀。active: 开关解析为 false 的组件仍可被命名——关闭一个组件不需要修改配置它的 Release。

**子系统不会为限定路径增加任何内容,因此无论 Aggregate 如何分组,边界都用组件的裸名称来指定它。**只有子模块组合会限定 id。所部署 Aggregate 中的组件,无论作者将其写在顶层还是名为 data 的子系统中,都是 store;深入一层模块的组件是 data.store,其中的 data 是模块的前缀,而不是任何子系统的名称。因此,对于位于名为 data 的子系统中的组件,写作 data.store 的边界条目指向不到任何内容:该条目本身会按上面的规则中止,它原本要指向的组件也未进入任何边界。将条目改为 store 即可同时解决这两个问题。

因此,放置子模块需要 boundaries:。单作用域形式没有路由入口——aggregates: 是边界的键,而不是 spec: 的键——且顶层 components: 映射只接受非限定名称,因此部署导入了子模块的 Aggregate 的 Release 需要声明 boundaries:。

递归路由。aggregates: 是递归的——边界 aggregates: 下的每个条目本身都可以声明一个嵌套的 aggregates: 映射,用于深度嵌套的模块组合。

**逐 aggregate 路由块。**路由条目只接受两个键,不接受其他任何键:components:,用于配置该子模块的各个组件;以及嵌套的 aggregates:,用于更深层嵌套的模块。annotations: 属于边界,逐组件 infra: 属于路由条目自身 components: 下的条目。

在路由条目内,组件以它在其子模块内的名称为键——consumer,而不是 data.consumer——因为这是它在那里唯一的名称。限定的点分路径是边界自身的 components: 映射指定同一组件的方式;这两种写法不可互换,路由条目会拒绝点分键。

boundaries:
eu-prod:
directory: "deploy/eu-prod"
annotations:
aggrega.ai/namespace: "finance-zone"
aggregates:
finance:
components:
ledger: # the component's name inside the finance module
infra:
replicas: 3
aggregates:
reporting: {} # a module nested inside finance

子 aggregate 自身的组件和 Features 不会在 Release 中重新声明——Release 路由它们而不是重述它们,只有在需要配置某个组件时才命名它。

时间顺序——按边界设置的 syncWave

Release 中的每个边界都可以选择声明一个整数字段 syncWave:,让 Operator 无需改动 Developer 的 Aggregate 即可显式控制部署顺序。波次编号是边界本身的属性;在产物输出时,边界子树中包含的每个组件都继承其所在边界的波次值。

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
boundaries:
infra:
directory: "deploy/infra"
syncWave: 0
components:
core-vpc: {}
postgres-db: {}
migrations:
directory: "deploy/migrations"
syncWave: 1
components:
db-migration-task: {}
apps:
directory: "deploy/apps"
syncWave: 2
components:
web-server: {}
ai-agent: {}

波次值语义。 syncWave: 是有符号整数(正数、零或负数)。省略该字段时默认值为 0。波次值不会从父边界继承——每个需要非默认波次的边界都要显式声明。Components 不能覆盖其边界的波次(波次是空间单元的属性,而不是单个组件的属性)。

按 provider 输出。 编译器以 provider 原生的形式将边界的波次值输出到渲染结果中。下文详细说明其中三种形式;波次在每个标准库 provider(包括 terraform)上的作用,列于 providers/reference-matrix.md 的“What a boundary’s syncWave does on each provider”一表中。

  • Kubernetes(helm / helm-chart provider)。 当波次不为 0 时,helm provider 为该边界渲染的每个 Kubernetes 资源都带有 GitOps 标准的 argocd.argoproj.io/sync-wave: "<N>" 注解;Helm 钩子还额外带有 helm.sh/hook-weight: "<N>" 注解,使同一个波次值也驱动 Helm 自身的 pre/post-install 顺序。ArgoCD 读取 sync-wave 注解,Helm 读取钩子的权重,二者各自据此安排资源的应用顺序。helm-chart provider 按源 chart 的模板作者所写的原样复制这些模板,因此子 chart 自身的资源只有在这些模板写入了波次时才会带有它;helm-chart provider 添加的通过 $import: 加载的制品带有 argocd.argoproj.io/sync-wave,但不带 helm.sh/hook-weight(参见 providers/helm-chart.md)。
  • Compose。 边界渲染进的 compose 文件中的每个服务,都会通过 depends_on 等待紧邻前一波次中向同一文件贡献的服务——若目标声明了 healthcheck,则以目标的健康状态为条件,否则以其启动为条件。因此,波次只对同一文件中的服务排序,不涉及文件之外的任何内容:渲染到不同 docker-compose.yaml 文件的边界属于不同的 compose 项目,对它们的排序由运维人员负责。uses: 边继续与波次一起表达按边的顺序。参见 providers/compose.md。
  • CloudFormation。 组装后的栈模板中的每个资源,都会通过 DependsOn 依赖紧邻前一波次中向同一个栈贡献的资源——因此波次决定了资源的创建顺序,并反向决定其删除顺序。这不是就绪顺序:栈模板中没有资源可用这一概念。片段自身的 DependsOn 会被扩展而不是被替换。组装到其他栈中的 Components 不在作用范围内,两个栈之间的排序由运维人员负责。参见 providers/cloudformation.md。

波次编写单元与可部署单元。 边界是波次编写单元。可部署单元是组件输出到的组装路径——默认与边界一一对应,但共享同一 directory: 的两个同级边界会合并为一个组装输出(一个 Chart.yaml、一个 docker-compose.yaml)。此时,组装输出中可能包含来自多个波次的资源;读取该输出的 ArgoCD Application 会在该 Application 内按每个资源自身所带的 sync-wave 注解为其排序——在 helm 上,这是为非零波次渲染的每个资源;在 helm-chart 上,则只有通过 $import: 加载的制品,子 chart 自身的模板保留其作者所写的内容。跨路径的 Application 之间的排序由运维人员的 CI 负责。

使用场景。 只要一个边界的启动依赖于另一个边界先完成,波次顺序就很重要。典型模式:波次 0 的 infra 边界(VPC + 数据库)、波次 1 的 migrations 边界(schema 迁移作业),以及波次 2 的 apps 边界(使用迁移后 schema 的应用)。如果没有显式波次,这三者会并发部署,应用在等待迁移完成期间会反复崩溃重启。

完整的架构阐述——DAG 执行模型、将时间顺序放在 Release 而非 Aggregate 上的理由,以及波次编写单元与可部署单元的区别——参见 architecture/12-day-two-lifecycles.md §1。

Feature 挂载

Release 既可以在 boundary 范围(宽泛策略)挂载 Features,也可以在特定 component 范围(精确定位)挂载,其执行遵循 architecture/10-compilation-pipeline.md 中定义的五层洋葱模型。在 Release 中声明的 Features 提供 type、infra 和 uses;它们不能声明 values(参见上文的 Schema 级约束)。

挂载在 boundary 上的 Feature 以你选定的实例名作为键,该名称不能是 . 或 ..。在为每个贡献者提供独立目录的 provider 上——terraform 位于 modules/ 下,helm-chart 位于 charts/ 下——boundary 级 Feature 的文件会写入仅以实例名命名的目录,而这两个名称都不构成独立目录:构建会停止,并指出该 Release、boundary 和实例。仅包含点号的名称(例如 audit.v2)是普通名称。

features: 是 Release 在两种范围内唯一的挂载入口——与 Aggregate 相同。凭据是带有 feature.aggrega.ai/kind: secret 标签的 Feature,因此由 Operator 挂载的凭据与其他任何 Feature 一样挂载在 features: 下,并在 infra 中指定其 secret,方式与连接上的凭据完全相同(参见逐边连接配置)——可以挂载在 Aggregate 未提供凭据的 component 上,也可以作为 Aggregate 声明但未指定 secret 的挂载的规格设定。任何范围内都不存在第二个挂载关键字;声明了这种关键字的文档会在加载时被拒绝,并给出指出该意外属性的 envelope 错误。

在整个 boundary 范围挂载的 feature 可以带有 uses: 块,该块会投射到路由进该 boundary 的每个 component:每个 component 都会获得一条指向该 feature 所指定目标的依赖边,并被注入这些目标的 provides。这样只需在 boundary 上声明一次共享依赖——“此 boundary 中的每个 component 都与共享缓存 / 采集器 / 消息总线通信”——而不必在每个 component 上重复同一条 uses: 边。Aggregate 中子系统级的 Feature 挂载也以同样方式将其 uses: 投射到该子系统的各个 component。uses 是拓扑连接声明,而不是值,因此允许在 Release 上使用。该投射与所挂载 Feature 的执行范围无关:即使某个 Feature 的 FeatureRecipe 每个 boundary 只渲染一次,它仍会按 component 投射其 uses:,而共享资源本身只渲染一次。

挂载到单个 component 的 feature 带有相同的 uses: 块,并从该 component 连接同样的边:该 component 获得指向每个指定目标的依赖边,被注入这些目标的 provides,且该边将此挂载记录为其来源,与整个 boundary 范围的形式完全相同。两者是同一声明的两种覆盖范围——挂载在 boundary 上以连接其中的每个 component,挂载在 component 上以只连接该 component——二者之间的选择只关乎覆盖范围,而与连接的作用无关。两者都不会创建计算资源:目标必须已经指向 Aggregate 声明的某个 component,否则构建会中止。Feature 所连接的连接本身不带任何挂载:其条目接受 target 和 inject,而其中的 features: 键会在 Release 加载时被拒绝。

boundaries:
cluster:
directory: ./dist/cluster
components:
api:
features:
shared_backend:
type: core/shared-backend
uses:
backend:
primary:
target: db # a component of the assembled graph
inject:
env:
- in: DB_HOST
from: host # db's `host` provides reaches api as DB_HOST
db: {}

目标的写法。 边的目标指向组装后图中的一个 component,因此只要目标属于已路由的子模块,就要使用限定的点分路径来书写——写 data.store,而不是 store。即使挂载本身位于某个路由条目之下(其 components: 键是模块本地的),这一点也同样成立:键表示挂载位于哪个 component 上,目标表示边到达哪个 component,只有后者是全图范围的名称。使用模块本地名称书写的目标不会匹配任何 component,并以与任何悬空边相同的诊断中止。

复合 Release 与 extends: 继承

Release 可以声明 spec.extends:,指向一个基础 Release,并继承其编写面。

引用是指向声明它的 Release 旁边某个文件的路径——./base-release.yaml 或 ../shared/base-release.yaml。Release 属于部署侧,不被目录索引,因此 extends: 引用从不通过目录解析。相对路径是它接受的唯一形式:写成注册表坐标的引用会被拒绝,裸名称同样会被拒绝,诊断信息中都会指出相对路径形式。Manifest 的 extends: 是与之相近但读法不同的情形——它接受相对路径或 Release 旁边某个 Manifest 的裸 metadata.name——因此两种形式不可互换,能在 Manifest 上解析的裸名称在这里无法解析。链中的每一环都以同样方式读取:保存在其他目录中的父 Release 通过其自身旁边的路径指定它自己的父级,无论你指定的 Release 位于何处,正如其 parameters 的 $import: 是在它旁边解析的一样。该路径必须指向工作区内的 Release,正如 Release 写出的每个路径都必须如此——或者,对于在工作区之外指定的 Release,必须位于存放该 Release 的目录内,其链中的每一环都受此约束:向外越出的路径,或被某一环带出的路径,会在读取其所指文件之前被拒绝。

编译器在加载 Release 时沿链追踪——拒绝回到链中已有文件的链、超出深度上限的链,以及不指向任何内容的引用——然后将整条链折叠为单个已解析的 Release。

继承的内容可以逐键替换。 你的值逐层优先,直到遇到一个不可分割的值——标量、列表、模板——你要么整体采用,要么整体替换。将继承的内容写为 null 即可移除它。扩展的 Component、Feature 和 Manifest 遵循同一规则,因此作者掌握其中一个,也就掌握了全部。

应用到 Release 上:boundaries 按边界名称组合,边界内按键组合;components 按组件名称组合;infra 深度组合;features 按实例名称、再按支柱组合;组件的 uses 按插槽、再按连接组合,其中子级写出的 target 替换继承的值,连接的 infra 逐键组合,其 features 按插槽、再按支柱组合,规则与组件自身的 features 相同;directory、subDirectory、syncWave 以及 Aggregate 和 Manifest 指针都是标量,直接替换。

有两项不会传递:

  • 身份与来源。 任何 metadata 字段都不会被继承。需要了解的是 metadata.environment:每个 Release 都必须提供它,且它本质上属于单个 Release,因此子级在其来源标签中使用自己的环境,而非父级的环境进行渲染。
  • Aggregate 指针被继承,而不可覆盖。 子级不能声明 aggregate:——schema 拒绝在同一文档中同时出现 extends: 和 aggregate:——因此子级部署的是与其基础相同的开发者意图(Developer Intent)。

子级可以省略 manifest: 以继承基础的设置,也可以为延迟绑定(Late Binding)覆盖它。

整条链使用同一种路由形态。 boundaries: 和 components: 在单个 Release 中互斥,这在整条链中同样成立:基础声明命名边界而子级声明顶层组件的情况会被拒绝,诊断信息会指出两个文件和两个键。选定一种路由形态,并贯穿始终。

本地开发桥接模式。 典型用例是开发者在本地运行其团队的生产 Aggregate,而无需 fork 该 Aggregate 或复制边界拓扑。团队发布一个生产 Release;本地 Release 通过 extends: 继承它,只覆盖 Manifest 指针,将面向云的 Recipes 替换为本地等价物:

# production Release (committed; the source of truth for prod deployments)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
environment: production
version: "1.0.0"
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
region: us-east-1
db_size: 100Gi
out_dir: prod
boundaries:
prod:
# A directory is a TEMPLATE, not a fixed path. Writing it against a
# parameter is what lets a child render somewhere else without
# restating the boundary topology.
directory: deploy/{{ .parameters.out_dir }}
components:
api: { infra: { replicas: 5 } }
db: {}
---
# Local Release (developer-side; inherits everything, swaps the Manifest)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: local-release
environment: local
version: "1.0.0"
spec:
extends: ./prod-release.yaml
manifest: local-manifest # surgically overrides for local
parameters:
region: dev-local
db_size: 1Gi
out_dir: local # the inherited directory resolves here instead

local-release 继承其基础的边界拓扑、Feature 挂载和组件覆盖;开发者只需维护一个 local-release.yaml,并运行 aggrega build --release local-release.yaml,无需复制任何生产配置。

基于参数编写 directory:。 由于目录与其他标量一样被继承,继承了不含模板变量的目录的子级会渲染到与其基础相同的路径,且没有命令行选项能够重定向它。如果这正是你的本意——例如只替换 Recipes 以比较其输出——这是合理的,因此构建会报告这一情况并继续,而不是拒绝。像上文那样基于参数编写目录,既能将拓扑保持在一处,又能让每个 Release 的输出去往各自的位置。

多文件参数分层。 Release 继承是多文件参数分层的归宿。基础 Release 提供通用参数集;各环境的子级通过 extends: 继承基础,并覆盖不同的槽位:

# base-release.yaml — common parameters
spec:
aggregate: my-app
parameters:
timeout_seconds: 30
feature_flags: { dark_mode: true }
---
# prod-release.yaml
spec:
extends: ./base-release.yaml
manifest: prod-manifest
parameters:
feature_flags: { dark_mode: false } # override one nested key
---
# staging-release.yaml
spec:
extends: ./base-release.yaml
manifest: staging-manifest

每个子级看到的是其基础继承的参数与自身参数合并后的结果。映射值参数深度合并,子级键优先;标量值参数由子级替换;子级写为 null 的键会被移除,而不是被设为空值。

基础可以导入其参数,子级仍可覆盖单个键。 上文 parameters: 中描述的两种编写模式——内联,或单个 $import:——是针对单个文档的规则,而非针对整条链:链上的每个 Release 各自声明其中一种模式,每个 Release 的导入都会在链折叠之前,相对于存放该 Release 的目录进行解析。因此,导入共享文件的基础与内联写出少量键的子级会逐键组合,与两个内联块完全相同:

# base-release.yaml — parameters arrive from a shared file beside it
spec:
aggregate: my-app
parameters:
$import: ./shared-params.yaml # tier: prod, region: eu
---
# local-release.yaml — overrides one key, inherits the rest
spec:
extends: ./base-release.yaml
manifest: local-manifest
parameters:
tier: local # region stays eu, from the imported file

错误模式。 循环的 extends: 链、缺失的父级指针以及子级中的 aggregate: 声明,都会使工作区加载停止,并给出明确的诊断信息,指出出错的 Release 及 schema 层面的违规。各错误的消息格式参见 errors/fatal-halts.md。