名称

podman-image.unit - 用于使用 Podman Quadlet 管理容器镜像拉取操作的 systemd 单元文件

简介

名称.image

描述

镜像文件以 .image 扩展名命名，并包含一个 [Image] 部分，描述容器镜像拉取命令。生成的服务是一个一次性命令，用于确保镜像存在于主机上，如果需要则进行拉取。

使用镜像单元允许容器和卷依赖于自动拉取的镜像。这在使用特殊选项控制镜像拉取时特别有用。

使用概述

.image 文件在启动或重新加载时由 podman-system-generator 解析，生成一个运行 podman image pull 的 systemd .service 文件。

.image 文件的引用可以在 .container 文件的 Image= 选项中使用。

选项

[Image] 的有效选项如下所示

[Image] 选项	podman image pull 等效
AllTags=true	--all-tags
Arch=aarch64	--arch=aarch64
AuthFile=/etc/registry/auth.json	--authfile=/etc/registry/auth.json
CertDir=/etc/registry/certs	--cert-dir=/etc/registry/certs
ContainersConfModule=/etc/nvd.conf	--module=/etc/nvd.conf
Creds=myname:mypassword	--creds=myname:mypassword
DecryptionKey=/etc/registry.key	--decryption-key=/etc/registry.key
GlobalArgs=--log-level=debug	--log-level=debug
Image=quay.io/centos/centos:latest	podman image pull quay.io/centos/centos:latest
ImageTag=quay.io/centos/centos:latest	解析 .image 引用时使用此名称
OS=windows	--os=windows
PodmanArgs=--os=linux	--os=linux
Policy=always	--policy=always
Retry=5	--retry=5
RetryDelay=10s	--retry-delay=10s
TLSVerify=false	--tls-verify=false
Variant=arm/v7	--variant=arm/v7

AllTags=true

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

重要提示：使用 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 完成。

CertDir=path

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

ContainersConfModule=module

加载指定的 containers.conf(5) 模块。

此选项可以列出多次。

Creds=[username[:password]]

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

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

DecryptionKey=key[:passphrase]

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

GlobalArgs=

此键包含一个参数列表，这些参数直接在生成文件中的 podman 命令之后传递。它可用于访问生成器不支持的 Podman 功能。由于生成器无法预知这些参数可能导致的意外交互，因此不建议使用此选项。

其格式是空格分隔的参数列表，可以选择单独转义以允许包含空格和其他控制字符。

此键可以列出多次。

Image=

要拉取的镜像。出于性能和稳健性考虑，建议使用完全限定的镜像名称而非短名称。

名称的格式与传递给 podman pull 时的格式相同。因此，它支持使用 :tag 或摘要来保证特定的镜像版本。

ImageTag=

引用的 Image 的实际 FQIN。仅当源是文件或目录存档时才有意义。

例如，使用以下 Podman 命令保存到 docker-archive 的镜像

podman image save --format docker-archive --output /tmp/archive-file.tar quay.io/podman/stable:latest

需要设置

• Image=docker-archive:/tmp/archive-file.tar

• ImageTag=quay.io/podman/stable:latest

OS=os

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

PodmanArgs=

此键包含一个参数列表，这些参数直接传递到生成文件中的 podman 命令末尾。它可用于访问生成器不支持的 Podman 功能。由于生成器无法预知这些参数可能导致的意外交互，因此不建议使用此选项。

其格式是空格分隔的参数列表，可以选择单独转义以允许包含空格和其他控制字符。

此键可以列出多次。

Policy=always

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

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

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

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

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

Retry=attempts

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

RetryDelay=duration

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

TLSVerify=

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

Variant=VARIANT

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

示例

基本镜像拉取

[Image]
Image=quay.io/centos/centos:latest

从 docker 存档拉取

[Image]
Image=docker-archive:/tmp/centos.tar
ImageTag=quay.io/centos/centos:latest

使用凭据拉取

[Image]
Image=quay.io/private/image:latest
Creds=myuser:mypassword

另请参阅

systemd.unit(5), podman-image-pull(1), [podman-quadlet(7)]