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

Aggrega 模板上下文 schema

自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。

Schema id:https://aggrega.ai/schemas/template-context-v1beta1.schema.json

编译器在渲染期间组装并传递给 Recipe 和 FeatureRecipe 模板的视图。渲染附加型 FeatureRecipe 时,编译器还会额外填充:.attachment_name 和 .inject,内容为附加项作用域的上下文;.context.render_facts,内容为宿主的 provider 对宿主渲染所报告的信息;以及在生成附加项自身资源的模板上,.context.used_by,内容为使用其宿主的 component。对于边界作用域的 FeatureRecipe(spec.executionScope: boundary),它为边界运行一次的模板——其中包括它的 locals、provides、source、valuesMapping、artifacts 和 pipeline 步骤——会发现 .context、.workload、.attachment_name、.inject 和 .inject_raw 支柱均不存在,转而填充了 .boundary.* 支柱——参见属性末尾的 boundary 块;它的 injectMapping 针对附加项所到达的每个组件各运行一次,在该组件的上下文中运行,因此它读取 .context.* 和 .attachment_name,而 .boundary 在那里未设置。此视图不会持久化到磁盘,仅在渲染期间存在于编译器内存中。本 schema 记录编译器与 Ops 模板作者之间的契约。

基础渲染各阶段的可用性,按阶段运行顺序排列:

  • Provides 求值(先 locals 前导部分,后 provides):仅节点本地支柱。一个 locals 条目可读取其所在块中位于它上方的条目;provides 模板可读取该节点完整解析后的 .locals。禁止自引用(任何 provides 条目都不能读取另一个 provides 条目)。
  • Source 解析(locals 发布 + source 求值):所有支柱;.source 和 .workload 不存在。这些 locals 在此阶段发布到 .locals,随后基于它们对 source: 求值。
  • Values 映射(valuesMapping):所有支柱 + .source;.workload 不存在。
  • Workload 合成(workload 求值):所有支柱 + .source;.workload 正在求值(不可自引用)。
  • Artifact 求值(artifacts):所有支柱 + .source + .workload(最完整的上下文)。

顶层类型: object

属性

