buildah source 子命令完全指南：创建、管理并分发 OCI Source Image

云原生【免费下载链接】buildahA tool that facilitates building OCI images.项目地址https://gitcode.com/gh_mirrors/bu/buildah点击查看免费下载buildah source是 Buildah 提供的实验性子命令组用于创建、推送、拉取和管理**源镜像source image**及其关联的源构件source artifact。本文以 docs/buildah-source.1.md 为主线结合 internal/source 下的源码实现完整讲解 source 镜像的概念、四个子命令create、add、pull、push的用法、全部命令行选项与底层工作原理帮助读者理解如何把构建普通 OCI 镜像所用的全部源代码SRPM、源码树、文本文件等打包成可分发、可追溯的源镜像。什么是 source image源镜像根据 docs/buildah-source.1.md 的定义source image 是一种包含构建普通 OCI 镜像所用到的全部源构件的镜像。这些构件可以是任何类型的源代码产物例如源码 RPMsource RPM完整的源码树entire source tree文本文件换句话说普通 OCI 镜像交付的是构建结果二进制、库、运行时而 source image 交付的是构建依据源码与原材料两者一一对应为合规审计、可复现构建reproducible build与供应链溯源提供基础。从 internal/source/source.go 的实现看source image 在 OCI 规范层面是一个OCI artifact// MediaTypeSourceImageConfig specifies the media type of a source-image config. const MediaTypeSourceImageConfig application/vnd.oci.source.image.config.v1json它本质上仍是 OCI v1 manifest 镜像但 config 部分使用自定义媒体类型application/vnd.oci.source.image.config.v1json这是区分普通镜像与源镜像的关键标记。对应的 config 结构source.go只包含两个字段type ImageConfig struct { // Created 是层创建的日期与时间按 RFC 3339 第 5.6 节格式定义。 Created *time.Time json:created,omitempty // Author 是源镜像的作者。 Author string json:author,omitempty }实验性声明buildah source及其所有子命令目前都是实验性功能未来可能发生变化该声明同时出现在主手册页和每个子命令手册页中。生产环境集成前请评估版本兼容性本文描述的行为以当前仓库代码为准。命令总览buildah source主命令本身不接受具体操作RunE直接返回 nil见 cmd/buildah/source.go其功能由四个子命令承担子命令手册页功能addbuildah-source-add(1)向源镜像添加一个源构件createbuildah-source-create(1)创建并初始化一个源镜像pullbuildah-source-pull(1)从 registry 拉取源镜像到指定路径pushbuildah-source-push(1)从指定路径推送源镜像到 registry四个子命令的参数个数与典型用法示例如下来自 source.go 中的 cobra 定义与 Example 字段# create路径参数必须不存在cobra.ExactArgs(1) buildah source create /tmp/fedora:latest-source # add两个参数——源镜像路径 源构件cobra.ExactArgs(2) buildah source add /tmp/fedora sources.tar.gz # pull两个参数——registry 上的镜像名 本地目标路径cobra.ExactArgs(2) buildah source pull quay.io/sourceimage/example:latest /tmp/sourceimage:latest # push两个参数——本地源镜像路径 registry 上的目标镜像名cobra.ExactArgs(2) buildah source push /tmp/sourceimage:latest quay.io/sourceimage/example:latest子命令 1buildah source create用途创建并初始化一个 source image也就是生成一个采用自定义 config 媒体类型的 OCI artifact。语法docs/buildah-source-create.1.mdbuildah source create [options] path选项选项默认值说明--authorauthor空不设置在 config 中设置源镜像作者--time-stampbool-valuetrue是否在镜像 config 中写入 created 时间戳底层实现create对应 internal/source/create.go 中的Create函数流程如下前置校验fileutils.Exists(sourcePath)检查目标路径是否已存在——已存在则直接报错creating source image: %q already existscreate.go。这与pull的约束一致源镜像目录必须从零创建。打开/创建 OCI 布局openOrCreateSourceImage内部通过layout.ParseReference(sourcePath)NewImageDestination在目标路径隐式创建完整的 OCI 目录布局oci-layout、index.json、blobs/见 source.go。写入 config blobaddConfig将ImageConfig{Author, Created}序列化为 JSON 后通过PutBlob写入blobs/sha256/source.go。写入 manifest构造 schemaVersion2 的 OCI manifest其Config.MediaType固定为MediaTypeSourceImageConfigConfig.Digest/Size指向刚写入的 config blobcreate.go。提交ociDest.Commit(ctx, nil)完成布局提交。关于--time-stamp对应CreateOptions.TimeStamp字段。为false时createdTime()返回nilconfig JSON 中created字段因omitempty被省略create.go。--author则直接写入 config 的author字段。两个选项在 CLI 层的绑定见 cmd/buildah/source.go。子命令 2buildah source add用途向已存在的源镜像添加一个源构件。构件会以gzip 压缩的 tar 包形式加入且只有必要时才做自动 tar / 自动压缩即 tar 包直接使用普通文件自动打包。语法docs/buildah-source-add.1.mdbuildah source add [options] path artifact选项选项默认值说明--annotationkeyvalue无为源镜像 manifest 中的该层 descriptor 添加注解输入格式为keyvalue--annotation可重复使用CLI 层用StringArrayVar绑定见 source.go每次给层添加一条注解。解析逻辑在 internal/source/add.go每个注解必须包含否则报错invalid annotation ... (expected format is keyvalue)同一个 key 只能指定一次重复会报错annotation ... specified more than once解析结果以map[string]string形式写入该层 descriptor 的Annotations字段。底层实现Add函数add.go的执行流程校验sourcePath必须已存在区别于create。解析--annotation为 map。使用archive.TarWithOptions(artifactPath, archive.TarOptions{Compression: archive.Gzip})生成 gzip 压缩的 tar 流add.go对应手册中gzip-compressed tar ball的表述。通过PutBlob将压缩流写入源镜像得到 blob 的 digest/size。读取现有 manifest把新构件作为一层追加MediaType为application/vnd.oci.image.layer.v1.targzip并携带注解add.go。写回新 manifest 后删除旧 manifest blobremoveBlob按blobs/sha256/digest的固定路径删除见 source.go。最后用updateIndexWithNewManifestDescriptor重写index.json使index.Manifests指向最新 manifest descriptoradd.go。这一新 manifest 生效、旧 manifest 删除的设计保证源镜像目录始终只保留一份当前有效的 manifest。子命令 3buildah source pull用途从 registry 将源镜像拉取到指定本地路径。若镜像不符合 source-image OCI artifact 规范拉取将直接失败。语法docs/buildah-source-pull.1.mdbuildah source pull [options] registry path选项选项默认值说明--credscreds无访问 registry 的认证信息[username[:password]]若用户名或密码缺失会弹出命令行提示输入密码不回显--quiet,-qfalse抑制拉取源镜像时的进度输出--tls-verifybool-valuetrue与容器 registry 通信时要求 HTTPS 并验证证书不可用于不安全的 registry底层实现Pull函数internal/source/pull.go目标路径sourcePath必须不存在否则报错pull.go。镜像引用解析stringToImageReference使用docker://transport不支持短名short name拉取必须使用完全限定名fully-qualified name见 pull.go。构建types.SystemContextTLSVerifyfalse时设置DockerInsecureSkipTLSVerify--creds非空时调用parse.AuthConfig填充DockerAuthConfigpull.go。合规校验validateSourceImageReference读取远端 manifest检查ociManifest.Config.MediaType必须等于MediaTypeSourceImageConfig否则报错invalid media type of image config ... (expected: ...)pull.go。这就是手册所述不符合 source-image artifact 则拉取失败的机制。获取默认签名策略signature.DefaultPolicy后通过copy.Image将镜像复制到layout.ParseReference(sourcePath)解析出的 OCI 布局目标非--quiet模式下进度输出到 stderrpull.go。子命令 4buildah source push用途将指定本地路径的源镜像推送到 registry。语法docs/buildah-source-push.1.mdbuildah source push [options] path registry选项选项默认值说明--credscreds无访问 registry 的认证信息[username[:password]]缺省部分会交互式提示密码不回显--digestfiledigestfile无镜像复制完成后将结果镜像的 digest 写入指定文件--quiet,-qfalse抑制推送源镜像时的进度输出--tls-verifybool-valuetrue与容器 registry 通信时要求 HTTPS 并验证证书不可用于不安全的 registry底层实现Push函数internal/source/push.go源引用通过layout.ParseReference(sourcePath)从本地 OCI 布局解析目标引用经stringToImageReference转为docker://引用。SystemContext的构建与pull一致DockerInsecureSkipTLSVerify对应--tls-verifyDockerAuthConfig对应--credspush.go。在签名策略上下文中执行copy.Image进度输出到 stderr非--quiet。若指定--digestfile则用manifest.Digest(manifestBytes)计算推送后镜像 manifest 的 digest并以 0644 权限写入文件push.go。该 digest 可用于后续的拉取验证或签名引用。典型工作流从源码到可追溯分发结合上述四个子命令与 internal/source 的实现一条完整的源镜像生命周期如下# 1. 初始化源镜像本地将生成标准 OCI 目录布局 buildah source create --author CI Bot ciexample.com ./src-image # 2. 逐个添加源构件自动 targzip可用 --annotation 标注元信息 buildah source add --annotation typesource-rpm ./src-image ./fedora-source.rpm buildah source add --annotation path/ ./src-image ./source-tree/ # 3. 推送到 registry并保存 digest 供后续验证 buildah source push --digestfile ./src-image.digest ./src-image quay.io/example/app:source # 4. 在另一环境拉取必须是完全限定名非源镜像会失败 buildah source pull --quiet quay.io/example/app:source ./recovered-src需要留意两个易错点create与pull的目标路径都必须尚不存在源码中均有显式检查pull不支持短名必须提供完整的 registry 镜像名。扩展阅读子命令手册 buildah-source-add(1) 、 buildah-source-create(1) 、 buildah-source-pull(1) 、 buildah-source-push(1)CLI 层实现与全部 flag 绑定cmd/buildah/source.go核心库实现internal/source/source.go媒体类型、manifest/config 读写、blob 管理、 internal/source/create.go 、 internal/source/add.go 、 internal/source/pull.go 、 internal/source/push.go父命令手册docs/buildah.1.md赞分享云原生【免费下载链接】buildahA tool that facilitates building OCI images.项目地址https://gitcode.com/gh_mirrors/bu/buildah点击查看免费下载相关推荐OpenShift Source-to-Image (S2I) 命令行工具完全指南OpenShift Source to Image S2I 命令行工具完全指南 什么是Source to Image S2I Source to Image S开发工具云原生WeChatTweak底层架构macOS微信客户端的二进制补丁机制实现WeChatTweak底层架构macOS微信客户端的二进制补丁机制实现 WeChatTweak是一个针对macOS微信客户端的命令行工具通过Mach O二进逆向工程CLI即时通讯Argo CD 源码完整性管理argocd proj source-integrity git policies update 命令完全指南Argo CD 源码完整性管理argocd proj source integrity git policies update 命令完全指南 本指南围绕 Ar云原生CI/CD容器编排DevOps后端上一篇mambaout_femto.in1k迁移学习教程自定义数据集训练完整流程下一篇Android-ObservableScrollView与Jetpack组件协同开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考