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

Recipe

Recipe 实体的概念角色(由 Ops 编写、将开发者意图映射为物理格式的转换模板)见 architecture/04-entity-taxonomy.md。本页介绍 Recipe 的编写接口:指针(source)、映射器(valuesMapping:)、原生 IaC 支持以及完整示例。

Recipe 架构:指针与映射器

一个 Recipe 恰好承担两项功能:

  1. 指针(source): 准确告诉编译器基础设施代码所在的位置。
  2. 映射器(valuesMapping): 将 Aggrega 的抽象上下文注入底层代码所期望的具体变量。该字段是单一的 Go 模板入口,有三种编写模式——内联块标量、文件 $import: 或库 $import:——按内容形态分派。参见下文的 valuesMapping 字段——三种编写模式。

由于 Recipe 与渲染能力严格一一对应,该能力(spec.capability)在根级显式声明,确保 Go 编译器准确知道应调用哪个下游 Wasm 渲染插件。

spec.implements 声明该 Recipe 能够实现哪种目录组件类型。编译器用它来校验 Manifest 映射(被映射的 Recipe 的 implements 必须与被映射的类型匹配),并用来推荐候选项——即无映射诊断中列出、在编辑器补全中排在最前的 recipe。它从不决定构建:Manifest 映射是用户显式的部署选择,固定在 lockfile 中。一个 implements 未带版本、为精确版本或为主版本兼容范围的 Recipe,仍然只是为某个类型提供自身;由用户固定选择。FeatureRecipe.spec.implements 对 feature 类型承担完全相同的角色。

A. Wasm 驱动的源 schema

为了让实现偏好不进入编译器,source 块并不是一组固定的基础设施字段。source 字段支持两种格式:

  • 通用字符串(快速、简洁): 最适合本地路径、OCI 制品和 Git 仓库。编译器根据字符串的前缀和后缀(./src、https://github.com/example/module.git、oci://...)推断获取方式:以 .git 结尾、或以 git:// 或 ssh:// 书写的 URL 是一个 Git 仓库,在其默认分支上获取;既不指向仓库、也不指向 .tgz chart 或 .yaml 片段的 https:// URL 会因含义不明确而被拒绝。
  • 开放结构化对象: 一个开放字典(additionalProperties: true),其键由 provider 定义,并以 .source.*(例如 .source.chart)的形式暴露给 Recipe 的模板。设计意图是由每个 provider 的 WebAssembly 插槽定义并校验自己的源形态(例如 Helm 的 registry/chart/appVersion)。

核心解析的内容。 没有任何 provider 会校验其自身的 source 键。需获取的源由一个内置标识解析,其 kind 选择解析器——helm-oci-chart、helm-https-chart、compose-https-fragment 和 git-repository。意图获取的源必须带有 kind 和 url;由哪个进一步的坐标选择内容取决于 kind。chart 和 fragment 类 kind 接受 version,并按所写内容固定。git-repository 接受 ref——一个 tag、分支或提交——以及可选的 module_subdir,用于指明仓库中作为制品的目录;由于只有提交所指的内容无法被重新指向,该引用在锁定时解析,lockfile 同时记录所编写的引用及其解析到的提交。按所写内容会越出仓库之上的 module_subdir(反斜杠也算作分隔符)会在获取任何内容之前被拒绝。仓库从其自身的检出中归档:仓库提交的符号链接,若指向仓库内部,则按其指向的文件或目录归档;若指向仓库之外,则中止拉取,并按其在仓库中的位置指明该链接。url: 指向文件系统路径的结构化源不会被获取:它与裸路径字符串一样从磁盘读取,相对的 url: 以声明它的实体文件所在目录为基准。省略 kind/url 的结构化源同样不会被获取;如果原本意图获取,构建会在锁定时的源下降阶段明确中止,而不是静默地解析为空。内容总是在编译前固定;编译器从不获取实时的运行时状态。

在 Recipe 旁边固定的内容。 对于 kind、url、chart、module_subdir、version 和 ref 均以字面写出而非模板化的需获取源,aggrega pin 会把它所获取内容的摘要记录在 entity.lock 中,这是 Recipe 自身目录中的一个文件,你将它与 Recipe 一同提交。固定是 Recipe 作者的步骤,不需要 Release;对 lock 中未记录固定的 Recipe 执行拉取会中止并指明该源,除非要求拉取执行同一步骤。构建会将该摘要与 Release 的 lockfile 为同一源记录的摘要进行比较,两者不一致时中止——但以 git ref: 编写的源除外,其条目按 ref 解析到的提交记录,不做比较。坐标由模板填入的需获取源则改为按 Release 固定,记录在每个 Release 的 lockfile 中。指向 Recipe 旁边的目录或文件的源不会被获取:aggrega pin 为它贡献给 Recipe 发布内容的每个文件记录一个摘要——对于以模板编写的源,则是 Recipe 目录中的每个文件——一旦 lock 记录了这些摘要,构建会在 provider 读取该源之前将其与之比较,若自固定以来有文件被添加、修改或删除则中止——报 E0305;若 Release 的 lockfile 是在变更之前写入、并按 Recipe 所携带的内容记录该 Recipe,则先报 E0130。若 lock 未为此类源记录固定,构建便无从比较,不执行固定的拉取或发布会拒绝它。Recipe 文件本身从不被写入。aggrega pull 介绍了该文件以及如何应对每种中止。

spec.capability 可以按 implements 所采用的形式携带版本固定——精确版本(helm:<version>)或脱字符范围(helm:^<version>)——用于选择由 provider 插件的哪个版本渲染该 Recipe;没有任何可用版本能满足的固定会中止构建。未固定时(spec.capability: "helm"),由最高的可用版本渲染。可用版本即 aggrega plugin list 所显示的版本:内置于 aggrega 的 provider 带有编译器自身的版本。该固定不属于 Recipe 名称的一部分:Manifest 将声明 capability: "compose:1.2.3" 的 Recipe 映射为 compose/<name>:<version>,与未固定的 Recipe 完全相同,更改固定也永远不会使其改名;将固定写入名称的映射值(compose:1.2.3/<name>:<version>)会在查找任何内容之前作为格式错误的 recipe 引用被拒绝(E0095)。

心智模型:spec.capability 指明你想要的输出格式(例如 helm、terraform、compose);编译器将其解析为渲染该格式的 Wasm 插件(例如 provider/helm)。你声明格式;Aggrega 绑定工具。

B. 上下文注入:语义映射层

为防止编译器在多个环境之间执行危险且不确定的深度合并,Recipe 的映射层只允许单一事实来源。

运维工程师编写映射内容,在 Wasm 渲染插件执行之前转换抽象上下文。映射语言是 Go template(text/template + Sprig);Sprig 库已预先注册;支持标准的 define 和 template 动作,include 未注册。

字段名作用范围与执行阶段最佳用例
injectMapping (仅限 FeatureRecipe)渲染前拦截。 在 Go 内存中、于基础 Recipe 之前求值。将其输出字典原生地、严格地深度合并到调用方的 .context.inject 管道之上。有意不包含在基础 Recipe schema 中——架构理由见 entities/featurerecipe。精确改写注入的 env 变量,或为调用方格式化 FQDN,而无需 Wasm JSONPatch。
valuesMapping基础渲染(Go template)。 求值以将变量映射到底层 source 基础设施 chart/module 中。单一字段,三种编写模式(内联、文件 $import:、库 $import:)。分派机制见下方小节。直接在 Recipe YAML 中将标准变量(如副本数或镜像标签)映射到 Helm chart,或通过 $import: 引用共享模板以便跨 Recipe 复用。

注意:injectMapping 为 FeatureRecipes 独有,它将变量拦截与 valuesMapping 隔离开来。基础 Recipe 的 valuesMapping 在不知情的情况下使用由 FeatureRecipe injectMapping 块生成的改写后的 .context.inject 字符串,因此两者保持解耦。

valuesMapping 写为 null 的键以 null 到达 provider,它在那里起什么作用由 provider 决定,因此每个 provider 页面都会说明:helm 移除 chart 中该键的默认值,helm-chart 将其写入 umbrella 的 values,compose 将其写入 compose 文件,terraform 将其写为 null 模块参数,而 cloudformation 拒绝它。

valuesMapping 字段——三种编写模式

Recipe 的 valuesMapping: 是单一的 Go template 表面,接受三种分派模式。编译器根据字段内容的形式进行分派;无需 $mode: 注解。

模式 1:内联 Go template(YAML 块标量)。 字段的值是以 YAML 块标量 | 形式书写的字符串:

spec:
valuesMapping: |
{{- with .values -}}
image:
tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }}
pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }}
architecture: {{ optional . `architecture` "standalone" }}
primary:
replicaCount: {{ optional .primary `replicaCount` 1 }}
{{- end }}