属性类型必需描述
contextobject是由编译器组装的执行上下文,提供身份、拓扑和交付数据。
valuesobject是该节点的不透明认知载荷,已在解析阶段由 schema 校验器校验。原样传递。
infraobject是从 Release 为该节点注入的物理规格载荷。完全绕过 Developer。
localsmap of string是Recipe 自身的私有状态(例如 primary_compute、volumes_path)。在 locals 前导部分求值——早于该节点的 provides——并在源解析阶段发布到此支柱上。每个条目都是一个 Go 模板,针对一个自包含的节点本地上下文求值,该上下文携带同一块中迄今已解析的条目,因此一个条目可以读取定义在其上方的同级条目,并获得该同级条目的解析值。只要一个条目读取另一个条目,编写顺序就是契约的一部分:把定义移到其读取者下方会导致构建失败。对后面条目或对块中未声明的键的 ‘.locals.’ 引用会中止构建。该检查读取的是引用所解析到的路径而不是按键输入的文本,因此直接形式、’{{ with .locals }}’ 块内的读取、通过直接绑定到 ‘.locals’ 的变量进行的读取,以及在括号中从块上读取的键,即 ‘(.locals).’ 或 ’($.locals).’,都同样被覆盖。它不覆盖一种写法:路径不由模板文本决定的引用——通过函数(例如 ‘index .locals’ 或 ‘(default dict .locals).’)到达的引用,或通过其管道应用了函数的 ‘with’ 块或变量绑定到达的引用。这种写法不做分析,以这种方式到达的缺失键不会中止构建:它会渲染出字面文本 '',而不是什么都不输出。唯一的例外是 ‘index’ 本身:在所有模板位置上,当它读取的映射不包含所请求的键时,它都会中止构建并指出该键,因此通过 ‘index .locals’ 到达的缺失键会中止构建。locals 条目不能读取 ‘.provides’。可用于 provides(在 provides 求值阶段、前导部分之后)、source、valuesMapping、workload、artifacts、assertions,并可通过 pipeline[].with(以及 pipeline[].when)提供给下游 Wasm 插件。从不暴露给调用方。
providesmap of string否Recipe 的公共 API 契约。由 provides 求值填充。可在基础渲染的 valuesMapping 中用于自引用(例如 {{ .provides.host }})。在 provides 模板自身内不可用(provides 自包含不变式)。调用方根据这些值解析 inject 键。
featuresmap of template_attachment否该节点上的每个附件,以作者为其指定的实例名为键。无论附件产出什么——运维 Feature、凭据 Feature、身份 Feature——都由同一个支柱承载,因为附件之间的差别在于它们产出什么,而不在于模板如何读取它们。Recipe 读取它们,以便根据所附加的能力调整渲染,并使用附件发布的内容。写在该节点某个连接上的附件不在其中:它在该连接下读取,位于 .context.uses..features.,因此遍历此支柱的模板只会遇到节点自身的附件。
metadataobject否Release 与编译元数据,为确定性命名提供全局身份。可用于所有模板块(valuesMapping、injectMapping、pipeline with)。
attachment_namestring否仅在渲染附件 FeatureRecipe 时填充。包含附件的实例名——即它在所属实体的 featuresSchema 中填充的槽位,或作者为其指定的自由名称(例如 ‘admin_password’、‘db_credentials’)。用于构造每个附件各不相同的确定性资源名,组合在宿主组件名之后:若宿主的 provider 报告了渲染名(如 helm 那样——宿主名以 Kubernetes 名称允许的字符拼写,附件名中的下划线折叠为连字符),则使用 ’{{ .context.rendered_name }}-{{ .attachment_name | replace ”_” ”-” }}‘;若宿主的 provider 未报告渲染名,则使用 ’{{ .context.instance_id }}-{{ .attachment_name }}‘。
injectobject否仅在渲染携带已编写 inject 块的附件 FeatureRecipe 时填充(例如 { env: [ { in: ‘OPENAI_API_KEY’, from: ‘api_token’ } ] })。不同于 .context.inject,后者是基础组件来自 uses 边的预水合交付管道。对于没有编写 inject 的附件以及基础 Recipes,求值为 null/缺失。
inject_rawobject 或 null否inject 块不可变、未经修改的 Developer 意图。该块指明的每种机制——env、file、arg,或诸如 ssm_param 的自定义机制——都位于其自身名称之下,按书写顺序保存完全按原样书写的条目(in,以及 from 或 value),因此 .inject_raw.ssm_param 读取自定义机制的方式与 .inject_raw.env 读取核心机制的方式相同。若 Developer 完全省略了 inject 块,则求值为 null。供 Ops 用于逻辑检查(例如 {{ if not .inject_raw }}),以在 inject 映射的修改之前检测省略。每个条目交付的是该组件自身的哪些 values 或 provides,应从 .context.self_inject 读取,而不是从条目的文本中读取。
stepsmap of object否流水线步骤间通信。仅在 Wasm 流水线的 ‘with:’ 块内可用。每个键是一个流水线步骤 ID,包含该步骤导出的输出。
sourcestring or object or null否已解析的 source 字段内容。在 Recipe 的模板上:在源解析阶段由 Recipe 的 source: 字段经 Go 模板求值后填充,从值映射阶段起可用(valuesMapping、workload、artifacts),当 Recipe 没有 source: 时为 null。在 FeatureRecipe 的模板上:FeatureRecipe 自身的 source: 字段经 Go 模板求值后的结果,在其 valuesMapping 之前求值,并在 valuesMapping 以及其后求值的每个模板(omits、workload、artifacts、pipeline 步骤)中读取,绝不是宿主组件的;当 FeatureRecipe 没有 source: 时为 null。FeatureRecipe 的 injectMapping 在其 source 之前求值,读取的是宿主组件的 source。字符串形式 = URI 路径;对象形式 = 结构化源(例如带已解析版本的 OCI 描述符)。
workloadworkload-v1beta1.schema.json or null否该节点已解析的 Workload 规格。在 workload 合成阶段由 Recipe 的 workload: 字段经 Go 模板求值 + Workload JSON Schema 校验(依据 workload-v1beta1.schema.json)后填充。从制品求值阶段起可用(artifacts),因此 artifacts 无需重复即可引用 workload 字段(例如 ServiceMonitor 读取 .workload.services.metrics.ports.prom)。当 Recipe 没有 workload: 块时求值为 null。模板尝试在 null 值上解引用 .workload.* 时,会在模板求值时以明确的错误失败。
boundaryobject否边界作用域上下文——仅在求值 spec.executionScope 为 ‘boundary’ 的 FeatureRecipe 为边界运行一次的模板时填充。Component 作用域的 FeatureRecipes 不会收到此支柱;它们的 context.instance_id、context.inject、context.uses 以及 .workload 支柱承载的是各组件的数据。边界作用域 FeatureRecipe 为边界运行的模板接收 .boundary.*,以取代这些按组件划分的支柱;它的 injectMapping 在附加项所到达的每个组件的上下文中运行,读取这些按组件划分的支柱,而不会收到此支柱。

