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

Aggrega 按 Release 划分的 Lockfile schema

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

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

机器生成的 lockfile,固定从一个 Release 解析出的每个 URI,以便未来进行确定性构建。它位于 <release-stem>.yaml 旁边的 <release-stem>.lock;由 aggrega pull --release <release> 生成;由 aggrega build --release <release> 使用。两种来源形态记录依赖图中两种不同的关系:referenced_from(字符串列表)出现在 entities 上,作为以点分隔的编写位置路径,记录每个 URI 是从 Release / Aggregate / Manifest / .aggrega-config.yaml 中的何处引入的;它也出现在 plugins 上,作为到达某个制品所经由的每个 Plugin 实体的引用;consumers({consumer_uri, fragments} 记录的列表)出现在 schema_libraries、mapping_libraries、workload_libraries 和 artifact_libraries 上,记录哪个目录实体引用了库的哪些 <entry-name> 片段——这种结构化形态使得“库版本升级影响了哪些使用方”的差异无需再次解析 Release 即可追溯。Schema 演进准则:新增顶层段属于 SemVer-MINOR(增量变更);在现有段中新增字段属于 SemVer-MINOR;删除键或收紧约束属于 SemVer-MAJOR。

顶层类型: object

属性

属性类型必需描述
entitiesobject[]否从此 Release 可达的目录实体:Component、Feature、Recipe、FeatureRecipe、Plugin、Aggregate,该 Release 自身的 Aggregate 和 Manifest,以及该 Manifest 所扩展的 Manifest。每个条目由其 kind 连同其规范 URI 共同标识,因此同名但种类不同的两个实体——例如都名为 imported/flow 的一个 Aggregate 和一个 Manifest——是两个条目,各自按其自身的摘要进行校验。每个条目记录解析出的版本、实体所携带内容的摘要,以及将该 URI 引入该 Release 依赖闭包的编写位置来源(referenced_from)。条目不带 kind 的锁文件已过时:aggrega pull --release <release> 会重新写入它。默认值:[]
external_inputsExternalInput[]否在获取时固定到内容寻址输入存储中的远程输入——即 provider 插件渲染时从工作区之外使用的内容,例如远程 schema 文档或未 vendor 的 chart 依赖。每个条目将一个 URL 固定到在存储中命名其字节的摘要。构建从存储中提供已固定的输入,并在无网络访问的情况下读取此部分。默认值:[]
generated_atstring是生成此 lockfile 的 pull 的 RFC 3339 时间戳;lockfile 加载时,pattern 将该值约束为此格式。诊断性来源信息——记录解析发生的实际时刻。在不同 pull 之间有意变化;不属于 lockfile 字节一致性保证的一部分。模式:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$。
mapping_librariesLibraryEntry[]否该 Release 的依赖闭包通过 Recipe / FeatureRecipe 的 valuesMapping: { $import: ... } 位置到达的 MappingLibrary 条目。每个条目的 consumers 列表记录哪个目录实体引用了该库的哪些 <entry-name> 片段——这一结构化记录使库版本升级的影响差异无需再次解析 Release 即可追溯。默认值:[]
mutatorsobject[]否已解析的 transform 角色治理挂载,按编写顺序排列。transform 角色插件(label-transform 重写节点标签;annotation-transform 在展开之前注入注解)会影响渲染输出的字节,因此挂载集合——有序列表,以及每个挂载的角色、插件坐标和导出函数——是决定字节的输入,在此固定。构建读取此部分——而从不读取 .aggrega-config.yaml——来重建集合、顺序、角色和导出函数,因此构建输出不受 pull 之后对 plugins.governance 所做更改的影响(仅在下一次 pull 时采用)。顺序具有语义:每个 transform 运行器按列表顺序应用其角色的挂载,因此与按 URI 排序的 plugins / providers 部分不同,此列表从不重新排序。插件的内容摘要不在此重复:它单一来源于 plugins 和 entities 部分,本记录按标识指向这些部分。默认值:[]
pluginsobject[]否其字节会影响渲染输出的 Wasm 插件,每个都按其 .wasm 的内容摘要固定:在 .aggrega-config.yaml plugins.governance 下以 transform 角色(label-transform、annotation-transform)挂载的治理插件,以及来自所引用的 Recipes / FeatureRecipes / Providers 的任何嵌入式插件 URI。以 verdict 角色(ir-verdict、render-verdict)挂载的治理插件和 plugins.linter 挂载只返回裁决,不影响任何输出字节,因此两者都不会被固定:两者都不出现在此处或 entities 下,verdict 挂载所读取的规则文件记录在 verdict_inputs 下。默认值:[]
providersobject[]否已解析的按能力 provider 选择。每个条目将一项能力(例如 helm)固定到渲染它的 provider 渲染插件的不含摘要的 OCI 标识;该标识在 pull 时解析,来源为 .aggrega-config.yaml 的 plugins.providers 列表(当能力由多个插件提供而存在歧义时)或唯一提供该能力的插件(无歧义时)。构建读取此部分——而从不读取 .aggrega-config.yaml——来选择 provider,因此构建输出不受 pull 之后工作区配置更改的影响。插件的内容摘要不在此重复:它单一来源于 plugins 和 entities 部分,本记录按标识指向这些部分。版本共存得以保留:本记录按能力选择插件仓库;具体版本位于 entities 中(每个已解析的插件版本一个条目),每个 Recipe 的 spec.capability 版本固定在渲染时从中进行选择。默认值:[]
releasestring是此 lockfile 对应的 Release 的路径,相对于 lockfile 自身所在目录解析(例如 ./release-prod.yaml)。按 Release 命名的约定将 <release-stem>.lock 放在 <release-stem>.yaml 旁边;相对路径使 lockfile 能够自描述,而无需依赖特定机器的绝对路径。此字段命名该 Release;该 Release 在解析时所包含的内容记录在 release_documents 下。
release_documentsobject[]否解析过程读取的 Release 文件,每个文件按其字节的内容摘要记录:首先是此 lockfile 所属的 Release,然后按遍历 extends 链的顺序列出它所扩展的每个 Release。Release 所请求的一切都依据其所包含的内容解析,因此在 pull 之后被编辑的 Release 将不再与其记录的摘要匹配,构建——或 aggrega pull --verify——会在任何渲染开始之前停止,并指出该文件,以 aggrega pull --release <release> 作为修复方法。摘要覆盖字节的原样内容,不做任何规范化,与 Aggregate 和 Manifest 固定所遵循的规则相同:对注释或空白的编辑也算作更改。没有此部分的 lockfile 不记录任何 Release 文件,持有此类 lockfile 的构建会报告该 Release 未被记录。Release 通过 parameters 导入的文件不在此记录。
schema_librariesLibraryEntry[]否该 Release 的依赖闭包通过实体 schema: / usesSchema: / featuresSchema: 内容中的 $ref 和 $import: 位置到达的 SchemaLibrary 条目。每个条目的 consumers 列表记录哪个目录实体引用了该库的哪些 <entry-name> 片段——这一结构化记录使库版本升级的影响差异无需再次解析 Release 即可追溯。默认值:[]
source_artifactsSourceArtifactEntry[]否在 pull 时从 Recipe / FeatureRecipe 的 spec.source 字段拉取的源制品。每个条目标识一个唯一的 {kind, url, chart, pinned_version} 标识,附带内容摘要、媒体类型,以及结构化的 referenced_by: 反向指针,指明解析到该制品的每个目录实体。url 是编写时的标识 URL;对于仓库根 helm 源,解析后的制品位置作为来源信息单独记录在 resolved_url: 下。多个 Recipes 以相同版本固定同一 chart 时,会去重为单个条目,并带有多条 referenced_by: 记录。kind 枚举涵盖可以解析的四种源类型,以及没有任何源适配器支持的 terraform-module-oci:指定它的 Recipe 或 FeatureRecipe 在读取时即被拒绝,因此任何 pull 都不会记录该类型的条目。默认值:[]
toolchainobject否生成此 lockfile 的工具链版本:编译器自身的版本,以及编译器所携带的每个核心插件的版本。记录这些信息是为了让 lockfile 能够事后回答是哪个编译器和哪些核心插件解析并渲染了某次构建——这是已固定的部分无法总是回答的问题,因为从编译器二进制内部提供的核心 provider 插件不会被固定,因而没有记录其自身的版本。仅记录版本:该标记从不记录插件字节的来源,因此两台机器使用相同编译器固定相同依赖闭包时会写入相同的标记。没有任何机制会比较此部分、对其发出警告或因其拒绝构建,lockfile 中缺少此部分时也不会有任何提示:工具链不属于 lockfile 所固定的依赖闭包。出于同样的原因,在对相同输入的两次 pull 进行字节一致性比较时,此部分与 generated_at 一样被豁免。
verdict_inputsobject[]否verdict 角色的治理挂载(ir-verdict / render-verdict)在编译时读取的外部规则输入——通过挂载的 with.sources 提供的 Kyverno / Rego 规则文件。按每个来源记录内容摘要,用于审计以及跨 pull 的漂移可见性:塑造某个裁决的摘要可在多次 pull 之间比较差异,因此规则文件的变更会以 lockfile 差异的形式呈现。本节是溯源信息(PROVENANCE),而非构建输入:与 mutators.sources 不同,它不携带 content,构建也不读取它——verdict 插件只缓存而不固定,并实时读取其规则输入(裁决不影响任何输出字节,因此 lockfile 为确定性输出所固定的内容都不包含它)。由于 verdict 插件不被固定,它不出现在 entities / plugins 节中;因此本记录通过挂载的编写 URI 标识挂载,独立成立,而不是指向那些节。记录摘要使决定接受/拒绝结果的输入可审计、可复现,而无需将其固定到构建中。默认值:[]
versionconst 1是Lockfile schema 版本:1。schema 的 SemVer-MAJOR 变更会使其递增。常量:1
workload_librariesLibraryEntry[]否该 Release 的依赖闭包通过 Recipe workload: { $import: ... } 位置到达的 WorkloadLibrary 条目。每个条目的 consumers 列表记录哪个目录实体引用了该库的哪些 <entry-name> 片段——这一结构化记录使库版本升级的影响差异无需再次解析 Release 即可追溯。默认值:[]
artifact_librariesLibraryEntry[]否该 Release 的依赖闭包通过 Recipe / FeatureRecipe artifacts.<name>: { $import: ... } 位置到达的 ArtifactLibrary 条目。每个条目的 consumers 列表记录哪个目录实体引用了该库的哪些 <entry-name> 包——这一结构化记录使库版本升级的影响差异无需再次解析 Release 即可追溯。默认值:[]

