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

Component

Component 实体的概念角色(Domain 2 中抽象的计算节点接口)见 architecture/04-entity-taxonomy.md。本页介绍 Component 的编写接口:架构师用来在运维基础本体之上叠加认知身份的语义标签分类法、数据支柱的 schema: 声明、用于拓扑插槽和附加槽位的 usesSchema 与 featuresSchema 声明式表、存在性强制要求、extends: 继承机制,以及 assertions: 跨字段规则块。

语义标签分类法(标准库约定)

如果基础类型是纯云原生的,那么架构的运维智能和认知智能就完全通过语义鸭子类型来分层叠加。

核心 Go 编译器不解释这些标签。编译器构建扁平的中间表示(IR)图,而不解释标签的语义。这些标签代表标准库约定——由平台架构师在领域 2 中编写的不可变“遗传标记”。它们提供明确的语义挂钩,供 Wasm 策略验证器和物理运维 Recipes 用来治理架构。

(A) 通用云层 这些标签描述通用行为,使策略引擎和生成的 L7 代理无需原生理解 AI 框架即可治理标准的企业架构。

标签前缀允许的值(约定)平台运维为何需要它(策略挂钩)
tool.aggrega.ai/impactread-only, mutating使策略引擎能够评估最小权限授权(AuthZ)。具有变更操作的工具可以自动触发策略,要求挂接严格的审批门禁 sidecar。
datastore.aggrega.ai/enginerelational、document、kv、vector、graph、semantic-memory、search(值集合正随已填充的目录逐步稳定)使策略引擎能够强制执行跨节点类型安全(例如,阻止代理尝试向向量数据库发送 SQL 负载)。
gateway.aggrega.ai/intelligencesemantic, l4-mesh规定路由器在物理上能够支持哪些功能(例如,阻止按请求所指定的模型进行路由的 Feature(如回退链)挂接到标准 TCP 网格上)。
dataplane.aggrega.ai/request-mirroringfull-rate, sampled使将实时流量复制到第二个目标的 Feature 能够选择一个确实能复制流量的代理,并区分复制每个匹配请求的代理与可设置复制请求比例的代理。
dataplane.aggrega.ai/caller-identityclient-certificate, injected-header使需要向代理后方服务标识原始调用方的 Feature 能够选择一个可以传递该身份的 component,并读取由哪种机制传递它——转发客户端自身的 TLS 证书详情,或由代理在认证调用方后自行构造的请求头。
dataplane.aggrega.ai/content-maskingentity-recognition, pattern-list使屏蔽敏感文本的 Feature 能够选择一个 component,该 component 可以在其路由的聊天和补全负载中、在文本继续传输之前将其替换为占位符。值表示保真度:使用 entity-recognition 时,该 component 替换其配置中提供的模式的匹配项,以及它所调用的识别服务检测到的实体类型;使用 pattern-list 时,它仅替换其配置中提供的模式的匹配项,且不调用任何识别服务。
dataplane.aggrega.ai/prompt-guardpattern-list, classifier使筛查模型提示词的 Feature 能够选择一个 component,该 component 可以检查其路由的聊天和补全负载,并根据内容拒绝请求。值表示保真度:使用 pattern-list 时,匹配依据其配置中提供的模式,针对的是模型负载而非任意 HTTP 正文;使用 classifier 时,判定来自经过训练的文本分类器,通过该 component 调用的检测服务得出,并对照其配置中提供的阈值。
dataplane.aggrega.ai/upstream-tlstrust-anchor使要求代理核验通信对象身份的 Feature 能够选择一个 component,该 component 能够依据 Release 提供的信任锚验证上游的证书。
dataplane.aggrega.ai/upstream-pinningpublic-key使固定上游可出示哪个密钥的 Feature 能够选择一个 component,该 component 能够拒绝上游,除非其出示的证书携带 Release 提供的某个公钥。这是与 upstream-tls 不同的断言:固定(pin)说明证书必须是哪个密钥,锚(anchor)说明证书必须声明什么。
dataplane.aggrega.ai/period-budgetcost, tokens使限定流量在一段时间内可消耗量的 Feature 能够选择一个 component,该 component 能够在其于该时段内累计的量超过配置中设定的限额后拒绝模型请求。值表示它计量的内容:cost,即流量的花费,按该 component 为每个模型维护的价格表计价;tokens,即每个模型的回复所报告的读取、写入或两者的 token 数,该 component 只计数而不计价。
dataplane.aggrega.ai/concurrency-captotal, per-target使限制 component 同时承载请求数的 Feature 能够选择一个 component,该 component 能够在超过配置中设定的上限时挂起或拒绝请求。值表示一个上限所计量的内容:total,即该 component 转发的所有请求,对照一个上限;per-target,即发往其每个上游目标的在途请求,每个目标各有一个上限,而总数不设上限。

dataplane.aggrega.ai/ 键表示流量路径上的位置,而非 component 的种类,因此代理、入口网关和服务网格都用同一套词汇描述 自身,而不必各自拥有一套。该系列有两个 特性值得仔细阅读,因为两者都很容易被理解反:

  • **值承载的是保真度,而不只是该能力是否存在。**两个 component 可能都能镜像请求,却在某个 Feature 关心的方面仍有差异, 因此这种区别体现在值中,由 Feature 选择它所需的保真度。 提供更强保真度的 component 携带更强的值,且不携带其他值。
  • **值断言的是产品能够做什么,而绝不是某次部署 开启了什么。**两者读起来相似,但只有前者是 component 的属性。能够验证上游证书的代理携带 upstream-tls: trust-anchor,无论某次部署是否启用该 检查,因为标签是 Feature 在任何配置 之前用于选择的依据。

在这些维度之一上没有可描述内容的 component,在该维度上不携带任何值, 而不是携带最弱的值,这与分类法中的其他部分完全一致:缺失意味着该 维度在该 component 上没有对象,因此要求该维度上有任意值的 Feature 正确地不会挂接。

(B) 专用 AI 层(认知身份) 这些标签描述 workload 的认知身份,使架构能够保护现代 AI 框架。

标签前缀允许的值(约定)平台运维为何需要它(策略挂钩)
model.aggrega.ai/capabilitygenerative, embedding, transcription由 usesSchema 选择器字符串使用(由 Go 编译器在静态分析期间原生求值),以保证开发者不会意外地将生成式文本负载路由到嵌入端点。
model.aggrega.ai/apiopenai, anthropic, gemini, native表示在 component 所发布的地址上应答的是哪种模型 API:openai 表示 OpenAI API,无论是厂商自身的还是某个服务器对它的实现;anthropic 表示 Anthropic 的 Messages API,无论是厂商自身的还是某个服务器对它的实现;gemini 表示 Google 的 Gemini API;native 表示产品自身的 API,且不属于上述任何一种。每个模型 component 都携带该标签,能够提供模型 API 的网关也携带它,因此选择 component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api 的插槽接受模型或此类网关,并拒绝无法提供任何模型 API 的网关;而指定某个值的插槽,例如 model.aggrega.ai/api=anthropic,只接受提供该 API 的对象。它表示产品提供什么,而非某个 Release 连接了什么:模型连接到其自身插槽的网关,即使没有连接任何内容也携带该标签。该标签是选择器匹配的字符串;没有任何机制检查该地址上实际应答的是什么。
agent.aggrega.ai/autonomyautonomous, copilot标识认知循环的执行风险,使策略能够为完全自主的代理强制要求人工审批功能。

(C) 横切标签(治理、状态与硬件) 这些是驱动零信任验证和硬件路由的基础企业标签。

标签前缀允许的值(约定)平台运维为何需要它(策略挂钩)
component.aggrega.ai/hostingself-hosted, managed, external, mixed记录由谁运营 component 的底层资源——即信任边界维度。策略引擎读取它来计算数据外泄风险(例如,路由到 managed 第三方 API 的内部数据会离开运营方的边界)。横切性:同样的值同样适用于描述托管数据库、托管模型 API 和自行运行的推理服务器。mixed 标记其 Recipes 跨越不止一种运营方式的组件——例如一个数据存储,由其 Helm 和 Compose Recipes 自行托管运行,由其 RDS Recipes 托管——因此 Release 的运营方式取决于其 Manifest 所选择的 Recipe。
compliance.aggrega.ai/data-classpublic, internal, restricted组件所持数据的类别。编译器将其作为字符串带入构建图,不做任何排序;运维人员在 ir-verdict 角色上挂接的策略在其自身设置中为各类别规定顺序,并沿编译器枚举出的路由读取该标签——例如,当一个 restricted 组件到达另一类别的组件、而路由上未挂接任何降密 Feature 时,终止构建(policy-data-class-route)。没有任何标准库 Component 携带该标签:类别描述的是一个资产体系如何使用某个组件,由该资产体系自己的 Component 携带——例如通过 extends 进行的特化。
compliance.aggrega.ai/contains-piitrue, false明确标记属于 GDPR/CCPA 范围的工作负载。运维人员挂接的策略可以读取它,以要求此类工作负载流量所经路由上具备特定的 Features——例如,在其发送模型流量所经的 AI 网关上挂接 core/data-masking,这正是 policy-data-class-route 针对数据类别所检查的形态。没有任何标准库 Component 携带该标签;与数据类别一样,它是资产体系对其自身组件的声明。
hardware.aggrega.ai/acceleratorgpu, tpu, npu由 DevOps 在 Release 文件中使用。他们通过 components: {} 映射,将这些组件显式路由到物理硬件池边界(例如支持 GPU 的集群)中,而治理裁决角色可以强制要求带 GPU 标签的组件绝不被放入非 GPU 边界。
state.aggrega.ai/retentionretain, delete解决 AOT 删除缺口。 如果开发者从其 Aggregate 中删除了一个数据库,GitOps 编排器会物理删除磁盘。Recipe 的 pipeline: 步骤可以读取 retain 标签,并为渲染出的制品加入编排器原生的保护(例如 helm.sh/resource-policy: keep)。
state.aggrega.ai/backup-tiermission-critical, standard, ephemeralSOC2 可用性钩子。 告知运维 FeatureRecipe 是否为该资源实际生成自动化的快照/卷备份配置。