不允许其他属性。

template-context.context

由编译器组装的执行上下文,提供身份、拓扑和交付数据。

属性类型必需描述
instance_idstring是当前节点的绝对扁平化 ID(例如 ‘backend’,或对于模块实例 data-layer 的组件 main-db 为 ‘data-layer-zdmain-db’),以每个编写的组件名称都满足的字母表写成。对于同一个 Aggregate,它在多次编译之间是确定且稳定的。它是为该节点构建的、没有任何 provider 为其派生名称的资源的名称——从 Recipe 放置的制品集,以及由以标识命名工作负载的 provider 合成的工作负载——因此为这些资源之一发布的地址就是基于此值构建的。
rendered_namestring否绑定到该节点的 provider 为其为该节点渲染的资源所起的名称——对于作者提供的 source,是所提供模板本身据以渲染的名称,例如 chart 读取的 release 名称;对于它合成的工作负载,是它在派生名称而非写入节点标识时为该工作负载的资源所起的名称,正如 helm provider 使用同一 release 名称所做的那样。只要该 Recipe 命名一个由所提供的 chart 或模块声明、或由此类 provider 合成的资源,无论是在 provides 条目、valuesMapping、workload、artifacts 条目中,还是在流水线步骤的 with 或 when 中,都应读取它,因为 provider 可能使用比编写组件名称所用字母表更受限的字母表来拼写该名称,此时两者会不同。当绑定的 provider 不派生此类名称时为空:放置的制品集的资源,以及由以标识命名工作负载的 provider 合成的工作负载的资源,都带有节点的标识,因此对这些资源应读取 ’{{ .context.instance_id }}‘;而自行编写资源名称的 Recipe 已经知道这些名称。在绑定的 provider 未报告名称时读取此键会中止构建,并说明应改写什么。该拒绝覆盖 Recipe 内联编写的模板;通过 ‘$import’ 提供的 valuesMapping、workload 或 artifacts 条目仅在渲染到达它时才被解析,因此其中的引用会渲染为空值,而不会中止。在绑定到组件附件的 FeatureRecipe 的模板中,它是宿主(HOST)组件的名称,由宿主自己的 provider 报告——即宿主自己的 Recipe 读取的值,正如其中的 instance_id 是宿主的标识——因此附件可据此以其宿主命名资源,并得到宿主平台接受的名称。当宿主的 provider 未报告名称时它为空,从附件除 injectMapping 以外的内联模板读取它会中止构建;此时应改为读取 ’{{ .context.instance_id }}‘。
labelsmap of string否当前节点的鸭子类型和本体标签,包括在拓扑构建时以 label-transform 角色附加的治理插件所做的任何更改。
annotationsobject否当前节点的三个级联注解桶,按来源分隔。
injectobject是预先水合并被拦截的交付管道。起初是编译器生成的映射,将 Developer 的 inject 键解析为 Target 的 provides 值。由 injectMapping 深度合并就地修改。到 Base Recipe 渲染时,其中包含完全解析的物理字符串。
usesmap of enriched_edge是增强的拓扑边映射。以 Developer 的别名为键(例如 ‘my_db’、‘my_api’)。每个条目都是编译器组装的视图,涵盖目标节点的标识、已解析的 provides、注入映射和级联注解,以及写在该连接上的附件——并且对于声明了 readsTargetRenderFacts 的 FeatureRecipe,还涵盖目标渲染所报告的内容。这不是原始的 IR 边——而是编译器专门为模板使用而构建的增强投影。遍历此映射的模板按键顺序(按别名排序)看到各连接,而不是按编写顺序。
self_injectobject是开发者已经为组件自身的哪些 values 和 provides 指定了交付名称,从写在该组件自身上的 inject: 块读取——即 .inject_raw 按原样保存、.context.inject 以解析后形式保存的那个块。该块指明的每种机制(env、file、arg,或诸如 ssm_param 的自定义机制)将开发者写下的每个名称映射到该条目所交付的自身键,方式与 .context.uses..inject 将连接的名称映射到它们所读取的键相同:对以 from: 书写的条目为 ‘provides.’;对其 value: 模板恰好只读取组件自身的一个 values 而不读取其他任何内容的条目为 ‘values.’,其中 是该值的顶层键,无论读取周围有何文本或函数,也无论它读入该值有多深——’{{ .values.config.port }}’、’{{ index .values.config “port” }}’ 和 ’{{ (default dict .values.config).port }}’ 都映射到 ‘values.config’;对其他所有条目则为空字符串——字面量、读取两个值的模板、读取 values 之外任何内容的模板,或其对 values 的读取无法由文本归属到单一顶层键的模板,例如 ’{{ index .values “role” }}‘、整体读取 values,或将整个上下文传给某个函数。因此,以默认名称交付自身值的 Recipe 会检查是否已有某个条目映射到 ‘values.’,若有则跳过其默认名称,例如 {{ range $name, $key := .context.self_inject.env }}{{ if eq $key “values.role” }}…{{ end }}{{ end }}。开发者未编写任何块时,该字段存在且为空;仅当块指明某种机制时,该机制才会出现,并且无论模板以何种方式读取,遇到的名称都是已排序的。从开发者所写的文本读取,绝不从解析后的值读取。
used_byinbound_edge[]否使用此组件的组件:其他组件对它建立的每个 uses 连接对应一个条目,顺序为连接组件的编写顺序,其次是各组件自身 uses 条目的顺序。连接两次的组件会出现两次。仅由附加到该组件的 FeatureRecipe 读取,且仅在生成附件自身资源的模板中读取——即其 valuesMapping、workload 和 artifacts。它不出现在组件自身的 Recipe 模板、injectMapping 以及流水线步骤的 with 和 when 中,因为这些模板的输出都可能进入组件自身的渲染输出,而无论谁连接到该组件,该输出都保持不变。每个条目是列表项而不是键,因此遍历它的模板按该顺序遇到各调用方。
render_factsrender_facts否渲染此组件的 provider 就其输出所报告的内容——即它报告的渲染事实——以事实名称为键。provider 报告哪些名称、每个条目包含什么,是该 provider 自己文档化的契约。每个值都是列表,即使只有一个条目,因此模板总是遍历它;当组件的渲染进行了多次 provider 调用且同一名称被其中多次调用报告时,其列表按调用运行顺序合并为一个。组件渲染完成后,出现在附加到该组件的 FeatureRecipe 的每个模板中——其 valuesMapping、workload、artifacts 以及流水线步骤的 with 和 when——当其 provider 未报告任何内容时为空,因此无人报告的名称读取为空列表。不出现在组件自身的 Recipe 模板和 injectMapping 中,因为它们在组件渲染之前运行。