不允许其他属性。

lockfile.entities[]

属性类型必需描述
kindstring(枚举)是目录实体的种类,从 Release、其 Aggregate 或其 Manifest 指明它的位置读取:component 和 feature 用于 Aggregate、Release 或某个 Manifest 映射所指明的 Component 或 Feature 类型,recipe 和 feature_recipe 用于某个 Manifest 映射所绑定的实现,plugin 用于 Plugin 实体,aggregate 用于该 Release 自身的 Aggregate 及其包含的每个 Aggregate,manifest 用于该 Release 自身的 Manifest 及其所扩展的 Manifest。它与 uri 一起标识该条目:构建会将每个条目与相同种类和 URI 的实体进行比较,因此对两个同名但种类不同的实体中任一个的编辑都会被发现。允许的值:"aggregate"、"component"、"feature"、"feature_recipe"、"manifest"、"plugin"、"recipe"
uristring是目录实体的规范 URI(例如 hub.aggrega.ai/component/core/compute/api-server)。
resolved_versionstring是解析器在 pull 时选定的具体版本——目录实体自身的版本(例如 1.2.3),对于按路径而非按版本解析的顶层实体则为空。它以单个路径段的形式记录,因为它命名的就是一个路径段,所以不含 /、\ 和 ..:该值构成构建读回此实体所用的缓存槽,越出缓存目录的值会指向缓存目录之外的位置。模式:^([^/\\.]|\.[^/\\.])*\.?$。
digeststring是实体的一次发布所携带内容的摘要,格式为 sha256: 后跟 64 个小写十六进制字符:对实体文档及其在旁声明的每个文件计算的 SHA-256,按路径排序,每个文件贡献其路径及其字节的 SHA-256。未声明任何文件的实体只计其一个文档。其他任何内容都不计入——归档的压缩方式、时间戳、任何权限位(包括执行位)均不计入——因此无论从目录读取还是从 registry 获取,无论在任何系统上检出相同文件,实体记录的摘要都相同。模式:^sha256:[a-f0-9]{64}$。
manifest_digeststring否已解析制品的 OCI manifest 摘要,格式为 sha256: 后跟 64 个小写十六进制字符。签名承诺此摘要,而 manifest 指明已发布字节的摘要;在实体按上述 digest 校验之前,获取和缓存读取都要先对照该摘要进行检查。仅对从 registry 解析的实体存在。模式:^sha256:[a-f0-9]{64}$。
referenced_fromstring[]否编写位置来源——指向 Release / Aggregate / Manifest YAML 的点分路径(例如 aggregate.spec.components.api.type),记录此 URI 为何位于该 Release 的依赖闭包中。默认值:[]
signatureVerifiedSignature否在 pull 时依据解析所用 registry 的信任策略验证此实体签名后记录的已验证签名事实。
deprecationDeprecationRecord否在 pull 时于此制品上发现经签名且受信任的弃用标记时记录的已验证追溯弃用标记。标记是其所弃用制品的已签名 OCI referrer,在发布之后附加,无需重新发布该制品。记录标记的严重级别和消息,以及编写该标记的已验证签名者。构建读取此事实,并仅依据 lockfile 执行弃用策略;它从不重新发现或重新验证该标记。