(D) 动态业务上下文(级联注解) labels 定义不可变的目录 DNA,而动态业务上下文(如 SOC2 审计范围划定或 FinOps 成本跟踪)则随部署应用的人和运行位置而变化。这些上下文由 Annotations 管控,它们由开发者的 subsystems、运维的 Release 边界或挂接在 annotation-transform 角色上的治理插件动态注入。

注解前缀允许的值(约定)平台运维为何需要它(策略挂钩)
business.aggrega.ai/cost-center例如 finance、ai-researchWasm 渲染插件需要它,以便将物理标记(例如 AWS 标签或 K8s 标签)注入最终生成的制品,供云账单仪表板使用。
business.aggrega.ai/owner例如 team-alpha@corp.com事件响应路由。保证基础设施映射到一个人员团队。
compliance.aggrega.ai/frameworks例如 soc2, hipaaSOC2 范围触发器。 通过环境 Release 注入。当应用进入生产合规边界时,Wasm 插件读取此字符串,自动生成严格的审计日志 sidecar 并禁用调试端口。

该分类体系是一种目录约定,而非编译器规则。企业可以忽略它、删除它,或自创标签词汇(mycompany.com/custom-trait)。Wasm 插件评估企业编写的任何标签键。

Schema 编写

Component schema(及其对应的 Feature,包括标记为 feature.aggrega.ai/kind: secret 的凭据 Features)通过 spec.schema: 块声明开发者编写的 values 的验证契约。该块接受 JSON Schema 2020-12,可以用紧凑形式的 YAML 简写表达(默认形式;约 15 个关键字,在编译时机械地转换为 JSON Schema),也可以用完整的 JSON Schema YAML 表达(冗长形式),并可通过 $ref: 进行跨文档引用,以使用在多个 Components 之间共享的 SchemaLibrary 条目。

  • **内联紧凑形式(默认编写方式):**直接在 Component YAML 中嵌入一个承载紧凑形式叶节点的 YAML 块。它能以完整 JSON Schema 行数的一小部分覆盖绝大多数目录 schema 内容。关键字词汇和编写约定参见 vocabulary/compact-form-authoring.md。
  • **内联 JSON Schema YAML:**冗长形式,适用于 schema 需要紧凑形式不直接支持的 JSON Schema 2020-12 关键字的情况($dynamicRef、深层 unevaluatedProperties、复杂的 not: 组合)。在单个 schema: 块内,可以通过 $jsonschema: 逃生舱口在任意节点边界混合使用紧凑形式和 JSON Schema。
  • **跨文档引用(指向 SchemaLibrary 条目的 $ref:):**一个 JSON Schema 原生的 $ref:,按标识指向某个 SchemaLibrary 条目(Datastores#/schemas/MariaDBValues 或类似形式)。长达数百行并在多个 Components 之间复用的企业 schema 存放在 SchemaLibrary 实体中;使用方 Component 引用该条目,而不内联其内容。库实体和解析语义参见 entities/schemalibrary.md 和 vocabulary/cross-document-ref.md。

上述三种形式用于编写支柱内容,可供不扩展任何基础的 Component 使用。声明了 extends: 的 Component 完全不编写支柱内容:它写入字面标记 schema: inherited,并原样接收其基础所编写的支柱块。在这样的 Component 上,该标记是 schema: 唯一可取的值。参见下文“目录编写:扩展基础 Components”。

在 Component 的验证阶段,编译器解析 schema: 块(展开紧凑形式、解引用 $ref: URL、应用 SchemaLibrary 库到库的链),并将得到的 JSON Schema 与由 usesSchema 和 featuresSchema 自动生成的基础(见下文相应章节)合并。验证针对解析后的 schema 进行;编写路径对下游流水线阶段不可见。

编写的实例在构建时根据此解析后的 schema 进行验证:组件实例中开发者编写的 values 和 Operator 解析出的 infra,以及任何 Feature 附加上的 values/infra,都必须符合声明的支柱——类型错误的值、超出范围的数字、不符合其声明 format 的字符串、缺失的必填字段,或(对于以封闭方式验证的 values)未声明的属性,都会在其编写源处使构建中止,而不是在部署时生成损坏的 manifest。如果某个支柱的 schema 指定了编译器不检查的 format——即 email、uri、hostname、ipv4、ipv6、uuid、date-time 和 date 之外的任何名称,包括 password——则在加载目录时被拒绝,并列出支持的名称;各名称检查的内容参见 vocabulary/compact-form-authoring.md。extends: 某个基础的 Component 的实例根据基础的支柱块进行验证,扩展方 Component 原样继承该支柱块——因此基础的实例与任何扩展它的实例面对相同的支柱契约。诊断信息和各支柱的规则(包括如何根据 Component 与 provider 的键并集验证 infra)参见 errors/fatal-halts.md §“Authored values or infra do not conform to the declared schema(编写的 values 或 infra 不符合声明的 schema)”。

**声明的默认值会具体化到渲染后的支柱中。**除验证之外,在 values 字段(或 infra 字段)上声明的 default: 会在构建时为作者省略的每个键填入渲染后的支柱——因此读取 {{ .values.charset }} 的 Recipe 模板会收到 schema 声明的 utf8mb4,而不是空值。作者提供的值始终优先;嵌套对象按每个省略的子项填充。由于具体化使用与验证相同的 schema 解析,通过跨文档 $ref: 引用到 SchemaLibrary 中的默认值也会具体化——无论是整个支柱的引用(values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}),还是基础加变体的形式(一个基础 $ref: 与同级 properties 并列,各自带有自己的默认值)。仅在本地文档内 #/$defs/ 引用中,或在 allOf / oneOf / anyOf 分支下声明的默认值不会具体化;标准库通过跨文档 $ref: 组合支柱,而这种方式会具体化。

values 支柱

Component schema 按所有权划分三个支柱:values 由 Developer 在 Aggregate 中填写(认知意图——数据库名称、版本、字符集),infra 由 Operator 在 Release 中填写(运维规格——计算、存储、HA),provides 由 Recipe 设置(公共 API 契约——主机、端口、协议)。Developer 永远看不到 infra;Operator 永远看不到 values。Recipes 在基础渲染期间使用这两个支柱,把抽象的支柱映射为其目标 provider 所期望的具体形态。本节介绍 values 支柱的编写方式。更广泛的支柱分类以及跨支柱级联规则,参见 vocabulary/data-pillars.md。

values 承载 Developer 的认知意图——描述应用是什么或做什么的选择,而不是它如何确定规格或如何运行。数据库名称、字符集、引擎版本、日志级别、功能开关,以及在应用版本之间变化但在各环境间保持稳定的应用层参数,都是典型的 values 内容。Operator 从不覆盖 values:(根据 architecture/06-data-taxonomy-and-composition.md §8 约束 4,Release schema 会机械地拒绝 values: 块);按环境的差异通过参数提升(Parameter Hoisting)传递——Aggregate 暴露带类型的 parameters.*,Component 的 values 模板引用它们,再由 Release 提供这些参数的值。

# Component schema declares the values shape:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] }
engine_version: { type: string, default: "10.11" }
log_level: { type: string, default: info, enum: [debug, info, warn, error] }
# Aggregate fragment — the developer fills values:
components:
customer-db:
type: core/datastore/mariadb
values:
database_name: customers
charset: utf8mb4
engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting
log_level: info

Recipe 侧的使用。 Recipes 在 valuesMapping:、provides:、assertions: 及其他模板位置中通过 .values.<field> 读取解析后的值——各模板的可用性矩阵参见 entities/recipe.md。编译器会把 Component 的 values schema 与同一 Component 节点上任何 Feature 附加项的 values: schema 合并,使解析后的模板上下文包含所有适用字段。

跨支柱规则。 values 是 Developer 在 Aggregate 中编写的唯一支柱。严格面向开发者的字段属于这里;运维参数(副本数、CPU/内存上下限)属于 Component 的 infra 支柱,从而位于 Release 中;公共输出(主机、端口)属于 Recipe 的 provides。混用这些会破坏所有权不变量;对于有意进行跨支柱传递确实合理的少数情况,参见 vocabulary/data-pillars.md 中的“跨支柱机制”。

infra 支柱

Component schema 按所有权划分三个支柱:values 由 Developer 在 Aggregate 中填写(认知意图——数据库名称、版本、字符集),infra 由 Operator 在 Release 中填写(运维规格——计算、存储、HA;数据存储的备份不在这里设定规格,而是 Operator 在 Release 中挂接的 core/backup Feature),provides 由 Recipe 设置(公共 API 契约——主机、端口、协议)。Developer 永远看不到 infra;Operator 永远看不到 values。Recipes 在基础渲染期间同时消费这两者,将抽象支柱映射为其目标 provider 期望的具体结构。

在标准库中每个与能力无关的 Component 上,有三条 infra 约定都很重要:用于 provider 专属参数的开放结构逃生舱口、用于上游制品版本的可选覆盖,以及用于高可用字段的基于意图的词汇。标准参考 Component 是标准库目录中的 core/datastore/mariadb——可由运行官方 mariadb 镜像、或将 MariaDB 自定义资源交给 mariadb-operator 控制器的 Helm Recipes,针对 AWS RDS 的 Terraform Recipes,针对同一 RDS 接口的 CloudFormation Recipes,以及针对本地容器的 Compose Recipes 实现——其 infra 块展示了第一种和第三种模式。

