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

aggrega push

aggrega push 将一个目录实体发布到 OCI 注册表,其他工作区可通过 aggrega pull 解析该实体。

功能说明

aggrega push 读取单个实体 YAML,将其打包以便传输,并推送到 <registry>/<kind>/<metadata.name>:<metadata.version>,其中仓库路径转换为小写;Recipe 或 FeatureRecipe 会将其 spec.capability、Plugin 会将其 metadata.pluginType 作为种类与名称之间的一段路径。运行 aggrega push --list-kinds 可查看已安装的二进制文件所发布的实体种类:每行一个种类,已排序,且不输出其他内容,因此脚本可以直接读取。该集合涵盖各个目录编写种类,以及 Aggregate(一种可复用模块)和 Plugin(对 WebAssembly 制品的内容寻址引用,由编译器路由、由运行时执行)。Plugin 是一种结构性的可发布制品,而不是目录编写种类。可发布性是实体本身的属性,与其使用方式无关:无论一个 Aggregate 之后被某个 Release 的顶层 spec.aggregate 引用,还是嵌套在另一个 Aggregate 的 aggregates: 块中,它都是可发布的。Release 和 Manifest 是部署侧的输入,而不是目录制品,因此会被拒绝。

打包

**一次推送发布实体文档以及实体自身在其旁边指明的文件——其目录中的其他内容一概不发布。**实体指明的文件为:

  • 对于 Recipe 或 FeatureRecipe,是其本地 source:——目录会连同其下所有被其 entity.lock 中记录的忽略规则保留的文件一起传输,如 哪些文件随实体一起发布 所述;其 valuesMapping:、workload: 和 artifacts: 条目通过 $import: 导入的每个文件;以及其旁边的 entity.lock;
  • 对于 Component 或 Feature,是其 spec.schema、某个支柱或某个 usesSchema 插槽通过 $import: 导入的每个 schema 文件,包括被导入文件再导入的每个文件。

Aggregate、Plugin 和各库类型不会在其文档旁指明任何文件。目录中的说明文件、README、其他实体的文件或构建输出都不会被发布,无论其名称如何。实体指明的文件中若有符号链接,会被拒绝而不是被跟随——A symbolic link sits among the files an entity carries(实体携带的文件中存在符号链接)——实体通过某个链接到实体目录之外的目录所指明的路径同样如此,这一检查在打包任何内容之前进行——A path names content outside the entity’s own directory(路径指向实体自身目录之外的内容)。

**发布形式由此而定。**未指明任何文件的实体,以其文档原样发布,使用其类型的 +yaml 媒体类型。指明了文件的实体,以 .tar.gz 形式发布,其中包含文档以及这些文件,各自位于其在目录中的位置,使用其类型的 +tar+gz 媒体类型。因此,内容全部内联的 Recipe 以其文档发布,而 schema 从文件导入的 Component 以归档发布。目录与注册表 §6 列出了每种类型的两种媒体类型。

**归档中的每个文件都带有模式 0644 且不带时间戳,无论其在磁盘上的权限位如何。**检出操作会以自己的权限位写入文件,而不记录执行位的系统会把另一系统检出为可执行文件的内容检出为普通文件,因此归档不携带从磁盘读取的模式:同一提交的两次检出,无论其 umask 如何、在哪个系统上完成,发布的文件都相同,翻转脚本的执行位也不会改变任何已发布内容。

推送会对归档中每个 Windows 无法按原样保存的条目发出警告——路径中某一部分以设备命名,如 CON、AUX 或 NUL,不区分大小写,且无论后面跟什么扩展名,例如 aux/x.yaml;或某一部分以句点或空格结尾,例如 report.。在 Windows 上,aggrega 拒绝解包此类条目,因此 Windows 工作区无法使用该版本。该警告在所有平台上都写入标准错误,每个条目一行,位于发布本身的输出之前;实体文档自身的文件名与其指明的文件一同判断,而未指明任何文件的实体仅以其文档发布,永远不会收到警告。警告不拒绝任何内容:推送照常进行或被拒绝,与没有警告时完全相同,--dry-run 也以同样方式发出警告。A published archive carries an entry Windows cannot use(已发布的归档包含 Windows 无法使用的条目) 展示了该行内容及处理方法。

**以模板形式编写的本地 source: 会携带整个目录。**诸如 ./charts/{{ .values.flavour }} 的模板只有在 Release 填入值后才指向某个目录,因此任何发布都无法得知它将是哪个目录。此类实体会携带其自身目录中被其记录的忽略规则保留的每个文件——但从不包括其 .aggregaignore,其规则随锁文件一同传输——推送会在其他信息下方说明这一点:

carries: every file in the entity's directory, because its source "./charts/{{ .values.flavour }}" is a template and the directory it names is decided by each Release that uses it