不允许其他属性。

lockfile.mutators[]

属性类型必需描述
pluginstring是transform 角色插件的已解析插件坐标——Plugin 实体的 <pluginType>/<name> 标识(例如 governance/tag-injector)。按标识连接到 plugins 和 entities 节,以获取固定的摘要和版本集。
rolestring(枚举)是此挂载所绑定的 transform 角色,按编写的 plugins.governance 条目原样记录,因此构建会恰好以该角色运行挂载,而不是推断角色:label-transform 在拓扑构建时重写节点标签;annotation-transform 在解析期间、展开之前注入注解。允许的值:"label-transform"、"annotation-transform"
functionstring否挂载指定的导出覆盖。缺省时选择该角色的默认导出(label-transform 为 mutate,annotation-transform 为 transform_annotations)。
settingsobject否挂载声明的自由格式设置对象,按编写内容固定并原样传给插件。构建从此处读取设置——从不读取实时配置——因此 pull 之后的设置变更不会改变构建输出。挂载未声明设置时缺省。
sourcesobject[]否挂载所声明源文件的内容寻址固定项,按基本名称排序。构建依据每个固定项记录的内容重建插件读取的源,而不是实时读取主机文件,因此构建输出不受 pull 之后源文件变更的影响。挂载未声明源文件时缺省。

