名称

podman-pull - 从注册表拉取镜像

简介

podman pull [选项] 源 [源…]

podman image pull [选项] 源 [源…]

podman pull [选项] [传输协议]名称[:标签|@摘要]

podman image pull [选项] [传输协议]名称[:标签|@摘要]

描述

podman pull 将镜像从注册表复制到本地机器。该命令可以拉取一个或多个镜像。如果命令行参数中的镜像引用不包含注册表，则将其称为短名称引用。如果镜像是“短名称”引用，并且short-name-aliases.conf中未指定该短名称的别名，则 Podman 会提示用户从哪个特定的容器注册表拉取镜像。如果未指定镜像标签，则 podman pull 默认为带有 latest 标签（如果存在）的镜像并将其拉取。镜像拉取后，podman 会打印完整的镜像 ID。podman pull 还可以使用摘要 podman pull image@digest 来拉取镜像，也可以用于使用不同的传输协议从存档和本地存储中拉取镜像。重要提示：镜像存储在本地镜像存储中。

源

SOURCE 是从中拉取容器镜像的位置。它支持 containers-transports(5) 中的所有传输协议。如果未指定传输协议，则输入将受短名称解析，并使用docker（即容器注册表）传输协议。对于远程客户端，包括 Mac 和 Windows（不包括 WSL2）机器，docker是唯一支持的传输协议。

# Pull from a container registry
$ podman pull quay.io/username/myimage

# Pull from a container registry with short-name resolution
$ podman pull fedora

# Pull from a container registry via the docker transport
$ podman pull docker://quay.io/username/myimage

# Pull from a local directory
$ podman pull dir:/tmp/myimage

# Pull from a tarball in the docker-archive format
$ podman pull docker-archive:/tmp/myimage

# Pull from a local docker daemon
$ sudo podman pull docker-daemon:docker.io/library/myimage:33

# Pull from a tarball in the OCI-archive format
$ podman pull oci-archive:/tmp/myimage

选项

--all-tags, -a

拉取存储库中的所有带标签的镜像。

重要提示：当使用 all-tags 标志时，Podman 不会遍历 containers-registries.conf(5) 中的搜索注册表，而是始终对不合格的镜像名称使用 docker.io。

--arch=ARCH

覆盖要拉取的镜像的架构，默认为主机架构。例如，arm。除非被覆盖，否则后续在本地存储中查找相同镜像时将匹配此架构，无论主机如何。

--authfile=path

认证文件的路径。Linux 上默认为${XDG_RUNTIME_DIR}/containers/auth.json，Windows/macOS 上默认为$HOME/.config/containers/auth.json。该文件由 podman login 创建。如果在此处找不到授权状态，则会检查$HOME/.docker/config.json，该文件是使用 docker login 设置的。

注意：也可以通过设置REGISTRY_AUTH_FILE环境变量来覆盖认证文件的默认路径。这可以通过 export REGISTRY_AUTH_FILE=path 完成。

--cert-dir=path

使用path中的证书（*.crt、*.cert、*.key）连接到注册表。（默认值：/etc/containers/certs.d）详情请参阅 containers-certs.d(5)。（此选项不适用于远程 Podman 客户端，包括 Mac 和 Windows（不包括 WSL2）机器）

--creds=[username[:password]]

用于向镜像仓库进行身份验证的 [username[:password]]（如果需要）。如果未提供一个或两个值，则会出现命令行提示，可以输入该值。密码输入时无回显。

请注意，指定的凭据仅用于针对目标注册表进行身份验证。它们不用于镜像或当注册表被重写时（参见containers-registries.conf(5)）；要对这些进行身份验证，请考虑使用containers-auth.json(5)文件。

--decryption-key=key[:passphrase]

用于解密镜像的 [key[:passphrase]]。Key 可以指向密钥和/或证书。会尝试使用所有密钥进行解密。如果密钥受密码短语保护，则必须在参数中传递它，否则省略。

--disable-content-trust

这是一个 Docker 特定的选项，用于禁用对容器仓库的镜像验证，Podman 不支持此选项。此选项是一个空操作（NOOP），仅为脚本兼容性而提供。