infra.overrides

通用 infra 字段——compute、storage、ha——涵盖了各 provider 的大部分运维规格。剩余部分本质上是 provider 专属的:Kubernetes Recipe 需要 nodeSelector,RDS Terraform Recipe 需要 instance_class,CloudFormation RDS Recipe 需要 DBInstanceClass,Compose Recipe 需要覆盖 image。Component schema 提供一个真正开放的映射作为逃生舱口,使这些参数得以传递而不会使 schema 膨胀:

infra:
# ... universal fields ...
# Provider-specific overrides. Accepts any nested structure.
# Each Recipe documents which keys it reads.
overrides:
type: object
additionalProperties: true # genuinely open map: arbitrary nested structure permitted

显式的 type: object 配合 additionalProperties: true 启用开放映射语义。编译器原样传递该结构;Recipe 的模板主体读取它认识的键并忽略其余部分。每个 Recipe 在其头部注释中记录覆盖键的体系,因此为特定 Component × Recipe 组合编写 Release 的 Operator 能知道该 Recipe 暴露了哪些参数。

使用 overrides 的 Release 片段:

components:
main-db:
infra:
compute: { cpu: "2", memory: 8Gi }
storage: { size: 40Gi, type: balanced-csi }
overrides:
nodeSelector:
kubernetes.io/hostname: cluster1-worker1
service_type: LoadBalancer
metrics:
enabled: true
image:
repository: bitnamilegacy/mysqld-exporter

Developer 永远看不到 overrides——它位于 Release 中,属于 Operator 的领域。

infra.source_version

Recipe 的 source 字段引用特定版本的上游制品(Helm chart 25.0.8、Terraform module 4.2.0、OCI 镜像标签)。在 Recipe 中硬编码版本,会迫使目录维护者在每次兼容的上游版本升级时发布新的 Recipe。Component schema 提供一个可选覆盖:

infra:
source_version:
type: string
description: |
Source artifact version. A Recipe versions its artifact from this key
where its source resolution reads it, and is unaffected where it does not.
Changing from the version a Recipe was authored against does not
guarantee value mapping compatibility.

Recipe 通过其 source 块中的 optional 辅助函数读取该值,因此 未固定版本时会回退到编写该 Recipe 时所针对的版本:

source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "{{ optional .infra `source_version` `25.0.8` }}"

Recipe source 字符串(以及结构化 source: 映射中的字符串值子字段)作为 Go 模板求值。远程坐标——例如上文的 version——在 aggrega pull 固定该制品时求值,依据 .values、.infra 和 .locals,没有 .context 根;指向工作区中某个路径的 source 在实体渲染时求值,其上下文与 Recipe locals 相同的自包含上下文——.context.instance_id、.values、.infra 以及该节点完整解析后的 .locals。两种情况下 .context.inject、.context.uses 和 .provides 均被禁止。正因该上下文中包含 .infra,上述覆盖才能生效;而 .locals 让 Recipe 可以一次计算出 source 片段并在此处读取。source 模板永远不会读取其自身节点的 provides:该支柱不属于此上下文,模板若尝试访问它会使构建中止——这是该接口的固定属性,而不是有待后续完善的缺口。完整的可用性规则参见模板展开矩阵第 5 行。将 infra.source_version 改为不同于 Recipe 默认值的版本,并不保证该 Recipe 的 valuesMapping 与新的上游版本在传输层面兼容;Component schema 中 source_version 声明的 description 带有这一警告。

infra.ha.*

高可用字段使用意图词汇,而不是机制词汇:

infra:
ha:
enabled: { type: boolean, default: false }
read_replicas: { type: integer, min: 0, default: 0 }

infra.ha.enabled 表示“让此 Component 高可用”,infra.ha.read_replicas 表示“我需要 N 个只读副本”。每个 Recipe 决定该意图在其 provider 上成为什么。core/datastore/mariadb 的标准库 Recipes,按 Manifest 映射它们时使用的名称列出:

Recipeha.enabled: true 映射为ha.read_replicas: N 映射为
helm/mariadb(基于官方 mariadb 镜像的 StatefulSet)只运行一个服务器,因此构建会中止并指出该键只运行一个服务器,因此 N 大于 0 会使构建中止
helm/mariadb-cluster(由 mariadb-operator 控制器协调的 MariaDB 自定义资源)开启自动故障转移(replication.primary.autoFailover: true);它会故障转移到只读副本,因此 N 为 0 会使构建中止将 spec.replicas 设为 N + 1 并开启复制;provides.host 变为 <name>-primary Service
terraform/mariadb-rds(AWS RDS)在主 aws_db_instance 上设置 multi_az = true创建 N 个独立的 aws_db_instance 只读副本资源
terraform/mariadb-rds-module、terraform/mariadb-rds-terraform-aws-modules(通过模块使用 AWS RDS)将 multi_az = true 传给该模块只预配一个实例,因此 N 大于 0 会使构建中止
cloudformation/mariadb-rds(AWS RDS)在 AWS::RDS::DBInstance 上设置 MultiAZ: true只预配一个实例,因此 N 大于 0 会使构建中止
compose/mariadb(本地开发容器)只运行一个服务器,因此构建会中止并指出该键只运行一个服务器,因此 N 大于 0 会使构建中止

机制词汇(infra.primary.replicas)对某一个 provider 而言很自然(Kubernetes pod 是 StatefulSet 的副本),在其他地方却是范畴错误——RDS 在主实例上没有“副本”概念,CloudFormation 与 RDS 一致,Compose 则完全没有水平副本抽象。意图词汇则可以转换:每个 provider 都有某种“让此数据库高可用”的概念和某种“我需要 N 个只读副本”的概念,而由 Recipe 承担针对各 provider 的转换。若某种实现没有这样的机制,其 Recipe 可以中止构建并指出该键,就像 helm/mariadb 和 compose/mariadb 对两个键所做的那样,以及单实例 RDS Recipes 对只读副本所做的那样。

infra.ha.read_replicas: 0 是默认值;两个键都取默认值时,helm/mariadb-cluster 渲染的是不带 replication 块的单实例 MariaDB,而不是基于单个实例的复制。compose/mariadb 在本地 Docker 主机上只运行一个服务器,因此 infra.ha.enabled: true 或非零的 infra.ha.read_replicas 会使构建中止并指出该键,消息会指向提供故障转移和只读副本的 helm/mariadb-cluster。

provides 支柱

provides 是由 Recipe 编写的公共 API:Component 解析后的 Recipe 通过下游调用方的 .context.uses.<alias>.provides.<provided-name> 接口(或者,当调用方在边上声明了 inject: 允许列表时,通过其 .context.inject 管道)向调用方提供的值。Component schema 声明其形状(键名及类型);绑定的 Recipe 的 provides: 块提供这些值。编写 Aggregate 的 Developer 在 Component 页面上看到的 provides 形状,就是调用方可以依赖的契约;Recipe 作者则为其所封装的具体实现履行该契约。

契约的履行以 Loud Guardrail 的方式强制执行:绑定的 Recipe 必须生成其 Component 声明的每一个 provides 键。如果绑定的 Recipe 遗漏了某个已声明的键,构建会中止并指出缺失的键,而不是静默地不向引用它的调用方交付任何内容。允许生成超出声明集合的额外键。编译器只检查键是否存在:生成的值是编译器原样传递的不透明字符串,因此其声明的类型仍是供调用方阅读的契约,而不是编译器会校验的值。

# Component schema declares the provides contract:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
provides:
host: { type: string }
port: { type: integer }
database: { type: string }
# Recipe fulfills the contract:
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "25.0.8"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
database: "{{ .values.database_name }}"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

先 provides 后 inject 的求值划分。 编译器在 provides 求值阶段,基于自包含的模板上下文(.context.instance_id、节点的 provider 报告了名称时的 .context.rendered_name、.values、.infra,以及同一节点上 Recipe 解析后的 locals:)对 provides: 模板求值,此时任何调用方状态都不可见。节点的 locals 在该阶段的前置步骤中解析,先于其 provides,因此 provides: 模板可以读取 .locals。在随后运行的 inject 注入阶段,编译器遍历 uses: 边,并依据已解析的 provides 值解析每个调用方的 .context.uses.<alias>.provides.<provided-name>。将两者分开可确保解析无环:provides: 无法引用调用方,而调用方的 inject: 在 inject 注入阶段运行之前,无法引用尚未解析的 provider 的输出。

契约演进。 重命名或删除 provides 字段,对每个依赖旧名称的调用方都是破坏性变更。Component 的 metadata.version(以及 Recipe 的 implements: 声明)承载契约演进的信号;固定到特定主版本的下游调用方会看到稳定的 provides 形状。

Recipe 侧的说明。 关于 provides: 模板的编写语法、各模板的可用性矩阵,以及跨命名空间和跨区域路由的完整示例,请参阅 entities/recipe.md 中的“The provides: block”和 architecture/06-data-taxonomy-and-composition.md §3。

存在性强制要求:features.aggrega.ai/requiredType.<label>

Component 可以声明其每个实例都必须带有某个给定 Feature 类型的附加项。这称为存在性强制要求(presence mandate),以可重复的注解形式写在 Component 自身的元数据上:

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/payment-processor
version: 1.0.0
labels:
component.aggrega.ai/type: server
annotations:
features.aggrega.ai/requiredType.audit: core/audit-logging
features.aggrega.ai/requiredType.compliance: core/pci-compliance
spec:
schema:
values:
processor_endpoint: { type: string, required: true }