不允许其他属性。

lockfile.mutators[].sources[]
属性类型必需描述
contentstring是源文件的内容,原样携带,以便构建从 lockfile 重建插件的源输入。
digeststring是所记录内容的内容地址,格式为 sha256: 后跟 64 个小写十六进制字符。重新 pull 时会将底层文件与此摘要比较以检测漂移。模式:^sha256:[a-f0-9]{64}$。
pathstring是源文件的基本名称——从不是主机绝对路径,因此该固定项可移植且具有确定性。

不允许其他属性。

lockfile.plugins[]

属性类型必需描述
uristring是Wasm 插件 .wasm 制品的裸标识,即 <pluginType>/<name> 路径(例如 governance/aggrega-security-baseline)。第一段是插件的类型(provider、linter、pipeline-step、governance、cli、parser、importer);其后的一段是插件的名称。类型与名称共同构成插件的标识:同一名称位于两种类型下即为两个插件。物理获取位置由该标识加上所配置的注册表推导得出,从不记录在 lockfile 中。
resolved_versionstring是该 Wasm 制品解析到的内容摘要,格式为 sha256: 后跟 64 个小写十六进制字符。插件制品按内容寻址而非按版本命名:.wasm 内联于其插件清单中,并由其字节的摘要固定,因此该字段记录的就是这个摘要,它同时也是下方的 digest。构建会依据它构造读回该制品的缓存槽位,因此其中不含 /、\ 和 ..,而 sha256: 格式本身已排除了这些字符。模式:^sha256:[a-f0-9]{64}$。
digeststring是已解析 Wasm 制品的内容摘要,格式为 sha256: 后跟 64 个小写十六进制字符,这是内容地址在所有进行比较之处的书写形式。模式:^sha256:[a-f0-9]{64}$。
manifest_digeststring否已解析 Wasm 制品的 OCI 清单摘要,格式为 sha256: 后跟 64 个小写十六进制字符。签名针对该摘要作出承诺;上方的内容 digest 是用于缓存固定和完整性检查的可移植标识。仅当制品从注册表解析时存在。模式:^sha256:[a-f0-9]{64}$。
referenced_fromstring[]否此制品为何位于该 Release 的依赖闭包中:到达它所经由的每个 Plugin 实体的引用,形式与 entities 部分记录该实体时相同(例如 governance/label-injector:1.0.0)。默认值:[]
signatureVerifiedSignature否在拉取时依据与目录实体相同的按注册表信任策略验证该插件签名后记录的已验证签名事实。
deprecationDeprecationRecord否在 pull 时于此制品上发现经签名且受信任的弃用标记时记录的已验证追溯弃用标记。标记是其所弃用制品的已签名 OCI referrer,在发布之后附加,无需重新发布该制品。记录标记的严重级别和消息,以及编写该标记的已验证签名者。构建读取此事实,并仅依据 lockfile 执行弃用策略;它从不重新发现或重新验证该标记。