**未指明的内容不会被传输,而发现问题的是使用方。**实体依赖但未通过上述某个字段指明的文件不在发布内容中,使用方构建时会失败,并指出其缓存槽中缺失的路径——失败的不是你的推送。请通过上述字段指明实体所需的每个文件。

每个已发布文件都在制品的清单中命名,因此 oras 等通用 OCI 客户端会将其写入同名文件:以文档发布的实体为 entity.yaml,连同文件发布的实体为 entity.tar.gz,对于 Plugin,实体为 entity.yaml,其旁的可执行文件为 entity.wasm。该名称由媒体类型决定,而非由你发布时所用的文件决定,因此从重命名后的文件发布相同内容,得到的是同一个制品。目录与注册表 §6 列出了每种发布形式及其落地的文件名。

Recipe 上的远程 source: URL(OCI chart 引用、HTTPS chart 或片段 URL、Git 模块)在发布的 YAML 中原样保留;它不会被拉取并内置到制品中。使用方在各自拉取时独立解析并固定远程源。这使目录实体分发与源制品解析保持为相互独立的关注点。

Aggregate 以其自身的单个文档发布:它在 aggregates: 中引用的子 aggregate 不会被打包进制品。每个子 aggregate 都是单独发布的 Aggregate,使用方在拉取时按标识独立解析并固定——这与适用于远程源的分发分离原则相同。

每个目录一个实体

归档在实体所指名的文件中包含实体文件本身,因此取出时必须能重新找到该实体。使用方通过实体携带的前导部分来找到它:位于包顶层、且其 kind: 为可发布实体类型的文档即为该实体。编写实体的文件可以取任意名称——recipe.yaml 是目录的约定,而非要求——位于实体旁边的 compose 片段、chart 模板或 Kubernetes manifest 不会被误认为实体,因为它们声明的是其他类型,或根本没有声明类型。位于更深层、source/ 树中的实体文档属于该实体所携带的内容,而非实体本身,永远不会被考虑。

推送会拒绝与另一个实体共用目录的实体。 除 Aggregate、Release 和 Manifest 外,每种类型都有自己的目录;这三种由工作区根目录并列存放。对于其他任何类型,推送在对该实体执行任何其他操作之前——在 pin 步骤、签名策略和打包之前——都会检查同一目录中没有其他实体文档,否则拒绝,并指出每个造成阻碍的实体,无论推送是否被要求执行 pin。aggrega pin 会以相同的措辞拒绝同样的目录;该终止为 An entity shares its directory with another entity(一个实体与另一个实体共用其目录)。实体旁边不属于任何实体类型的文档——chart 文件、compose 片段、README——不构成阻碍,子目录中的任何内容也不构成阻碍。实体旁边的每个文档都只从工作区内部读取;对于你在工作区之外指定的实体,则只从该实体自身的目录内部读取,因此如果某个文档是指向外部的链接,推送会停止,并指出该链接而不读取它,详见工作区边界。

这条规则确保一个 entity.lock 只属于一个实体:锁文件的文件名对每个实体都相同,因此在同一目录中编写的两个实体将共用该目录只能容纳的那一个锁文件。只有在从该目录产出内容时才会进行这项检查,因此包含多个实体的目录仍然可以加载、lint 和构建。

目录名称不受检查。 单独位于其目录中的实体,无论该目录位于何处,都会以其 metadata.version 发布;<name>/<version>/ 是标准库目录所遵循的布局,属于约定。其他客户端从包含两个实体的目录发布的制品仍能被安全读取:拉取它时会终止并指出两个文档,而不会返回其中任何一个,记录于 errors/fatal-halts.md。

在打包之前读取实体

推送读取 Component、Feature、Recipe 或 FeatureRecipe 的方式与构建读取它的方式相同,并拒绝该读取所拒绝的实体——原因相同,短代码相同,且发生在构建包之前、联系目标注册表之前。因此,不符合其种类 schema 的文档、指向实体自身目录之外内容的路径,以及 Component 或 Feature 通过 $import: 导入但缺失或无法使用的 schema,都会在发布时被拒绝,而不会被发布。其中每一种都是其使用者首次构建时会拒绝的实体;离开该目录的路径还指向一个不会随实体一起传递的文件,因为发布所携带的每个文件都取自实体自身的目录——参见 A path names content outside the entity’s own directory(路径指向实体自身目录之外的内容)。

Recipe 或 FeatureRecipe 在比较其固定版本时以这种方式被读取(下一节将对此进行说明),因此无论推送是否被要求固定版本,也无论实体是否有需要固定的内容,这一读取都会发生。这四种种类中的每一种在构建其包之前也会立即以这种方式被读取,因为正是这一读取说明了它指向哪些文件。Aggregate 和库不指向任何文件,不会以这种方式被读取。Plugin 同样不指向任何文件,它会在读取其 .wasm 之前先按其种类的 schema 被读取,如 发布 Plugin 所述。

发布 Plugin

Plugin 与其 .wasm(由 --plugin 指定)一同发布,push 会在发布任何字节或联系注册表之前对两者进行判定。--dry-run 的判定方式与发布时完全相同。

