Aggrega Entity Lock schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/entity-lock-v1beta1.schema.json
entity.lock 文件位于实体旁边,记录该实体在自身文档之外所引用输入的内容固定值:其 artifact 导入的文件、本地源的文件,以及实体完整写出其标识的远程源——对于目录形式的本地源,还记录决定其中哪些文件属于该实体的规则。写入它的只有一个步骤:aggrega pin,由实体作者运行,无需任何 Release。aggrega pull 和 aggrega push 在被要求时也会运行同一步骤,并写入相同的字节——通过 --pin-sources,或通过工作区的 pin_sources_at_pull 或 pin_sources_at_push。未被要求固定的 pull 不会在此写入任何内容:对于工作区自身目录中的实体,它会将该步骤将要记录的内容与文件中已有的内容进行比较,并在某个固定值缺失或不再与其输入匹配时停止并提示 aggrega pin——对于本地源,自固定以来新增、修改或删除的文件会像其他过期固定值一样使 pull 停止。aggrega build 会读回该文件,并在磁盘上的内容的摘要不再与记录值一致时停止。它的作用范围由其所在目录决定——它固定该目录中实体的输入——因此一个文件名适用于所有种类,而无需每个种类各自使用不同的拼写。对于不读取此类输入的实体,该步骤会删除其锁文件,而不是留下一个空文件。实体文档本身从不由机器写入:作者键入的内容保持原样,机器推导的内容存放在这里。正是这种分离使锁文件可以安全提交,并能以 diff 形式阅读,因为每一行对应一个输入,而变化的摘要会指出发生变化的输入。它不包含时间戳,也不包含解析元数据,因此对未变化的输入重新运行该步骤,文件将保持字节一致。所有能够记录固定值的种类共用同一种行结构,因此无论固定值属于哪个种类,其读法都相同。线上结构是封闭的(additionalProperties: false)。Schema 演进原则:添加新的可选字段属于 SemVer-MINOR(增量);删除字段或收紧约束属于 SemVer-MAJOR。
顶层类型: object
属性
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
version | const 1 | 是 | entity-lock schema 版本:1。schema 的 SemVer-MAJOR 变更会递增此值。常量:1 |
sourceDigests | object[] | 否 | 该实体所引用、且由实体完整写出其标识的远程源的内容固定值,在解析时根据获取的字节冻结,并在构建时读回,以验证缓存的源未发生漂移。每个条目镜像已解析源的标识 {kind, url, chart, moduleSubdir, version},外加内容摘要(对于通过 OCI 分发的源,还包括 manifest 摘要)。标识由模板填充的源(例如从 Release 的基础设施值中读取的版本)在此没有条目:它指向哪个制品由使用该实体的每个 Release 决定,因此它解析到的每个标识改为固定在该 Release 的 lockfile 中。本地(相对于文件系统的)源在此同样没有条目:它指向的是路径而非获取的内容,因此没有可固定的已获取归档,它的文件改为在 localSourceDigests 中逐个固定。 |
artifactDigests | object[] | 否 | 该实体的制品通过 $import 导入的文件的内容固定值(对于 Recipe,还包括其 boundary.artifacts 条目导入的文件),在解析时冻结,并在构建时读回,以验证导入的文件未发生漂移。每个值为文件导入的制品对应一个条目;内联(字面量)制品本身已是实体的一部分,不单独固定,而取自库的制品则由该库解析时的版本固定。构建以相同方式将任一块中的条目与其固定值比较,并在相同条件下拒绝不再匹配的文件。 |
localSourceDigests | object[] | 否 | 该实体本地源的文件的内容固定值(本地源是写为实体旁路径而非获取的源),在固定实体时冻结,并在构建时读回,以验证这些文件未发生漂移。该源为实体发布内容贡献的每个文件对应一个条目:源所指目录下、被 ignore 中记录的规则保留的每个文件,或源所指的那一个文件。写为模板的本地源只有在 Release 填充模板后才指向其目录,因此它贡献实体自身目录中被所记录规则保留的每个文件,且每个文件都会被固定。实体文档、其旁边作者的 .aggregaignore 以及本文件绝不会成为条目:文档就是实体本身,ignore 文件的规则记录在 ignore 下,而锁文件无法记录自身的摘要。一旦锁文件在此记录了任何条目,构建就会拒绝以下情况的源:包含没有条目的文件、文件内容的摘要不再与其条目一致,或缺少某个条目所指的文件。 |
ignore | object | 否 | 决定该实体本地源目录下哪些文件属于该实体的规则,在固定实体时记录。此后对该目录的每次读取都只应用这些规则:实体的发布、pull 或发布将锁文件与之比较的过程、作者的实体行、构建的比较及其渲染,以及验证性的 pull。因此,对作者的 .aggregaignore、工作区的 provider 绑定或 aggrega 二进制文件的更改在实体再次固定之前不会改变任何摘要,而再次固定后,此处会以 diff 的形式显示该更改。仅当实体声明了一个目录形式的本地源,或写为模板的本地源时才出现。未记录任何规则的锁文件保留该目录下的所有文件。其下任何位置的符号链接都会被拒绝,而不会被跟随。 |
不允许其他属性。
entity-lock.sourceDigests[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
kind | enum | 是 | 已解析的源类型。取值属于一个封闭集合(与 lockfile 中源制品的 kind 和缓存元数据的 kind 所用集合相同),因为三者记录的是相同的已解析源标识,且构建会读取该类型以选择加载器。terraform-module-oci 属于该集合,但没有任何源适配器为其提供服务:指定它的 Recipe 或 FeatureRecipe 在读取时即被拒绝。允许的值:"helm-oci-chart"、"helm-https-chart"、"compose-https-fragment"、"git-repository"、"terraform-module-oci" |
url | string | 是 | 摘要所固定的、作者编写的源 URL,即 spec.source.url 中写出的标识 URL(仓库根地址,或对于 helm-https-chart 为直接的 .tgz)。构建会离线重建同一 URL,因此它是固定值所依据的稳定标识,而不是已解析的制品位置。 |
chart | string | 否 | 仓库根形式的 helm 源的 chart 名称(spec.source.chart),属于已解析源标识的一部分,使从同一仓库根以相同版本提供的两个 chart 分别固定。对于直接 .tgz、OCI、compose 或 git 源不存在,这些源都不在 URL 内选择 chart。 |
moduleSubdir | string | 否 | git 源仓库中作为制品的目录(spec.source.module_subdir),属于已解析源标识的一部分,使同一仓库在同一提交下的两个目录分别固定。当整个仓库就是制品时不存在;对于通过 URL 而非深入克隆来获取制品的所有类型也不存在。 |
version | string | 是 | 源解析到的具体固定版本:对于 helm-* 类型是 chart 版本,对于 git-repository 是引用解析到的提交。记录为单个路径段,因为它构成构建读回源所用的缓存槽位,所以不含 /、\ 和 ..。模式:^([^/\\.]|\.[^/\\.])*\.?$。 |
digest | string | 是 | 所获取源归档的内容摘要,格式为 sha256: 后接 64 个小写十六进制字符,在构建时根据缓存的字节进行验证。模式:^sha256:[a-f0-9]{64}$。 |
manifestDigest | string | 否 | 通过 OCI 分发的源的 OCI manifest 摘要(独立的信任根),格式为 sha256: 后接 64 个小写十六进制字符。仅对 OCI 源(helm-oci-chart)存在;对于 https 或 git 源不存在,这类源从结构上就没有 manifest。模式:^sha256:[a-f0-9]{64}$。 |
不允许其他属性。
entity-lock.artifactDigests[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 此条目固定的是哪个制品的 $import 文件:对于 artifacts 的条目,是 artifacts: 映射的键;对于 Recipe 的 boundary.artifacts 的条目,是 boundary/ 后接该键。因此两个块中写在同一键下的条目会分别固定。 |
digest | string | 是 | 导入文件字节的内容摘要,格式为 sha256: 后接 64 个小写十六进制字符,在构建时验证。模式:^sha256:[a-f0-9]{64}$。 |
不允许其他属性。
entity-lock.localSourceDigests[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
path | string | 是 | 文件相对于实体文档所在目录的路径,使用正斜杠书写,例如 charts/app/templates/deployment.yaml。 |
digest | string | 是 | 文件字节的内容摘要,格式为 sha256: 后接 64 个小写十六进制字符,在构建时验证。模式:^sha256:[a-f0-9]{64}$。 |
不允许其他属性。
entity-lock.ignore
决定该实体本地源目录下哪些文件属于该实体的规则,在固定实体时记录。此后对该目录的每次读取都只应用这些规则:实体的发布、pull 或发布将锁文件与之比较的过程、作者的实体行、构建的比较及其渲染,以及验证性的 pull。因此,对作者的 .aggregaignore、工作区的 provider 绑定或 aggrega 二进制文件的更改在实体再次固定之前不会改变任何摘要,而再次固定后,此处会以 diff 的形式显示该更改。仅当实体声明了一个目录形式的本地源,或写为模板的本地源时才出现。未记录任何规则的锁文件保留该目录下的所有文件。其下任何位置的符号链接都会被拒绝,而不会被跟随。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
plugin | object | 否 | 固定该实体时,在作者的工作区中为该实体的能力提供服务的插件(即工作区中该能力的 provider 绑定,否则为 aggrega 二进制文件内置的插件),以不带版本的名称记录,以及该插件声明的忽略规则。插件的版本和摘要均不记录:每次读取所应用的是这些规则,因此在同一插件的另一个版本下重新固定时,除非规则发生变化,否则锁文件保持不变。如果某次拉取自身用于该能力的插件声明了不同的规则,则会通过一条提示信息说明这一点,指出两个插件及其差异,但绝不会因此停止。没有插件为该能力提供服务时不存在。 |
rules | object[] | 否 | 组合后的确切规则,按其应用顺序排列:先是插件的模式,然后是遍历时找到的、插件所指定的每个忽略文件中的各行(某目录自身的文件先于其下级目录中的文件),最后是实体旁作者的 .aggregaignore 中的各行。后出现的匹配会覆盖先出现的匹配,因此对于作者文件所指定的任何路径,以作者文件为准;以 ! 开头的行会恢复先前规则所排除的内容。被某条规则排除的目录不会被进入,因此其下的文件只有在该目录被恢复后才会恢复。 |
不允许其他属性。
entity-lock.ignore.plugin
固定该实体时,在作者的工作区中为该实体的能力提供服务的插件(即工作区中该能力的 provider 绑定,否则为 aggrega 二进制文件内置的插件),以不带版本的名称记录,以及该插件声明的忽略规则。插件的版本和摘要均不记录:每次读取所应用的是这些规则,因此在同一插件的另一个版本下重新固定时,除非规则发生变化,否则锁文件保持不变。如果某次拉取自身用于该能力的插件声明了不同的规则,则会通过一条提示信息说明这一点,指出两个插件及其差异,但绝不会因此停止。没有插件为该能力提供服务时不存在。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 固定该实体时为其能力提供服务的插件,写作 <pluginType>/<name>,不带版本:读取时应用的是下面的规则,而该名称说明这些规则属于谁。长度至少为 1 个字符。 |
patterns | string[] | 否 | 插件声明的忽略模式,与其声明时保持一致。 |
files | string[] | 否 | 插件声明其生态系统在源中遵循的忽略文件的名称。 |
不允许其他属性。
entity-lock.ignore.rules[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
pattern | string | 是 | 一个采用 gitignore 语法的忽略模式。 |
within | string | 是 | 该模式所作用的目录,相对于包含实体文档的目录,使用正斜杠书写;. 表示该目录本身。插件声明的模式作用于本地源目录,忽略文件中的一行作用于包含该文件的目录,作者的 .aggregaignore 中的一行作用于实体所在的目录。 |
from | string | 是 | 该模式的声明位置:插件声明的模式为 plugin,否则为读取该模式的忽略文件的路径,相对于包含实体文档的目录。 |
不允许其他属性。