不允许其他属性。

lockfile.providers[]

属性类型必需描述
capabilitystring是此绑定为其选择 provider 的能力,即 Recipe 通过 spec.capability 绑定的裸能力名称(例如 helm、compose)。
pluginstring是已解析的 provider 渲染插件的裸标识(Plugin 实体的标识,即以斜杠连接的 metadata.pluginType 与 metadata.name,例如 provider/helm)。按标识关联到 plugins 和 entities 部分,以获取固定的摘要和版本集。

不允许其他属性。

lockfile.release_documents[]

属性类型必需描述
digeststring是解析读取 Release 文件时其字节的内容摘要,格式为 sha256: 后跟 64 个小写十六进制字符。模式:^sha256:[a-f0-9]{64}$。
pathstring是Release 文件相对于此 lockfile 所属 Release 所在目录的路径,使用正斜杠(例如 release-prod.yaml、../shared/base-release.yaml);从不使用宿主机绝对路径,因此该记录可移植且确定。

不允许其他属性。

lockfile.toolchain

生成此 lockfile 的工具链版本:编译器自身的版本,以及编译器所携带的每个核心插件的版本。记录这些信息是为了让 lockfile 能够事后回答是哪个编译器和哪些核心插件解析并渲染了某次构建——这是已固定的部分无法总是回答的问题,因为从编译器二进制内部提供的核心 provider 插件不会被固定,因而没有记录其自身的版本。仅记录版本:该标记从不记录插件字节的来源,因此两台机器使用相同编译器固定相同依赖闭包时会写入相同的标记。没有任何机制会比较此部分、对其发出警告或因其拒绝构建,lockfile 中缺少此部分时也不会有任何提示:工具链不属于 lockfile 所固定的依赖闭包。出于同样的原因,在对相同输入的两次 pull 进行字节一致性比较时,此部分与 generated_at 一样被豁免。

属性类型必需描述
compiler_versionstring是写入此 lockfile 的编译器版本,采用所有 Aggrega 界面统一报告的不带 v 的形式(1.2.0,而非 v1.2.0)。带有版本标记的构建记录该版本——带标签的发布构建记录其标签——未带版本标记的构建则记录 (devel) 标记,以免将未加版本标记的编译器生成的 lockfile 误认为发布产物。以单个路径段记录,因此其中不含 /、\ 和 ..。模式:^([^/\\.]|\.[^/\\.])*\.?$。
core_pluginsobject[]是编译器所携带的每个核心插件的版本,每个插件一项,按插件坐标排序。核心插件以相同版本发布在编译器自身的标签上,因此无论编译器是从自身内部提供插件还是从注册表获取,这些版本读起来都相同,这正是该标记不含机器特定细节的原因。对于不携带核心插件的构建,此项为空。默认值:[]

不允许其他属性。

lockfile.toolchain.core_plugins[]
属性类型必需描述
pluginstring是核心插件的坐标,即 Plugin 实体的 <pluginType>/<name> 标识(例如 provider/helm),与 providers 和 mutators 部分用来指称插件的标识相同。
versionstring是该核心插件的版本,采用所有 Aggrega 界面统一报告的不带 v 的形式。以单个路径段记录,因此其中不含 /、\ 和 ..。模式:^([^/\\.]|\.[^/\\.])*\.?$。

不允许其他属性。

lockfile.verdict_inputs[]

属性类型必需描述
pluginstring是裁决挂载所编写的插件 URI,与 .aggrega-config.yaml 的 plugins.governance 中所写一致(例如 governance/aggrega-security-baseline:1.0.0)。用于标识所记录的规则输入属于哪个挂载;裁决插件只缓存而不固定,因此在 plugins / entities 部分中没有可供关联的条目。
rolestring(枚举)是此挂载所绑定的裁决角色:ir-verdict(在静态分析阶段,作用于 IR 图)或 render-verdict(在渲染阶段,作用于渲染产物)。用于区分在两个裁决阶段挂载的同一插件,每个阶段可能有各自的规则输入。允许的值:"ir-verdict"、"render-verdict"
sourcesobject[]否该挂载所声明的规则输入文件的内容摘要,按基本名称排序。挂载未声明任何源时不存在。