首先依据其类型的 schema 读取实体,读取方式与加载 catalog 时相同,且在读取 .wasm 之前进行。因此,不是语义化版本的 metadata.version(例如裸提交 415148e)会按照 schema 自身的条件被拒绝,并指明该字段;任何其他偏离 schema 的情况(例如缺少 spec.abiVersion)同样会被拒绝。此处什么算作语义化版本,取决于 schema 自身为 metadata.version 定义的模式;push 不会添加任何自己的规则。

然后加载 .wasm 并将其与实体对照。 它报告提供的内容必须与实体声明的内容一致,实体记录的命令集和宿主函数必须与之匹配,它报告的自身构建版本必须等于 metadata.version——参见 A Plugin entity’s recorded version does not match the plugin(Plugin 实体记录的版本与插件不匹配)。

从含有未提交更改的工作树构建的 .wasm 会被拒绝。 这样的构建会在其报告的版本末尾带有 -dirty 标记,例如 1.0.0-dirty、1.0.0-3-g1a2b3c4-dirty。这是有效的语义化版本,但它指向的提交并不包含实际构建的内容,因此没有人能根据发布时所用的版本重新构建出已发布的内容。push 会拒绝它,并指明该版本和修复方法:从该 release 的标签所指提交的干净检出构建插件,使其报告的正是 release 版本本身——若要发布该更改,请先将 metadata.version 设为新 release 后提交该更改,并为该提交打上标签——而不是把重新构建报告的版本复制到实体中。从提交构建的开发版本(例如 1.0.0-3-g1a2b3c4)和预发布版本(例如 1.0.0-rc.1)都可以发布。该拒绝为 A plugin was built from a working tree with uncommitted changes(插件是从含有未提交更改的工作树构建的)。

发布前固定

Recipe 或 FeatureRecipe 把它所读取输入的固定记录——完整写出的远程 source:、某个 artifacts 条目导入的文件、旁边某个 source: 的文件——保存在它旁边的 entity.lock 中,push 会把该文件与实体一同发布。固定是你在发布前运行的一个步骤,即 aggrega pin,并提交它写出的锁文件。

push 会拒绝锁文件未记录这些固定的实体。 在构建 bundle 之前,push 会算出固定步骤将为该实体记录的内容,并与旁边的 entity.lock 比较。若缺少某个固定,或锁文件中的某个固定已与输入不再匹配,push 会在构建任何归档或联系任何 registry 之前停止。该拒绝会指明实体以及每个此类输入——各自为 remote source、imported file 或 local source file——以及应运行的命令:对该实体运行 aggrega pin,在你刚运行的 push 上加 --pin-sources,或为工作区中的每次 push 设置 pin_sources_at_push。这与 pull 针对同一锁文件引发的拒绝相同,即 An entity reads an input the lock beside it records no pin for(实体读取了其旁边锁文件未记录固定的输入),只是附带 push 自己的补救办法。因此,push 发布的 Recipe 或 FeatureRecipe 会在其 bundle 内携带一个锁文件,记录发布那一刻固定步骤本应记录的每一个固定。

有两类实体无需固定,会原样发布:不读取远程源、不导入文件且不指明本地源的实体;以及远程源坐标由模板填充的 Recipe。这种源只有在某个 Release 填充模板后才指向某个制品,因此它的固定属于每个 Release 的锁文件,push 不会要求实体旁边有它。Component、Feature、库、Aggregate 或 Plugin 不读取锁文件所记录的任何内容,在此从不会被拒绝。

比较远程源的固定意味着要获取该源,与 aggrega pin 一样,因为固定是否已不再匹配,只有对照源当前提供的内容才能看出。因此,对带有此类源的实体执行 push,会先访问源的主机,再访问 registry。比较时按固定步骤的方式通过目录读取 Recipe 或 FeatureRecipe,因此目录拒绝读取的实体——例如不符合其种类 schema 的文档——会在此以目录自身的理由被拒绝。

若未找到工作区也未指定工作区,需要为比较而获取远程源的 push 会在获取之前被拒绝,与 aggrega pin 相同。 比较会把实体完整写出的每个远程源获取到制品缓存中,与固定步骤完全一样;而在未找到工作区的文件夹中写入缓存,会使该文件夹成为工作区。因此,当没有任何东西指定根目录、也没有任何东西锚定根目录时——无论是从你运行 push 的文件夹,还是对于以绝对路径指定的实体,从实体自身所在的文件夹——带有此类源的 Recipe 或 FeatureRecipe 的 push 会在获取源之前停止,dry run 和 --pin-sources 也不例外,并指明该源、该文件夹以及两种解决办法:用 --workspace-root 或 AGGREGA_WORKSPACE_ROOT 指定你的工作区,或为该文件夹提供一个带有 workspace: 块的 .aggrega-config.yaml。对于上述两类实体,以及源为本地的实体,比较不会获取任何内容,因此它们都会与其锁文件比较,并像在其他地方一样在那里发布;其他所有种类都不受锁文件约束,也不会因此被拒绝。配置列出了同样适用此规则的其他命令。

