名称

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

概要

podman pull [选项] 源 [源…]

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

podman pull [传输]名称[:标签|@摘要]

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

描述

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

源

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=路径

身份验证文件的路径。在 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=路径 来完成。

--cert-dir=路径

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

--creds=[用户名[:密码]]

用于对注册表进行身份验证的 [用户名[:密码]]（如果需要）。如果一个或两个值未提供，则会出现命令行提示，并且可以输入该值。密码将不显示地输入。

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

--decryption-key=密钥[:密码]

用于解密镜像的 [密钥[:密码]]。密钥可以指向密钥和/或证书。使用所有密钥尝试解密。如果密钥受密码保护，则需要在参数中传递密码，否则省略。

--disable-content-trust

这是一个 Docker 特定的选项，用于禁用对容器注册表的镜像验证，Podman 不支持。此选项是 NOOP，仅用于脚本兼容性。

--help, -h

打印使用说明。

--os=操作系统

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

--platform=操作系统/体系结构

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

--quiet, -q

在拉取镜像时抑制输出信息。

--retry=尝试次数

在注册表和本地存储之间拉取或推送镜像失败时，重试次数。默认为 3。

--retry-delay=持续时间

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

--tls-verify

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

--variant=变体

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

文件

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

当用户指定不包含镜像存储的容器注册表的镜像时，这称为短名称。使用未限定搜索注册表会导致歧义，因为不清楚从哪个注册表拉取给定镜像，该镜像通过短名称引用。

使用短名称可能会遇到被占用的注册表命名空间。如果未限定搜索注册表设置为 [“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 中定义的默认未限定注册表列表中选择注册表。用户的选择将存储在缓存文件中，用于所有将来的短名称扩展。有根短名称存储在 /var/cache/containers/short-name-aliases.conf 中。无根短名称存储在 $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 次拉取镜像，并在 quet 模式下每次重试之间延迟 10 秒。

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

另请参阅

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 编写