Buildah pull 命令完全指南：镜像拉取的传输协议、认证配置与拉取策略详解

云原生【免费下载链接】buildahA tool that facilitates building OCI images.项目地址https://gitcode.com/gh_mirrors/bu/buildah点击查看免费下载Buildah 是构建 OCI 镜像的实用工具buildah pull是其核心命令之一负责按照指定输入从各类镜像源registry、本地目录、tar 归档、docker daemon 等拉取镜像并存入本地容器存储。本文以仓库中的 docs/buildah-pull.1.md 手册为主干结合 cmd/buildah/pull.go 命令行实现、根目录 pull.go 的底层拉取函数、define/pull.go 的拉取策略定义以及 tests/pull.bats 的端到端测试系统讲解buildah pull的全部选项、传输机制、认证方式、环境变量与配置文件帮助你在实际构建流程中正确、高效地拉取镜像。命令概述与工作方式buildah pull的完整语法为buildah pull [options] image拉取动作基于指定的输入image完成。与docker pull不同Buildah 支持containers-transports(5)定义的全部传输协议transports例如docker://、docker-daemon:、docker-archive:、oci-archive:、dir:、oci:等。如果未显式指定传输协议输入将先经过短名称解析short-name resolution见containers-registries.conf(5)随后默认使用docker即容器镜像仓库 registry传输协议。在 cmd/buildah/pull.go 中命令的长描述明确说明Pulls an image from a registry and stores it locally. An image can be pulled using its tag or digest. If a tag is not specified, the image with the latest tag (if it exists) is pulled.也就是说可以用 tag 或 digest摘要拉取镜像未指定 tag 时默认拉取latest如果存在。依赖条件Buildah 解析要拉取的 registry 路径时依赖/etc/containers/registries.conf配置文件对应containers-registries.conf(5)。如果buildah pull命令失败并报出 image not known 错误应首先检查registries.conf文件是否已正确安装并配置了相应的 registry。这一点在 tests/pull.bats 中也有验证本地没有镜像时执行--policy never会以 image not known 失败。返回值命令成功时标准输出返回所拉取镜像的 image ID镜像 ID失败时返回退出码 1。底层实现中CLI 在调用buildah.Pull()成功后通过fmt.Printf(%s\n, id)输出该 ID见 cmd/buildah/pull.go。支持的镜像源传输方式buildah pull支持containers-transports(5)中定义的所有传输方式。手册中的示例覆盖了最常见场景buildah pull imagename # 默认 docker 传输 短名称解析 buildah pull docker://myregistry.example.com/imagename buildah pull docker-daemon:imagename:imagetag # 从 Docker daemon 拉取 buildah pull docker-archive:filename # 从 Docker 归档 tar 文件拉取 buildah pull oci-archive:filename # 从 OCI 归档 tar 文件拉取 buildah pull dir:directoryname # 从本地目录拉取在 tests/pull.bats 中各类传输方式均有端到端测试覆盖docker-daemonpull docker-daemon:docker.io/library/alpine:latesttests/pull.batsdocker-archive先 push 生成alp.tar再pull docker-archive:${TEST_SCRATCH_DIR}/alp.tartests/pull.batsoci-archivepull oci-archive:${TEST_SCRATCH_DIR}/alp.tartests/pull.batsdirpull dir:${TEST_SCRATCH_DIR}/buildahtest且通过 dir 传输拉取的镜像不带 tagnone:nonetests/pull.batsocioci:${TEST_SCRATCH_DIR}/withref:$name:$tag可携带可选引用未携带引用时镜像无名称tests/pull.bats。测试还验证了重要限制docker-archive、oci-archive、oci、dir传输不支持--all-tags报错信息为 pulling all tags is not supported for ... transport见 tests/pull.bats。选项详解--all-tags, -a拉取仓库repository中的所有带 tag 镜像。对应 CLI 中的flags.BoolVarP(opts.allTags, all-tags, a, false, ...)cmd/buildah/pull.go。tests/pull.bats 的 pull-all-tags 测试验证将 alpine 以 0.9、0.9.1、1.1、alpha、beta、gamma2.0、latest 共 7 个 tag 推送到本地 registry 后buildah pull --all-tags会逐一尝试拉取每个 tag且buildah images -a能列出全部 tag底层所有 tag 共享同一个镜像 ID。--archARCH指定要拉取镜像的架构architecture覆盖宿主机的默认架构。示例值arm、arm64、386、amd64、ppc64le、s390x。该选项在 cmd/buildah/pull.go 中注册时默认值为runtime.GOARCH即当前机器架构。实际行为在 pkg/parse/parse.go 的PlatformsFromOptions()中体现只有当--arch标志被显式修改c.Flag(arch).Changed时才生效。tests/pull.bats 验证pull --arch arm64 alpine后buildah inspect --format {{ .Docker.Architecture }}和{{ .OCIv1.Architecture }}均输出arm64而传入不存在的架构--arch bogus会报 no image found in manifest list。--authfile path指定认证文件authentication file路径默认值为${XDG_RUNTIME_DIR}/containers/auth.json详见containers-auth.json(5)。该文件由buildah login创建。认证状态查找顺序指定的 authfile 或默认的${XDG_RUNTIME_DIR}/containers/auth.json如果其中没有授权状态则回退检查$HOME/.docker/config.json该文件由docker login设置。此外可以通过设置REGISTRY_AUTH_FILE环境变量覆盖默认认证文件路径export REGISTRY_AUTH_FILEpath在 cmd/buildah/pull.go 中--authfile的默认值正是auth.GetDefaultAuthFile()在命令执行入口还会调用auth.CheckAuthFile(iopts.authfile)校验认证文件存在性cmd/buildah/pull.go对应测试 pull should fail with nonexistent authfiletests/pull.bats。tests/pull.bats 演示了完整流程先buildah login --authfile /tmp/test.auth --username testuser --password testpassword生成认证文件再buildah pull --authfile /tmp/test.auth拉取私有镜像。--cert-dir path使用指定路径path包含*.crt、*.cert、*.key证书文件连接 registry。默认证书目录为/etc/containers/certs.d。--creds creds以[username[:password]]形式提供连接 registry 所需的认证凭据。如果用户名或密码有一项未提供命令行会提示输入密码输入时不回显。底层解析逻辑在 pkg/parse/parse.goparseCreds()用SplitN(creds, :, 2)切分用户名和密码AuthConfig()在缺少用户名时提示Username:fmt.Scanln读取缺少密码时提示Password:term.ReadPassword(0)无回显读取。--decryption-key key[:passphrase]指定用于解密镜像的密钥key[:passphrase]。key可以指向密钥key和/或证书certificate。解密时会尝试使用所有提供的密钥。如果密钥受口令passphrase保护则必须在参数中传入该口令否则省略。CLI 通过cli.DecryptConfig(iopts.decryptionKeys)构造解密配置cmd/buildah/pull.go最终传入PullOptions.OciDecryptConfig根目录 pull.go 注释若为 nil 则不尝试解密镜像。tests/pull.bats 中 pull encrypted local image 和 pull encrypted registry image 完整验证了三种情形不带密钥拉取加密镜像 → 失败报 does not match configs DiffID带错误密钥拉取 → 失败报 decrypting layer ... no suitable key unwrapper found or none of the private keys could be used for decryption带正确密钥openssl genrsa生成的mykey.pem拉取 → 成功。--osOS指定要拉取镜像的操作系统OS覆盖当前宿主机操作系统。默认值为runtime.GOOScmd/buildah/pull.go。--platformOS/ARCH[/VARIANT]指定要拉取镜像的 OS/ARCH例如linux/arm覆盖当前宿主机操作系统与架构。OS/ARCH 取值遵循 Go 编程语言的定义即$GOOS/$GOARCH部分 ARCH 值与arch命令输出的名称不同。有效组合可参考go tool dist list输出。注意--platform不能与--arch、--os或--variant组合使用。该限制在 pkg/parse/parse.go 中强制实现当--platform被修改且--os/--arch/--variant也已被修改时返回错误invalid --platform may not be used with --os, --arch, or --variant。--platform支持传递多个值StringSlice多平台场景下 cmd/buildah/pull.go 会发出警告 ignoring platforms other than ...仅使用第一个平台。tests/pull.bats 验证pull --platform linux/arm64 alpine后镜像的 Docker/OCIv1 架构均为arm64--platform linux/bogus报 no image found in manifest list。--policyalways|missing|never|ifnewer拉取镜像策略默认值为missing。四种策略的含义always始终拉取镜像若拉取失败则抛出错误missing仅当本地容器存储中找不到该镜像时才拉取若本地无镜像且拉取失败则抛出错误默认策略never从不拉取直接使用本地容器存储中的镜像若本地找不到镜像则抛出错误ifnewer仅当 registry 上的镜像比本地存储中的更新时才拉取。判定更新的依据是digest 是否不同比较时间戳容易出错若本地已有镜像则拉取错误被抑制。在 cmd/buildah/pull.go 中--policy默认值为字符串missing随后在 cmd/buildah/pull.go 通过define.PolicyMap[iopts.pullPolicy]映射为内部枚举未知策略报unsupported pull policy ...。define/pull.go 的PolicyMap定义了完整的策略别名表规范值内部策略别名missingPullIfMissingifmissing、notpresentalwaysPullAlwaystrueneverPullNeverfalseifnewerPullIfNewernewertests/pull.bats 的 pull-policy 测试验证了关键行为--policy bogus报错 unsupported pull policy本地无镜像时--policy never报 image not known本地已有镜像时--policy never返回原 IID--policy always拉取后 IID 必然改变新镜像--policy missing在本地已有镜像时返回原 IID。测试 tests/pull.bats 则遍历全部 10 个策略取值missing/ifmissing/notpresent/always/true/never/false/ifnewer/newer逐一验证可用性。--quiet, -q当需要从 registry 拉取镜像时抑制进度输出。实现上CLI 在iopts.quiet为真时将options.ReportWriter置为nil关闭日志输出见 cmd/buildah/pull.go。默认情况下ReportWriter为os.Stderr即进度信息输出到标准错误。--remove-signatures拉取镜像时不复制签名signatures。该选项直接透传给PullOptions.RemoveSignatures根目录 pull.go丢弃镜像上已有的任何签名。--retry attempts拉取 registry 镜像失败时的重试次数。默认值为3。值得注意的是CLI 中该选项的默认值并非硬编码而是取自defaultContainerConfig.Engine.Retry容器配置的引擎段见 cmd/buildah/pull.go。--retry与--retry-delay的 flag 顺序校验也有专门测试tests/pull.bats。--retry-delay duration重试之间的延迟时长。默认值为2s。同样取自defaultContainerConfig.Engine.RetryDelaycmd/buildah/pull.go并经由time.ParseDuration解析cmd/buildah/pull.go解析失败时报unable to parse value provided ... as --retry-delay。--tls-verify bool-value连接容器 registry 时要求 HTTPS 并校验证书默认值为true。注意与不安全的 registryinsecure registry通信时不能使用 TLS 校验此时需显式设置--tls-verifyfalse。该默认值在 cmd/buildah/pull.go 中注册flags.BoolVar(opts.tlsVerify, tls-verify, true, ...)。--variant指定要拉取镜像的架构变体architecture variant例如--archarm --variantv7拉取 ARMv7 变体。完整示例以下示例覆盖手册中的全部典型用法可直接用于实战# 基础拉取短名称解析 docker 传输 buildah pull imagename # 显式指定 registry 与传输协议 buildah pull docker://myregistry.example.com/imagename buildah pull docker-daemon:imagename:imagetag buildah pull docker-archive:filename buildah pull oci-archive:filename buildah pull dir:directoryname # 对不安全的 registry 关闭 TLS 校验 buildah pull --tls-verifyfalse myregistry/myrepository/imagename:imagetag # 使用用户名/密码凭据 自定义证书目录 buildah pull --credsmyusername:mypassword --cert-dir ~/auth myregistry/myrepository/imagename:imagetag # 指定认证文件 buildah pull --authfile/tmp/auths/myauths.json myregistry/myrepository/imagename:imagetag # 指定架构 buildah pull --archaarch64 myregistry/myrepository/imagename:imagetag # 指定架构 变体 buildah pull --archarm --variantv7 myregistry/myrepository/imagename:imagetag此外cmd/buildah/pull.go 内嵌的帮助示例还展示了按 tag/digest 拉取的能力buildah pull myregistry/myrepository/imagename:imagetag。环境变量BUILD_REGISTRY_SOURCES如果设置了BUILD_REGISTRY_SOURCES它会被解析为一个 JSON 对象其中包含以下三个键对应的 registry 名称列表insecureRegistries不安全的 registry 列表blockedRegistries被阻止的 registry 列表allowedRegistries被允许的 registry 列表。拉取行为规则如果要拉取的 registry 名称命中blockedRegistries中的任一条目则拒绝拉取如果allowedRegistries非空而目标 registry 名称不在列表中则拒绝拉取。示例来自 tests/pull.batsexport BUILD_REGISTRY_SOURCES{blockedRegistries: [docker.io]} # 拉取报错registry docker.io denied by policy: it is in the blocked registries list export BUILD_REGISTRY_SOURCES{allowedRegistries: [some-other-registry.example.com]} # 拉取报错registry docker.io denied by policy: not in allowed registries listTMPDIRTMPDIR环境变量允许用户指定拉取pulling和推送pushing镜像时临时文件的存放位置默认值为/var/tmp。tests/pull.bats 验证了其作用将TMPDIR指向一个仅 1M 的 tmpfs 挂载点后pull --policy always会因 no space left on device 失败不设置TMPDIR时拉取成功。相关配置文件registries.conf/etc/containers/registries.confregistries.conf指定了在镜像名称中不含 registry 或域名部分时应查询哪些容器 registry即短名称解析。若拉取出现 image not known 错误请先检查此文件。policy.json/etc/containers/policy.json签名策略文件定义了容器镜像的信任策略trust policy控制哪些容器 registry 可用于拉取镜像以及工具是否应信任这些镜像。注意该文件对拉取行为的影响体现在镜像校验环节。源码级实现原理buildah pull的完整调用链为CLIcmd/buildah/pull.go→ 顶层 Pull() 函数pull.go→ containers/common 的 libimage runtime.Pull()。PullOptions 结构根目录 pull.go 定义了PullOptions它是 CLI 与底层库之间的数据契约核心字段包括SignaturePolicyPath签名策略文件路径覆盖通常留空以使用系统默认策略ReportWriter进度日志输出目标CLI 中为os.Stderr--quiet时置 nilStore本地容器存储SystemContext保存凭据等认证/授权信息的系统上下文BlobDirectory拉取层 blob 的缓存目录CLI 的隐藏选项--blob-cacheAllTags是否拉取全部 tagRemoveSignatures是否丢弃已有签名MaxRetries/RetryDelay重试次数与重试间隔OciDecryptConfig镜像解密配置PullPolicy拉取策略define.PullPolicy。Pull() 函数根目录 pull.go 的Pull()函数将PullOptions转换为libimage.PullOptions并注意以下细节若指定了BlobDirectory则通过cacheLookupReferenceFunc生成目标引用查找函数DestinationLookupReferenceFunc实现 blob 缓存MaxRetries 0时才会透传重试次数通过config.ParsePullPolicy(options.PullPolicy.String())将 buildah 的拉取策略转换为 common 库的对应策略调用runtime.Pull(ctx, imageName, pullPolicy, libimageOptions)成功后将pulledImages[0].ID()作为 image ID 返回若未拉取到任何镜像且无错误则返回内部错误 no image pulled and no error。拉取策略枚举define/pull.go 定义了四种PullPolicy枚举值PullIfMissing、PullAlways、PullIfNewer、PullNever并通过PolicyMap支持多组别名见上文策略表。注释特别提醒该枚举的数值与containers/common/pkg/config.PullPolicy不同零值含义不同因此不能互换这也是 pull.go 中需要显式调用String()再解析的原因。结合测试验证核心行为tests/pull.bats 是buildah pull的端到端测试套件覆盖了本文讨论的几乎所有要点可作为排查问题的参考清单测试主题位置关键断言本地镜像解析tests/pull.bats强制失败拉取时错误信息包含解析后的docker://localhost/image:latest拉取被阻止的 registrytests/pull.batsregistry docker.io is blocked各传输方式拉取tests/pull.bats支持 digest、tag、--all-tags限制全部 tag 拉取tests/pull.bats多个 tag 共享同一镜像 ID加密镜像解密tests/pull.bats无 key/错误 key/正确 key 三种结果拉取策略tests/pull.batsnever/missing/always 的行为差异架构与平台tests/pull.bats--arch/--platform影响最终镜像架构TMPDIR 与磁盘满tests/pull.bats临时目录空间不足导致拉取失败与其他命令的协作buildah pull通常与以下命令配合使用buildah-from(1)buildah from同样支持拉取策略--pull构建工作流中常用它来准备基础镜像buildah-login(1)buildah login用于生成--authfile所需的认证文件buildah push / commit / rmi拉取后的镜像可进一步推送、提交或删除。可参考 docs/buildah-from.1.md、docs/buildah-login.1.md 及仓库根目录 pull.go 了解完整上下文。若需要深入底层传输机制可进一步阅读containers-transports(5)、containers-registries.conf(5)、containers-policy.json(5)与containers-auth.json(5)的相关说明。赞分享云原生【免费下载链接】buildahA tool that facilitates building OCI images.项目地址https://gitcode.com/gh_mirrors/bu/buildah点击查看免费下载相关推荐Podman --pull 镜像拉取策略详解always / missing / never / newer 的语义与实战Podman pull 镜像拉取策略详解always / missing / never / newer 的语义与实战 本文围绕 Podman 中 pull容器运行时云原生CLITrivy 拉取 AWS ECR 私有镜像权限配置与认证原理详解Trivy 拉取 AWS ECR 私有镜像权限配置与认证原理详解 导读 本文围绕 Trivy 扫描 AWS ECRElastic Container Reg应用安全漏洞扫描SBOM供应链安全云原生Kubernetes镜像拉取策略终极防护Kyverno强制配置指南Kubernetes镜像拉取策略终极防护Kyverno强制配置指南 还在为容器镜像拉取策略配置不一致而烦恼担心生产环境因镜像缓存问题导致部署失败一文掌握K网络安全云原生合规审计应用安全上一篇BlockSuite与Yjs深度集成理解底层CRDT技术实现下一篇Min浏览器任务自动化专家策略企业流程优化战略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考