BuildKit 弃用功能演进与迁移指南从 Build information 到 SLSA Provenance Attestations【免费下载链接】buildkitconcurrent, cache-efficient, and Dockerfile-agnostic builder toolkit项目地址: https://gitcode.com/GitHub_Trending/bu/buildkitBuildKit 在持续演进中会淘汰旧功能弃用deprecated机制保证了移除过程的平滑与可预期。本文以 docs/deprecated.md 为核心系统梳理 BuildKit 的弃用策略与状态定义完整回顾已被弃用并移除的 Build information 功能v0.10 引入、v0.11 弃用、v0.12 移除并深入讲解其官方推荐替代方案——SLSA provenance attestations 的用法、参数与源码实现帮助读者理解该功能的迁移路径并掌握新方案的实战操作。BuildKit 的弃用机制与生命周期随着 BuildKit 持续演进既有功能不可避免地需要被移除或替换。为保证生态的平滑过渡BuildKit 建立了一套明确的弃用deprecated策略其核心规则如下弃用前置任何功能在被移除之前必须先在文档中标记为 deprecated弃用并且至少保留一个稳定版本除非文档中明确另行说明。也就是说一个功能在 vX 版本被标记弃用后最早也要到 vX1 版本才可能被移除给用户留出至少一个版本周期的迁移窗口。迁移责任用户需要跟踪每个版本发布中的弃用功能清单尽早规划从旧功能向替代功能的迁移。这是弃用机制能够真正发挥作用的前提——文档负责告知用户负责行动。从源码结构看BuildKit 主版本信息由 version/version.go 维护其中Version、Revision等变量在链接linking阶段注入未注入时使用默认值v0.0.0unknown。弃用与移除的节奏正是以这样的版本号为刻度来推进的。弃用状态的两级定义docs/deprecated.md对功能的生命周期状态给出了精确的两级定义状态含义用户应如何应对Deprecated已弃用功能已被标记为弃用不应再在新构建中使用可能在未来的某个版本中被移除、禁用或改变行为。文档中的 Deprecated 列标注该功能被标记弃用的版本 Remove 列标注计划移除的版本若 Remove 列为空则表示移除时间尚未确定立即停止使用规划迁移到替代方案Removed已移除功能已被移除、禁用或隐藏详见对应章节。部分功能属于 soft软弃用——出于向后兼容目的仍保持可用允许用户逐步迁移这种情况下 BuildKit 可能会打印警告但用户不应继续依赖该功能必须完成迁移依赖该功能的旧配置或调用可能失效当前弃用功能总览截至本文撰写时以当前仓库 docs/deprecated.md 为准BuildKit 的弃用功能清单如下状态功能弃用版本移除版本推荐替代方案DeprecatedBuild informationv0.11v0.12SLSA provenance attestations需要特别指出的是表格中该行目前仍标注为 Deprecated弃用版本 v0.11计划移除版本 v0.12但实际上 Build information 已在 v0.12.0 版本中被移除。这一细节提醒读者弃用表格反映的是功能状态的历史快照实际移除进度请以各版本发布说明为准。下面我们将完整回顾这一功能的来龙去脉。Build information 回顾从 v0.10 引入到 v0.12 移除它解决什么问题Build information构建信息数据结构在 BuildKit v0.10.0 中首次引入。它随构建过程生成一批构建元数据使使用者能够完整还原一次构建的输入全景所有构建源构建用到的镜像images、Git 仓库git repositories等精确到具体版本构建配置传递给构建的配置参数。更关键的是这些信息在生成镜像时会被嵌入到镜像配置image configuration中因此构建产物本身即携带了完整的来源追溯信息。从仓库现状看这一功能的官方说明页面 docs/buildinfo.md 如今已只剩一句话Build information has been removed since BuildKit v0.12.0.这从文档层面确认了该功能的最终归宿——被移除。为什么被弃用Build information 的使命在 BuildKit v0.11.0 引入provenance attestations来源证明后被彻底取代。provenance attestations 在记录构建如何产生这一信息上能力更为完整它至少包含构建参数与构建环境构建时间戳构建源的版本控制元数据带不可变校验和的构建依赖如基础镜像、构建使用的外部 URL所有构建步骤的描述及其 source 与 layer 的映射关系。从设计定位看provenance attestations 覆盖了 Build information 的全部能力并大幅扩展例如增加 SLSA 格式化的证据结构因此 BuildKit 官方在 v0.11 标记弃用 Build information并在 v0.12.0 中将其移除。这是旧功能被能力更完整的新功能取代这一弃用模式的典型案例。迁移指南使用 SLSA provenance attestations通过 buildctl 开启 provenance使用buildctl构建镜像时通过attest:provenance选项即可启用 provenance attestationsbuildctl build \ --frontenddockerfile.v0 \ --local context. \ --local dockerfile. \ --opt attest:provenance也可以使用参数定制 attestation 行为buildctl build \ --frontenddockerfile.v0 \ --local context. \ --local dockerfile. \ --opt attest:provenancemodemin,inline-onlytrue各 exporter 的行为差异BuildKit 的所有 exporter 都支持为构建结果附加 attestations当最终输出格式是容器镜像image或ociexporter时provenance 按照 attestation storage specification 描述的格式附加到镜像上构建多平台镜像时每个平台的镜像版本都会拥有各自独立的 provenance。使用local或tarexporter 时provenance 会以名为provenance.json的文件写入构建结果根目录并随结果一起导出。完整参数说明docs/attestations/slsa-provenance.md给出了 provenance 的完整参数表参数类型默认值说明modemin,maxmax配置生成的 provenance 信息量详见下文builder-idString空显式设置 SLSA Builder ID 字段filenameStringprovenance.json使用local或tarexporter 导出时 provenance 文件的文件名reproducibletrue,falsefalse显式标记构建为可复现inline-onlytrue,falsefalse仅将 provenance 嵌入支持内联内容的 exporterversionStringv1使用的 SLSA provenance 版本v0.2或v1modemin 与 max启用 provenance 时mode默认值为max。两种模式的信息粒度差异很大min模式只生成最精简的 provenance包含构建时间戳、所用 frontend、构建材料build materials。不包含构建参数值、secret 身份、丰富的 layer 元数据。官方明确说明modemin在所有构建上都是安全的因为它不会泄露构建环境中任何部分的信息。max模式在min基础上额外包含源 Dockerfile 与丰富的 layer 元数据含 sourcemap可关联源码与构建结果、传递的构建参数值、关于 secret 与 ssh mount 的元数据。官方建议只要条件允许就优先使用modemax因为它包含显著更详细的分析信息。但对于某些构建会泄露构建参数值和 secret 元数据的场景并不合适——这类构建应重构为尽可能通过 secret 传递隐藏值避免不必要的信息泄露。这也正是 Build information 时代无法做到的精细化控制是 provenance 的核心优势之一。builder-id与reproducible这两个参数写入的 SLSA 字段取决于所选versionSLSA 版本builder-id写入字段reproducible写入字段v1runDetails.builder.idrunDetails.metadata.buildkit_reproduciblev0.2builder.idmetadata.reproducibleinline-only默认情况下provenance 会包含在所有支持 attestations 的 exporter 结果中。inline-onlytrue可改变这一行为仅将 provenance 结果包含在支持内联内容的 exporter 中——具体来说只有产出容器镜像的 exporter。原因在于其他 exporter 将 attestations 作为独立文件写入其文件系统中如果这些场景不希望携带 provenance就可以用该参数排除。输出示例min 与 max 对比对于一个基于alpine:latest的简单镜像FROM alpine:latestmodemin构建的 provenance attestation 如下in-toto Statement v1 包裹的 SLSA provenance v1 格式{ _type: https://in-toto.io/Statement/v1, predicateType: https://slsa.dev/provenance/v1, subject: [ { name: pkg:docker/registry/imagetag/digest?platformplatform, digest: { sha256: e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862 } } ], predicate: { buildDefinition: { buildType: https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-definitions.md, externalParameters: { configSource: { path: Dockerfile }, request: { frontend: dockerfile.v0, args: {}, locals: [ { name: context }, { name: dockerfile } ] } }, internalParameters: { builderPlatform: linux/amd64 }, resolvedDependencies: [ { uri: pkg:docker/alpinelatest?platformlinux%2Famd64, digest: { sha256: 8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4 } } ] }, runDetails: { builder: { id: }, metadata: { invocationId: yirbp1aosi1vqjmi3z6bc75nb, startedOn: 2022-12-08T11:48:59.466513707Z, finishedOn: 2022-12-08T11:49:01.256820297Z, buildkit_reproducible: false, buildkit_completeness: { request: false, resolvedDependencies: false }, buildkit_metadata: {} } } } }同样的构建在modemax下provenance 会显著更丰富核心差异体现在internalParameters中新增buildConfig.llbDefinitionLLB 步骤的依赖图描述如step0、step1及其输入关系runDetails.metadata.buildkit_completeness.request变为truebuildkit_metadata中包含source.infos源文件信息与layers每个步骤产出的 layer 的 mediaType、digest、size 等元数据{ _type: https://in-toto.io/Statement/v1, predicateType: https://slsa.dev/provenance/v1, subject: [ { name: pkg:docker/registry/imagetag/digest?platformplatform, digest: { sha256: e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862 } } ], predicate: { buildDefinition: { buildType: https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-definitions.md, externalParameters: { configSource: { path: Dockerfile }, request: { frontend: dockerfile.v0, args: {}, locals: [ { name: context }, { name: dockerfile } ] } }, internalParameters: { builderPlatform: linux/amd64, buildConfig: { llbDefinition: [ { id: step0 }, { id: step1, inputs: [ step0:0 ] } ] } }, resolvedDependencies: [ { uri: pkg:docker/alpinelatest?platformlinux%2Famd64, digest: { sha256: 8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4 } } ] }, runDetails: { builder: { id: }, metadata: { invocationId: 46ue2x93k3xj5l463dektwldw, startedOn: 2022-12-08T11:50:54.953375437Z, finishedOn: 2022-12-08T11:50:55.447841328Z, buildkit_reproducible: false, buildkit_completeness: { request: true, resolvedDependencies: false }, buildkit_metadata: { source: { infos: [ { filename: Dockerfile } ] }, layers: { step0:0: [ [ { mediaType: application/vnd.oci.image.layer.v1.targzip, digest: sha256:c158987b05517b6f2c5913f3acef1f2182a32345a304fe357e3ace5fadcad715, size: 3370706 } ] ] } } } } } }需要说明示例中buildType字段引用的 SLSA 字段生成定义详见仓库内的 slsa-definitions.md它详细描述了每个 attestation 字段是如何由构建过程生成的是理解 provenance 语义的权威参考。检查已生成的 provenance构建完成并推送镜像后可以通过docker buildx imagetools命令在 registry 中检查附加到镜像上的 provenance其展示格式与 attestation-storage.md 描述的一致。源码视角provenance 的生成与导出链路从文档到代码Build information 的残留痕迹Build information 移除后代码库中仍保留了少量命名痕迹可供追溯在 LLB 嵌套构建客户端 client/llb/llbbuild/llbbuild.go 中仍存在BuildInfo类型其字段为llb.Constraints与DefinitionFilename以及WithFilename、WithConstraints等BuildOption。这是嵌套 LLB 构建--frontendgateway.v0场景用来传递定义文件信息的内部结构与已被移除的镜像级 Build information 是不同层级的机制属于同名概念的延续而非旧功能残留。导出器接口 exporter/exporter.go 中定义了ExportBuildInfo结构含Ref、InlineCache、SessionID、CompatibilityVersion字段这是每次Export调用时随附的构建上下文信息用于传递缓存与兼容性版本等内部数据同样与旧的镜像内嵌 Build information 无直接关系。上述两个命名相似的内部结构提示我们Build information 作为嵌入镜像配置的元数据这一对外特性已被整体移除而构建内部传递信息的通用结构依然存在二者不应混淆。SLSA provenance 的实现predicate 生成当前仓库中provenance 的核心实现位于 solver/llbsolver/provenance 包其中predicate.go 负责构造 SLSA provenance 的 predicate谓词主体。例如slsaMaterials函数会遍历构建的SourcesImages、ImageBlobs、Git、HTTP 四类来源为每个来源生成ProvenanceMaterialURI Digest 集合。镜像来源的 URI 通过purl.RefToPURL生成 package-urlOCI 本地引用使用pkg:oci类型registry 引用使用pkg:docker类型Git 来源的 URI 为原始仓库 URL 并以 commit 摘要作为 Digest——这正是前面 JSON 示例中resolvedDependencies数组的生成来源。capture.go 负责在构建过程中捕获 provenance 所需的各类元数据来源、参数、layer 信息等。provenance/types子目录定义 predicate 等结构化类型。导出链路上的承接在导出阶段solver/llbsolver/export.go 会为每个待导出结果调用exp.Export并传入携带Ref、SessionID、InlineCache、CompatibilityVersion的exporter.ExportBuildInfo。镜像导出器随后按 attestation-storage.md 的规范将 provenance 写入镜像 manifest 的 attestation manifest 中。整个链路从构建时捕获capture→ 谓词构造predicate→ 导出附着export闭环完成。总结与迁移建议Build information 的弃用与移除是 BuildKit 功能演进的典型样本v0.10 引入、v0.11 被能力更完整的 SLSA provenance attestations 取代并标记弃用、v0.12 正式移除。对使用者而言迁移路径清晰明确确认依赖检查自己是否依赖嵌入在镜像配置中的 Build information 字段启用替代通过--opt attest:provenancemodemax等方式开启 provenance attestations获得更丰富、格式标准in-toto SLSA的构建追溯信息关注版本节奏每次发布时留意 docs/deprecated.md 的状态表遵循弃用后至少保留一个稳定版本的窗口期及时完成迁移善用安全选项对敏感构建使用modemin或重构为 secret 传递隐藏值避免modemax泄露构建参数与 secret 元数据。这套标记弃用 → 提供替代 → 到期移除的机制保证了 BuildKit 生态在持续创新的同时用户始终拥有明确、可预期的升级路径。【免费下载链接】buildkitconcurrent, cache-efficient, and Dockerfile-agnostic builder toolkit项目地址: https://gitcode.com/GitHub_Trending/bu/buildkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考