不允许其他属性。

template-context.context.annotations

当前节点的三个级联注解桶,按来源分隔。

属性类型必需描述
releasemap of string否从 Release 边界级联而来的物理拓扑字符串。
catalogmap of string否由平台架构师在领域 2 中编写的不可变内在特征。
aggregatemap of string否从 Aggregate 子系统级联而来的认知元数据。

不允许其他属性。

template-context.context.inject

预先水合并被拦截的交付管道。起初是编译器生成的映射,将 Developer 的 inject 键解析为 Target 的 provides 值。由 injectMapping 深度合并就地修改。到 Base Recipe 渲染时,其中包含完全解析的物理字符串。

属性类型必需描述
envmap of string否环境变量交付。键是 Developer 的本地变量名,值是已解析的目标字符串。
filemap of string否文件挂载交付。键是本地文件路径,值是已解析的目标字符串。
argmap of string否命令行参数交付。键是标志前缀,值是已解析的目标字符串。
allmap of string否env + file + arg + 自定义机制的预先计算的扁平合并。在 uses-inject 解析后填充,并在注入映射后重新计算。模板使用 {{ toJson .context.inject.all }} 进行通用序列化。
template-context.context.self_inject

开发者已经为组件自身的哪些 values 和 provides 指定了交付名称,从写在该组件自身上的 inject: 块读取——即 .inject_raw 按原样保存、.context.inject 以解析后形式保存的那个块。该块指明的每种机制(env、file、arg,或诸如 ssm_param 的自定义机制)将开发者写下的每个名称映射到该条目所交付的自身键,方式与 .context.uses..inject 将连接的名称映射到它们所读取的键相同:对以 from: 书写的条目为 ‘provides.’;对其 value: 模板恰好只读取组件自身的一个 values 而不读取其他任何内容的条目为 ‘values.’,其中 是该值的顶层键,无论读取周围有何文本或函数,也无论它读入该值有多深——’{{ .values.config.port }}’、’{{ index .values.config “port” }}’ 和 ’{{ (default dict .values.config).port }}’ 都映射到 ‘values.config’;对其他所有条目则为空字符串——字面量、读取两个值的模板、读取 values 之外任何内容的模板,或其对 values 的读取无法由文本归属到单一顶层键的模板,例如 ’{{ index .values “role” }}‘、整体读取 values,或将整个上下文传给某个函数。因此,以默认名称交付自身值的 Recipe 会检查是否已有某个条目映射到 ‘values.’,若有则跳过其默认名称,例如 {{ range $name, $key := .context.self_inject.env }}{{ if eq $key “values.role” }}…{{ end }}{{ end }}。开发者未编写任何块时,该字段存在且为空;仅当块指明某种机制时,该机制才会出现,并且无论模板以何种方式读取,遇到的名称都是已排序的。从开发者所写的文本读取,绝不从解析后的值读取。