aggrega push --pin-sources 会先替你运行同一步骤。 该步骤在构建 bundle 之前运行,因此它写出的锁文件包含在发布的制品中,发布的 digest 也涵盖它;并且它先于所有其他评判实体的拒绝运行,因此被评判的是已固定的实体。只有上述目录规则先于它,因为该步骤写入的是目录中唯一的锁文件。它写出的字节与 aggrega pin 相同,因此上述拒绝在该次运行中永远不会触发:该步骤刚写出的锁文件恰好记录了拒绝所要比较的内容。工作区键 pin_sources_at_push 使其成为每次 push 的默认行为,而 --pin-sources=false 会在单次运行中跳过该步骤,从而使该拒绝重新生效。该步骤写在实体旁边,这需要一个可写的位置——而 push 总有一个,因为它发布的就是你指定的文档。

--dry-run 的回答与发布时一致。 不带 --pin-sources 时,它会像发布一样拒绝未固定的实体,因此报告了 bundle 的 dry run 就是该拒绝会放行的那种。带 --pin-sources 时,该步骤以 dry run 方式固定:它打印将要写出的锁文件但不写入任何内容,随后的 bundle 信息描述的是目录的当前状态,不含该锁文件——因此 digest 是不含该锁文件的发布的 digest;若该锁文件是新的,大小以及(对于未指明其他任何内容的实体)媒体类型也是如此。拒绝不会触发,因为发布时会先进行固定。

最佳实践:对已发布版本的更改应放入新版本,然后再固定。 把实体复制到新的版本目录中,在那里进行更改,固定它,然后发布。其中由产品强制执行的一半见下一节:在已发布的版本上发布不同的内容会被拒绝。另一半——在你自己的工作区中编辑已发布的版本后不要重新固定——需要你自己遵守;本地不会拒绝这样做,因为对尚未发布的实体重新固定是合理的。

注册表、标签与内容寻址

目标注册表在提供了 --registry <ref> 时为该值,否则为工作区的 default_registry(默认为 hub.aggrega.ai)。标签是实体的 metadata.version,仓库路径由其类型和名称推导而来,因此已发布版本的落点与发布时所在的目录无关。

default_registry 可以带有仓库路径,通过它进行的发布会落在该路径下。 当 default_registry: ghcr.io/acme 时,版本为 1.0.0 的 Component core/api-server 发布在 ghcr.io/acme/component/core/api-server:1.0.0——这正是通过同一默认值进行的拉取获取它的位置,因此此处附加的签名就是该拉取找到的签名。--registry 指定的是主机,由它指定的发布会落在该主机上,不带路径。无论以哪种方式指定目标,适用的签名要求和签名配置都是为其主机保存的那些:路径永远不会选择不同的策略。路径的写法见如何书写注册表主机。

manifest 指明所发布字节的摘要,lockfile 记录这些字节所承载内容的摘要。 push 写入的 OCI manifest 指明所发布文档或归档的摘要,aggrega pull 会拒绝与之不匹配的下载,因此在发布与拉取之间被篡改的字节会被发现。pull 写入的 lockfile 以另一个摘要记录该实体:其内容的摘要——每个文件的路径及其字节,而不涉及归档的压缩方式或其中文件的权限位。这与作者自己工作区中的 pull 为其目录(catalog directory)中同一实体记录的摘要相同,因此作者和同一发布的每个使用者都记录相同的值,任何一方的构建都会拒绝不再与之匹配的内容。两个摘要回答的是不同的问题:manifest 中的摘要校验下载,lockfile 中的摘要是实体的身份标识。

覆盖已有版本发布

在上传任何字节之前,aggrega push 会解析目标注册表在其即将写入的引用处已持有的内容,并与手头的内容进行比较。共有三种结果:

  • 该处尚未发布任何内容——推送照常进行并正常发布。
  • 内容相同——不上传任何内容,命令报告该版本已发布,因此重复或重试的推送不是错误。先前推送未附加的内容(签名或发布日期)此时会被附加,如完成先前推送遗留的部分发布所述。
  • 内容不同——推送中止,并给出已发布的摘要和本应写入的摘要。没有任何标志可以强制推送。

因此,已发布的版本始终指代在其下发布的字节。已变更的内容应以新的 metadata.version 发布;aggrega lint --pre-publish 通过将变更与先前发布的版本进行比较分类,回答下一个问题:该版本需要升级多少。

--dry-run 会打印推送将写入的摘要,以及将写入的引用:

aggrega push (dry-run): <reference>:<tag> (<digest>)