键由前缀 features.aggrega.ai/requiredType. 加上你选择的标签构成;值是至少一个附加项必须带有的 Feature 类型 URI。标签用于在未满足的强制要求所产生的诊断中为该要求命名(如上例中的 audit 和 compliance),这就是它的全部作用。Component 通过带标签的键同时声明多个强制要求:注解是扁平的字符串映射,不能包含重复的键。

编译器针对实例的最终附加项集合评估每个强制要求,此时 5 层洋葱模型(5-Tier Onion Model)级联已合并所有作用域:Aggregate 的组件级和子系统级 features: 块、Release 的边界级和组件级 features: 块,以及由注解驱动的展开所产生的附加项。其中任何一个都能满足强制要求——该规则检查存在什么,从不关心它是如何来的。因此,一个仅因运维人员在 Release 中设置了监控注解而满足强制要求的 Component,与开发者手动附加该 Feature 的 Component 一样通过检查。

没有任何附加项满足的强制要求会使构建停止,并给出诊断,指明组件实例、该要求的标签以及所需类型。注解值是不透明字符串,因此在编译器读取之前不会校验其形式;所以,值不是 Feature 类型 URI,或键在前缀后没有标签,都会以一条单独的诊断停止,说明该声明格式有误。两者是有意区分的:错误的声明应在目录实体中修正,而未满足的要求应通过附加该 Feature 来解决——拼写错误绝不能被当作已满足的要求。

这两条诊断均记录在 errors/fatal-halts.md 的“Required feature not attached(未附加所需 Feature)”中。

强制要求不是插槽。 两者回答的是不同的问题,而且区别并非表面上的:

featuresSchema 插槽存在性强制要求
声明内容一个具名绑定点对必须存在之物的约束
名称可解引用是——from: <slot> 和 .features.<slot>.provides.*否——标签仅为要求命名,别无他用
基数每个插槽恰好填充一次至少一个该类型的附加项
约束填充项selector, inject, sensitive除类型外不作约束
可由自由附加项满足否——插槽按名称填充是——在任意作用域、以任意名称
需求未满足时当 required: true 且没有任何项绑定该插槽名称时停止当没有附加项带有该类型时停止

两种需求都针对同一输入(实例的最终附加项集合)进行检查,并各自以自己的诊断停止,因为它们对该输入提出的问题不同:一个是某个具名绑定点是否已绑定,另一个是是否有某个附加项带有指定类型。两者不能相互替代。

当 Recipe 需要读取所附加的内容时,使用插槽。当 Component 的契约要求某项能力必须存在、而不关心由哪个实例提供时,使用强制要求。强制要求 core/audit-logging 的支付处理 Component,无论开发者是否记得附加,在每次部署中都会获得审计日志;强制要求 core/pci-compliance 的 PCI 合规 Component,在部署中未于某处附加该合规 Feature 时便无法发布。

继承。 在基础 Component 上声明的强制要求会被每个 extends: 它的 Component 继承,因为元数据注解沿 extends 链合并,并按键以子级为准。因此,子级可以通过用不同类型重新声明同一标签来重定向继承的强制要求,或在新标签下添加自己的强制要求;但不能删除基础 Component 声明的强制要求。

拓扑插槽:usesSchema

Component 可以通过 usesSchema: 块声明拓扑插槽——这是一个与 featuresSchema 平行的声明式 YAML 映射。每个条目命名一个插槽,Component 通过该插槽接受跨组件依赖,并规定开发者可以将哪些形态的 Component 连接到该插槽。编译器根据声明的插槽自动生成 JSON Schema 2020-12 校验规则,并在 Component 解析期间将其与 Component 的 schema: 合并;开发者无需在 schema: 中手写 uses: 支柱,因为其结构来自 usesSchema。

# Component declares the sockets it accepts:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/ai-agent/orchestrator
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
primary_datastore:
required: true
selector: "datastore.aggrega.ai/engine=vector"
inject: [env]
cache:
required: false
selector: "datastore.aggrega.ai/engine=kv"
inject: [env, file]
log_destination:
required: false
selector: "component.aggrega.ai/category=messaging"
inject: []
# Aggregate fragment — developer wires the sockets:
components:
agent:
type: core/ai-agent/orchestrator
uses:
primary_datastore:
main: { target: vector-db-instance }
log_destination:
audit: { target: audit-sink }

连接形式——插槽接受一个或多个目标。 上面的示例将每个插槽连接到单个目标,但一个插槽也可以扇出到多个目标。插槽的值以以下两种形式之一编写:

uses:
# Compact form — a list of target names. Each entry produces an edge
# whose alias equals its target. Use it for the single-target case, and
# when one socket connects to several peers of the same shape.
shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object
# carrying its own `target:`, and may carry its own inject directives.
# Use when the connections need distinct names or per-edge inject.
databases:
primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } }
replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }

别名始终映射到一个条目对象,而不是裸目标名:databases: { primary: orders-db } 会在加载时被拒绝,省略 target: 的条目对象同样会被拒绝。若要连接单个目标而无需另起别名,请使用紧凑形式——primary_datastore: [vector-db-instance]——它只命名一次目标,并从中派生别名。

每个条目——列表元素或映射别名——都成为一条边,并按编写顺序保留。插槽的 selector: 适用于通过它连接的每个目标(静态分析期间每条边独立进行类型检查),而 required: true 表示必须至少连接一个目标。

字段语义:

字段类型默认值含义
requiredboolfalse为 true 时,开发者必须向该插槽连接至少一个依赖。为 false 时,该插槽是可选的。
selectorstring—一个标签选择器,采用 Feature appliesTo 所用的语法,通过该插槽连接的每条边的目标都必须满足它。它按此处所写的字符串读取,并在静态分析期间针对目标的标签求值:标签不满足它的目标会使构建中止;语法拒绝的选择器同样会使构建中止,并指出无法读取的需求。空选择器不对目标施加任何约束。
injectstring[]—允许的注入交付机制的白名单(与 featuresSchema[].inject 平行)。缺省或为 [](空)表示黑盒——开发者的 uses: 条目上不允许出现 inject: 块;由 Recipe 控制交付。[env, file, arg](非空)表示透明——开发者可以指定由哪种机制交付依赖的 provides 值。强制执行:参见下文“插槽的 inject 白名单在何处强制执行”。
valueSchemaobject—可选的逐边契约,用于约束通过该插槽连接的边上由开发者编写的 values(在 Aggregate 中编写)。采用 JSON Schema 2020-12,编写形式与 schema: 相同。省略表示该插槽不声明 values 契约。
infraSchemaobject—可选的逐边契约,用于约束通过该插槽连接的边上由运维人员编写的 infra(在 Release 中编写)。编写形式与 valueSchema 相同。省略表示该插槽不声明 infra 契约。
featuresSchemamap—通过该插槽连接的每个连接可以填充的附加槽位,以槽位名为键,每个槽位接受与 Component 级槽位相同的键。省略表示通过该插槽的连接不携带附加项。参见下文“每个连接填充的槽位”。

插槽的 inject 白名单在何处强制执行。 白名单是插槽对以下问题的声明:使用方是否可以选择交付形式,以及如果可以,能选择哪些形式——因此,一旦边和插槽的声明都已就绪,就会针对通过该插槽连接的每条 uses: 边进行检查。同一条规则导出两种拒绝,两者都会中止构建:

  • 边指定了白名单未列出的机制时会中止,并指出插槽、违规的机制以及该插槽允许的机制。边上所有违规的机制会一并报告。
  • 通过白名单缺省或为空的插槽指定任何交付的边同样会中止。这正是黑盒声明在发挥作用:它表示“由 Recipe 在内部交付;不要指定交付方式”,空白名单表示一概不允许,而不是全部允许。

socket 从声明它的那个实体上读取,而该实体并不总是边所挂靠的 component:在 Feature 附件的 uses: 上编写的边,依据所附加 Feature 的 usesSchema 解析;其他所有边(在 Aggregate 中编写的、从 Release 接线的,或经由子 aggregate 到达的)则依据消费方 Component 的声明解析。通过 extends 继承的 socket,与该实体自身编写的 socket 完全一样地读取。

不指定任何内容的边不受这两种拒绝影响,无论插槽如何声明:在使用方 Recipe 中从 .context.uses.<alias>.provides.<name> 读取依赖的值无需 inject: 块,且始终可用。两种诊断参见 errors/fatal-halts.md。

逐边连接契约——valueSchema 和 infraSchema。 除了规定哪些 Components 可以连接到插槽之外,插槽还可以声明每个连接携带什么配置。两个可选的逐插槽 schema 会校验通过该插槽连接的每条边上的连接级配置:

  • valueSchema 是 uses 边上由开发者编写的 values 块的契约——开发者在 Aggregate 中表达的逐连接调优(例如连接池大小或客户端模式)。
  • infraSchema 是 uses 边上由运维人员编写的 infra 块的契约——运维人员在 Release 中表达的逐连接运维规格。

两者都接受 JSON Schema 2020-12,内容形态与 schema: 字段相同——内联紧凑形式、内联 JSON Schema YAML,或指向 SchemaLibrary 条目的跨文档 $ref:。它们是逐边契约,针对每条边的配置独立校验;它们不会组合进使用方 Component 自身的 values schema。某插槽若省略某个支柱的逐边 schema,则在该处不声明契约,为该支柱编写的任何配置都不经校验。逐边配置按封闭方式校验,且两个支柱的校验都会考虑默认值:schema 为其提供 default: 的键即使作者省略,也视为已提供。

声明的 default: 在两个支柱中也会实际生效。作者省略的键会携带其声明的默认值进入使用方 Recipe 的渲染上下文,与省略的组件 value 或 infra 键完全一样——因此在插槽上声明默认值就足够了,Recipe 模板无需为其编写回退表达式。编写的值始终优先于声明的默认值,且只填充它所提供的键:只编写了插槽契约中一个键的边,仍会获得该契约其他键的声明默认值。默认值附着于边,因此未连接的插槽不贡献任何内容。