不允许其他属性。

lockfile.verdict_inputs[].sources[]
属性类型必需描述
digeststring是拉取时规则输入文件字节的内容地址,格式为 sha256: 后跟 64 个小写十六进制字符。重新拉取时会重新计算它,因此规则文件的变更会体现为 lockfile 差异。模式:^sha256:[a-f0-9]{64}$。
pathstring是规则输入文件的基本名称;从不使用宿主机绝对路径,因此该记录可移植且确定。

不允许其他属性。

定义

DeprecationRecord

在 pull 时于此制品上发现经签名且受信任的弃用标记时记录的已验证追溯弃用标记。标记是其所弃用制品的已签名 OCI referrer,在发布之后附加,无需重新发布该制品。记录标记的严重级别和消息,以及编写该标记的已验证签名者。构建读取此事实,并仅依据 lockfile 执行弃用策略;它从不重新发现或重新验证该标记。

属性类型必需描述
messagestring是标记携带的人类可读弃用消息——通常是迁移指引。
severitystring(枚举)是标记的严重级别,顺序为 warning < error < retracted。当该严重级别达到或超过所配置的中止阈值时,构建中止;否则发出提示。允许的值:"warning"、"error"、"retracted"
signerVerifiedSignature否标记的已验证签名者,记录方式与制品签名的签名者相同:无密钥签名时为证书主体/颁发者,有密钥签名时为固定密钥的指纹。标记本身就是一个已签名的制品,因此其签名者与制品签名具有相同的结构——此处的 bundle_digest 指的是标记自身的签名包,而不是被弃用制品的签名包。

不允许其他属性。

ExternalInput

单个固定的外部输入:渲染所请求的 URL、在内容寻址输入存储中指向其字节的 SHA-256 固定值(sha256/<digest>)、负载大小,以及需要它的使用方的来源。固定值具有权威性——已固定的 URL 始终从存储中提供,且存储重新填充时,会在字节到达渲染之前依据该摘要进行验证。

属性类型必需描述
required_bystring[]是来源——请求该输入的渲染位置。由 lockfile 写入器排序并去重。
sha256string是小写十六进制的 SHA-256 固定值。对于 https 输入,为负载字节的摘要;对于 oci 输入,为引用解析到的清单摘要。指向位于 sha256/<digest> 的存储 blob。模式:^[0-9a-f]{64}$。
sizeinteger是已固定负载的字节大小。字节数永远不为负。最小值:0。
urlstring是在渲染位置编写的输入 URL——将渲染时请求与其固定值匹配的查找键。

不允许其他属性。

LibraryEntry

schema_libraries、mapping_libraries、workload_libraries 和 artifact_libraries 条目共享的通用结构。consumers 列表记录目录图中的关系——哪个目录实体引用了该库的哪些 <entry-name> 片段——以便在库的摘要变化时支持结构化的影响差异分析。库与其他任何 OCI 制品一样,因此它记录与目录实体相同的已验证事实:其签名所承诺的清单摘要、已验证的签名本身,以及拉取时发现的任何已验证追溯弃用标记。

属性类型必需描述
uristring是库实体的规范 URI。
resolved_versionstring是拉取时解析出的具体版本(在库依赖图上进行最小版本选择)——即库自身的版本。以单个路径段记录,因为构建会用它组成读取该库的缓存槽位,所以不包含 /、\ 和 ..:跳出缓存目录的值会指向缓存目录之外的位置。模式:^([^/\\.]|\.[^/\\.])*\.?$。
digeststring是已解析库制品的内容摘要,格式为 sha256: 后跟 64 个小写十六进制字符——这是内容地址在所有比较场合中的书写形式。模式:^sha256:[a-f0-9]{64}$。
manifest_digeststring否已解析库制品的 OCI 清单摘要,格式为 sha256: 后跟 64 个小写十六进制字符。签名承诺的是该摘要;上面的内容 digest 是用于缓存固定和完整性检查的可移植标识。仅对从注册表解析的库存在。模式:^sha256:[a-f0-9]{64}$。
signatureVerifiedSignature否拉取时验证该库的签名时记录的已验证签名事实,所依据的按注册表划分的信任策略与目录实体相同。
deprecationDeprecationRecord否拉取时在该库上发现的已验证追溯弃用标记。构建会报告它,并在工作区配置的中止阈值被记录的严重级别达到时中止——因此,在版本固定之后被撤回的库会在每次构建时都被告知,而不仅仅在版本选择时告知,因为显式固定的版本会绕过版本选择。
consumersobject[]否记录哪个目录实体引用了该库以及引用了哪些 <entry-name> 片段。体现扇入关系:每个库有多个使用方,每个使用方可能引用多个片段。每条记录包含使用方 URI 以及该使用方引入的片段集合。默认值:[]

