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

aggrega pin

aggrega pin <entity-path> 会在 Recipe 或 FeatureRecipe 旁边的 entity.lock 中,为该实体从其自身文档之外读取的每个输入记录内容固定值(pin)。这是实体作者执行的步骤:在实体被使用或发布之前运行它,并提交它写入的锁文件。

aggrega pin catalog/recipe/helm/server/1.0.0/recipe.yaml

它记录什么

实体可以依赖其自身文档之外的字节,锁文件为每一项保存一个固定记录:

  • 坐标完全写出的远程 source:——其 kind、url、chart、module_subdir、version 或 ref 中均没有模板。该步骤会获取它,并记录它解析到的版本(对于 git 源,即其 ref 所指的提交)以及所获取内容的内容摘要。
  • artifacts 条目通过 $import 导入的文件。 该步骤按文件在你的工作区中的当前状态计算其摘要。
  • 指向实体旁边的目录或文件的 source: 中的每个文件。 不会获取任何内容:该步骤对该源为实体发布内容所贡献的每个文件计算摘要——即其所指目录下被实体的忽略规则保留的每个文件,或那一个文件——并按其在实体旁边的路径记录。Recipe 旁边但不由该源贡献的文件(例如 README)不会被固定。以模板形式写出的源,例如 ./charts/{{ .values.flavour }},只有在 Release 填入后才指向其目录,因此它贡献实体目录中被规则保留的每个文件,而这些文件都会被固定。构建会在其 provider 读取源之前将源与这些固定记录进行比较,因此自固定以来新增、修改或删除的文件会使构建中止——A local source no longer matches the pins recorded beside its Recipe(本地源不再与其 Recipe 旁边记录的固定内容一致)。
  • 对于作为目录的 source:,还包括忽略规则本身。 该步骤记录是哪个插件提供了该实体的能力,以及它组合出的确切规则,如下一节所述。

它不记录的内容:坐标由模板填入的远程源——它只有在 Release 填入后才指向某个制品,并由 aggrega pull 固定在每个 Release 的锁文件中;以及内联的 artifacts 条目或取自 ArtifactLibrary 的条目。该文件本身在 实体锁 schema 中逐字段说明。

无需 Release。 完全写出的源对于将来使用该实体的每个 Release 都指向同一个制品,因此解析它不需要 Release 提供的任何内容。正因如此,作者可以在完全没有 Release 的工作区中固定实体。

实体文件永远不会被写入。 该步骤推导出的内容放在实体旁边;你输入的内容保持原样。在输入未变的情况下重新运行,锁文件逐字节保持不变;若实体不再读取任何锁文件所记录的内容,其锁文件会被删除。Component、Feature 或任何不读取此类输入的其他类型,会被报告为没有需要固定的内容,其旁边的任何内容都不会被改动。

哪些文件随实体一起发布

如果一个 Recipe 或 FeatureRecipe 的 source: 指向其旁边的目录(同目录下的 chart、模块),那么它在发布时会携带该目录中的文件。但并非其中的每个文件都应该包含在内:版本控制目录、依赖缓存、编辑器遗留文件都不属于其中。哪些文件应包含在内由忽略规则决定,规则采用 .gitignore 的语法,并且由你控制。 这些规则有两个来源:

  • 渲染该实体能力的插件会声明其自身生态从不发布的内容。chart 插件会排除版本控制目录(.git/、.hg/、.svn/、.bzr/)以及 chart 的 templates/ 下的隐藏文件,并遵循 chart 自身的 .helmignore:遍历源目录时,每遇到一个该文件,其中各行都会作为对其所在目录的附加规则读取。Terraform 插件会排除版本控制目录和 .terraform/ 工作目录(但不排除依赖锁文件,该文件本应随模块一起分发),并以同样方式遵循 .terraformignore。未声明任何内容的插件会保留所有文件。
  • 你自己的 .aggregaignore,即实体文档旁边的一个文件,采用相同的语法。其中各行在插件的规则以及插件指定的所有忽略文件之后应用,因此对于你指定的任何路径,你拥有最终决定权:例如 .venv/ 这样一行会排除插件一无所知的目录,而 !.git/ 这样一行会恢复插件排除的目录。该文件本身从不随实体分发;它的规则会随锁文件一起分发。
catalog/recipe/helm/server/1.0.0/.aggregaignore
.venv/
*.bak
!notes.bak

每条规则都相对于其所属目录读取。 插件声明的规则从源目录的根开始读取;.helmignore 中的一行从该文件所在目录读取;你的 .aggregaignore 中的一行从实体自身的目录读取。不含斜杠或仅含末尾斜杠的规则会匹配任意深度的名称;末尾斜杠仅匹配目录;开头的 ! 会恢复先前规则排除的内容。被规则排除的目录不会被进入,因此其中的文件只有在目录本身被恢复后才会恢复:在 .git/ 被排除时,仅凭 !.git/HEAD 无法恢复该文件,而 !.git/ 可以。