spec:
usesSchema:
databases:
required: true
selector: "datastore.aggrega.ai/engine=relational"
inject: [env]
valueSchema: # developer per-edge values, authored in the Aggregate
pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 }
tls_mode: { type: string, enum: [disable, require, verify-full], default: require }
infraSchema: # operator per-edge infra, authored in the Release
storage_class: { type: string, default: standard }

声明该插槽后,Aggregate 省略 pool_size 的边渲染为 10,Release 省略 storage_class 的边渲染为 standard。编写的值按键优先,且限于其自身支柱:设置了 pool_size: 42 的 Aggregate 渲染为 42,而 tls_mode 仍填充为 require;设置了 storage_class: gp3 的 Release 渲染为 gp3,不影响任一开发者键。

使用方 Component 的 Recipe 从增强的拓扑管道中读取解析后的逐边配置,位置为 .context.uses.<alias>.values.<key> 和 .context.uses.<alias>.infra.<key>——参见 vocabulary/topology-triad.md。

每个连接填充的槽位——插槽的 featuresSchema。 插槽还可以声明附加槽位,这样通过它连接的每个连接都可以在每个槽位中携带自己的附加项:连接多个模型的网关为每个模型持有不同的凭据,因为凭据位于连接上而不是网关上。

spec:
usesSchema:
models:
selector: "component.aggrega.ai/category=ai-model"
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: The credential the consumer presents to the component this connection reaches.

连接通过在其自身的 features: 中以槽名携带一个附件来填充该槽——位于 Aggregate 的连接条目上(Aggregate)或 Release 的连接条目上(Release)——该附件成为消费方组件的附件之一,名为 <alias>.<slot>。

该声明的确切作用如下:

  • 槽名是一个封闭集合。 Component 自身的 featuresSchema 允许以任意名称挂载自由附件,而套接字的槽则不同,它们是经由该套接字的连接唯一可以携带的名称:任何其他名称都会在构建加载时中止,未声明 featuresSchema 的套接字不允许其连接携带任何附件。临时套接字(即此 usesSchema 未声明的套接字)不声明任何槽,因此其连接也不携带任何附件。每个连接自行填充其槽:更大作用域上的附件绝不会级联到连接上,而拼写出连接附件组合名称的 Release 键会中止。
  • 其他键使每个连接受该槽约束。 此处的槽接受与 Component 级槽相同的键——required、selector、inject、sensitive、description——每个连接各自受其约束。selector 与连接用于填充该槽的 Feature 的标签进行匹配,不被允许的填充会中止,并定位到写入该填充的文档中该连接的条目。required: true 是经由该套接字连接的每个连接都须履行的:让槽空着的连接会中止并指明该连接,而旁边填充了该槽的连接则通过。sensitive 的解读与 Component 级槽完全相同:填充该槽的附件在构建图和 aggrega inspect 中被标记为敏感。在连接上和在组件上一样,附件的哪些值作为敏感值被隐藏,仅由所附加 Feature 自身的 schema 决定。inject 约束投递该槽内容的 Workload 条目:连接的附件自身不携带 inject: 块——两种文档都不允许在连接条目上出现它——因此 Workload 通过在槽旁指明该连接来投递它,且该条目受套接字槽的允许列表约束,正如指明 Component 级槽的条目受该槽的允许列表约束一样。

Feature 的 usesSchema 不接受 featuresSchema:Feature 发起的连接不携带附件,在套接字上声明槽的 Feature 会在加载时被拒绝。此类连接所需的凭据是 Feature 自身 featuresSchema 中的一个槽。

从 usesSchema 生成 schema。 编译器从声明的套接字生成基础 JSON Schema 2020-12 片段,并将其与用户的 schema: 声明组合——与 featuresSchema 使用的模式相同。生成的 schema 从不写入磁盘,仅在 Component 校验阶段存在于内存中。开发者在 Aggregate 中的 uses: 映射根据合并后的 schema 进行校验;每个套接字的 selector: 在静态分析期间针对候选 Component 标签求值,作为跨节点类型安全检查。

选择器语义——Split Schema 机制。 usesSchema[].selector: 使 Aggrega 的拓扑不只是无类型的字符串传递。声明 selector: "datastore.aggrega.ai/engine=vector" 的套接字只接受连接到带有匹配键值对标签的 Components;试图将其 primary_datastore 套接字连接到 relational Component 的智能体会在 Static Analyzer 中失败,并得到清晰的选择器违规诊断。选择器是 Kubernetes 风格的标签选择器字符串——由 =、!=、in (...)、notin (...)、裸键和 !key 形式构成、以逗号表示 AND 的需求——与 Feature appliesTo 使用的语法相同;语法参见 vocabulary/modifier-system.md,引擎语义参见 architecture/13-catalog-and-registry.md §2“Kubernetes 风格选择器”。超出这些形式的需求会被拒绝,而不会被解读为其他选择器:空需求(开头、结尾或重复的逗号)、包含空白或 =、!、(、) 及逗号中任一字符的键,或缺少右括号的集合,都会使每个经由该套接字连接边的构建中止,并指明该需求。因此,用于排除前端的套接字应写作 selector: "tier!=frontend";"!tier=frontend" 会被拒绝,因为 ! 只用于指明标签键。

临时套接字——声明套接字能带来什么,以及不声明时作者能做什么。 Aggregate 作者可以在自己的组件上,以此 usesSchema 未声明的套接字名称编写 uses: 条目,包括在完全未声明 usesSchema 的 Component 上。该边会被构建。目录对某个套接字未作说明,意味着该连接未被预见,而非被禁止,应用的拓扑由开发者负责。

这种临时套接字所放弃的,正是已声明套接字所提供的,因为这些都位于 usesSchema 条目中:没有 selector,因此没有任何东西约束边可以到达哪个组件,跨节点类型安全检查也无从求值;没有 inject: 允许列表;没有每边 valueSchema,因此每边 values: 没有可供校验的契约,也没有可继承的声明默认值。它也放弃了 infraSchema,不过无论如何此类套接字上都不会用到该契约:每边 infra 是在 Release 边条目上编写的,而 Release 条目只能指明消费方 Component 声明的套接字。不变的是边可以携带的内容:每个 inject 条目的 from: 仍必须指明目标 Component 的 schema.provides 声明的键,且目标仍必须存在——两者都会像在已声明套接字上一样中止构建。

应将“没有 inject: 允许列表”理解为缺少约束,而不是黑盒声明,因为两者看似相同,行为却相反。经由临时套接字的边可以自由指定投递方式:既没有可供机制超出的允许列表,也没有实体承诺在内部处理这些值。上文的黑盒拒绝适用于实体确实声明了却未提供 inject: 允许列表的套接字——这种省略是对实体所预见连接的一种陈述,而临时套接字不作此类陈述。

投递走的是同一路径,渲染产物不记录任何差异。 临时边的 inject 块与已声明套接字的完全一样被解析和投递:每个 from: 键从目标求值后的 provides 中读取,并以作者选定的投递键落入消费方节点的注入上下文,再由此到达渲染产物。投递路径只有一条,其上没有任何分支取决于套接字是否已声明。已声明套接字能增加的是内容——其 valueSchema 或 infraSchema 填入的每边默认值——因此在已声明套接字不携带此类契约时,同一条边在两种套接字下的渲染结果完全相同。声明是关于连接的事实,而不是渲染内容的输入。

临时套接字上的每边 values: 会被接受,并在 .context.uses.<alias>.values 处到达消费方 Recipe,但不经校验:没有可供衡量的 valueSchema,不检查任何键,也不拒绝任何键。这并非临时套接字特有——未为该支柱编写契约的已声明套接字也以同样方式处理其每边配置。临时套接字的不同之处在于,不声明套接字就无法添加契约。此类边上的 .context.uses.<alias>.infra 为空,因为提供每边 infra 的界面无法指明未声明的套接字。

输出图中的每条边都会记录自己属于这两种中的哪一种,因此使用方无需自行推断;希望每个连接都经过已声明插槽的组织,可以将其作为治理策略加以要求。在此处声明插槽仍然是更好的做法,也是标准库目录的做法:已声明的插槽带有一个 selector,约束该边可以到达哪些组件;带有一个 inject: 允许列表、一个带自身默认值的逐边契约,以及一段描述——这是对预期连接的可审查声明,并随做出该声明的实体一起进行版本管理。临时(ad-hoc)形式是一个逃生舱口,而不是新的默认做法。有两个表面刻意不以这种方式开放——Feature 附件的 uses 只能指定被附加的 Feature 所声明的插槽,Release 的逐边 uses 只能指定使用方 Component 所声明的插槽。

示例 examples/adhoc-uses-socket/ 在同一个使用方上构建了这两种边,并在渲染输出中并排展示两个交付的值,同时展示未声明的 from: 键所产生的中止。

插槽名称拼写错误以提示形式呈现,而非中止。 由于未声明的插槽名称是合法的,拼错的插槽名称会自成一个临时连接,而不是连接到作者原本想要的插槽——构建仍然保持通过,而其上没有任何数据流动。对于与此 usesSchema 所声明名称相差一次编辑的插槽名称,编译器会报告一条同时列出两种拼写的警告——参见 errors/warnings.md “Uses-socket near-miss lint(Uses 插槽近似拼写检查)”。该警告从不改变构建的结论;编译器不干预作者如何命名插槽。