它正是推送本身与已发布内容进行比较的摘要,同样仅根据内容计算,打印它不会联系任何注册表。因此,在推送任何内容之前,就可以将手头的内容与某个版本发布时的摘要进行比对:若在已发布版本处二者不同,推送将被拒绝。使用 --pin-sources 时,它是目录当前状态的摘要,如发布前固定所述。

完成先前推送遗留的部分发布

推送先写入内容,之后再附加签名和发布日期,因此在其中某项附加上失败(在重试之后)的推送会使内容在缺少该项的情况下处于已发布状态,并以非零状态退出,指明无法附加的内容。再次运行同一推送即可完成该发布。它会发现内容已发布,打印 Already published: 行,不上传任何内容,并附加该版本仍缺少的项,每项都打印首次发布时为其打印的那一行:

  • 签名,在本次推送进行签名时。 当该版本没有可视为本次发布所属的签名时,会附加签名。若你的配置为目标主机固定了信任策略(public_key 或 trusted_identities,或对 hub.aggrega.ai 而言的内置基线),则签名在该策略下验证通过时才算数,因此策略不接纳的签名永远不会被当作本次发布自己的签名。若策略二者都未固定,则没有签名能据此验证,因此该版本携带的任何签名都算数,推送只会对不带签名的版本进行签名;若此时依据验证来判断,每次运行都会再附加一个签名。
  • 发布日期,在日期规则要求提供日期(从刚附加的签名或已计入的签名中读取),且该版本完全没有 published-at 引用方时附加。不进行签名的推送按未签名发布的方式提供日期,无论之后该版本被附加了哪些签名。它所声明的日期取自本次推送自己的时钟:即发布完成的时间,这晚于内容最初落地的时间,因为注册表提供的任何内容都没有记录那一时刻。

已经完整的发布不会被附加任何内容,无论推送重复多少次。在附加任何内容之前,推送会读取该版本携带哪些签名和日期,并生成它应提供的签名。对于它无法回答的问题(无法读取的列表或签名,或因无法获取信任根而无法判断的签名)以及它无法生成的签名,都会以非零状态退出且不附加任何内容,而不会被当作该版本不携带任何签名。

当注册表写入失败时

推送分步骤写入注册表:先写入内容(对于 Plugin,即实体及其 .wasm),然后写入引用该内容的 manifest,再写入版本标签,最后在旁边写入签名和发布日期。每个写入步骤在以后续尝试可能成功的方式失败时都会重试:注册表返回服务器错误(任何 5xx 状态,但带有 Retry-After 的 503 除外)或 408 Request Timeout,或者连接超时、被重置、或在响应中途中断。每个步骤最多尝试三次,第二次尝试前等待半秒,第三次尝试前等待一秒。

对于要求放慢速度的注册表,推送会等待,且不消耗上述任何一次尝试。收到 429 Too Many Requests,或带有 Retry-After 的 503 时,发往该注册表的每个请求(读取和写入都一样)都会按注册表要求的时间等待,然后再次发送;内容被拒绝的步骤会作为新的上传重新开始,没有固定的尝试次数,直到注册表连续五分钟只回答“放慢速度”为止。要求放慢速度的注册表介绍了这种等待以及结束等待的拒绝。

**每次尝试都是对相同字节的一次新上传,而不是重新发送失败的请求。**已经接收过某次上传请求体的注册表可能会拒绝第二次相同的请求,而它接受的是一次新上传。注册表已持有的内容视为已上传,重试的步骤写入的内容与第一次尝试本应写入的相同,因此一次已落地但响应丢失的尝试不会造成任何重复写入:manifest 保持其摘要,版本只带有一个签名和一个发布日期。

其他所有失败都会立即终止该步骤:凭据被拒绝(401、403,或没有为该注册表存储凭据)、注册表给出的任何其他响应、完全无法连接的注册表,或你中断的推送。某个步骤在最后一次尝试后仍然失败时,命令失败,错误会指明该步骤——内容、manifest、标签、签名或发布日期。之前步骤已发布的内容保持已发布状态;签名和发布日期说明了这对该版本意味着什么。

对于这些失败,只有写入会重试。在上传任何内容之前读取注册表在该版本上已持有的内容,不会重试,不过它会像每个请求一样,按要求放慢速度的注册表所要求的时间等待。

签名

aggrega push 可以在发布时为制品签名,并将签名作为 OCI referrer 附加——即基于制品不可变 manifest 摘要的 Sigstore(兼容 cosign)bundle。签名是一个同级 manifest,因此签名从不重新推送或修改已发布的字节。该 referrer 将其 bundle 命名为 signature.json,因此通用 OCI 客户端按摘要拉取该 referrer 时,会将 bundle 写入该文件。