--help, -h

打印使用说明。

--os=OS

覆盖要拉取的镜像的操作系统，默认为主机操作系统。例如，windows。除非被覆盖，否则后续在本地存储中查找相同镜像时将匹配此操作系统，无论主机如何。

--platform=OS/ARCH

指定选择镜像的平台。（与 --arch 和 --os 冲突）--platform选项可用于覆盖当前架构和操作系统。除非被覆盖，否则后续在本地存储中查找相同镜像时将匹配此平台，无论主机如何。

--policy

拉取镜像策略。默认值为 always。

• always：始终拉取镜像，如果拉取失败则抛出错误。

• missing：仅当在本地容器存储中找不到镜像时才拉取。如果没有找到镜像且拉取失败，则抛出错误。

• never：从不拉取镜像；只使用本地版本。如果本地不存在镜像，则抛出错误。

• newer：如果注册表上的镜像比本地容器存储中的镜像新，则拉取。当摘要不同时，镜像被认为是更新的。比较时间戳容易出错。如果找到本地镜像，则会抑制拉取错误。

--quiet, -q

拉取镜像时抑制输出信息

--retry=attempts

在仓库和本地存储之间拉取或推送镜像失败时重试的次数。默认为 3。

--retry-delay=duration

在拉取或推送镜像失败时，注册表和本地存储之间重试尝试的延迟持续时间。默认是从两秒开始，然后以指数级退避。当设置此值时使用延迟，并且不会发生指数级退避。

--tls-verify

联系注册表时要求 HTTPS 并验证证书（默认值：true）。如果明确设置为 true，则使用 TLS 验证。如果设置为 false，则不使用 TLS 验证。如果未指定，则使用 TLS 验证，除非目标注册表在 containers-registries.conf(5) 中被列为不安全注册表

--variant=VARIANT

使用VARIANT而不是容器镜像的默认架构变体。某些镜像可以使用 arm 架构的多个变体，例如 arm/v5 和 arm/v7。

文件

short-name-aliases.conf (/var/cache/containers/short-name-aliases.conf, $HOME/.cache/containers/short-name-aliases.conf)

当用户指定的镜像不包含存储镜像的容器注册表时，这称为短名称。使用不合格的搜索注册表会带来歧义，因为不清楚给定镜像（由短名称引用）可能从哪个注册表拉取。

使用短名称存在撞到抢注的注册表命名空间的风险。如果 unqualified-search 注册表设置为 ["public-registry.com", "my-private-registry.com"]，攻击者可能会接管public-registry.com的命名空间，以便可以从public-registry.com而不是预期的源my-private-registry.com拉取镜像。

虽然强烈建议始终使用完全限定的镜像引用，但使用短名称的现有部署可能不容易更改。为了规避上述歧义，可以配置指向完全限定镜像引用的短名称别名。发行版通常在 /etc/containers/registries.conf.d/ 目录中提供一个默认的 shortnames.conf 扩展文件。管理员可以使用此目录添加自己的本地短名称扩展文件。

拉取镜像时，如果用户未指定完整的注册表，容器引擎会尝试将短名称扩展为完整名称。如果命令在 tty 下执行，系统会提示用户从 registries.conf 中定义的默认非限定注册表列表中选择一个注册表。用户的选择会存储在一个缓存文件中，供将来所有短名称扩展使用。Rootful 短名称存储在 /var/cache/containers/short-name-aliases.conf 中。Rootless 短名称存储在 $HOME/.cache/containers/short-name-aliases.conf 文件中。

有关短名称的更多信息，请参阅containers-registries.conf(5)

registries.conf (/etc/containers/registries.conf)

registries.conf 是配置文件，它指定在完成不包含注册表或域部分的镜像名称时应咨询哪个容器注册表。

注意：使用环境变量TMPDIR来更改下载容器镜像的临时存储位置。Podman 默认使用/var/tmp。

示例

拉取具有短名称解析的单个镜像。

$ podman pull alpine:latest
Resolved "alpine" as an alias (/etc/containers/registries.conf.d/000-shortnames.conf)
Trying to pull docker.io/library/alpine:latest...
Getting image source signatures
Copying blob 5843afab3874 done
Copying config d4ff818577 done
Writing manifest to image destination
Storing signatures
d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83