usesSchema 与 featuresSchema 的关系。 二者都是声明式表,都带有语义相同的 inject: 允许列表,但插槽(socket)和槽位(slot)是不同的东西,不可互换。usesSchema 管理跨组件的边——即拓扑图——声明哪些插槽带有契约。featuresSchema 管理附件槽位,而槽位是一个命名绑定点,而非枚举:在组件自身的块上,以任何槽位都未声明的名称进行附加是合法的。(插槽为其连接声明的槽位是唯一的封闭集合,如上文“Slots each connection fills”所述。)两个表面在这一点上已趋于一致——组件自身以未声明插槽名称编写的 uses: 条目同样合法——但二者仍然不同:未声明的槽位是 Component 上的一个自由附件,不影响其已声明的槽位;而未声明的插槽是一条没有选择器、也没有逐边契约的边。许多 Components 同时声明二者;两张表彼此独立地组合。

附着槽:featuresSchema

Component 可以通过 featuresSchema 块声明附着槽。每个槽命名一个绑定点,Component 期望在该点附着一个 Feature(例如 root 密码、API 密钥、认证令牌、身份绑定),并约束哪个 Feature 可以绑定它,以及填充的材料可以如何交付。

本节讨论的是 Component 自身的槽。socket 为每个连接声明的槽则是一个封闭集合,参见拓扑 Socket 下的“每个连接填充的槽”。

声明槽并不会封闭附着面。 作者可以在没有任何槽声明的名称下附着 Feature,这种附着称为自由附着:完全合法,只是不绑定到已声明的槽。正是这种开放性,让同一个目录实体无需分叉目录即可服务两种不同的部署形态:

  • 按消费者。 每个实例用自己的 Feature 填充该槽,因此每个消费者都得到自己渲染出的凭据。
  • 共享。 没有实例填充该槽;而是在更宽的作用域(一个子系统,或一个 Release 边界)上附着一次凭据,并级联到其下的每个 component,因此每个消费者都由这一个声明填充。渲染结果取决于实现方式:在渲染 Secret 的实现下,每个消费者一个 Secret,各自携带相同的材料;在让每个消费者指向已存在 Secret 的实现下,则不渲染任何 Secret。

作者通过附着的内容在两者之间做出选择。两种情况下目录实体都是相同的。

该开放面上有一种形态会中止构建:以另一个名称写在 component 上的填充。 当直接写在 component 本身上的附着(在 Aggregate 中该 component 自身的 features: 块上,或在 Release 中针对该 component 的条目上)使用了没有任何槽声明的名称,且其 Feature 满足某个槽的 selector,而在所有作用域折叠之后该 component 上没有任何东西绑定该槽时,构建中止。这正是本应填充该槽的附着被写在错误名称下时的形态:若不处理,它会成为自由附着而槽保持为空,而一个留空的可选槽会构建通过却什么也不交付。消息会指出该附着、component、Feature 以及该 Feature 适配的每个空槽,补救方法是以槽的名称附着它。这适用于所有 Feature,而不仅是凭据。附着面上的其他一切保持自由:Feature 不适配任何已声明槽的附着、在其适配的每个槽都已绑定后的额外附着,以及 component 从子系统或 Release 边界继承的附着;因此上述共享形态不受影响。未声明 selector 的槽没有说明它面向哪个 Feature,因此不会以这种方式约束任何附着。该中止在 errors/fatal-halts.md 中的“An attachment written under another name fits a slot its component leaves empty(以另一个名称写入的附着适配了其 component 留空的槽)”下说明。

两种形态可以组合,更近的一方胜出。 作者可以同时采用两者:在更宽的作用域附着一个 Feature,使其到达该作用域下的每个 component,并在需要不同内容的那个 component 上填充该槽。component 作用域的填充胜出,且是逐字段胜出,因此它只需重新声明它要更改的字段,其余字段仍来自更宽的附着。未填充该槽的兄弟 component 保持更宽的附着不变。完整的优先级规则,包括它与注解驱动的附着以及组合 Aggregates 的交互方式,见 vocabulary/labels-and-annotations.md 中的“附着优先级”。

Component 上的 schema 定义:

spec:
featuresSchema:
root_password:
inject: []
description: Root database password. Recipe controls delivery (Black-Box).
user_password:
inject: [env, file]
description: Application user password, auto-generated if omitted.
replication_password:
inject: []
description: Replication password for HA setups.

字段语义:

字段类型默认值含义
requiredboolfalse声明该槽最终必须被绑定。当此 Component 的某个实例上没有任何东西绑定该槽的名称时,构建中止;检查依据的是实例在整个附着级联之后持有的附着集合,因此在实例所继承的作用域上声明的附着,与直接在实例上编写的填充一样能满足该槽。诊断会指出该 component 和该槽。
injectstring[]—允许的 inject 交付机制的允许列表。[](空)表示黑盒:Recipe 在内部控制交付,材料永远不会交付给 workload。[env, file] 表示透明:填充的材料可以通过所列机制交付。语义与 usesSchema[].inject 相同。
descriptionstring—供人阅读的文档,由 IDE 和 hub 渲染。
selectorstring—可选的 Kubernetes 风格标签选择器,约束哪个 Feature 可以填充此槽;它是 usesSchema socket 的 selector 在槽上的对应物,语法相同,使用相同的原生标签匹配引擎。在静态分析期间针对所附着 Feature 自身的标签求值;标签不满足它的填充会中止构建,语法无法接受的选择器同样会中止构建,并指出无法解析的要求。省略则不对填充施加约束。
sensitiveboolfalse声明无论什么绑定此槽都会处理秘密材料。这是关于绑定点的陈述,而非关于任何特定填充;参见下文“将槽声明为敏感”。

槽约束的是哪个填充可以绑定它,而不是填充配置什么。有意不设槽级别的 values 或 infra 契约:所附着 Feature 自身的 schema: 拥有这些支柱,因此每个契约都恰好只有一个归属。

槽 selector 是 Component 收窄哪个 Feature 可以填充槽的方式,例如收窄到特定 provider 的凭据 Feature(feature.aggrega.ai/kind=secret, provider=helm),而无需指定 FeatureRecipe,这与 usesSchema socket 选择器收窄依赖边目标的方式完全相同。编译器仅针对所附着 Feature 的标签对选择器求值:它读取填充携带的标签,并报告选择器是否接受它们。要求哪些标签有意义是目录编写时的选择,而不是编译器强加的规则。

槽名称拼写错误以建议形式呈现,而非中止。 由于未声明的附着名称是合法的,拼错的槽名称会成为自由附着,而不是填充作者本意的槽。对于与某个已声明槽名称相差一次编辑的附着名称,编译器会报告一条同时列出两种拼写的警告,参见 errors/warnings.md 中的“Attachment-slot near-miss lint”。该警告从不改变构建结论;编译器不干预作者如何命名附着。若名称与某个槽相差一次编辑,且附着的 Feature 满足该槽的 selector,则不会产生警告:该槽最终为空时,由上述中止报告该附着;若有其他东西绑定了该槽,则该附着只是一个普通的额外附着。

将槽位声明为敏感

槽位上的 sensitive: true 表达的是消费方自身的要求:绑定此点的任何内容都处理机密材料。

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: "Optional database password credential."

这与 schema 叶子节点上的 sensitive: true 是确实不同的信息,而不是为方便而设的重复,标准库目录两者都需要。一个可引用的凭据发布 provides.name 和 provides.key——资源的定位符及其中的数据键——而两者都不敏感:Kubernetes Secret 的名称是公开的,其中的键也是公开的。然而该凭据所填充的槽位无疑处理机密材料。叶子节点表达的是此数据是机密材料;槽位表达的是此绑定点处理机密材料;这两种声明针对的是不同的事物,可以各自独立成立。

其实际结果是,这一要求随绑定点而非填充传递。一个完全不声明敏感叶子节点的 Feature——因为凭据由目标引擎掌管,作者无需编写任何内容——在绑定敏感槽位时仍是一个敏感附加,因为槽位如此声明。反之亦然:声明了敏感叶子节点的填充即使绑定的是未作此声明的槽位,或者是不绑定任何槽位的自由附加,也仍是敏感附加。

该声明遵循附加级联,而不是任何单个编写的块。槽位的要求适用于所有作用域合并后最终绑定的那个填充,因此取代更大范围填充的组件级填充会原样继承该要求。

槽位上的 sensitive 与叶子节点级关键字具有相同的上限——它只做标注,不加密、不校验、不拒绝、不强制交付机制,也不改变任何渲染出的字节。完整说明见 vocabulary/compact-form-authoring.md “What the keyword does not do”。

sensitive 与 compliance.aggrega.ai/data-class 是两个不同的维度,二者相邻记述,从不混为一谈。sensitive 是单个叶子节点或单个槽位上的布尔值:此数据或此绑定点处理机密材料。compliance.aggrega.ai/data-class 是整个节点上的分级标签——public、internal、restricted——为组件所持有的数据赋予治理身份。一个按数据且为二元,另一个按节点且有序;二者互不替代,一个实体可以同时带有两者。该标签的说明见 vocabulary/labels-and-annotations.md 和 architecture/08-credential-model.md “Data governance around credentials”。

从 featuresSchema 投影 schema

声明的槽位会投影为一个描述附加块形状的 JSON Schema 2020-12 片段。有两类填充会据此进行校验:由导入的模块提供的组件的附加块(在导入它的组合构建完成后校验),以及在更宽作用域声明的附加(针对它所到达的每个组件上的槽位校验)。由 Aggregate 自身声明的组件的附加块则改由 Aggregate 的文档 schema 和槽位的 inject 允许列表来衡量(见下文),而该片段的形状使两者对任何填充都会得出相同的结论。该投影从不写入磁盘,只存在于内存中,Component 的 schema: 永远无需手工编写附加支柱。

输入 featuresSchema:

featuresSchema:
root_password:
inject: []
user_password:
inject: [env, file]

投影出的片段(位于内存中;紧凑形式表示):