读取其规则的插件,是你执行 pin 时在工作区中为该能力提供服务的插件:即你的工作区为该能力配置的 provider 绑定,否则为 aggrega 内置的插件。该步骤会在 entity.lock 中按名称记录该插件(例如 provider/terraform,不含版本)以及它组合出的确切规则;使用更新的 aggrega 再次 pin 时,如果其插件声明的规则相同,锁文件保持不变。此后,对该目录的每次读取都只应用所记录的规则,而不应用其他规则:包括该实体的发布、pull 或 push 依据锁文件进行的比较、该实体在 lockfile 中的行、构建的比较、将目录交给 provider 的渲染,以及 aggrega pull --verify。因此,你发布的内容正是你自己的构建所渲染的内容;更改绑定、编辑 .aggregaignore 或升级 aggrega 在你再次 pin 之前都不会改变任何东西,而再次 pin 时,锁文件的 diff 会显示哪些内容发生了变化。插件指定为忽略文件的文件(例如 .helmignore)本身也是源中的文件之一,除非有规则将其排除,否则会像其他文件一样被 pin,因此编辑它而不重新 pin 会在下一次 pull 或构建时被发现。未记录任何规则的锁会保留该目录下的所有文件。

使用方渲染的是你的规则所保留的文件。 当一个插件使用相同的 ABI 版本、其契约与其实体的声明相符,并且不需要已发布集合之外的任何文件时,它就可以渲染为其能力发布的 Recipe。如果插件需要的文件被该集合排除,它必须让构建明确失败并指出该文件;宿主的职责是拒绝对集合未携带文件的任何打包或读取,并指出该文件。如果使用方工作区为该能力绑定的插件声明的规则与你的锁所记录的规则不同,使用方的 aggrega pull 会发出警告,指出两个插件及其差异,然后继续执行。

实体文件中的符号链接会被拒绝,无论它指向何处、能否解析,参见 A symbolic link sits among the files an entity carries(实体携带的文件中存在符号链接)。被你的规则排除的链接会像其他被排除的文件一样被跳过。如果实体指定的路径经过一个链接到实体目录之外的目录,该路径同样会在 pin 任何内容之前被拒绝,参见 A path names content outside the entity’s own directory(路径指向实体自身目录之外的内容)。

lock 写在哪里

lock 写在你所指定的文档旁边,位于同一目录中,因此该实体需要一个可写的归属位置:位于你自己目录中的文档。由 pull 从内容缓存解析得到的实体没有这样的归属位置,任何操作都不会对其进行固定。

一个目录,一个实体。 一个目录只容纳一个 entity.lock,因此,如果某个 Recipe 或 FeatureRecipe 与任何其他实体共用目录,无论其中任何一方是否有需要固定的内容,该步骤都会拒绝执行,并列出每个妨碍它的实体——该拒绝即 An entity shares its directory with another entity(一个实体与另一个实体共用目录)。除 Aggregate、Release 和 Manifest 可以并列放置外,每种类型都有自己的目录;push 对其发布的实体也遵循同一规则,详见 One entity per directory(每个目录一个实体)。该步骤只判断它要为之写入 lock 的内容,因此对于 Component 或它无需固定任何内容的其他类型,会报告为无可固定的内容,而拒绝会在该实体发布时作用于它。实体旁边不是实体文档的文件——chart 文件、被导入的文件本身——不构成妨碍。实体旁边的每个文档只从工作区内部读取,或者,对于你在工作区之外指定的文档,从其自身目录内部读取——lock 也保存在该目录中——因此,若某个文档是指向外部的链接,该步骤会停止,并在不读取的情况下列出该链接,详见工作区边界。

由谁固定,何时固定

固定是创作者的职责。 输入未被固定的实体尚不能被使用,因此默认情况下 pull 不会记录任何固定:对于 Release 所构建的、位于你某个目录目录中的 Recipe 或 FeatureRecipe,它会将此步骤将要记录的内容与锁文件中的内容进行比较,并在某个固定缺失或不再与其输入匹配时中止。中止信息会指出该实体、每个输入及其是远程源、导入文件还是本地源中的文件,以及本命令。该中止为 An entity reads an input the lock beside it records no pin for(实体读取了其旁边的锁文件未记录固定的输入)。push 对其发布的实体执行同样的比较,并以同样的中止拒绝,因此实体无法在有固定未记录的情况下通过 aggrega push 进入注册表——发布前固定对此有详细说明。本地源被视为一组文件: 锁文件未记录其中任何文件时,pull 或 push 会停止;自固定以来添加、更改或删除了文件时也会停止,与其他缺失或过期的固定相同。

首次 pull 时出现的中止应由发布者修复,而非使用者。 当你使用他人编写的目录时——例如在你自己的某个目录中检出该目录——而其中某个实体未被固定,说明作者从未运行此步骤。你的解决办法不是手动编辑他们的目录,而是设置下文的工作区键,让你的 pull 自行记录固定。