不允许其他属性。

LibraryEntry.consumers[]

属性类型必需描述
consumer_uristring是引用此库的目录实体的规范 URI:对于 schema 库,是 Component 或 Feature;对于映射库、工作负载库或制品库,是 Recipe 或 FeatureRecipe;也可以是其条目引用此库的另一个同类库。
fragmentsstring[]是该使用方在库中引用的 <entry-name> 片段集合(例如 ["#/schemas/PortSpec", "#/schemas/EndpointSpec"])。写入器按字典序对顺序进行规范化。

不允许其他属性。

SourceArtifactEntry

单个源制品固定项:{kind, url, chart, module_subdir, pinned_version} 标识、用于校验拉取的内容摘要、规范 mediatype,以及指向每个解析到该制品的目录实体的结构化反向指针。chart 和 module_subdir 是两个选择器项——对于需要选择器的种类,各自指明仅凭 URL 无法确定的内容。

属性类型必需描述
kindenum是源种类。决定由哪个适配器解析该制品,以及预期的 mediatype。terraform-module-oci 属于该集合,但没有任何源适配器支持它:指定它的 Recipe 或 FeatureRecipe 在读取时即被拒绝。允许的值:"helm-oci-chart"、"helm-https-chart"、"compose-https-fragment"、"git-repository"、"terraform-module-oci"
urlstring是编写的 URL——即 Recipe 的 spec.source.url 中所写的标识 URL。对于 helm-https-chart,它是与编写时完全一致的仓库根(repo-root 形式)或直接的 .tgz(direct 形式);build 会离线重建同一个 URL,因此它是固定项所依据的稳定标识。对于 git-repository,它是可克隆的仓库 URL。对于 helm-oci-chart,它是注册表引用。对于 compose-https-fragment,它是该片段的 HTTPS URL。repo-root helm 源解析出的制品位置作为来源信息单独记录在 resolved_url: 下。
chartstring否repo-root helm 源的 chart 名称(Recipe 的 spec.source.chart),属于 {kind, url, chart, module_subdir, pinned_version} 标识的一部分,因此从同一仓库根提供、版本相同的两个 chart 会固定为不同的条目。对于直接 .tgz、OCI、compose 或 git 源则不存在,这些源都不会在 URL 内选择 chart。
module_subdirstring否git 来源仓库中作为制品的目录(Recipe 的 spec.source.module_subdir),属于 {kind, url, chart, module_subdir, pinned_version} 标识的一部分,因此同一仓库在同一提交下的两个目录会固定为不同的条目。当整个仓库即为制品时不存在;对于通过 URL 而非进入克隆目录来获取制品的所有种类也不存在。
pinned_versionstring是拉取时固定的具体版本。对于 helm-* 种类,为 chart 版本。对于 git-repository,为编写的引用所解析到的提交(而非原始的 tag/branch 引用——只要 Recipe 编写了 spec.source.ref:,该引用就记录在每个 referenced_by: 条目的 requested_ref: 下)。build 根据 Recipe 所写的内容查找此条目:有编写的 ref: 时,将其与记录的 requested_ref: 匹配,否则使用此固定值——因此,指定 tag 的 Recipe 会解析到该 tag 被固定时的提交,而提交本身无需出现在 Recipe 中。记录为单个路径段,因为它用于构造 build 读回制品的缓存槽位,所以不包含 /、\ 和 ..。模式:^([^/\\.]|\.[^/\\.])*\.?$。
resolved_urlstring否仅作来源信息:编写的 URL 在拉取时解析到的具体制品位置。对于 repo-root helm 源,这是仓库索引将 chart+version 解析到的直接 .tgz URL;它用于诊断,不属于制品标识。当解析出的位置与编写的 URL 相同时(直接 .tgz、OCI、compose 或 git 源)不存在。
digeststring是解析出的 .tar.gz 归档的内容摘要,格式为 sha256: 后跟 64 个小写十六进制字符。构建时校验会读取缓存槽位的字节、重新计算摘要,并将其与此字段比较;不匹配时构建中止,并报告内容摘要不匹配。模式:^sha256:[a-f0-9]{64}$。
manifest_digeststring否解析出的制品的 OCI manifest 摘要,格式为 sha256: 后跟 64 个小写十六进制字符。manifest 是校验缓存归档所依据的独立信任根;上面的内容 digest 是用于缓存固定和完整性检查的可移植标识。仅对通过 OCI 分发的源(helm-oci-chart)存在。模式:^sha256:[a-f0-9]{64}$。
mediatypestring是registry 声明的规范媒体类型(对于没有 registry 元数据的类型,则为该类型的默认值)。记录用于诊断来源信息。
referenced_bySourceArtifactReference[]是解析到该制品的目录实体,按 (uri, field) 排序,以保证输出确定。条目之所以存在,只因为某个 Recipe 或 FeatureRecipe 拉取了它,因此该列表永远不会为空。至少 1 个条目。