# The OUTER object is open: an attachment under a name no slot declares is
# admitted, because a free attachment is legal authoring.
root_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
# inject admits only an empty block — inject: [] means the Recipe controls
# delivery, so a fill may name no mechanism
inject: {}
user_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
inject:
env: { type: array }
file: { type: array }
# arg is absent — not in the inject allowlist

这两个层级相互独立。外层对象是开放的,因此声明的槽位从不禁止实体未列举的附加。每个声明槽位自身的片段是封闭的,因此确实绑定了声明槽位的填充仍受该槽位形状的约束。

该片段只描述形状。它不包含哪些槽位必须被绑定的任何声明,因为标记为 required 的槽位可能由从更大作用域级联而来的附加绑定——这会使该片段描述的块为空。因此,这一要求是针对组件最终拥有的附加集合检查的,而不是针对任何单个块所声明的内容;这两个问题从不相互矛盾,因为对编写的块只会提出其中一个。

允许的键与附加在任何位置可以携带的键一致,因此在自由附加上合法的键在槽位填充上同样合法。每个列入允许列表的交付机制都是一个交付条目列表——与 inject: 在各处采用的形状相同;槽位限定的是可以出现哪些机制名称,而不是条目的样子。

inject 允许列表在何处执行

允许列表在两个不同的步骤约束槽位的两侧。

针对 Recipe 的 Workload,在渲染步骤:通过其容器附加条目引用槽位的 Workload 必须指明实体声明的槽位,并且必须选择槽位 inject 允许列表所允许的交付机制;引用黑盒槽位(inject: [])、允许列表之外的机制或实体从未声明的槽位都会使构建中止。诊断信息会指明 Recipe、容器路径和出错的槽位,并归类为目录错误——出错的是 Recipe。

针对 Aggregate 自身的附加,在解析其附加时、任何渲染之前:绑定声明槽位的填充上的 inject: 块只能指明槽位允许列表所允许的机制,而黑盒槽位不允许任何机制——其空允许列表表示“由 Recipe 在内部交付;不要指定交付方式”,为其编写交付会使构建中止。诊断信息定位在该附加上,指明槽位和出错的机制,并在槽位允许某些机制时一并列出这些机制;它被归类为开发者错误,因为出错的是 Aggregate。空的 inject: {} 块不指明任何机制,因此不指定任何交付方式,在每个槽位上都会被接受,黑盒槽位也不例外——无论是在 Aggregate 声明的组件上、在导入的模块提供的组件上,还是在更宽作用域声明的附加上,都是如此。自由附加——即使用任何槽位都未声明的名称的附加——不受此约束,因为允许列表属于槽位而不属于块。

贯穿编译管道的端到端流程——Aggregate 附加如何连接到凭据 Feature(例如 core/secret-value),再连接到将凭据交付给运行中工作负载的特定于 provider 的 FeatureRecipe——详见 examples/05-credential-features。

调用方出示的密钥与服务端校验的密钥

当一个 component 调用另一个会校验密钥的 component 时,两端各自在自己一侧持有密钥,放在各自声明的 slot 中。这是标准库目录遵循的约定;编译器对此不做任何强制——它只根据每个 component 自身的附件检查该 component 的 slot,将其字符串原样传递,从不比较一个 component 持有的内容与另一个 component 持有的内容。

  • 调用方出示的密钥属于调用方。 它位于调用方的 socket 为每个连接声明的 slot 中——参见上文“Slots each connection fills”——因此连接多个目标的调用方为每个目标各持有一个密钥。core/ai-agent/crewai 的 model socket 将该 slot 声明为 credential,其 Recipes 将填充它的内容作为 OPENAI_API_KEY 交付。core/gateway/litellm、core/gateway/kong 和 core/gateway/apisix 的 models socket 也声明了它,其 Recipes 将每个连接的密钥交付到各自独立的变量中,变量以连接的别名命名,因此网关提供的每个模型都持有自己的密钥。如果 Component 改为在自己的 slot 中声明密钥,则它发起的所有连接共用这一个密钥。
  • 服务器校验的密钥属于服务器自己的槽位。core/ai-model/vllm、core/ai-model/tei 和 core/ai-model/tgi 各自声明一个可选的 api_key,它们的每个 Recipes 都会把填充该槽位的内容作为服务器读取其密钥的变量进行交付。LiteLLM 模型和网关为 LiteLLM 称之为 master key 的密钥声明 api_key。
  • 任何一端都看不到另一端的附件。 连接上的附件是调用方的附件之一,只进入调用方的渲染;无论到达服务端的连接携带什么,服务端的渲染输出都相同。标记为 required 的 slot 由声明它的 component 负责满足,而不是由与之连接的 component 负责;填充一端的 slot 不会填充另一端的任何内容——因此在两端都声明密钥是最低要求,而非重复。
  • 两端读取同一个参数,因此调用方出示的密钥与服务端校验的密钥不会被写得不一致。
# Aggregate fragment — one parameter feeds both ends
spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
agent:
type: core/ai-agent/crewai
# values (role, goal, backstory, …) elided
uses:
model:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

只校验一个密钥的服务端无法区分其调用方:vLLM、TEI 和 TGI 各自只校验单个密钥,因此无论有多少连接到达服务端,每个调用方出示的都是同一个密钥。两端是引用同一个 secret 还是各自持有自己的 secret,取决于每个 provider 在何处按引用解析 secret,而 Manifest 为每一端选择实现方式——Credential Model 详细讲解了这两种情况。

component 为自身持有的凭据——例如用于签名自身会话的密钥——与其他凭据一样,是其自身 featuresSchema: 中的一个 slot。它通过某个 socket 访问数据存储时出示的密码,属于上文所说的调用方密钥,因此作为 credential 位于该连接上:core/gateway/kong 的 backend socket 声明了它,其 workload 合成 Recipes 将其作为 KONG_PG_PASSWORD 交付;core/gateway/litellm 的 cache_store socket 为其语义缓存向存储出示的密码声明了它,以 REDIS_PASSWORD 交付。当一个连接出示一对凭据——访问密钥标识符及其 secret——时,secret 部分为 credential,标识符部分为 credential_id,如 core/ai-agent/agenta-api 的 store socket 所示。

自注入:spec.inject

Component 可以声明一个顶层 spec.inject: 数组,用于将自注入交付机制列入允许列表。存在该数组时,开发者可以在 Aggregate 中的组件级别使用 inject: 块,将该 Component 自身的 values: 或 provides: 键直接注入其自身的交付管道(其容器的环境变量、挂载文件或进程参数)。当 spec.inject: 不存在或为空时,禁止组件级别的自注入——由 Recipe 控制所有内部连接,这与 usesSchema[].inject: [] 和 featuresSchema[].inject: [] 分别对跨组件交付和凭据交付所采用的黑盒模式一致。

# Component declares its self-inject allowlist:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/web-server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
inject: [env, file]
schema:
values:
log_level: { type: string, default: info }
tls_enabled: { type: boolean, default: false }
provides:
health_endpoint: { type: string }
# Aggregate fragment — developer dictates self-inject delivery:
components:
api:
type: core/web-server
values:
log_level: debug
tls_enabled: true
inject:
env:
- in: LOG_LEVEL
value: '{{"{{"}} .values.log_level }}'
- in: TLS_ENABLED
value: '{{"{{"}} .values.tls_enabled }}'
file:
- in: /etc/web/health-probe
from: health_endpoint