对于映射内容为小到中等规模(约 50 行以内)的 Recipes,内联模式是典型的编写形式。模板主体与 Recipe 的其余部分内联放置;Recipe 的内容自成一体。

模式 2:文件 $import:。 字段的值是一个仅包含 $import: 及本地文件路径的映射:

spec:
valuesMapping:
$import: ./mappings/api-server.tmpl

编译器加载该文件的内容(一个 Go template),基于标准 Recipe 模板上下文渲染它,并将结果视为映射输出。路径相对于 Recipe 的目录解析——相对路径以包含声明它的 recipe.yaml 的目录为基准,而非以调用构建的目录为基准——且路径必须位于该目录之内,详见 Content paths stay inside the Recipe’s own directory。文件模式适用于中到大规模的映射内容(约 50 行以上),以及希望映射变更以独立文件 diff 呈现的评审方式。

模式 3:库 $import:。 字段的值是一个仅包含 $import: 及指向某个 MappingLibrary 条目的裸名称标识引用的映射:

spec:
valuesMapping:
$import: DatastoreHelpers#/mappings/MariaDBCore

编译器在已解析的 MappingLibrary 集合(本地目录加上所有由 lockfile 固定的库)中解析该引用,加载条目内容,并将其视为映射输出;主体本身为字段根 $import: 的条目会递归解析。引用不携带 registry 主机——库名称按标识解析,版本来自每个 Release 的 lockfile,可选 :<version> 作为最低版本下限(<Library>:<version>#/mappings/<entry>)。库内容共享标准 Recipe 模板上下文。库模式适用于跨 Recipe 复用——在许多 Recipes 中反复出现的映射模式(多个数据存储 Recipes 共享数据存储辅助逻辑;多个 Helm provider Recipes 共享 pod 模板模式)。MappingLibrary 实体提供版本管理、lockfile 固定和 hub UI 展示。

分派规则。 编译器遍历 YAML 节点,并按内容形式分派:

  1. 如果节点是字符串标量,则按内联模式(模式 1)分派。
  2. 否则节点为映射;检查是否有 $import: 键。
  3. 如果 $import: 的值是裸名称库引用(<Library>#/mappings/<Entry>,可选带 :<version> 下限),则按库模式(模式 3)分派。
  4. 否则(本地文件路径)按文件模式(模式 2)分派。
  5. 任何其他形式(不含 $import: 的映射、除 $import: 外还有额外键的映射等)都会产生构建时错误。

$import: 仅限单一来源。 $import: 只接受单一来源。valuesMapping: 不支持多来源合并。需要组合多个映射片段的 Recipe 可以使用内部采用 Go template define / template 组合的 MappingLibrary 条目、使用 Go template template 指令调用同级文件的本地文件,或对简短内容使用内联组合。库实体见 entities/mappinglibrary,更广泛的 $ref: / $import: 区别见 vocabulary/cross-document-ref。

来源追溯。 模板渲染失败的错误消息按模式引用相应的来源位置:内联模板引用 Recipe 中块标量开始处的 file:line;文件导入引用被导入文件的内容;库导入引用 MappingLibrary 条目的源位置,并以不含主机的库标识(<Library>#/mappings/<entry>)作为稳定引用的规范指针——引用中的 registry 主机会被拒绝,因此物理位置永远不会进入指针。

C. 原生 IaC 支持

自带基础设施即代码的 Ops 团队可以将其保存在 Recipe 自身的目录中——由 source: 指定的模块或模板目录,例如 ./src——或通过结构化的 source: 获取(例如从其 git 仓库获取 Terraform 模块,使用 kind: git-repository),或将其编写为 artifacts: 下的模板化主体。映射层(valuesMapping:——内联、文件导入或库导入)为这些代码提供抽象上下文,provider 以目标自身的格式输出结果;不会将任何一种配置语言转换为另一种:

  1. Terraform: 模块逐文件 vendor,编写的主体按原样输出,原生 HCL(main.tf)和 Terraform JSON(.tf.json)都是如此——terraform CLI 两者都能读取。边界的根配置 aggrega.modules.tf 将每个 component 的目录作为一个 module 块调用,以源为基础的模块的 valuesMapping: 输出成为该块的参数。参见 terraform provider。
  2. CloudFormation: 源模板(YAML 或 JSON)以及 Recipe 编写的资源片段会被规范化为长格式 JSON,并按边界合并为一个 stack 模板,valuesMapping: 的输出填充源模板所声明的参数。参见 cloudformation provider。

仅在基础设施应用之后才存在的值,始终是由目标解析的指针——Terraform 的 ${ ... } 插值、CloudFormation 的 Ref 或 Fn::GetAtt——在构建时从不求值。

示例 A:远程 Helm Chart(内联映射与 Locals 契约)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-chart
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
# The shipped fetch form: { kind, url, version }. 'kind' selects a built-in
# resolver (helm-oci-chart, helm-https-chart, compose-https-fragment).
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
# Default chart version. Override via infra.source_version.
version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals:
primary_compute: mariadb
listen_port: "3306"
volumes_path: "/spec/template/spec/volumes"
root_path: "/-"
# The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm
# pipeline: the suffix it follows the rendered name with. A local cannot read
# .context.rendered_name, so each template writing the full name joins the two.
secret_target_db_password: "mariadb-auth"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
# Every key the Component's provides contract declares is published
user: "{{ .values.user }}"
database: "{{ .values.database }}"
protocol: "mariadb"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"
auth:
# Reads the suffix from the local rather than restating it, so the secret
# name is authored once and every reader follows that one definition
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"
primary:
persistence:
size: "{{ .infra.storage.size }}"

示例 B:本地 Terraform 模块(文件映射)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: aws-s3-tf
version: 1.0.0
spec:
capability: terraform
implements: aws/s3-bucket:1.0.0
source: "./src"
locals:
primary_compute: bucket_instance
resource_path: "/resource/aws_s3_bucket/main"
root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments
valuesMapping: |
bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data"
region: "{{ .infra.aws_region }}"

示例 C:具体的 Component Recipe(绑定基础设施) 运维将通用接口映射到物理现实。(L4 网络细节就在这里绑定——要么硬编码,要么像下面的代理端口那样,取自 Release 填写的 infra 块。)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: kong-gateway
version: 1.0.0
spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
# A chart repository root paired with the chart's name.
kind: helm-https-chart
url: https://charts.konghq.com
chart: kong
version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides:
# The chart's proxy Service: it suffixes the name pinned below with "-proxy"
host: "{{ .context.rendered_name }}-proxy"
port: "{{ .infra.proxy_port }}"
protocol: "http"
# The contract's other keys: empty while nothing is wired to the models
# socket, and while metrics are off
endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}'
model: '{{ optional .values "model" "" }}'
metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

云资源命名准则。

输出云资源名称的 Recipes——S3 存储桶名称、RDS 数据库标识符、IAM 角色名称、CloudFormation 栈名称,以及其他任何值占用云服务商全局命名空间的字段——必须将 {{ .metadata.release_name }} 和/或 {{ .context.instance_id }} 拼接到渲染出的名称中,以免同一个 Recipe 在多个 Releases 或多个组件实例中运行时发生冲突。示例 B 中的 bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" 是标准模式。

凡是名称受单一全局命名空间约束之处,都适用该准则。AWS S3 存储桶名称在一个区域内的所有账户间共享全局命名空间;同一个 Aggregate 的两个 Releases(prod-billing 和 staging-billing)不能都部署名为 customer-data 的存储桶——第二次部署会在运行时被 AWS 拒绝而失败。拼接 release_name 可区分 Release;拼接 context.instance_id 可区分每个组件实例;两者都拼接则可区分每个 Release 中的每个组件。

编译器检查什么、不检查什么。 编译器不会检查 valuesMapping: 的输出中是否有缺少这些插值的云资源名称字段。该准则由 Recipe 作者(他们知道哪些字段为目标服务商命名全局唯一资源)和评审者(他们在 PR 评审时发现未命名资源的模式)共同维护。linter 插件可以标记那些 valuesMapping: 输出引用了云资源名称字段却没有 release_name / instance_id 插值的 Recipes;linter 插槽已经提供,并通过 aggrega lint 运行(见 plugins/plugin-contract.md “Placement criterion: the linter socket vs the governance verdict roles”),而发布用 linter 的规则中没有一条检查这一点。

该准则是由约定维护的若干社会契约之一——作者从文档而非编译器强制中了解的编写准则。完整的约定列表以及每项契约分类的架构依据,见 vocabulary/social-contracts.md。

source 字段模板化。 Recipe 的 source 字段本身就是一个模板化接口。source 的两种形式都接受 Go 模板:通用字符串形式

source: "{{ optional .infra `module_path` \"./src\" }}"

以及结构化对象形式(每个字符串值子字段都会进行模板求值;非字符串子字段原样传递)。source 模板可以读取什么,取决于该 source 是否指向远程制品。 远程 source 的坐标——指向 registry、chart 仓库或 git 仓库的结构化块中的 version、chart、ref 和 module_subdir——在 aggrega pull 解析制品以将其锁定时求值,只针对 .values、.infra 和 .locals,只能使用 Aggrega 自身的辅助函数(optional、capitalizedWords 和 index),不能使用任何 Sprig 函数。.context 不在该接口上,因此为某个组件锁定哪个制品,取决于提供给它的 values 和 infra,绝不取决于其实例名称。在此处求值的 locals: 条目,是这些字段读取的条目,以及这些条目又读取的条目:没有任何 source 字段读取的条目在解析 source 时不会求值,因此只有渲染才需要的 local——调用 Sprig 函数的,或读取 .context.instance_id 的——不影响锁定,并在节点渲染时求值。以不指明具体条目的方式读取 .locals 的字段,例如 {{ index .locals "version" }},会使所有条目都被求值。指向工作区中某个路径的 source(如上例)不会为锁定而解析:其模板在节点渲染时求值,针对与 Recipe locals 相同的自包含上下文——.context.instance_id、.values、.infra 以及 .locals(该节点完整的已解析块)——因此它接受和拒绝的引用根与 locals: 条目相同,只有一点更宽松:它可以读取块中声明的任何条目,而不仅是位于其上方的条目。远程坐标同样可以读取块中声明的任何条目。.provides 不在这两个上下文中,source 模板若试图读取自身节点的 provides,构建会中止并指出出错的引用。这是该接口的固定属性,而不是等待后续工作填补的空缺——节点的 locals 先于其 provides 解析,以便 provides: 可以读取 .locals,而 source 模板读取的是同样这些已解析的 locals,而不是向前去取 provides。出于同样的自包含理由,禁止引用 .context.inject 和 .context.uses;source URI 必须在拓扑管道注入数据之前、在任何下游加载该 URI 指向的 chart、模块或制品内容之前解析。完整的可用性规则和禁止引用的依据见模板展开矩阵第 5 行。标准用法是将 Component 暴露的 infra.source_version 覆盖值传入 source 的 version 字段——见 entities/component “The infra Pillar”——这样目录无需在每次兼容的上游版本升级时重新发布 Recipe。

source 字段方案清单。 source: 字段在 schema 中接受多种形式变体。每种变体的运行时支持因 provider 而异;下表记录了每种形式的作用。

形式示例状态
裸相对文件系统路径source: "./charts/postgres"available——所有已发布的 provider(helm、helm-chart、compose、terraform、cloudformation)都接受裸文件系统路径字符串。
裸绝对文件系统路径source: "/abs/path/to/chart"accepted but blocked——schema 接受它,但每个读取该 Recipe 的命令都会拒绝它:绝对路径指向的是编写它的那台机器上的位置,而不是 Recipe 自身目录中的内容,因此它不会随 Recipe 一起迁移。请将 chart 移入 Recipe 的目录,并使用相对于该目录的路径;见内容路径保持在 Recipe 自身目录内。
空字符串source: ""accepted but blocked — schema 接受空字符串,但每个加载该 Recipe 的命令都会在读取该 Recipe 时拒绝它,因为空字符串不指定任何一种模式。该拒绝会指出其中的歧义,并给出两种解决方式:省略该字段以使用无源模式,或为其提供真实的路径或 URI 以使用有源模式。aggrega validate <recipe-file> 针对该 Recipe 报告它,而 aggrega pull、aggrega build 和 aggrega validate --release 针对到达该 Recipe 的 Release 报告它。参见 errors/fatal-halts.md 中的“Recipe source: is an empty string(Recipe 的 source 字段为空字符串)”。
url: 带有传输协议方案的结构化对象source: { url: "oci://…/mariadb", version: "25.0.8" }available — 内置的 source-resolver 读取 {kind, url, version, chart, ref, module_subdir} 形式(由 url: 的协议选择类型:oci:// → OCI chart,https://….tgz → chart 归档,https:// 仓库根地址搭配 chart: → 仓库 chart;也可以用 kind: 显式指定),在 aggrega pull 时拉取并固定该制品,构建时从缓存中解压。也支持将 chart 本地 vendor 作为替代方案,但这不是必需的。schema 接受开放的结构化对象。参见 providers/helm.md “source: keyset”。
url: 指向文件系统路径的结构化对象source: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" }available — 不带传输协议的 url: 指向一个路径,因此不会拉取也不会固定任何内容;构建从磁盘读取内容。相对 url: 以声明它的 recipe.yaml 所在目录为基准,离开该目录的路径(包括绝对路径)会被拒绝:这与上面两行裸路径的解读相同,你采用的书写形式不会改变它。只有 url: 决定从哪里读取内容;其他字段选择的是本应拉取的内容,并且仍以 .source.* 的形式传给该 Recipe 的模板。
OCI URI(oci://...)source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0"planned — 面向 catalog 分发的设计目标。当前的三层解析器(Release 按路径指定的文件、工作区 catalog、远程 OCI 仓库)记录在 architecture/13-catalog-and-registry.md 中;实体级解析器通过该级联使用 OCI URI,但目前各 provider 尚未接入单个 Recipe 的 source: 字段的 OCI 形式。
其他 URL 协议(https://、git+https:// 等)(示意)planned — 作为设计意图记录在架构的可插拔 source 路线图中;目前没有 provider 支持。

source: 路径如何锚定。 锚定只适用于文件系统路径,不适用于其他任何内容,并且无论路径由两种形式中的哪一种承载都适用。相对路径以声明它的 recipe.yaml 所在目录为基准,离开该目录的路径(包括绝对路径)会被拒绝,详见 内容路径保持在 Recipe 自身目录内。带有传输协议的引用(oci://、https://、http://、git://、ssh://、git+ssh://,或任何以 .git 结尾的引用)指向的是待拉取的内容而非路径,因此会按你书写的原样传递,绝不会与目录拼接。

在结构化形式中,路径就是 url: 字段,其解读方式相同:相对 url: 以 recipe.yaml 所在目录为基准,离开该目录的会被拒绝,带传输协议的则会被拉取。结构化 source: 的其他所有字段(包括 provider 定义的字段)都原样传递。

以模板形式书写的 source: 依据模板产生的值进行锚定,而不是依据模板自身的文本。模板在求值之前不指向任何内容,因此上述解读作用于其结果:结果为相对路径时,以 recipe.yaml 所在目录为基准;离开该目录的结果(包括绝对路径)会使构建中止;带传输协议的结果会被传递并拉取。因此,模板可以产生上表中的任何形式,每种形式的处理方式都与直接书写相同的值完全一致;区别仅在于何时能够判断路径:对模板而言,是在构建对其求值时,而不是在读取 Recipe 时。

不产生任何内容(结果为空)的模板会使 Recipe 没有 source,即无 source 模式。这与你自己书写 source: "" 不同,后者不指定任何模式,会被拒绝;参见上表中对应的行。

该清单是作者可以在 source: 中填写哪些内容的权威参考;其标签即 10-status.md 所定义的标签。

内容路径须位于 Recipe 自身的目录内

Recipe 的内容位于该 Recipe 自身的目录中,因为其发布所携带的每个文件都取自该目录。Recipe 为其携带的内容所写的每个路径——它的 source:(无论是裸路径还是结构化形式的 url:),以及其 valuesMapping:、workload: 和 artifacts: 条目通过 $import: 导入的每个文件——都相对于包含 recipe.yaml 的目录读取,并且必须位于该目录内。这些路径也正是发布所携带的内容:它们指向的文件随 Recipe 一起分发,而其目录中的其他任何内容都不会(参见 aggrega push)。离开该目录的路径指向一个不会随 Recipe 分发的文件,因此使用方无法获得该文件,而基于它记录的固定版本将为使用方无法获取的字节作担保。

有两种形式会离开该目录,两者都会被拒绝:

  • 向上越出该目录的路径,例如 ../shared/charts/app;
  • 绝对路径,例如 /opt/charts/app,它指向编写它的那台机器上的某个位置。

向上越出后又回到目录内的路径,是目录内的普通路径:./charts/../values.tmpl 指向 Recipe 旁边的 values.tmpl。判定的依据是路径最终落在何处,并且从 Recipe 的目录出发、不离开该目录来衡量——因此,越出后在返回途中再次指明该目录的路径,例如在名为 1.0.0 的目录中写下的 ../1.0.0/values.tmpl,同样会被拒绝。目录本身的名称不会随之分发:已发布的 Recipe 是从使用方缓存所命名的目录中读取的,在那里该名称找不到任何内容。

在何处被拒绝。 每个读取 Recipe 的命令都会在读取时拒绝此类路径,早于任何获取、渲染或发布操作:aggrega validate(无论针对目录(catalog)还是 Recipe 自身的文件)、aggrega pull、aggrega build、aggrega pin 和 aggrega push。以模板形式编写的 source: 在构建对其求值之前不指向任何内容,因此生成目录外路径的模板会由构建在该值产生的那一刻拒绝。对应的终止错误为 A path names content outside the entity’s own directory(路径指向实体自身目录之外的内容),它会给出你所写的路径。

应当怎么做。 把文件放在 Recipe 的目录中,或放在其下的某个目录中,并以相对于 Recipe 的路径命名它:./charts/app、./extras/netpol.yaml。多个 Recipes 共用的 chart 会被复制到每个 Recipe 的目录中,因为每个 Recipe 都是单独发布的;多个 Recipes 共享的 mapping、workload 或 artifact 主体应放在 MappingLibrary、WorkloadLibrary 或 ArtifactLibrary 中,由每个 Recipe 按标识引用。

为什么 Release 不同。 Release 指向其他实体——它的 Aggregate、它的 Manifest、它所扩展的 Release——并且从不发布,因此它读取的任何内容都不会被分发到任何地方。这些引用,以及其 parameters: 导入的文件,都按所写内容读取,正因如此,同一个 Aggregate 才能被子目录中的各个 Release 变体共享。参见 entities/release.md。

同样的限制也适用于 FeatureRecipe,以及 Component 或 Feature 导入的每个 schema。

workload: 字段——合成输入类型

Recipe.spec.workload: 声明编译器合成为 provider 原生资源的 Workload 主体。它是 Recipe 可以声明的三种输入类型之一,另外两种是 source:(源渲染)和 artifacts:(辅助清单)。对每个 provider 而言,三者中至少必须存在一个;构建不负责供应的服务则声明一个 form: reference 的 workload:。

该字段接受三种编写模式——内联块标量、文件 $import: 或库 $import:。编译器根据字段的内容形状进行分派;无需 $mode: 注解。

**模式 1:内联(Go 模板字符串标量)。**值是一个 YAML 块标量,其输出解析为 aggrega.ai/v1beta1 Workload:

spec:
capability: helm
implements: core/web-server:1.0.0
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra "replicas" 1 }}
containers:
app:
image: "{{ .values.image }}"
ports:
http: 8080

Workload 的字段位于文档根部——没有 spec: 包装层——且 containers: 和每个容器的 ports: 是按名称作为键的映射而非序列,并保留作者编写的顺序。provider 将该形状转换为其自身的原生形式,因此一个容器映射条目在 helm 的渲染输出中呈现为一个以其键命名的 containers[] 元素;编写的形状是映射,而非渲染后的列表。

**模式 2:文件 $import:。**值是一个只含单个 $import: 键的映射,该键指向一个本地 Go 模板文件:

spec:
workload:
$import: ./workload/web-server.yaml.tmpl

路径解析与 valuesMapping: 一致:相对路径以声明它的 recipe.yaml 所在目录为基准,而不是以调用构建的目录为基准,并且必须保持在该目录之内。导入的主体是一个在 Recipe 的渲染上下文中求值的 Go 模板,与内联主体完全相同。

**模式 3:库 $import:。**值是一个只含单个 $import: 键的映射,该键携带指向某个 WorkloadLibrary 条目的裸名称身份引用:

spec:
workload:
$import: BaseWorkloads#/workloads/StatelessService

#/workloads/ 片段用于选择 Workload 条目,也正是这个片段将此引用与 valuesMapping: 使用的 #/mappings/ 形式区分开来——后者指向 MappingLibrary 条目,并不指定 Workload 主体。该引用不携带注册表主机,解析出的版本来自每个 Release 的锁文件,可以用 <Library>:<version>#/workloads/<Entry> 的形式声明可选的 :<version> 最低版本下限,而主体本身是字段根 $import: 的条目会递归解析。导入的主体是一个在使用方 Recipe 的渲染上下文中求值的 Go 模板,因此 .values、.infra 和 .features 会像流入内联主体一样流入其中。关于该库实体及完整的引用语法,参见 entities/workloadlibrary。

目标 provider 必须支持合成(按照约定,标准库目录会在此类 provider 上声明 workloadSchema);以无法合成的 provider 为目标时,会在节点渲染时被拒绝,并给出 provider 能力诊断——该诊断依据的是 provider 能力,而不是 workloadSchema 是否存在。关于完整的 Workload 语法、K8s 形状的透传字段以及各 provider 的转换行为,参见 entities/workload.md。关于更全面的三种输入类型模型,以及将合成结果与源渲染输出和制品合并的组装器,参见 architecture/16-recipe-input-composition.md。

将组件自身的值交付给开发者自己的镜像。按照标准库目录的约定,运行开发者所构建镜像的 Recipe 预期会从 .context.inject 交付开发者的 inject: 块解析出的全部内容,也可以用它自己选定的名称交付组件自身的值。当 Component 声明了 spec.inject 时,名称由开发者自己的块来选择,而 .context.self_inject 会告诉 Recipe 每个条目的模板所读取的那一个自身值——对于恰好只读取一个自身值、不读取其他任何内容的条目,即为 values.<key>。标准库目录的约定是把 Recipe 为这些值所取的名称视为默认名称,而不是开发者代码必须读取的契约:只有在没有任何条目映射到某个值时,才以其默认名称交付该值;企业目录可以另作选择。模板上下文契约给出了该映射的确切规则以及一个完整的模板示例。

artifacts: 字段——辅助清单

Recipe.spec.artifacts: 是一个从条目名称 → 制品主体编写的映射,其中的条目会在该 Recipe 的源渲染或合成的主输出之外,额外生成清单文件。它是三种输入类型(源渲染 / 合成 / 制品)之一——一个 Recipe 可以只声明 artifacts:,也可以与 workload: 和/或 source: 一起声明。

每个条目的值采用三种按内容形状分派的模式之一,与 workload: 对应——内联内容、文件 $import: 或库 $import:。编译器根据值的内容形状进行分派,无需 $mode: 注解。在三种模式下,映射键都命名该条目生成的内容:对两种单文件模式,它是输出文件名;对捆绑包模式,它是捆绑包文件所嵌套的目录。由于键命名的是输出,它被限定在单个文件名所能取的范围内:以字母或数字开头,后接字母、数字、点、连字符和下划线。点用于保留键按约定携带的扩展名——main.tf、template.yaml、serviceaccount.yaml——而该字母表不允许 /(否则键命名的将是路径而非文件),也不允许以 . 开头,因此键永远不会是父目录段。超出该字母表的键会在工作区加载时、在 aggrega validate 中以及在编辑器诊断中未通过信封校验。

spec:
capability: helm
implements: core/web-server:1.0.0
artifacts:
extra-configmap.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: "{{ .context.instance_id }}-extras"
data:
threshold: "{{ .values.threshold }}"
network-policy.yaml:
$import: ./artifacts/network-policy.tmpl
operator-support:
$import: PlatformArtifacts#/artifacts/OperatorSupport

模式 1:内联(Go 模板字符串标量)。 值是一个块标量,映射键即输出文件名,按原样使用——上面的第一个条目生成 extra-configmap.yaml。

模式 2:文件 $import:。 值是一个只含单个 $import: 键的映射,指向一个本地 Go 模板文件,并且映射键即输出文件名,与模式 1 完全相同。被导入的文件提供内容,但不提供名称。上面的第二个条目的键为 network-policy.yaml,生成 network-policy.yaml,尽管它导入的文件名为 network-policy.tmpl。因此,想要特定输出文件名的作者把它写作键;两个条目导入恰好同名的不同文件——./extras/shared.yaml 和 ./overrides/shared.yaml——则是两个不同的输出。路径解析与 valuesMapping: 和 workload: 一致:相对路径锚定到包含声明它的 recipe.yaml 的目录,而不是调用构建时所在的目录,并且必须保持在该目录之内。

模式 3:库 $import:。 值是一个只含单个 $import: 键的映射,携带对某个 ArtifactLibrary 捆绑包的裸名称身份引用 <Library>#/artifacts/<name>。捆绑包是作为一个单元导入的一组文件,因此一个条目会按捆绑包中的每个文件展开为一个输出,每个输出以 <key>/<filename> 的形式嵌套在映射键之下——键命名的是使用位置,是这些文件所在的目录,而不是其中任何一个文件的名称。上面的第三个条目的键为 operator-support;如果 PlatformArtifacts#/artifacts/OperatorSupport 声明了 crd.yaml 和 rbac.yaml,这个单一条目就会生成 operator-support/crd.yaml 和 operator-support/rbac.yaml。该引用不携带注册表主机——带主机的 oci://… 形式会被拒绝——解析出的版本来自每个 Release 的锁文件,并且可以用 <Library>:<version>#/artifacts/<name> 断言一个可选的 :<version> 最低版本下限。关于该库实体和完整的引用语法,参见 entities/artifactlibrary。

文件 $import: 固定在 Recipe 旁边。 aggrega pin 会将每个被导入文件字节的摘要记录在该 Recipe 目录中的 entity.lock 里,以条目的映射键为键;aggrega build 会再次计算该文件的摘要,并在不再匹配时以 [CATALOG_ERROR E0026] 停止——或者当 Release 的锁文件(在编辑之前写入)按 Recipe 所携带的内容记录该 Recipe 时,先以 E0130 停止——因此固定后被编辑的文件绝不会在未经验证的情况下被渲染。如果该更改是有意的,请对该 Recipe 运行 aggrega pin 以记录新的摘要;否则请恢复该文件。内联条目是 Recipe 文件的一部分,库条目则由锁文件记录的库版本固定,因此两者都不带有自己的固定记录。aggrega pull 描述了该文件。

无论条目主体由哪种模式提供,每个制品条目的模板都使用与 valuesMapping: 相同的模板上下文求值。两个具有相同文件名的输出会在节点渲染时使构建停止。同一个 artifacts: 映射中的两个条目不可能命名同一个输出:映射键在一个文档内唯一并且拼写单个文件名,因此单文件条目的输出就是它的键,而捆绑包条目的文件位于以其键命名的目录之下——条目生成的每个路径的第一段都是产生它的键,因此无论被导入的文件叫什么,不同的键始终是不同的输出名称。该停止所涵盖的是由两种不同输入类型贡献的同一个文件名——例如 chart 模板和制品条目都生成 servicemonitor.yaml——它会针对该 Recipe 报告,诊断信息会列出每个贡献来源。

使用场景。 artifacts: 用于存放主 chart 或模块不生成的辅助资源:伴随工作负载的 NetworkPolicy、与 Deployment 配对的 HPA、以 instance_id 为键的边车 ConfigMap。适用于多个组件的横切辅助资源(例如附加到每个数据存储的备份边车)应放在 FeatureRecipe 的资源生成中,而不是每个 Recipe 的 artifacts: 中——关于 FeatureRecipe 的扩展面,参见 entities/featurerecipe.md。

boundary: 块——用于边界共享输出的文件

大多数 Recipes 从不需要它。Recipe 写入的其他所有内容都属于它自己的组件:provider 会将其放在该组件在边界输出中的自身位置之下。但有些文件属于整个边界——目标为边界部署的全部内容只读取一次的文件。Terraform 的 provider 配置是常见情形:Terraform 的文档要求被其他配置调用的模块中不包含 provider 块,而自带此类块的模块无法通过 depends_on、count 或 for_each 调用。spec.boundary.artifacts 就是 Recipe 写入此类文件的位置。

spec:
capability: terraform
implements: core/api-gateway/azure-api-management:1.0.0
artifacts:
main.tf:
$import: ./module/main.tf
boundary:
artifacts:
# Terraform reads this beside the root configuration; one copy serves every
# component of the boundary that declares it.
provider-azurerm.tf: |
provider "azurerm" {
features {}
}

该块是第二个作用域上的 artifacts:。 artifacts 是它唯一的成员,其形状与 Recipe 自身的 artifacts: 完全相同:同样的三种模式——内联内容、文件 $import:、库 $import:(其文件以 <key>/<filename> 的形式嵌套在条目的键下)——同样的键到文件名规则和同样的键字母表,以及同样的模板上下文,因此条目读取 .values、.infra、.locals 等内容的方式与 artifacts: 条目完全一致。它至少需要一个条目,boundary: 下的任何其他成员会在读取 Recipe 时被拒绝。FeatureRecipe 没有这样的块。

文件写入的位置。 只写一次,写入存放边界组装输出的目录,位于 provider 自身组装写入该目录的文件旁边——对于 terraform,位于 aggrega.modules.tf 根配置旁边,而不是组件的模块内部。provider 不会收到这些文件中的任何一个:编译器自行求值并写入它们,且不会在文件中标记它来自哪个组件,因为它属于声明它的每一个组件。模板渲染结果为空的条目不写入任何文件。

多个贡献者如何汇合。 对于 Recipe 在边界中渲染的每个组件,每个条目都会求值一次,边界的所有贡献者声明的文件按名称合并。同一名称求值得到相同字节——无论是由绑定到同一 Recipe 的两个组件,还是由以相同方式配置同一 provider 的两个 Recipes——即为同一个文件。同一名称求值得到不同字节则会终止构建,并指出该文件和每个贡献者,因为没有任何单一文件是它们全部所写的内容;与 provider 自身组装所写名称(如 aggrega.modules.tf)相同的名称也会终止构建。两者都属于组装输出冲突。以两个不同文件名配置同一 provider 的两个 Recipes 不会被合并——每个文件都会写入——此时由目标报告重复配置,因此打算共享 provider 配置的 Recipes 应共享其文件名,按约定以其所配置的 provider 命名。

哪些 providers 接受它。 放在边界组装输出旁的文件是否有意义,取决于 provider 的目标,因此这是 provider 自身声明的一部分。声明了该块但其 provider 不接受它的 Recipe,无论其条目渲染为何,都会在任何渲染之前被拒绝;参见 The provider does not support boundary artifacts(该 provider 不支持边界 artifacts)。能力矩阵列出了每个 provider 的声明。

Providerboundary.artifacts:
terraform接受。每个文件都写在边界的根配置旁边,Terraform 会将其与该目录中的所有其他配置文件一起读取。
helm, compose, helm-chart, cloudformation在任何渲染之前被拒绝。

此处的文件 $import: 与 artifacts: 条目导入的文件一样被固定。 实体锁将其摘要记录在同一个 artifactDigests 列表中,键为 boundary/<key> 而不只是键本身,因此两个块中以同一键写入的条目会分别固定。固定步骤会记录它;不执行固定的 pull 在其固定缺失或不再匹配时终止;构建会拒绝自固定以来被编辑过的文件,与拒绝 artifacts: 文件的方式完全相同。

outputLabels: 字段——作者声明的渲染输出标签

Recipe.spec.outputLabels: 是一个标签键 → 值的映射,provider 会将其标记到该 Recipe 渲染输出所产生的每个对象上。它是实现特征的恰当归宿——即某个特定 Recipe 如何实现一个 component 的属性,而不是该 component 本身是什么。以某种实现所使用的持久化存储为例,下文用示例键 example.io/storage-backing 表示:挂载 PersistentVolumeClaim 的 Helm Recipe 与挂载命名卷的 Compose Recipe 通过不同的机制实现同一个 component,因此它们携带不同的 outputLabels,下游工具(成本分摊、策略、资产清单)可以在生成的资源上区分它们。该键仅为示例——example.io/ 是一个示例命名空间,catalog 自行选择其工具所读取的键。

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/storage-backing: persistent-volume
example.io/team: platform

输出标签与固定的构建溯源标签走同一条通道:它们被合并到每个输出面所标记的标签集中,因此溯源标签出现在哪里,它们就出现在哪里。不同之处在于归属——溯源键归编译器所有,outputLabels 归 Recipe 作者所有。

component 自身的身份标签不在此处填写——这是 catalog 的约定,而不是编译器强制执行的规则。 说明 component 是什么、而非某个 Recipe 如何实现它的键——其认知类别、运维类型、按角色划分的能力标签、底层资源由谁运维、其所封装内容的许可类别——都声明在 Component 的 metadata.labels 上;各维度参见 entities/component 中的“The Semantic Label Taxonomy”。Recipe 要将其中某个键放到渲染输出上,应在下文的 outputComponentLabels: 中列出该键,而不是在此处填写键和值。原因在于,字面量条目是 component 已携带值的第二份副本,而第二份副本可能与第一份不一致:Recipe 作者可能在一个节点上填写某种姿态,而该节点的 Component 声明的却是另一种,从而向下游读者传达图中并未表达的信息。提升的条目按引用复制,因此没有会产生偏差的第二份副本。除下文的保留命名空间规则外,核心接受你写的任何内容;该约定由 catalog 作者维护。

保留命名空间。 aggrega.ai/ 和 app.kubernetes.io/ 命名空间保留给平台原生溯源使用。声明了这两个前缀之一下的 outputLabels 键的 Recipe 会在加载时被拒绝,并给出一条指明违规键的明确 catalog 错误。其他所有键都被接受。除此之外,核心不对键或值做检查——对目标引擎的标签面无效的键或值由作者负责,并由下游运行时拒绝;除保留命名空间规则外,编译器不加干预。

按 provider 呈现。 每个 provider 将这些标签转换到其自身的输出面上:

  • helm,workload 合成——同时标记在对象的 metadata.labels 和 pod 模板的 metadata.labels 上,与合成放置溯源标签的位置一致。
  • helm,source-render 和 artifacts——标记在对象的 metadata.labels 上。
  • compose——标记在每个服务的 labels: 映射上。
  • terraform——作为按资源的标签,标记在结构上可寻址的 .tf.json artifact 主体上,尽力而为:已声明 tags(AWS/azurerm)或 labels(Google)映射的资源块会在其中接收输出标签,作者声明的键永不被覆盖,没有此类属性的资源保持不变(永不凭空添加属性)。原生 HCL 主体(main.tf、*.tf)和 vendored 模块按原样输出,不携带注入的标签。Terraform 溯源信息仍通过其配套的注释文件传递,与标签通道相互独立。

输出标签仅限于标签;不存在单独的输出注解面。outputLabels 由 Recipe 作者(由运维编写的实现层)声明,而不是由 Aggregate 声明——它描述的是实现,绝不是开发者抽象图中的身份。

outputComponentLabels: 字段——提升组件自身的标签

Recipe.spec.outputComponentLabels: 是一个标签键的列表,而不是键值对的列表。对于其中列出的每个键,provider 都会把该键标记到渲染输出上,其值取自正在渲染的组件实例上该键所带的值。outputLabels 给出一个值,而 outputComponentLabels 指明从哪里读取这个值。

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/team: platform
outputComponentLabels:
- component.aggrega.ai/hosting

假设某个 Component 的 metadata.labels 声明了 component.aggrega.ai/hosting: managed,那么该 Recipe 为这个组件渲染的每个对象都带有 component.aggrega.ai/hosting: managed。把同一个 Recipe 绑定到声明 self-hosted 的组件上,该组件的对象就会改为带有 self-hosted——一个 Recipe、一个指定的键,每个组件各有其值。

**提升是按引用进行的,这正是关键所在。**每次渲染输出时都会从组件读取该值,因此它不会与其来源的身份产生偏差:组件的标签变化时,不存在需要同步的第二份副本。一个重述组件标签的字面 outputLabels 条目就是那第二份副本,只要其中任意一方发生变化,两者就不再一致。因此,当值是该 Recipe 实现组件方式的一种属性时,使用 outputLabels;当值已存在于组件上、且渲染输出也应带有它时,使用 outputComponentLabels。

被提升的键与字面键落在完全相同的位置——上文所述的各 provider 呈现方式原样适用,没有任何 provider 会区分被提升的键和直接写入的键。

保留命名空间。aggrega.ai/ 和 app.kubernetes.io/ 命名空间保留给平台原生的来源信息,位于其中任一前缀下的被提升键会在加载时被拒绝,并给出一个指明该键及其所在字段的目录错误。判断依据是裸前缀:诸如 component.aggrega.ai/hosting 这样的键位于自己的命名空间中,而不在保留的根之下,因此可以被提升。

**一个键只属于其中一个块。**在 outputLabels 和 outputComponentLabels 中声明同一个键会在加载时被拒绝,因此每个被标记的键都只有单一来源——要么是写在 Recipe 上的字面值,要么是组件自身的标签,绝不会两者兼有。

**组件未声明的被提升键不会标记任何内容。**构建会继续,并发出一条指明节点、Recipe 和缺失键的警告。这是有意为之:绑定到标签集不同的多个组件的 Recipe 仍然可以渲染,差异会被报告出来,而不是导致中止。

**单一形态的组件——这是约定,而非规则。**提升会携带组件声明的任何值,编译器不会解释该值。因此,如果某个组件的身份标签存放的是代表“不固定”的占位符,该占位符就会被提升到为它渲染的每个对象上。当一个组件确实具有不止一种形态时,标准库目录的约定是:由每个 Recipe 通过该 Recipe 自有的 outputLabels 键来声明其自身实现的形态,而不是通过组件的身份键——按照同一约定,身份键改由 outputComponentLabels: 传递——或者干脆不标记任何内容。这两个键回答的是不同的问题,彼此不能替代:身份键说明组件在所有实现中是什么,Recipe 自有的键说明这一个实现做了什么。这是由目录作者维护的目录约定,而不是编译器强制执行的约束。

locals: 块

Recipe.spec.locals: 是私有运维状态(Private Ops State)——一个由具名 Go 模板字符串组成的映射,其渲染输出向该 Recipe 后续的模板暴露一个 .locals.* 映射。它是一个工作区,用于一次性计算物理实际(目标容器、JSON 路径、派生主机名),并在 provides:、source:、valuesMapping:、workload:、artifacts:、assertions: 和 pipeline[].with 载荷中复用,无需重复计算。每个条目的渲染输出在存储时会去除首尾空白。

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
locals:
primary_compute: postgresql
listen_port: "5432"
secret_target_db_password: "postgres-auth"
volumes_path: "/spec/template/spec/volumes"
valuesMapping: |
primary:
auth:
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"

locals: 从不暴露给调用方——通过 uses: 使用该 Recipe 的下游组件只能看到 provides:。该 Recipe 自身的 provides:、source:、valuesMapping:、workload:、artifacts:、assertions: 和 pipeline[].with 模板都能看到已解析的 .locals.* 映射。每个键的值可以是普通字符串或 Go 模板;编译器在 locals 前导阶段、先于该节点的 provides: 解析整个块,因此后续每个模板观察到的都是稳定的已解析值。

每个条目都针对一个自包含的节点本地上下文求值:.context.instance_id、.values、.infra,以及同一块中已解析的条目。local 不能读取 .provides——该支柱不在此求值面上,试图读取它的条目会中止。它也不能读取 .context.rendered_name,即 helm 等 provider 为该节点渲染的资源所赋予的名称,因此命名这些资源之一的 local 只包含该名称之后的部分,如上文的 secret_target_db_password,由写出完整名称的模板将两者拼接。

编写顺序至关重要

条目按编写顺序解析,条目可以读取在其上方定义的同级条目,并获得该同级条目的已解析值:

spec:
locals:
db_identifier: "{{ .context.instance_id }}-postgres" # defined first
secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry above

链式引用只能向下进行。当一个条目读取另一个条目时,条目的顺序决定构建能否成功:把 db_identifier 移到 secret_target 下方,构建就会中止。编译器从不为了让引用得以解析而对块进行排序或重排,因此编写顺序就是契约——重排 locals: 块是行为上的变更,而非外观上的变更。

作者可能犯的两种错误由两种不同的中止区分开来,因为它们的修复方式不同:

  • 引用块中稍后定义的条目会中止,并指出顺序错误;修复方法是把定义移到读取它的条目上方。
  • 引用块中根本未声明的键会中止,并指出该键;修复方法是更正拼写。

检查会跟随块的别名。通过 with .locals 主体重新绑定的点访问的键,或通过绑定到 .locals 的变量访问的键,与直接写法受到完全相同的检查:{{ with .locals }}{{ .nope }}{{ end }} 和 {{ $l := .locals }}{{ $l.nope }} 都会中止并指出 .locals.nope,与 {{ .locals.nope }} 一样;{{ (.locals).nope }} 和 {{ ($.locals).nope }} 也是如此,因为括号产生的就是块本身,别无其他。只有一种写法可以绕过该检查:通过模板文本无法确定其结果的调用访问的键——{{ index .locals "nope" }} 或 {{ (default dict .locals).nope }}——因为这种调用的结果在模板运行时决定,而不取决于所写的内容。作为字段从这类调用的结果上读取不存在的键不会中止,并且会渲染出字面文本 <no value>,而不是空内容。通过 index 访问不存在的键会中止并指出该键,因为当 index 读取的映射中没有所请求的键时,它在每个模板求值面上都会中止——这与本检查的报告不同,记录在 errors/fatal-halts.md 的“A template indexes a map with a key the map does not hold(模板使用映射中不存在的键对映射进行索引)”下。因此,index 仍是访问名称本身需要计算的键的方式,例如 {{ index .locals (printf "secret_target_%s" .values.slot) }},而块中未声明的计算名称仍会按其键报告。

provides: 读取 .locals 并获得已解析的值,因为节点的 locals 先于其 provides 解析。命名 locals 块中未声明的键的 provides: 模板会中止。这意味着 provides: 条目和 artifact 都需要的值只需在 locals: 中编写一次,然后从两处读取。

关于对应的公共 API,请参阅下文的 provides: 块。FeatureRecipe 求值面遵循相同的规则——请参阅 entities/featurerecipe.md 中的“locals: 块”。

provides: 块

Recipe.spec.provides: 是公共开发者 API——一个“名称 → Go 模板字符串”的映射,声明该 Recipe 向下游调用方的 .context.inject 和 .context.uses 管道提供的值。编译器在 provides 求值阶段(自包含,顺序任意)对 provides: 模板求值;调用方的 inject 键在 inject 注入阶段根据这些值解析。

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
provides:
# The Service this chart names after its release name, suffixed "-postgresql"
host: "{{ .context.rendered_name }}-postgresql"
port: "5432"
database: "{{ .values.db_name }}"

每个条目的模板都在自包含的 provides 求值上下文中求值——.context.instance_id、.context.rendered_name(当节点的 provider 报告该值时)、.values、.infra、节点已解析的 .locals 以及静态文本。节点所在的命名空间不在其中,因此发布的主机名不带命名空间:位于其他命名空间的使用方在自己一侧对其加以限定。.locals 之所以在其中,是因为节点的 locals 在同一阶段的前置步骤中解析,先于其 provides;provides 模板若引用 locals 块未声明的键,则会停止。将 provides 求值与 inject 注入分开至关重要:Recipe 的 provides: 不能引用任何调用方的状态,因为 provides 求值运行时调用方尚未解析——根据架构不变量,provides: 是自包含的。随后,调用方在自己的模板中通过 .context.uses.<alias>.provides.<provided-name> 读取这些值——提供的名称嵌套在边上的 provides 之下,与边的其他字段并列。在边上声明了 inject: 允许列表的调用方则改为通过其 .context.inject 管道获取相同的值。

provides: 的键是 Recipe 契约接口的一部分。重命名或删除某个键,对所有依赖旧名称的调用方都是破坏性变更;implements: 接口版本应反映契约的演进。关于级联解析语义、inject 管道契约,以及涵盖跨命名空间和跨区域路由的完整示例,请参阅 architecture/06-data-taxonomy-and-composition.md §3 和 templates/expansion-matrix.md。

读取附件发布的值

Recipe 在 .features.<instance-name> 处读取附加到其组件的 Features,在 .features.<slot> 处读取凭据 Features。两者是相同的附件结构——.type、.values、.infra、.provides——因此无论附件位于哪个映射中,读取方式都相同;两者的区别在于附件产生的内容。

.provides 是附件发布的输出,由绑定到该附件的 FeatureRecipe 解析得出。它是上文 provides: 块从消费方看到的对应物:Recipe 向其调用方发布,而附件向其宿主组件发布。

workload: |
# The identity attachment emits a ServiceAccount and publishes its name;
# the pod binds to that published name rather than restating it.
serviceAccount: "{{ .features.identity.provides.name }}"
containers:
main:
env:
DB_SECRET: "{{ .features.app_credentials.provides.name }}"

读取已发布的值,而不是从相同的 values/infra 输入重新计算,区别在于名称只有一处声明,还是有两处可能逐渐不一致的声明。完整的逐字段结构(包括可用性规则)见 templates/template-context-contract.md。

写在组件某个连接上的附件——即组件向某个目标出示的凭据——以相同结构在该连接下读取,位于 .context.uses.<alias>.features.<slot>,且从不出现在 .features 中。访问多个目标的 Recipe 在每个目标的别名下读取该目标自己的凭据,而遍历 .features 并按类型挑选附件的循环只会遇到组件自身的附件:

artifacts:
routes.yaml: |
{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
{{- end }}{{ end }}
{{- end }}

关于其结构以及模板遍历连接的顺序,参见连接的附件。

pipeline: 字段

Recipe.spec.pipeline: 是一个按顺序排列的 Wasm 流水线步骤数组,这些步骤在渲染之后作用于渲染出的文档集,每个步骤返回 RFC 6902 补丁和副作用。每个条目声明一个 id(每个步骤的标识符:字母、数字和下划线)、一个 plugin(该步骤运行的 Plugin 实体,按其插件类型限定作用域——pipeline-step/<name>,可带版本;裸 .wasm 或制品引用会被拒绝)、一个 function(要调用的插件导出函数)、一个可选的 with: Go 模板体(提供插件的载荷),以及一个可选的 when: Go 模板(控制该步骤是否运行)——结果为假值时,该步骤作为直通被跳过,文档集保持不变。when: 门控、它与 optional: 的相互独立,以及它的真值规则,在 entities/featurerecipe.md 的“Conditional steps — when:”中有完整说明:

spec:
capability: helm
implements: core/web-server:1.0.0
source: { kind: helm-oci-chart, url: "oci://…", version: "…" }
pipeline:
- id: inject_sidecar
plugin: pipeline-step/envoy-sidecar:1.0.0
function: Inject
with: |
target_container: "{{ .locals.primary_compute }}"
envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"

编译器按声明顺序执行基础 Recipe 的 pipeline: 步骤,方式与执行 FeatureRecipe 的 pipeline: 相同:针对渲染输出调度每个步骤所指定的 Wasm 插件,将返回的 JSON Patch 操作应用到所指向的文档,并发出该步骤的副作用。FeatureRecipe 的 pipeline: 字段共享相同的 schema 结构和相同的执行方式——各部分的执行状态请参见 entities/featurerecipe.md 的“Authoring Contract”以及 语言状态。

该字段的机制与 FeatureRecipe 的语义一致:按声明顺序依次求值,将 JSON Patch 操作应用到渲染后的文档,随文档一同发出副作用,并在报告错误时附带指向出错步骤的来源信息。when: 门控渲染为假值的步骤作为直通被跳过,文档集保持不变,交给下一个步骤。

assertions: 块

Recipe.spec.assertions: 是一个可选的映射,由若干具名规则组成,用于表达 Recipe 的实现不变量——即在该 Recipe 所引用的特定 chart 或模块下成立的跨字段规则。每个键是一个规则标识符,会出现在失败消息中;每个值是一段 Go 模板主体。Component 断言表达的是契约层面的不变量,与绑定的是哪个 Recipe 无关;与之不同,Recipe 断言是所选特定实现的属性。

spec:
implements: core/datastore/mariadb:^1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "20.0.0"
assertions:
# Bitnami 20.x: serviceMonitor namespace requirement.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}

上面的规则特定于 Bitnami chart 20.x;如果绑定的是另一个 MariaDB Recipe,它就不适用。契约中的 Component 级规则仍会同时适用,并在更早的流水线阶段求值。

Recipe 断言在 Recipe 绑定之后、渲染之前求值,此时每个节点的 locals 和 provides 都已解析。除实体实例字段(.values、.infra、.uses、.features)外,模板上下文还包含该 Recipe 的 .provides、.locals 和 .recipe.source。其中的 .uses 和 .features 是断言层面较窄的结构,而非 Recipe 模板中的结构:连接的条目包含其目标和别名、目标的 labels、连接自身的 values,以及在 features 下写在该连接上的附加项,但不包含目标发布的任何内容;附加项的条目(无论是组件自身的还是某个连接的)包含其 type、resolved_version 和 values,但既不包含其 infra,也不包含其 provides——断言运行时,附加项的 FeatureRecipe 尚未解析其 provides。因此,引用 .features.<name>.provides 会导致中止,而对它进行感知存在性的读取则会返回其回退值。完整的编写语法、契约级规则与实现级规则之间的职责划分以及完整示例,请参见 templates/assertions-block.md。

omits: 字段——将渲染出的文档排除在源之外

大多数 Recipes 从不需要它。它用于你原样采用的源——最常见的是从仓库获取的 chart——而该源渲染出了你的 Release 不得交付的文档:例如 chart 在每次渲染时都重新生成的 Secret,它会使两次构建结果不同,并且一旦应用,就会覆盖运维人员提供的 Secret。你不会编辑获取来的 chart,也没有任何忽略规则能作用到其中,因此 omits: 是 Recipe 将此类文档排除在构建之外的方式。获取来的 compose 文件也是同样的情况:它可能捆绑了 Release 不得包含的 service、volume 或 config,而 valuesMapping: 覆盖层可以修改它们,却永远无法移除。获取来的 CloudFormation 模板同样如此,它可能声明了 Release 不得创建的资源:valuesMapping: 可以填充它声明的参数,却永远无法移除它的某个资源。

spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/gateway
version: "2.4.0"
omits:
# The chart generates this key on every render; the operator supplies it.
- kind: Secret
name: "{{ .context.rendered_name }}-session-key"
# Left out only where the Release asks for it.
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: "{{ .context.rendered_name }}-dashboards"
namespace: monitoring

它涵盖的范围。 仅限 source: 渲染的内容。workload: 和 artifacts: 条目永远不会被过滤:它们是你在 Recipe 中编写的,因此你不想要的文档不写即可。该键要求存在 source:;违反该规则的文档在读取时即被拒绝,并指明该规则。

条目。 每个条目通过三个字段指明要排除的内容,第四个字段决定它是否生效。前三个字段所指称的内容采用 provider 自身对其源渲染内容的词汇,各 provider 的情况见下表:

  • kind——源所渲染内容的种类:对于 chart,是渲染出的文档的种类——Secret、ConfigMap、Deployment;对于 compose 文件,是 service、volume 或 config;对于 CloudFormation 模板,是资源的 Type——AWS::S3::Bucket。它与结构化 source: 所带的 kind: 无关,后者指明源的获取方式。
  • name——其名称:文档的 metadata.name;compose 单元在 services:、volumes: 或 configs: 下的键;CloudFormation 资源的逻辑 ID,即其在 Resources 下的键。
  • namespace (可选)——文档所在的命名空间,适用于输出带有命名空间的 provider。省略时,该条目指称任意命名空间中具有该种类和名称的内容;渲染结果为空的 namespace 视为未提供。
  • when (可选)——该条目是否适用于本次构建。它最先求值,读取规则与 pipeline 步骤的 when: 相同:结果为 false 时丢弃该条目,其其他字段不会被求值,它既不会交给 provider,也不会被检查;而缺省或为空的 when: 则保留该条目。

kind 和 name 为必填项,带有任何其他字段的条目在读取 Recipe 时即被拒绝。

每个值都是模板,求值所用的上下文与 valuesMapping: 相同。该上下文带有 .context.rendered_name,即 provider 为节点资源指定的名称,也是 chart 通常用来为资源命名的名称,因此条目可以按照 chart 将使用的名称准确指称文档。渲染失败的模板会使构建中止,与 valuesMapping: 模板失败时相同。

每个生效的条目都必须排除某些内容。 provider 会报告每个条目排除了多少单元,未排除任何内容的条目会停止构建,并指明该条目;参见 An omits entry left out nothing the source rendered(omits 条目未排除源渲染出的任何内容)。常见原因是源升级后重命名或移除了该文档,而这一中止正是为了防止被重命名的文档在不被察觉的情况下进入你的输出。若只想在某些情况下排除文档,请用 when: 明确表达,而不要依赖文档不存在。

源仍会完整渲染。 只有其输出被过滤:chart 的每个模板仍会运行,因此失败的模板仍会使构建失败,被排除的文档会先渲染再丢弃。一旦被丢弃,它就不会进入构建之后的任何环节——不会生成文件,不会与其他组件的名称比较,不会成为 Feature 读取的关于渲染的事实,也不会交给任何 pipeline 步骤。

Release 通过 infra 和 parameters 作用于该键。 该键属于 Recipe,因此 Release 不能编写它。但它仍可以决定条目的行为:条目的模板会读取 Release 填写的 infra,而它提供的 parameters 只要被 Aggregate 路由到 Recipe 的 .values,就会到达那里。因此 Release 可以通过 when: 开启或关闭某个条目,如上面第二个条目所示,或决定它所指称的内容。

排除什么由你负责。 构建中没有任何环节知道某个文档的用途。排除了 chart 其余部分在运行时依赖的文档——Deployment 挂载的 Secret、pod 运行所用的 ServiceAccount——会产生能顺利构建、但在应用时失败的输出,除非与之一同应用的其他内容提供了该文档。对于 compose 文件和 CloudFormation 模板,构建确实会检查,因为它们各自声明了自己的引用:剩余内容中仍指称被排除单元的——指称被排除 service 的 service,指称被排除资源的资源或输出——会停止构建,如下表所述。

哪些 provider 支持它。 排除文档只有 provider 能做到,因为只有 provider 知道其源渲染什么,所以 provider 是否支持该键属于 provider 自身声明的一部分。声明了 omits: 而其 provider 不支持该键的 Recipe,会在任何渲染之前被拒绝,无论其条目的 when: 渲染为何值;参见 The provider does not support omits(该 provider 不支持 omits)。

Provideromits:
helm支持。条目通过文档自身的 kind、metadata.name,以及在条目指定了命名空间时文档所在的命名空间,指称 chart 渲染出的文档——来自模板或来自其 crds/ 目录。参见 helm → Sourced mode。
compose支持。条目通过 services:、volumes: 或 configs: 下的键指称所源 compose 文件中的 service、volume 或 config,匹配在 valuesMapping: 合并进文件之后进行,且不指定命名空间:指称其他种类或指定命名空间的条目会在组件渲染时停止构建。若文件中剩余内容仍指称被排除的单元——通过 depends_on、links、volumes_from、service: 网络或命名空间模式、extends、构建上下文,或 volumes: 或 configs: 条目——则停止构建,并指明每个引用。参见 compose → Sourced mode。
cloudformation支持。条目通过 Type 和逻辑 ID 指称所源模板中的资源,适用于目录源中的每个模板,且不指定命名空间:带有命名空间的条目会在组件渲染时停止构建。若模板中剩余内容仍指称被排除的资源——通过 Ref、Fn::GetAtt、DependsOn 或 Fn::Sub 变量——则停止构建,并指明每个引用。参见 cloudformation → Leaving resources out of a sourced template。
helm-chart, terraform拒绝:该 provider 将其源交出,在部署时才渲染,因此构建时不存在可排除的文档。对于本地 chart 或模块,可改用 Recipe 旁边 .aggregaignore 中的一行来排除其中的文件。

FeatureRecipe 上也可编写同一个键;参见 entities/featurerecipe.md。

有关完整示例——排除获取来的 chart 生成的 Secret、同一 chart 在没有该条目时遇到的确定性中止,以及条目未匹配任何内容时的中止,均来自真实构建——参见 ai-gateway-own-webhook-certificate。