不允许其他属性。

SourceArtifactReference

单个“目录实体 → 源制品”反向指针。entity 与 uri 共同标识目录实体;field 指明实体 spec 中声明该制品的源侧路径。可选的 requested_ref: 保留 Recipe 编写的 spec.source.ref:,只要 Recipe 编写了它就会写入(git-repository 的 tag/branch → 提交 SHA)。

属性类型必需描述
entityenum是持有此反向指针的目录实体种类。允许的值:"recipe"、"feature_recipe"
uristring是Recipe 或 FeatureRecipe 的规范 URI(例如 hub.aggrega.ai/recipe/helm/mariadb-bitnami:1.0.0)。
fieldstring是实体 spec 中声明该制品的源侧路径。该值为 spec.source。
requested_refstring否可选——Recipe 编写的 spec.source.ref:,只要 Recipe 编写了它就会写入。对于编写了 ref: v1.0.0 的 git-repository Recipe,此字段保留 "v1.0.0",而 pinned_version: 保存该引用解析到的提交。当 Recipe 未编写 ref: 时不存在,所有解析器按原样固定编写版本的种类(helm-、compose-)均属此情况。它同时承担两项职责,而无条件地记录它,正是这两项职责互不排斥的原因。build 依据它进行关联,从指定引用而非提交的 Recipe 找到此条目。而非升级的 pull 会将每个记录的引用保持在其固定版本:远程端已移动的引用会中止运行,而不会被采用。

不允许其他属性。

VerifiedSignature

已验证签名事实,在拉取时依据解析所用 registry 的信任策略验证了制品签名后记录。每一种可签名的制品都以相同方式记录它——目录实体、库、Wasm 插件——因为它们都通过同一条路径验证,而不是每种类型各有一条。记录验证模式、匹配的无密钥身份/签发者(在无密钥模式下),以及内容缓存中签名包的内容寻址摘要。构建不会重新执行验证。在渲染任何内容之前,构建会在每个分区中、对其所依据的每个条目读取这一事实:重新哈希缓存的签名包,并将结果与 bundle_digest 比较,若该 blob 缺失或不一致则停止;对于由内容缓存提供的条目,构建会从该签名包中读取签名所针对的制品,若签名针对的制品不同于构建为该条目读取的制品则停止——因此,从一个条目复制到另一个条目上的 signature 会被拒绝,无论签名要求如何规定。构建不验证任何签名,因此手动写入缓存、针对该条目自身制品制作的签名包,与经拉取验证的签名包无法区分。而当工作区的信任配置要求由内容缓存提供的条目必须有签名时——这是 pull 在获取制品时应用的要求,因此允许拉取接纳无签名制品的跳过项和 advisory registry,也同样允许构建接纳其条目——未携带该事实的条目会使构建停止。从目录文件夹、编译器二进制文件内的副本或 Release 旁边读取的条目,永远不受该要求约束。

属性类型必需描述
bundle_digeststring是缓存的签名包 blob 的 SHA-256 摘要,格式为 sha256: 后跟 64 个小写十六进制字符。它用于命名缓存 blob,因此会构成路径,不包含 /、\ 和 ..——sha256: 格式本身已排除这些——并且对于任何分区中的条目,构建都依据它重新哈希该 blob 进行比对。模式:^sha256:[a-f0-9]{64}$。
identitystring否签名的已验证签名者:无密钥签名时为签名证书的主体;有密钥签名时为 keyed:sha256: 后跟固定公钥 PEM 文本的 SHA-256。
issuerstring否无密钥签名的已验证 OIDC 签发者。有密钥签名时为空。
modestring(枚举)是接纳该签名的验证模式。允许的值:"keyless"、"keyed"

不允许其他属性。