属性类型必需描述
envmap of string否环境变量交付:键是开发者的变量名,值是每个条目所交付的自身键。
filemap of string否文件挂载交付:键是开发者的文件路径,值是每个条目所交付的自身键。
argmap of string否命令行参数交付:键是开发者的标志前缀,值是每个条目所交付的自身键。

template-context.metadata

Release 与编译元数据,为确定性命名提供全局身份。可用于所有模板块(valuesMapping、injectMapping、pipeline with)。

属性类型必需描述
release_namestring否正在构建的 Release 的名称(例如 ‘prod-billing’)。Ops 用它来构建全局唯一的云资源名称(S3 存储桶、IAM 角色)。与 .context.instance_id 组合以保证跨环境的唯一性。
release_versionstring否Release 的语义版本。
environmentstring否来自 Release 元数据的环境字符串(例如 ‘production’、‘local’)。
aggregate_namestring否正在编译的根 Aggregate 的名称。

不允许其他属性。

template-context.inject

仅在渲染携带已编写 inject 块的附件 FeatureRecipe 时填充(例如 { env: [ { in: ‘OPENAI_API_KEY’, from: ‘api_token’ } ] })。不同于 .context.inject,后者是基础组件来自 uses 边的预水合交付管道。对于没有编写 inject 的附件以及基础 Recipes,求值为 null/缺失。

属性类型必需描述
envmap of string否作用于附件范围的环境变量传递。
filemap of string否作用于附件范围的文件挂载传递。
argmap of string否作用于附件范围的参数传递。
allmap of string否由编译器生成的、合并所有附件注入方式的便捷合集。

template-context.boundary

边界作用域上下文——仅在求值 spec.executionScope 为 ‘boundary’ 的 FeatureRecipe 为边界运行一次的模板时填充。Component 作用域的 FeatureRecipes 不会收到此支柱;它们的 context.instance_id、context.inject、context.uses 以及 .workload 支柱承载的是各组件的数据。边界作用域 FeatureRecipe 为边界运行的模板接收 .boundary.*,以取代这些按组件划分的支柱;它的 injectMapping 在附加项所到达的每个组件的上下文中运行,读取这些按组件划分的支柱,而不会收到此支柱。