拉取一个或多个具有/不具有短名称解析的镜像。

podman pull busybox:musl alpine quay.io/libpod/cirros
Trying to pull docker.io/library/busybox:musl...
Getting image source signatures
Copying blob 0c52b060233b [--------------------------------------] 0.0b / 0.0b
Copying config 9ad2c435a8 done
Writing manifest to image destination
Storing signatures
9ad2c435a887e3f723654e09b48563de44aa3c7950246b2e9305ec85dd3422db
Trying to pull docker.io/library/alpine:latest...
Getting image source signatures
Copying blob 5843afab3874 [--------------------------------------] 0.0b / 0.0b
Copying config d4ff818577 done
Writing manifest to image destination
Storing signatures
d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83
Trying to pull quay.io/libpod/cirros:latest...
Getting image source signatures
Copying blob 8da581cc9286 done
Copying blob 856628d95d17 done
Copying blob f513001ba4ab done
Copying config 3c82e4d066 done
Writing manifest to image destination
Storing signatures
3c82e4d066cf6f9e50efaead6e3ff7fddddf5527826afd68e5a969579fc4db4a

使用其摘要拉取镜像。

$ podman pull alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e
Trying to pull docker.io/library/alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e...
Getting image source signatures
Copying blob 188c0c94c7c5 done
Copying config d6e46aa247 done
Writing manifest to image destination
Storing signatures
d6e46aa2470df1d32034c6707c8041158b652f38d2a9ae3d7ad7e7532d22ebe0

通过指定认证文件拉取镜像。

$ podman pull --authfile temp-auths/myauths.json docker://docker.io/umohnani/finaltest
Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
 1.90 MB / 1.90 MB [========================================================] 0s
Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
 1.41 KB / 1.41 KB [========================================================] 0s
Writing manifest to image destination
Storing signatures
03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438

通过向注册表进行身份验证来拉取镜像。

$ podman pull --creds testuser:testpassword docker.io/umohnani/finaltest
Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
 1.90 MB / 1.90 MB [========================================================] 0s
Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
 1.41 KB / 1.41 KB [========================================================] 0s
Writing manifest to image destination
Storing signatures
03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438

使用 tls 验证拉取镜像。

$ podman pull --tls-verify=false --cert-dir image/certs docker.io/umohnani/finaltest
Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
 1.90 MB / 1.90 MB [========================================================] 0s
Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
 1.41 KB / 1.41 KB [========================================================] 0s
Writing manifest to image destination
Storing signatures
03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438

通过覆盖主机架构拉取镜像。

$ podman pull --arch=arm arm32v7/debian:stretch
Trying to pull docker.io/arm32v7/debian:stretch...
Getting image source signatures
Copying blob b531ae4a3925 done
Copying config 3cba58dad5 done
Writing manifest to image destination
Storing signatures
3cba58dad5d9b35e755b48b634acb3fdd185ab1c996ac11510cc72c17780e13c

在静默模式下，最多重试 6 次拉取镜像，每次重试之间延迟 10 秒。

$ podman --remote pull -q --retry 6 --retry-delay 10s ubi9
4d6addf62a90e392ff6d3f470259eb5667eab5b9a8e03d20b41d0ab910f92170

仅当本地不存在镜像时才拉取。

$ podman pull --policy missing alpine:latest

从不拉取镜像，只使用本地版本。

$ podman pull --policy never alpine:latest

即使本地存在镜像也始终拉取。

$ podman pull --policy always alpine:latest
Trying to pull docker.io/library/alpine:latest...
Getting image source signatures
Copying blob 5843afab3874 done
Copying config d4ff818577 done
Writing manifest to image destination
Storing signatures
d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83

另请参阅

podman(1)、podman-push(1)、podman-login(1)、containers-certs.d(5)、containers-registries.conf(5)、containers-transports(5)

故障排除

有关常见问题的解决方案，请参阅 podman-troubleshooting(7)。

历史

2017年7月，由 Urvashi Mohnani umohnani@redhat.com 最初编写