每个 value: 模板都以 {{"{{"}} 而不是 {{ 开头。Aggregate 的全文会在自注入解析运行之前,为参数插值而作为模板读取一次,而此时 .values 尚不存在;这种转义会把 {{ 放回去,供自注入解析求值。参见自身带有双花括号的文本。

字段语义。 spec.inject: 是一个机制名称数组。定义了三个值:

  • env —— 容器中的环境变量。
  • file —— 挂载的文件路径。
  • arg —— 进程命令行参数。

其语义与 usesSchema[].inject 和 featuresSchema[].inject 完全对应——相同的词汇,省略时采用相同的黑盒模式,在 Aggregate 一侧采用相同的编写形式。区别在于来源:usesSchema[].inject 决定跨组件依赖的 provides 如何流入使用方的交付管道;featuresSchema[].inject 决定凭据如何到达容器;spec.inject 决定该 Component 自身的 values 和 provides 如何到达该 Component 自身的容器。

编写规范。 声明了 spec.inject: [env, file] 的 core/web-server Component 选择透明交付——由 Aggregate 作者决定哪些环境变量名承载哪些值。声明 spec.inject: [](或省略该字段)的 Component 保持交付不透明——由 Recipe 的 valuesMapping: 决定哪些字段流入哪些容器变量,开发者无法在 Aggregate 中覆盖。黑盒模式适用于契约稳定的 Components(例如 core/postgres-db Component,其 Recipe 知道如何将数据库密码连接到 POSTGRES_PASSWORD 环境变量);透明模式适用于开发者意图本身就合理地指定交付细节的 Components(例如 core/web-server,其应用程序从开发者希望自定义的非标准变量名读取 LOG_LEVEL)。

错误模式。 如果开发者的 Aggregate 在 spec.inject: 缺失或为空的 Component 上使用 inject: 块,构建会在加载工作区时中止(“Self-inject on a component without an allowlist (在没有允许列表的组件上进行自注入)”)。使用不在允许列表中的机制的 inject: 块会以同一条件中止,并指出该机制以及允许列表所允许的机制(“Self-inject mechanism not in the component’s allowlist (自注入机制不在组件的允许列表中)”)。自注入、跨组件注入和凭据注入之间的交付键冲突同样会中止(“Duplicate delivery key across inject sources (各注入来源之间存在重复的交付键)”)。各错误的消息格式参见 errors/fatal-halts.md。

目录编写:扩展基础 Components

平台架构师使用 extends 关键字在企业或社区基线之上叠加专用接口。扩展会组合结构,并整体继承数据支柱。编译器从基础开始沿链向下遍历;这两部分的行为不同,而这一差异就是整个编写模型。

扩展组合的内容。 以下界面沿链合并,按键以扩展方 Component 为准,列表按基础优先的顺序拼接且不含重复项:

界面组合方式
metadata.labels按键合并;共享键上以扩展方 Component 的值为准
metadata.annotations按键合并,优先级相同——这正是基础的存在性强制要求会作用于每个扩展它的 Component 的原因
spec.featuresSchema附加槽取并集;扩展方 Component 重新声明的槽会替换基础中同名的条目
spec.usesSchema拓扑插座取并集,按名称替换的规则相同
spec.inject两个自注入允许列表拼接,基础条目在前,重复项被去除
spec.assertions命名规则累积,基础规则在前——且唯独这一界面不允许按名称替换;参见下文“断言继承是累加的”

扩展方 Component 添加的插座可以携带其自身的逐边 valueSchema 和 infraSchema;它们是该插座各条边上的契约,而不是对该 Component 自身支柱的补充。

metadata: 的其余部分保留在声明它的文档中。 labels 和 annotations 是唯一沿链向下传递的元数据。name、version、description、maintainers、license、repository、home 和 keywords 属于扩展方 Component 自身,完全按其编写内容读取——省略 description: 的 Component 就没有描述,而不会借用其基础的描述。身份与来源属于你正在阅读的文档,因此包装器永远不会被误认为它所包装的对象。

扩展整体继承的内容。 三个数据支柱——values、infra、provides——不进行组合。扩展方 Component 不编写任何支柱内容:它写下字面标记 schema: inherited,并完全按基础的编写内容接收其 schema: 块。在任意深度的链上,链中每个 Component 都原样携带链根的块,因此对叶节点执行 aggrega inspect --resolved 显示的支柱与根相同。

已发布的 Component schema 决定三种可能结果中哪一种合法,并在文档加载时拒绝另外两种——每种给出不同的诊断,因为它们是不同的错误:

  • 带有 extends: 且 schema: 下有支柱内容会被拒绝。该 Component 的契约就是其基础的契约;第二份有分歧的契约无处安放。
  • **带有 extends: 且完全省略 schema:**会被拒绝。省略会让读者无法区分继承的支柱块和遗忘的支柱块。
  • **有 schema: inherited 但没有 extends:**会被拒绝。该标记指明支柱的来源,而此 Component 没有可从中获取支柱的基础。

扩展方 Component 无法重塑键集。 它不声明任何支柱键,因此无法隐藏、删除或更改其基础所声明键的类型,也不会添加自己的键。新的支柱键应放在拥有该契约的 Component 上。基础暴露什么,所有扩展它的对象就完全相同地暴露什么。

特化通过 assertions: 收紧约束。 当特化必须比其基础的支柱接受更少的值时——更窄的数值范围、继承的 enum: 的子集——它在自己的 assertions: 块中表达:其中的规则会拒绝继承的 schema 所接受的值。收紧约束就在这一界面上进行;参见下文“assertions: 块”。

上面两段是同一条规则,只看任何一半都会产生误解:无法收窄键集,但可以收紧约束。 只看前一段,你会得出特化无法约束任何东西的结论;只看后一段,你会得出它可以重塑契约的结论。两者都不对——键集由基础确定,而键集内所接受的值可以通过谓词收窄。

断言继承是累加的,且按根优先的顺序累积。 扩展方 Component 的实例既要检查其链声明的每条规则,也要检查该 Component 自身声明的规则,且继承的规则先求值。在任意深度的链上,规则从链根向下累积,因此当实例会违反多条规则时,报告的是在链上声明位置最靠上的那条——最基础的契约最先作答。

由于继承是累加而非替换,扩展方 Component 不得复用继承的规则名来声明一条不同的规则:当 extends 链针对目录解析时,这会被拒绝,诊断信息会指明两个 Components 以及共享的名称。该检查需要拿到基础 Component,因此在目录验证或构建解析该链时报告——单独验证扩展方文档无法发现它。规则名是稳定的标识符,因此既不能删除基础的规则,也不能悄悄重命名它,修复方法是在扩展方 Component 中重命名。在其原名下逐字节重述继承的规则会被接受,视为无操作。

aggrega pull 会获取基础实体。 基础实体是每个触及扩展它的 Component 的 Release 的依赖,无论是否有其他地方提及它。aggrega pull 会沿每个 extends: 追溯到链的末端,从 registry 获取任何 catalog 目录中都没有的基础实体,并把每个基础实体记录到该 Release 的锁文件中,由提及它的 Component 的 spec.extends 引用;构建会从那里读取基础实体。因此,Manifest 只映射包装实体自身的类型,别无其他——只有当某个 Aggregate 也声明了基础实体的实例时,基础实体才需要自己的映射行。针对整个 catalog 的 aggrega validate 以同样的方式读取基础实体,因此发布到 registry 的基础实体在被 pull 获取之前,会在那里被拒绝,并提示 aggrega pull。

schema 内容格式参见 architecture/13-catalog-and-registry.md §3。

示例 A:基础 Component(企业基线) 平台架构师定义了一个基础的企业服务器。该基础设置了所需的运维云原语标签,并在 schema 中确立了安全约束。由于支柱块被原样继承,这里的每条约束都会完全按编写内容作用于每个扩展方 Component。

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/base-enterprise-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
inject: [env]
schema:
values:
# The corporate baseline constraint. Every Component extending this base
# receives this leaf verbatim; none of them can restate or loosen it.
tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter
# bound expresses it as an assertion, not as a redeclared schema leaf.
timeout_ms: { type: integer, default: 5000 }
assertions:
# A baseline invariant. It is evaluated for instances of this Component AND
# for instances of every Component extending it, under this same name.
audit-window-is-observable: |
{{- if lt (int .values.timeout_ms) 100 -}}
{{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}}
{{- end -}}

示例 B:扩展方 Component(特化基线) 一个网关从该基线特化而来。它整体继承基础的支柱,添加自己的结构——一个标签、一种自注入机制、一个带有附加槽的拓扑插座——并通过断言收紧继承的超时。它没有重述基线的 audit-window-is-observable 规则:该规则是继承的且先求值,因此该网关的实例必须同时满足两个界限——至少 100,至多 2000。

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/gateway/kong
version: 1.0.0
labels:
# Every Component declares the reserved base-ontology key, including one
# that extends: the envelope requires it on the document itself.
component.aggrega.ai/type: "server"
api.aggrega.ai/protocol: "http" # merged with the base's labels
spec:
extends: core/base-enterprise-server
schema: inherited # values, infra and provides are the base's, verbatim
inject: [file] # concatenates with the base's [env] -> [env, file]
usesSchema: # a socket of its own; the base declared none
backend:
required: true
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]
featuresSchema: # a slot each connection through it fills
credential:
sensitive: true
inject: [env]
description: Password the gateway presents to the configuration backend this connection reaches.
assertions:
# The tightening. The inherited schema admits any integer for timeout_ms;
# this gateway admits only 2000 or less, so the rule rejects a value the
# inherited pillar block would accept.
timeout-within-gateway-budget: |
{{- if gt (int .values.timeout_ms) 2000 -}}
{{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}}
{{- end -}}

关于针对实际 Helm chart 实现此 core/gateway/kong 接口的 Recipe,参见 entities/recipe 示例 C(kong-gateway)。

assertions: 块

Component.spec.assertions: 是一个可选的具名规则映射,用于表达 Component 契约的架构不变量——无论哪个 Recipe 绑定到该 Component,开发者的编写都必须满足的跨字段规则。每个键是一个规则标识符,会出现在失败消息中;每个值是一段 Go 模板主体。编译器在 schema 校验之后、Recipe 绑定之前,按书写顺序对每个实例求值这些规则,第一个失败的规则会按照 Loud Guardrails 契约,以该规则自身的错误消息中止构建。

spec:
assertions:
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt (int .values.secondary.replicaCount) 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}

上面的规则是 Component 契约的一项属性——无论绑定的是哪个 Recipe(Bitnami chart、手写的替代实现、未来的实现),复制模式都要求至少两个从副本。

assertions: 是扩展 Component 进行收紧的地方。 一个 extends: 基础的 Component 会原样继承基础的支柱块,且不声明自己的支柱内容,因此,若特化必须比继承的 schema 接受更少的值,就在这里以谓词的形式声明该限制,而不是以收窄的 schema 叶节点声明——即一条拒绝继承支柱所接受的某个值的规则。完整的示例对及完整的继承行为见上文“Catalog Authoring: Extending Base Components”:规则沿链从根开始累积,复用继承的规则名来声明不同的规则会被拒绝,而不是允许其替换原规则。

编译器不检查两条规则能否同时被满足。 规则是一个模板谓词,而不是编译器会进行推理的约束,因此一对没有任何值能同时满足的规则——基础要求至少 100,而特化要求至多 50——在 catalog 加载时不会产生任何警告。它会以普通方式显现:编写一个实例,构建在两者中先触发的那条规则上中止,作者读到的是该规则的消息。不要指望矛盾会被提前报告;请对照基础已有的要求检查特化的收紧。

assertions: 应用于真正的跨字段规则。单字段约束(范围、模式、枚举)应放在 schema: 关键字中;单字段自定义谓词应放在紧凑形式的 validate: 中;条件形态(某个子树的约束是否适用)应放在 when: 中。完整的编写语法——模板上下文字段、{{ fail }} 消息约定、求值阶段,以及涵盖 Component 和 Recipe 角色的完整示例——见 templates/assertions-block.md。