属性类型必需描述
pathstring否FeatureRecipe 所附加到的 Release 边界的路径:从最外层向内的边界名称,以 ’/’ 连接(例如 ‘bridge’、‘bridge/frontend’)。它指的是边界本身,而不是其输出写入的目录,后者由边界的 directory: 设置。
assembly_pathstring否相对于构建输出目录、此附加项自身输出被汇编到的目录:即其边界求值后的 directory: 和 subDirectory:,也就是构建将该输出路由到的目录(例如 ‘bridge/compose’)。当且仅当某个连接端点渲染到同一个汇编文件中时,它与该端点的 source_assembly_path 或 target_assembly_path 完全相等,因此 FeatureRecipe 通过比较它们来区分位于其自身文件内的连接和位于另一文件中的连接。不透明数据;核心不解释它。
boundary_namestring否边界的名称(release.spec.boundaries 中的映射键)。
componentsobject否边界子树中每个组件的 instance_id 到一个条目的映射(递归,包含嵌套边界中的组件)。每个条目包含该组件解析后的类型 URI、实例 ID,以及按组件对 provides 求值得到的提供值。
internal_uses_edgesobject[]否源和目标都位于此边界子树中的 uses 边。
outgoing_cross_boundary_uses_edgesobject[]否源位于此边界子树内、目标位于子树外的 uses 边。
incoming_cross_boundary_uses_edgesobject[]否目标位于子树中、源位于子树外的 uses 边。供需要知道谁在调用进来的 ingress 类聚合器使用。
cross_boundary_uses_edgesobject[]否出站和入站跨边界边的便捷并集。
labelsmap of string否子树中各组件标签的并集,保留作者编写的顺序。
annotationsmap of string否级联解析完成后边界自身的注解。
feature_attachmentstemplate_attachment[]否直接附加到此边界的附件(用于在边界范围内跨附件引用),其结构与 .features 中的附件结构相同。

不允许其他属性。

定义

inbound_edge

另一个组件与所附加 FeatureRecipe 为之渲染的组件建立的一条连接:谁发起连接、通过哪个 socket、发起连接的组件发布了什么,以及它所处的命名空间和边界。每个值都是编译器原样携带、不加解释的字符串。

属性类型必需描述
component_idstring是发起连接的组件的扁平化实例 ID(例如 ‘frontend’ 或 ‘data-layer.etl’)——即 subDirectory 路径模板以 .component_id 读取的值,其写法与 .context.uses..target 表示连接另一端的写法相同。
socketstring是发起连接的组件建立此连接所经由的 usesSchema 类别(例如 ‘databases’、‘apis’)。
providesmap of string是发起连接的组件已解析的 provides,收窄到其 Component 声明的键——与该组件的使用方在 .context.uses..provides 读取的值相同。若其未发布任何值则为空。
source_namespacestring否发起连接的组件所处的命名空间:即其自身渲染所接收的 aggrega.ai/namespace 注解——取自其所在边界的注解,并最后应用其自身 Release 条目的注解,因此条目中设置或清除了命名空间的组件携带的是自己的设置,而非其边界的设置。它是边界作用域的 FeatureRecipe 在 .boundary uses-edge 列表中同一连接的条目上以 source_namespace 读取的值。若发起连接的组件没有适用的命名空间则不存在;打印前请用 if 或 with 进行判断。
source_boundary_pathstring否容纳发起连接的组件的 Release 边界的斜杠分隔路径(例如 ‘edge’ 或 ‘aws-prod/payments’)——即边界作用域的 FeatureRecipe 在 .boundary uses-edge 列表中同一连接的条目上以 source_boundary_path 读取的值。
render_factsrender_facts否发起连接的组件的各次渲染就其输出所报告的内容,按事实名称作为键:先是其自身 provider 调用报告的事实,然后是附加到它并随它一起渲染的每个 Feature 的事实,按渲染顺序排列;同一名称从其中多个来源得到的列表按该顺序合并为一个。每个值都是列表,即使只有一个条目,因此模板总是对其进行 range 遍历。仅对声明了 readsCallerRenderFacts 的 FeatureRecipe 存在——其附加项在每个组件都渲染完毕后才渲染,因此每个调用方的渲染都已完成——此时每个条目上都存在,对于其 provider 未报告任何内容的调用方则为空。对其他所有 FeatureRecipe 均不存在。

不允许其他属性。

render_facts

按名称作为键的渲染事实:渲染某个组件的 provider 就其输出所报告的内容。provider 报告哪些名称、每个条目包含什么,由该 provider 自己文档化的契约决定;对于这两者,编译器只知道每个值是一个列表。列表保持其条目的顺序。对象条目按 provider 写入的键顺序携带,模板对其进行 range 遍历时按键顺序得到它们,与此上下文中所有带键映射的情况相同。