签名采用先签名后推送:manifest 摘要在发布前即已确定,因此 aggrega push 会在任何字节到达注册表之前构造签名器并对摘要签名。如果无法构造签名器或签名失败,推送会在上传任何内容之前被拒绝——不会发布任何内容,因此签名失败绝不会在注册表上留下未签名的内容。在拒绝之前,暂时性失败的签名调用——即注册表写入会因之重试的任何失败,或无密钥证书颁发机构报告无法处理身份令牌——会再次尝试,最多三次,等待时间相同。在无密钥签名调用内部,证书颁发机构、透明日志或时间戳机构以 429 Too Many Requests 或服务器错误应答的请求,会先再次发送给该服务,如 aggrega sign 所述。

**签名在内容写入之后才附加,因此附加失败确实会让内容在没有签名的情况下处于已发布状态。**附加是一次写入,按当注册表写入失败时所述进行重试。如果仍然失败,命令以非零状态退出,并指出无法附加的签名;注册表要求签名的使用方在附加签名之前会拒绝该版本。再次运行相同的推送即可附加签名,如补全先前推送遗留的不完整发布所述;aggrega sign 可按引用为已发布版本附加签名。

当目标注册表自身的 signing 块设置了 required: true,或顶层 signing 块为所有注册表设置了它时,发布需要签名——若 kinds 列出了任何类型,则各自仅限于其列出的类型。这样的发布默认进行签名,--sign 则显式请求签名。没有任何标志可以在需要签名的情况下推送未签名内容——这样的推送总是会中止。