有两个命令会代你运行这一步骤,并写入相同的字节:

  • aggrega pull --pin-sources 会对 Release 所构建的实体运行该步骤,而不是中止。
  • aggrega push --pin-sources 会在打包实体之前对其运行该步骤,使其写入的锁文件成为发布内容的一部分,而不是拒绝。

每个命令都有一个使固定成为其默认行为的工作区键,即 pin_sources_at_pull 和 pin_sources_at_push,两者默认均关闭,且各自只控制自己的命令。标志在两个方向上都会覆盖其键:--pin-sources 会在单次运行中进行固定,无论键如何设置;--pin-sources=false 则不会。因此,配置为固定的工作区仍可在某次 pull 中恢复中止。填充自身锁文件的构建属于 pull,因此遵循 pin_sources_at_pull。这些键在配置参考中有说明。

更改已发布的实体

最佳实践:对已发布实体的修改应放入新版本,然后再固定——绝不要重新固定已经发布的版本。 将实体复制到新的版本目录,在那里进行更改,然后对新版本运行 aggrega pin。已发布的版本会继续准确描述其发布时的字节,而转向新版本的使用者是有意为之。

产品强制执行其中一半:在已发布的版本上发布更改后的内容会被拒绝,因此已发布的版本无法被悄然替换。它不会在你自己的工作区中强制执行另一半。修改后重新固定现有版本有时恰恰是正确的——例如,你在某个应用内部使用且尚未发布的实体——因此没有任何东西会阻止你,这一纪律需要由你自己遵守。

其他接口上的同一步骤

守护进程以 aggrega/pin 提供这一步骤(aggrega serve),工具协议则以 pin 工具提供(aggrega mcp);两者写入的字节与本命令写入的完全相同。通过 HTTP 监听器调用时,该工具会在工作区内写入,并访问实体的来源所指定的主机,因此调用方需要 workspace-write 作用域才能调用它——与拉取所需的授权相同。

另请参阅

概要

aggrega pin <entity-path> [flags]

说明

Record, in the entity.lock beside a Recipe or FeatureRecipe, the content pin for every input
the entity reads from outside its own document: a remote source: whose coordinates you wrote out
in full, a file an artifacts entry imports with $import, and each file of a local source:.
Pinning is the entity author's step. Run it on an entity before it is consumed — before you
publish it, and after every change to one of its inputs — and commit the entity.lock it writes
beside the entity. A pull over an entity whose lock does not record these pins halts and names
this command, and so does a push of it; so does one whose local source has had a file added,
changed or removed since it was pinned.
No Release is needed. A source whose coordinates carry no template names one artifact for every
Release that uses the entity, so it is resolved and pinned here, with nothing supplied. A remote
source whose coordinates are filled in from a template is not pinned here: which artifact it names is
decided by each Release, and each identity it resolves to is pinned in that Release's lockfile.
A source that names a directory beside the entity is not fetched: each file it contributes to what
a publication of the entity carries is digested as it stands and pinned by its path, so a build
refuses a file added, changed or removed after the pin. A local source written as a template
contributes every file in the entity's directory, so each of those is pinned.
Which files a source directory contributes is decided here, once, and recorded. The step reads the
ignore rules the plugin serving the entity's capability declares — this workspace's provider binding
for that capability, or else the plugin built into aggrega — together with the ignore files that
plugin names inside the source, such as a chart's .helmignore, and the .aggregaignore beside the
entity, in gitignore syntax, whose lines come last and so have the final say. It records the plugin
and the composed rules in the entity.lock, and every publication, pull, build and render of the
entity applies the recorded rules and no others, so a changed binding or a newer binary moves
nothing until you pin again. A symbolic link among the files is refused rather than followed.
The step writes beside the entity, so the entity needs a writable home: the document you name is
read from its own directory and the lock lands next to it. The entity file itself is never
written to. Re-running over unchanged inputs leaves the lock byte-identical; an entity that reads
nothing a lock records has its lock removed. A Component, a Feature or any other kind that reads
no such input is reported as having nothing to pin, and nothing beside it is touched.
A directory holds one entity.lock, so the step refuses a Recipe or FeatureRecipe that shares its
directory with any other entity, naming the entity in the way, whether or not either has anything
to pin. Every kind has a directory of its own except Aggregate, Release and Manifest, which may sit
side by side; a push holds the entity it publishes to the same rule.
aggrega pull --pin-sources and aggrega push --pin-sources run this same step on your behalf, and
write the same bytes.

标志

标志默认值描述
--dry-runfalse解析实体的输入,并打印该步骤将要写入的 entity.lock,而不实际写入:其路径和将包含的内容输出到 stdout,磁盘上的任何内容都不会改变。该步骤会保持字节完全相同的锁不会被打印。解析过程与正常运行时完全相同,因此内容缓存仍会被填充