自由格式对象;值为 any[]。

template_attachment

模板所读取的一个附加项:已附加 Feature 的按实例视图。无论产出什么,每个附加项都暴露相同的字段,因此无论该名称是实体声明的插槽还是自由附加项,.features. 的读取方式都相同。

属性类型必需描述
typestring否已附加 Feature 的 Catalog Feature URI。
resolved_versionstring否已附加 Feature 经 Manifest 解析后的版本——即本次构建实际绑定的版本,以 .features..resolved_version 读取。与 .context.uses..resolved_version 相对应,因此附加项和边以相同方式报告绑定的版本。若附加项的类型未解析到任何 Catalog 实体则为空。
labelsmap of string否已附加 Feature 的 Catalog 标签,按该 Feature 声明的顺序原样携带——不做任何过滤、重命名或去前缀,因此模板读到的正是 Feature 作者所写的内容。使模板能够依据已附加 Feature 是什么进行分支,而不是依据其名称或 URI。与 .context.uses..labels 相对应。若 Feature 未声明任何标签,或附加项的类型未解析到任何 Catalog 实体,则该键完全不存在,因此在访问单个标签前请用 if 判断或对该映射进行 range 遍历。
valuesobject否附加项自身的开发者意图支柱,从附加项声明中原样携带。
infraobject否附加项自身的运维规格支柱,从附加项声明中原样携带。
providesmap of string否绑定到此附加项的 FeatureRecipe 已解析的公共契约——所生成资源的名称、其键、一个标识以及任何其他产出的键——以 .features..provides. 暴露给使用方。使用方读取这些值,而不是重新推导附加项的物理标识。若所绑定的 FeatureRecipe 未发布任何内容,附加项将完全不携带 provides 键,而非一个空映射,因此模板在访问单个键之前应先进行判断。

不允许其他属性。

enriched_edge

由编译器组装的一条经过丰富的拓扑边。包含目标的已解析标识、provides 以及级联的注解。