两种签名模式:

  • 无密钥(默认)——一个临时密钥,通过短期 Fulcio 证书绑定到 OIDC 身份,并记录在 Rekor 透明日志中。Fulcio 和 Rekor 默认使用公益 Sigstore 实例(https://fulcio.sigstore.dev、https://rekor.sigstore.dev)。无密钥模式的可信时间戳来自 Rekor 透明日志的收录;单独的 RFC3161 时间戳颁发机构是可选的——提供带完整端点的 --timestamp-url 即可启用。在交互式终端中,无密钥签名无需任何标志:CLI 会打开浏览器以获取短期 OIDC 身份令牌。在 GitHub Actions 上同样无需标志:CLI 会从 runner 的环境端点自动生成工作流 OIDC 令牌。对于其他非交互式 / CI 用途,请导出 AGGREGA_IDENTITY_TOKEN(或 SIGSTORE_ID_TOKEN),或传入 --identity-token;如果既未提供令牌,也没有环境端点和终端,推送会被拒绝。CI 令牌模型参见 environment-variables.md。
  • 有密钥(--key)——离线保存的 ECDSA P-256 密钥(兼容 cosign 的 PEM),是为没有 OIDC 身份提供方的环境准备的逃生舱口。不会连接任何身份提供方、证书颁发机构或透明日志。

无密钥服务 URL 和有密钥模式的密钥路径也可以在 .aggrega-config.yaml 的 signing: 块中设置(全局及按注册表);标志优先于配置,配置优先于公益默认值。OIDC 身份令牌绝不是配置字段(它是短期机密),私钥也绝不内联在配置中——只写入其路径。

发布日期

manifest 的创建时间是固定的,因此 manifest 摘要只取决于发布的内容,而与发布时间无关。版本的发布日期改为随版本另行记录,其来源取决于签名:

  • 无密钥签名本身已携带发布日期。 其透明日志条目记录了日志收录该签名的时间,日志的签名承诺证明了该时间。aggrega push 不再写入任何内容。
  • 密钥签名或无签名不携带时间。 因此,在实体及任何签名落地之后,aggrega push 会向 manifest 附加一个小型的 published-at 引用者(对通用 OCI 客户端命名为 published-at.json),其中包含一个精确到秒的 UTC RFC 3339 时间戳,读取自发布机器自身的时钟。它未经签名:它是发布者的声明,读取方也将其作为发布者的声明记录。Publication date attached: 这一行会报告它。

与签名一样,published-at 引用者是指回已发布 manifest 的同级 manifest,因此它不改变任何摘要和标签,对覆盖已有版本发布时的检查也没有影响。重复推送相同内容时,只会给尚无日期的版本附加日期,并注明自身时钟的时间,参见完成先前推送遗留的不完整发布。日期在首次尝试附加之前从时钟读取一次,因此重试的附加(参见当注册表写入失败时)注明的是同一日期。如果推送已发布内容,但经过这些尝试后仍无法附加日期,则以非零状态退出,并指出未附加的内容。aggrega registry update 会记录每个版本的日期,以及该日期来自两种来源中的哪一种。

离线

发布是一次网络往返,不存在无需网络的形式,因此在离线模式下——即配置文件中的顶层 offline 键、AGGREGA_OFFLINE 或 --offline——aggrega push 会在读取你的实体之前拒绝执行。拒绝信息会指明是这三者中的哪一个设置了该模式;当开启该模式的是项目中已提交的配置,而不是读者自己输入的任何内容时,读者需要的正是这一信息。

--dry-run 是例外,而它之所以是例外,是由它所做的事情决定的:它计算 bundle,打印它将要发布的引用以及该发布将落地的摘要,并且从不联系 registry。这使它成为发布的离线安全形式,而不是与离线模式相冲突,因此它在该模式下仍可正常工作——但有一点限定。对于完整写出远程 source: 的 Recipe 或 FeatureRecipe,会获取该源以比对其固定版本,而在离线模式下,这一获取会被拒绝并给出其自身的提示信息,因此针对此类实体的试运行会在此停止,而不会报告一个它无法担保的 bundle。

要在配置为离线的工作区中进行单次发布,请传入 --offline=false。

环境变量

签名输入和目标镜像仓库可以通过环境变量提供,环境变量会覆盖 .aggrega-config.yaml,但标志仍然优先:

  • AGGREGA_IDENTITY_TOKEN —— 无密钥 OIDC 身份令牌(--identity-token 对应的环境变量)。SIGSTORE_ID_TOKEN 作为 sigstore 生态互操作别名同样被接受,其优先级低于 AGGREGA_IDENTITY_TOKEN 和 GitHub Actions 环境提供的端点。该令牌永远不是配置字段。
  • AGGREGA_SIGNING_FULCIO_URL、AGGREGA_SIGNING_REKOR_URL、AGGREGA_SIGNING_TIMESTAMP_URL —— 无密钥服务的 URL。
  • AGGREGA_SIGNING_KEY_PATH —— 指向有密钥签名所用 PEM 文件的路径(绝不是密钥内容本身)。
  • AGGREGA_DEFAULT_REGISTRY —— 省略 --registry 时使用的目标镜像仓库。

优先级为:标志 > 环境变量 > 配置 > 默认值。完整列表和优先级模型参见 environment-variables.md。

身份验证

aggrega push 读取镜像仓库凭据的方式与 aggrega pull 相同——从 Docker 凭据配置及其指定的凭据助手读取。推送到私有镜像仓库之前,请运行 aggrega login <registry>(它不需要任何其他工具)或 docker login <registry>。该配置从何处读取,请参阅 aggrega-pull.md。

另请参阅

  • ./aggrega-sign.md — 在事后为已发布的制品签名(--sign 在发布后的对应操作)。
  • ./aggrega-lint.md — 应在推送之前执行的发布关卡(--pre-publish)。
  • ./aggrega-pull.md — 消费端,负责解析并固定 push 发布的内容。
  • ./aggrega-serve.md — 守护进程在 aggrega/publishEntity 上提供同样的发布功能,因此编辑器无需离开会话即可运行它;它仅在 请求指定它时运行,并返回引用、已发布的摘要(在试运行时为 --dry-run 打印的摘要)、调用进行到哪一步,以及本命令发出警告的条目,即 windowsUnusableEntries。
  • ./aggrega-mcp.md — 同样的功能以 publish-entity 工具的形式提供, 助手可以调用它,并以 windows_unusable_entries 返回这些条目。在允许它之前,请先阅读该页面 关于允许它的说明。
  • ../../architecture/13-catalog-and-registry.md — 目录、注册表和 OCI 媒体类型模型。

概要

aggrega push <entity-path> [flags]

说明

Publish a single catalog entity to an OCI registry, where other workspaces
resolve it with "aggrega pull".
The entity is read from the path given, bundled for transport, and pushed to
<registry>/<kind>/<metadata.name>:<metadata.version>, the repository path
lowercased; a Recipe or FeatureRecipe carries its spec.capability, and a Plugin
its metadata.pluginType, as a segment between <kind> and <metadata.name>. The
tag is the entity's own metadata.version. Run "aggrega push --list-kinds" for
the kinds this binary publishes, one per line and nothing else, so a script can
read it directly. Release and Manifest are deployment-side inputs rather than
catalog artifacts and are refused.
Every kind has a directory of its own except Aggregate, Release and Manifest: an
entity of any other kind is refused when another entity sits in its directory,
before anything is pinned or bundled, and the refusal names the entity in the way.
The directory's name is not judged.
A Component, Feature, Recipe or FeatureRecipe is read the way a build reads it
before it is bundled, and one that read refuses is refused here for the same
reason: a document that fails its kind's schema, a path naming content outside
the entity's own directory, which would not travel with the entity, or a schema
a Component or Feature imports that cannot be read or used.
A Plugin is read against its kind's schema too, before its .wasm is read, so a
metadata.version that is not a semantic version is refused. Its .wasm must then
agree with the entity on what the plugin offers and on its version, and a .wasm
whose version says it was built from a working tree with uncommitted changes —
the -dirty mark a build adds — is refused. A version disagreement and a build
from uncommitted changes are both cleared by building the plugin from a clean
checkout of the commit its release tag names, never by copying the version it
reports into the entity. A development version such as 1.0.0-3-g1a2b3c4, built
from a commit, and a prerelease such as 1.0.0-rc.1 publish.
What is published is the entity document and the files the entity itself names
beside it — a Recipe's or FeatureRecipe's local source, each file an $import:
names, the entity.lock beside it, and each schema file a Component or Feature
imports — and nothing else in its directory. An entity that names nothing
publishes as its document, unchanged; one that names a file publishes as a
gzipped archive of the document and those files. A directory it names travels
with every file under it that the ignore rules recorded in its entity.lock keep:
the rules the plugin serving its capability declared, and the author's own
.aggregaignore beside it, composed when the entity was pinned. A symbolic link
among those files is refused rather than followed. A local source written as a
template names no one directory until a Release fills it in, so an entity with
one carries every such file in its own directory, and push says so.
Push warns about each file an archive carries whose path holds a part Windows
cannot hold as written: a name Windows reserves for a device — CON, PRN, AUX,
NUL, COM1 or LPT1, say, in any letter case and whatever extension follows — or a
part ending in a full stop or a space. On Windows, aggrega refuses to unpack
such a file, so a Windows workspace cannot use the version. The warning is
written to standard error on every platform, one line per file, the entity
document's own file name judged with the rest, and it refuses nothing: the push,
or its dry run, goes ahead or stops exactly as it would without it. An entity
that names nothing publishes as its document alone and is never warned about.
Each file travels with mode 0644, whatever its permission bits — the execute
bit included — in the checkout it is published from. The OCI manifest names the
digest of the published bytes, so "aggrega pull" refuses a download that does
not match it. The lockfile a pull writes records the entity by the digest of its
content — each file's path and its bytes — which is the digest a pull in the
author's own workspace records for the same entity in its catalog directory, so
a build on either side refuses content that no longer matches.
Push signs before it publishes: where signing applies, the signature is made
over the manifest digest before any bytes reach the registry, so a failed
signing refuses the push rather than leaving unsigned content published.
The manifest's creation time is pinned, so the digest depends only on what is
published and never on when. Push states when it published beside the manifest
instead, as a small published-at attachment carrying this machine's clock, in
UTC to the second — unless the signature it attached already carries a time a
transparency log attests, as a keyless signature does. So a keyed or unsigned
publication writes one, and a keyless one does not. The attachment moves no
digest and changes no tag. "aggrega registry update" records the date, with
which of the two it came from.
Push refuses to replace content already published at the same version:
publish changed content under a new version instead.
A Recipe or FeatureRecipe carries the pins for its own inputs in the entity.lock
beside it, and pinning them is a step you run before publishing: aggrega pin.
A push that does not run that step refuses an entity whose entity.lock is
missing a pin, or holds one an input no longer matches, and names the step.
Pass --pin-sources, or set pin_sources_at_push in the workspace configuration, to
have push run that same step first, so the lock it writes is part of what is
published; --pin-sources=false skips it for one run.

标志

标志默认值描述
--dry-runfalse计算包并打印拟发布的 : 以及发布将产生的摘要,不联系注册表。发布时会因缺少固定而拒绝的实体,在此也会被拒绝
--entity—要发布的实体 YAML 的路径(也可以作为位置参数传入)
--fulcio-url—用于无密钥签名的 Fulcio 证书颁发机构 URL。省略时使用公共 Fulcio 实例。
--identity-token—用于无密钥签名的 OIDC 身份令牌。在交互式终端中(通过浏览器流程获取令牌)和在 GitHub Actions 上(自动签发工作流 OIDC 令牌)为可选;在其他非交互式/CI 场景中必须提供,也可以改为导出为 AGGREGA_IDENTITY_TOKEN 或 SIGSTORE_ID_TOKEN。
--key—用于离线密钥签名的已持有 ECDSA P-256 私钥 PEM 文件路径。省略时使用无密钥签名。
--list-kindsfalse列出所有可发布的实体种类,然后退出,不发布任何内容。输出是机器可读的,且格式稳定:每行一个种类,按排序顺序排列,不含其他内容。
--pin-sourcesfalse在打包实体之前对其运行实体作者的固定步骤,使该步骤在实体旁写入的 entity.lock 成为发布内容的一部分,而不是拒绝其锁文件未记录固定信息的实体。该步骤与 aggrega pin 相同,写入相同的字节。它写入实体旁边,因此仅在实体有可写位置时运行:即从某个目录读取的文档——推送总是满足这一点,因为它发布的是你指定的实体文档。在两个方向上覆盖工作区的 pin_sources_at_push:无论该设置如何,—pin-sources 会在本次运行中执行固定,—pin-sources=false 则不执行
--plugin—Plugin 实体的本地 .wasm 制品路径。发布 Plugin 时必需:publish 会推送 .wasm 制品、计算其内容摘要,然后推送实体。
--registry—目标注册表主机(覆盖工作区的 default_registry)
--rekor-url—用于无密钥签名的 Rekor 透明日志 URL。省略时使用公共 Rekor 实例。
--signfalse为已发布的制品签名,并将签名作为 OCI referrer 附加。省略时,签名遵循目标注册表的策略。
--timestamp-url—用于无密钥签名的可选 RFC3161 时间戳颁发机构 URL。