属性类型必需描述
targetstring是目标节点的绝对扁平化 ID(例如 ‘data-layer.main-db’)。
socketstring是该边所属的 usesSchema 类别(例如 ‘databases’、‘apis’)。
sourcestring否源(消费者)节点的绝对扁平化 ID。为按消费者节点为每个消费者的输出设键的边界作用域视图填充。
source_namespacestring否源端点的原始 aggrega.ai/namespace 注解(不存在时为空)。与 source 一样,仅为边界作用域视图填充;组件自身的 .context.uses 条目中该值为空。它是供 provider 进行网络标识解析的不透明数据;核心不解释它。
source_boundary_pathstring否源端点的边界路径:容纳它的 Release 边界的以斜杠分隔的路径(例如 ‘bridge/frontend’)。与 source 一样,仅为边界作用域视图填充;组件自身的 .context.uses 条目中该值为空。
source_assembly_pathstring否源端点的汇编路径:相对于构建输出目录、其输出被汇编到的目录,由其边界求值后的 directory: 和 subDirectory: 组成(例如 ‘bridge/compose’)。汇编路径相同的两个端点渲染到同一个汇编文件中,而汇编路径等于 .boundary.assembly_path 的端点会渲染到读取它的 FeatureRecipe 自身输出被汇编到的文件中。将端点放置到网络上的边界作用域 FeatureRecipe,在没有适用的 aggrega.ai/namespace 时,可以将其读作源端点的网络。与 source 一样,仅为边界作用域视图填充;组件自身的 .context.uses 条目中该值为空。不透明数据;核心不解释它。
target_namespacestring否目标端点的原始 aggrega.ai/namespace 注解(不存在时为空)。与 source 一样,仅为边界作用域视图填充;组件自身的 .context.uses 条目中该值为空。它是供 provider 进行网络标识解析的不透明数据。
target_boundary_pathstring否目标端点的边界路径:容纳它的 Release 边界的以斜杠分隔的路径(例如 ‘bridge/backend’)。与 source 一样,仅为边界作用域视图填充;组件自身的 .context.uses 条目中该值为空。
target_assembly_pathstring否目标端点的汇编路径:相对于构建输出目录、其输出被汇编到的目录,由其边界求值后的 directory: 和 subDirectory: 组成(例如 ‘bridge/compose’)。汇编路径等于 .boundary.assembly_path 的端点会渲染到读取它的 FeatureRecipe 自身输出被汇编到的文件中。将端点放置到网络上的边界作用域 FeatureRecipe,在没有适用的 aggrega.ai/namespace 时,可以将其读作目标端点的网络。与 source 一样,仅为边界作用域视图填充;组件自身的 .context.uses 条目中该值为空。不透明数据;核心不解释它。
providesmap of string是目标节点完全解析后的 provides 字典。在 provides 求值阶段求值,早于 inject 填充。
injectobject是开发者为该边编写的原始 inject 映射(键 = 本地变量名,值 = 目标的 provides 键)。这是原始(RAW)映射,而不是解析后的值。
labelsmap of string否目标节点的鸭子类型和本体标签(拓扑构建中变更之后的结果)。
annotationsobject否目标节点的三个级联注解桶。
componentstring否目标节点的 Catalog 组件类型 URI(例如 ‘core/postgres’)。
resolved_versionstring否目标节点已解析的 SemVer。
boundary_pathstring否目标节点来自 Release 的物理空间层级(例如 ‘aws-eks-cluster/backend-ns’)。
origin_featurestring否如果该边由某个 Feature 自主声明(包括标记为 feature.aggrega.ai/kind: secret 的凭据 Features),则为该 Feature 实例名。对于开发者声明的边,该值为 null 或不存在。
origin_release布尔值否当该连接由 Release 接线而非由 Aggregate 声明时为 true。对于 Aggregate 声明的连接,该值不存在。
valuesobject否在 Aggregate 中该连接的 uses 条目上编写的每连接开发者配置,按原样携带。连接未携带时不存在。它只进入消费节点的上下文,绝不进入目标的上下文。
infraobject否在 Release 中该连接的 uses 条目上编写的每连接运维配置,按原样携带。连接未携带时不存在。它只进入消费节点的上下文,绝不进入目标的上下文。
featuresmap of template_attachment否写在该连接上的附件,以连接的 socket 为每个附件声明的插槽名为键,每个都采用 .features 所携带的附件结构:其类型、已解析版本、labels、values、infra,以及绑定到它的 FeatureRecipe 的已解析 provides。Recipe 以 .context.uses..features..provides. 读取某个连接的凭据,因此连接多个目标的消费者会读取每个目标各自的凭据。这些附件绝不属于消费节点自身的 .features,因此遍历 .features 以按类型查找节点附件的模板不会遇到连接上的附件。在模板中遍历时,插槽按键的顺序出现。连接未携带附件时不存在。
render_factsrender_facts否目标的渲染针对其输出所报告的内容,以事实名为键,采用 .context.used_by 上调用方条目所携带的结构:先是其自身 provider 调用报告的事实,然后是附加到它并随它一起渲染的每个 Feature 的事实,按渲染顺序排列;同一名称从其中多个来源得到的列表按该顺序合并为一个。每个值都是列表,即使只有一个条目,因此模板总是遍历它。仅在声明了 readsTargetRenderFacts 的 FeatureRecipe 的 .context.uses 上存在(其附件在所有组件渲染完成后才渲染,因此每个目标的渲染都已完成),此时出现在每个条目上;对于 provider 未报告任何内容的目标为空。对于其他所有 FeatureRecipe、流水线步骤的 with 和 when、组件自身的 Recipe 模板,以及边界作用域 FeatureRecipe 读取的边列表,该值都不存在。

不允许其他属性。

enriched_edge.inject

开发者为该边编写的原始 inject 映射(键 = 本地变量名,值 = 目标的 provides 键)。这是原始(RAW)映射,而不是解析后的值。

属性类型必需描述
envmap of string否环境变量投递:键是使用方的本地变量名,值是目标的 provides 键。
filemap of string否文件挂载投递:键是使用方的本地文件路径,值是目标的 provides 键。
argmap of string否命令行参数投递:键是使用方的标志前缀,值是目标的 provides 键。

enriched_edge.annotations

目标节点的三个级联注解桶。

属性类型必需描述
releasemap of string否来自目标节点 Release 边界的物理拓扑字符串。
catalogmap of string否来自目标节点 Catalog 实体的不可变特征。
aggregatemap of string否来自目标节点 Aggregate 子系统的认知元数据。

不允许其他属性。