名称

podman-build - 使用 Containerfile 构建容器镜像

概要

podman build [选项] [上下文]

podman image build [选项] [上下文]

描述

podman build 使用来自一个或多个 Containerfile 或 Dockerfile 的指令以及指定的构建上下文目录来构建镜像。Containerfile 在内部使用与 Dockerfile 相同的语法。对于本文档，称为 Containerfile 的文件可以是名为“Containerfile”或“Dockerfile”的任何文件。任何附加了其他扩展名的文件都不会被podman build .识别，除非使用-f标志指定该文件。

构建上下文目录可以指定为存档、git 仓库或 Containerfile 的 http(s) URL。

当使用-f以及 Containerfile 的路径调用，且没有显式指定 CONTEXT 目录时，Podman 将使用 Containerfile 的父目录作为其构建上下文。

以“.in”后缀结尾的 Containerfile 将通过 CPP(1) 预处理。这对于将 Containerfile 分解成多个可重用的部分很有用，这些部分可以通过 CPP 的#include指令来使用。以 .in 结尾的 Containerfile 限制了没有注释行，除非它们是 CPP 命令。请注意，Containerfile.in 文件仍然可以通过其他工具来使用，这些工具可以通过cpp -E手动预处理它们。

当 URL 是一个存档时，URL 的内容将被下载到一个临时位置并提取，然后执行。

当 URL 是一个 Containerfile 时，Containerfile 将被下载到一个临时位置。

当 Git 仓库被设置为 URL 时，该仓库会被克隆到本地，然后被设置为上下文。如果 URL 带有git://前缀或.git后缀，则它被视为一个 Git 仓库。

注意：podman build使用来自Buildah项目的代码来构建容器镜像。此Buildah代码为容器存储中的RUN选项创建Buildah容器。在某些情况下，当podman build崩溃或用户终止podman build进程时，这些外部容器可能会留在容器存储中。使用podman ps --all --external命令来查看这些容器。

podman buildx build命令是podman build的别名。并非所有buildx build功能都可以在 Podman 中使用。提供buildx build选项是为了脚本兼容性。

选项

--add-host=主机名[;主机名[;…]]:ip

向容器的/etc/hosts文件添加自定义主机到 IP 映射。

该选项采用一个或多个以分号分隔的主机名，这些主机名将被映射到单个 IPv4 或 IPv6 地址，地址由冒号分隔。它还可以用于覆盖 Podman 默认添加到/etc/hosts中的主机名的 IP 地址（另请参见--name和--hostname选项）。此选项可以多次指定以向/etc/hosts添加其他映射。它与--no-hosts选项冲突，也与containers.conf中的no_hosts=true冲突。

除了 IP 地址之外，还可以使用特殊标志host-gateway。这将解析为容器可以用来连接到主机的 IP 地址。选择的 IP 地址取决于您的网络设置，因此无法保证 Podman 能自动确定host-gateway地址，这会导致 Podman 出现错误消息并失败。您可以使用containers.conf中的host_containers_internal_ip选项覆盖此 IP 地址。

host-gateway地址也由 Podman 用于自动将host.containers.internal和host.docker.internal主机名添加到/etc/hosts中。您可以通过提供--no-hosts选项或在containers.conf中设置host_containers_internal_ip=”none”来阻止这种情况。如果未手动配置host-gateway地址，并且 Podman 无法自动确定 IP 地址，则 Podman 将静默地跳过将这些内部主机名添加到/etc/hosts中。如果 Podman 在使用podman machine的虚拟机中运行（包括 Mac 和 Windows 主机），则 Podman 将静默地跳过将内部主机名添加到/etc/hosts中，除非手动配置了 IP 地址；内部主机名由 gvproxy DNS 解析器解析。

默认情况下，Podman 将使用主机的/etc/hosts文件作为基础，也就是说，此文件中存在的所有主机名也会出现在容器的/etc/hosts文件中。可以使用containers.conf中的base_hosts_file配置来配置不同的基础文件。

--all-platforms

而不是为使用--platform选项指定的平台集构建，而是检查构建的基础镜像，并为所有可用的平台构建。使用scratch作为起始点的阶段无法检查，因此必须存在至少一个非scratch阶段才能使检测有效地工作。

--annotation=注释=值

向镜像元数据添加镜像注释（例如注释=值）。可以多次使用。

注意：此信息不存在于 Docker 镜像格式中，因此在以 Docker 格式写入镜像时会被丢弃。

--arch=架构

将要构建的镜像的架构，以及要拉取的基础镜像的架构（如果构建使用基础镜像）设置为提供的值，而不是使用构建主机的架构。除非覆盖，否则后续在本地存储中查找相同的镜像将匹配此架构，而与主机无关。（示例：arm、arm64、386、amd64、ppc64le、s390x）

--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=路径来完成此操作。

--build-arg=参数=值

指定构建参数及其值，该值将在从 Containerfile 中读取的指令中进行插值，其方式与环境变量相同，但不会添加到结果镜像配置中的环境变量列表中。

--build-arg-file=路径

指定包含以参数=值形式构建参数的行的文件。建议的文件名为argfile.conf。

以#开头的注释行将被忽略，空行也会被忽略。所有其他行必须是传递给--build-arg的参数=值格式。

如果通过--build-arg-file和--build-arg选项提供了多个参数，则构建参数将合并到所有提供文件和命令行参数中。

通过--build-arg-file选项提供的任何文件都会在通过--build-arg选项提供的参数之前被读取。

当给定的参数名被多次指定时，最后一次实例是传递给结果构建的实例。这意味着--build-arg值始终会覆盖--build-arg-file中的值。

--build-context=名称=值

使用其简短名称和位置来指定额外的构建上下文。可以使用与访问 COPY 指令中不同阶段相同的方式来引用额外的构建上下文。

有效值为

  • 本地目录 – 例如 --build-context project2=../path/to/project2/src （此选项不可用于远程 Podman 客户端。在 Podman 机器设置（即 macOS 和 Windows）上，路径必须存在于机器 VM 上）

  • 指向 tarball 的 HTTP URL – 例如 --build-context src=https://example.org/releases/src.tar

  • 容器镜像 – 使用 container-image:// 前缀指定，例如 --build-context alpine=container-image://alpine:3.15，（也接受 docker://、docker-image://）

在 Containerfile 一侧，在所有接受“from”参数的命令中引用构建上下文。以下是可能的外观

FROM [name]
COPY --from=[name] ...
RUN --mount=from=[name] …

[名称] 的值将按照以下优先级顺序匹配

  • 使用 --build-context [名称]=.. 定义的命名构建上下文

  • 在 Containerfile 中使用 AS [名称] 定义的阶段

  • 镜像 [名称]，本地或在远程注册表中

--cache-from=镜像

用作潜在缓存源的仓库。当指定时，Buildah 会尝试在指定的仓库中查找缓存镜像，并尝试拉取缓存镜像，而不是在本地实际执行构建步骤。只有当缓存镜像被认为是有效的缓存命中时，Buildah 才会尝试拉取以前缓存的镜像。

使用--cache-to选项来填充远程仓库中的缓存内容。

示例

# populate a cache and also consult it
buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .

注意：除非指定了--layers，否则--cache-from选项会被忽略。

--cache-to=镜像

设置此标志来指定用于存储缓存镜像的远程仓库。Buildah 会尝试将新构建的缓存镜像推送到远程仓库。

注意：使用 --cache-from 选项以在远程存储库中使用缓存内容。

示例

# populate a cache and also consult it
buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .

注意：除非指定了 --layers，否则 --cache-to 选项将被忽略。

--cache-ttl

限制对缓存映像的使用，仅考虑创建时间戳小于 *duration* 的映像。例如，如果指定了 --cache-ttl=1h，Buildah 将考虑在 1 小时内创建的中间缓存映像，而忽略此时间段之外的中间缓存映像。

注意：手动设置 --cache-ttl=0 等同于在实现中使用 --no-cache，因为这意味着用户根本不想使用缓存。

--cap-add=CAP_xxx

执行 RUN 指令时，以指定的权限添加到其权限集中，运行指令中指定的命令。某些权限默认授予；此选项可用于添加更多权限。

--cap-drop=CAP_xxx

执行 RUN 指令时，以指定的权限从其权限集中删除，运行指令中指定的命令。CAP_CHOWN、CAP_DAC_OVERRIDE、CAP_FOWNER、CAP_FSETID、CAP_KILL、CAP_NET_BIND_SERVICE、CAP_SETFCAP、CAP_SETGID、CAP_SETPCAP 和 CAP_SETUID 权限默认授予；此选项可用于删除它们。

如果对 --cap-add 和 --cap-drop 选项都指定了权限，则无论选项的顺序如何，该权限都会被删除。

--cert-dir=path

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

--cgroup-parent=path

创建容器的 cgroup 的 cgroups 路径。如果路径不是绝对路径，则该路径被视为相对于 init 进程的 cgroups 路径。如果 cgroups 不存在，则会创建它们。

--cgroupns=how

在处理 RUN 指令时设置 cgroup 命名空间的配置。配置的值可以是“” （空字符串）或“private”，表示创建一个新的 cgroup 命名空间，也可以是“host”，表示重用 buildah 本身运行的 cgroup 命名空间。

--compat-volumes

处理使用 VOLUME 指令标记的目录（包括此构建中的目录以及从基础映像继承的目录），以便其内容只能通过 ADD 和 COPY 指令修改。RUN 指令在这些位置进行的任何更改都将被还原。在引入此选项之前，此行为是默认行为，但现在默认情况下已禁用。

--compress

添加此选项是为了与其他容器 CLI 保持一致。Podman 不与守护程序或远程服务器通信。因此，在发送数据之前压缩数据与 Podman 无关。（此选项在远程 Podman 客户端不可用，包括 Mac 和 Windows（不包括 WSL2）机器。）

--cpp-flag=flags

设置要传递给 C 预处理器 cpp(1) 的附加标志。以“.in” 结尾的容器文件通过 cpp(1) 进行预处理。此选项可用于将附加标志传递给 cpp。注意：您还可以通过设置 BUILDAH_CPPFLAGS 环境变量来设置默认 CPPFLAGS（例如，export BUILDAH_CPPFLAGS=”-DDEBUG”）。

--cpu-period=limit

设置完全公平调度程序 (CFS) 的 CPU 周期，这是一个以微秒为单位的持续时间。一旦容器的 CPU 配额用完，它将不会被调度运行，直到当前周期结束。默认为 100000 微秒。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不支持。

--cpu-quota=limit

限制 CPU 完全公平调度程序 (CFS) 配额。

限制容器的 CPU 使用率。默认情况下，容器使用完整的 CPU 资源。该限制是一个以微秒为单位的数字。如果提供了数字，则容器被允许使用该数量的 CPU 时间，直到 CPU 周期结束（可以通过 --cpu-period 控制）。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不支持。

--cpu-shares, -c=shares

CPU 份额（相对权重）。

默认情况下，所有容器都获得相同比例的 CPU 周期。可以通过更改容器的 CPU 份额权重（相对于所有正在运行的容器的组合权重）来修改此比例。默认权重为 1024。

该比例仅在运行 CPU 密集型进程时适用。当一个容器中的任务处于空闲状态时，其他容器可以使用剩余的 CPU 时间。实际的 CPU 时间量取决于系统上运行的容器数量。

例如，考虑三个容器，一个容器的 cpu-share 为 1024，另外两个容器的 cpu-share 设置为 512。当三个容器中的进程都尝试使用 100% 的 CPU 时，第一个容器将获得总 CPU 时间的 50%。如果添加第四个容器，其 cpu-share 为 1024，则第一个容器仅获得 CPU 的 33%。其余容器分别获得 CPU 的 16.5%、16.5% 和 33%。

在多核系统上，CPU 时间份额会分布在所有 CPU 内核上。即使容器的 CPU 时间限制低于 100%，它也可以使用每个单独 CPU 内核的 100%。

例如，考虑一个拥有三个以上内核的系统。如果容器 *C0* 以 --cpu-shares=512 启动并运行一个进程，另一个容器 *C1* 以 --cpu-shares=1024 启动并运行两个进程，则可能会导致以下 CPU 份额分配

PID

容器

CPU

CPU 份额

100

C0

0

CPU0 的 100%

101

C1

1

CPU1 的 100%

102

C1

2

CPU2 的 100%

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不支持。

--cpuset-cpus=number

允许执行的 CPU。可以指定为逗号分隔列表（例如 0,1）、范围（例如 0-3）或它们的任何组合（例如 0-3,7,11-15）。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不支持。

--cpuset-mems=nodes

允许执行的内存节点 (MEM)（0-3、0、1）。仅在 NUMA 系统上有效。

如果系统上有四个内存节点（0-3），则使用 --cpuset-mems=0,1，那么容器中的进程仅使用来自前两个内存节点的内存。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不支持。

--creds=[username[:password]]

用于对注册表进行身份验证的 [username[:password]]，如果需要。如果未提供一个或两个值，则会出现命令行提示，并且可以输入该值。密码在没有回显的情况下输入。

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

--cw=options

使用 krun（即使用 libkrun 功能启用并作为 *krun* 调用的 *crun*）生成适合用作在可信执行环境 (TEE) 中运行的机密工作负载的映像。映像的根文件系统将包含加密的磁盘映像和 krun 的配置信息，而不是常规内容。

*options* 的值是一个逗号分隔的键=值对列表，提供生成将包含在容器映像中的其他数据的配置信息。

识别的 *键* 是

*attestation_url*: 密钥代理/证明服务器的位置。如果指定了值，则新的映像的工作负载 ID 以及用于加密磁盘映像的密码将注册到服务器，并且服务器的位置将存储在容器映像中。在运行时，krun 预计会联系服务器以使用工作负载 ID（也存储在容器映像中）检索密码。如果未指定值，则 *必须* 指定 *passphrase* 值。

*cpus*: 映像在运行时预计要使用的虚拟 CPU 数量。如果未指定，则将提供默认值。

*firmware_library*: libkrunfw-sev 共享库的位置。如果未指定，buildah 会检查它是否在许多硬编码位置中存在。

*memory*: 映像在运行时预计要使用的内存量，以兆字节为单位。如果未指定，则将提供默认值。

*passphrase*: 用于加密将包含在容器映像中的磁盘映像的密码。如果未指定值，但指定了 *attestation_url* 值，则将使用随机生成的密码。作者建议设置 *attestation_url* 但不设置 *passphrase*。

*slop*: 与容器映像内容的大小相比，分配给磁盘映像的额外空间，以百分比 (..%) 或大小值（字节，如果存在 KB 或 MB 等后缀，则为更大的单位）表示，或者两个或多个此类规范的总和。如果未指定，buildah 会猜测比内容多 25% 的空间就足够了，但提供此选项是为了防止其猜测错误。

*type*: 映像应标记为与其一起使用的可信执行环境 (TEE) 的类型。接受的值是“SEV”（AMD 安全加密虚拟化 - 加密状态）和“SNP”（AMD 安全加密虚拟化 - 安全嵌套分页）。如果未指定，则默认为“SNP”。

*workload_id*: 将记录在容器映像中的工作负载标识符，用于在运行时检索用于加密磁盘映像的密码。如果未指定，则将从基础映像的映像 ID 派生一个半随机值。

此选项在远程客户端不支持，包括 Mac 和 Windows（不包括 WSL2）机器。

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

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

--device=主机设备[:容器设备][:权限]

将主机设备添加到容器。可选的 权限参数可用于通过组合 r（读）、w（写）和 m（mknod(2)）来指定设备权限。

示例：--device=/dev/sdc:/dev/xvdc:rwm。

注意：如果 主机设备 是符号链接，则先对其进行解析。容器只存储主机设备的主设备号和次设备号。

Podman 可能会加载使用指定设备所需的内核模块。Podman 在必要时加载模块的设备包括：/dev/fuse。

在无根模式下，新设备将从主机绑定挂载到容器，而不是 Podman 在容器空间内创建它。由于绑定挂载在 SELinux 系统上保留其 SELinux 标签，因此容器在访问挂载设备时可能会收到权限被拒绝的错误。修改 SELinux 设置以允许容器通过以下命令使用所有设备标签

$ sudo setsebool -P container_use_devices=true

注意：如果用户仅通过组拥有访问权限，则无法从无根容器内部访问该设备。crun(1) 运行时提供了一种解决方法，通过添加选项 --annotation run.oci.keep_original_groups=1 来实现。

--disable-compression, -D

在构建镜像时不要压缩文件系统层，除非镜像写入的位置要求压缩。这是默认设置，因为镜像层在推送到注册表时会自动压缩，并且写入本地存储的镜像只需解压缩即可存储。可以通过指定 --disable-compression=false 来强制在所有情况下进行压缩。

--disable-content-trust

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

--dns=ipaddr

设置自定义 DNS 服务器。

此选项可用于覆盖传递给容器的 DNS 配置。通常，当主机 DNS 配置对容器无效时（例如，127.0.0.1），需要使用此选项。在这种情况下，每次运行都需要使用 --dns 标志。

可以指定特殊值 none 来禁用 Podman 在容器中创建 /etc/resolv.conf。镜像中的 /etc/resolv.conf 文件将使用，无需更改。

此选项不能与设置为 none 的 --network 选项组合使用。

注意：此选项仅在构建中的 RUN 指令期间生效。它不会影响最终镜像中的 /etc/resolv.conf。

--dns-option=选项

设置构建期间使用的自定义 DNS 选项。

--dns-search=域名

设置构建期间使用的自定义 DNS 搜索域。

--env=环境变量[=值]

向构建的镜像添加一个值（例如 env=值）。可以多次使用。如果既未指定 = 也未指定 值，但 环境变量 在当前环境中设置，则当前环境中的值将添加到镜像中。要从构建的镜像中删除环境变量，请使用 --unsetenv 选项。

--file, -f=容器文件

指定一个容器文件，其中包含用于构建镜像的指令，可以是本地文件，也可以是 http 或 https URL。如果指定了多个容器文件，则 FROM 指令仅从最后一个指定的文件中接受。

如果未指定构建上下文，并且至少有一个容器文件是本地文件，则其所在的目录将用作构建上下文。

指定选项 -f - 会导致从 stdin 读取容器文件内容。

--force-rm

在构建完成后始终删除中间容器，即使构建失败（默认值为 true）。

--format

控制构建的镜像的清单和配置数据的格式。识别的格式包括 oci（OCI 镜像规范 v1.0，默认值）和 docker（版本 2，使用模式格式 2 作为清单）。

注意：您还可以通过设置 BUILDAH_FORMAT 环境变量来覆盖默认格式。 export BUILDAH_FORMAT=docker

--from

覆盖容器文件中的第一个 FROM 指令。如果容器文件中有多个 FROM 指令，则只更改第一个指令。

对于远程 podman 客户端，并非所有容器传输都能按预期工作。例如，oci-archive:/x.tar 会引用远程机器上的 /x.tar，而不是客户端上的 /x.tar。在使用 podman 远程客户端时，最好限制使用 containers-storage 和 docker:// 传输。

--group-add=组 | keep-groups

将额外的组分配给在容器进程中运行的主用户。

  • keep-groups 是一个特殊标志，告诉 Podman 保持补充组访问权限。

允许容器使用用户的补充组访问权限。如果文件系统或设备只能由无根用户的组访问，则此标志告诉 OCI 运行时将组访问权限传递到容器中。目前，仅适用于 crun OCI 运行时。注意：keep-groups 是独占的，不能与其他组一起指定。（不适用于远程命令，包括 Mac 和 Windows（不包括 WSL2）机器）

--help, -h

打印使用说明语句

--hooks-dir=路径

路径中的每个 *.json 文件都会为 buildah build 容器配置一个钩子。有关 JSON 文件的语法和钩子注入语义的更多详细信息，请参考。Buildah 目前支持 1.0.0 和 0.1.0 钩子模式，尽管 0.1.0 模式已弃用。

此选项可以多次设置；来自后面选项的路径具有更高的优先级。

对于注释条件，buildah 使用在生成的 OCI 配置中设置的任何注释。

对于绑定挂载条件，仅考虑调用方通过 --volume 显式请求的挂载。buildah 默认插入的绑定挂载（例如 /dev/shm）不被考虑。

如果对于根调用方未设置 --hooks-dir，Buildah 目前默认使用 /usr/share/containers/oci/hooks.d 和 /etc/containers/oci/hooks.d，优先级递增。使用这些默认值已弃用。迁移到显式设置 --hooks-dir。

--http-proxy

默认情况下，如果为 Podman 进程设置了代理环境变量，则会将其传递到容器中。可以通过将值设置为 false 来禁用此功能。传递的環境變數包括 http_proxy、https_proxy、ftp_proxy、no_proxy，以及这些变量的大写版本。此选项仅在主机系统必须使用代理但容器不使用任何代理时才需要。以任何其他方式为容器指定代理环境变量会覆盖从主机传递的值。（为容器指定代理的其他方式包括使用 --env 标志传递值，或在容器构建时硬编码代理环境）。在与远程客户端一起使用时，它使用在服务器进程上设置的代理环境变量。

默认值为 true。

--identity-label

如果设置了默认身份标签 io.buildah.version，则添加该标签。（默认值为 true）。

--ignorefile

指向备用 .containerignore 文件的路径。

--iidfile=镜像 ID 文件

将构建的镜像的 ID 写入文件。当多次指定 --platform 时，尝试使用此选项会导致错误。

--ipc=方式

在处理 RUN 指令时，设置 IPC 命名空间的配置。配置的值可以是 ""（空字符串）或 "container"，表示创建一个新的 IPC 命名空间，也可以是 "host"，表示重用运行 podman 本身的 IPC 命名空间，也可以是另一个进程正在使用的 IPC 命名空间的路径。

--isolation=type

控制在处理 RUN 指令时运行进程所使用的隔离类型。识别出的类型包括 oci（兼容 OCI 的运行时，默认值）、rootless（使用修改后的配置并启用其 --rootless 选项调用的兼容 OCI 的运行时，在其 create 调用中添加了 --no-new-keyring --no-pivot，并禁用网络和 UTS 命名空间，并启用 IPC、PID 和用户命名空间；无特权用户的默认值）和 chroot（一个更倾向于 chroot(1) 而不是容器技术的内部包装器）。

注意：您也可以通过设置 BUILDAH_ISOLATION 环境变量来覆盖默认隔离类型。 export BUILDAH_ISOLATION=oci

--jobs=number

并行运行最多 N 个并发阶段。如果作业数大于 1，则从 /dev/null 读取标准输入。如果指定为 0，则并行运行的作业数没有限制。

--label=label

将图像 标签（例如 label=value）添加到图像元数据。可以多次使用。

用户可以在 Containerfile 中设置一个特殊的 LABEL io.containers.capabilities=CAP1,CAP2,CAP3，它指定容器正常运行所需的 Linux 功能列表。在容器镜像中指定的这个标签告诉 Podman 仅使用这些功能来运行容器。Podman 使用指定的这些功能启动容器，只要这些功能列表是默认列表的子集即可。

如果指定的功能不在默认集中，Podman 会打印一条错误消息并使用默认功能运行容器。

--layer-label=label[=value]

将中间图像 标签（例如 label=value）添加到中间图像元数据。可以多次使用。

如果 标签已命名，但未提供 = 或 value，则 标签将设置为一个空值。

--layers

在构建过程中缓存中间图像（默认值为 true）。

注意：您也可以通过设置 BUILDAH_LAYERS 环境变量来覆盖层的默认值。 export BUILDAH_LAYERS=true

--logfile=filename

将发送到标准输出和标准错误的日志输出记录到指定的文件，而不是记录到标准输出和标准错误。此选项在远程客户端上不受支持，包括 Mac 和 Windows（不包括 WSL2）机器。

--logsplit=bool-value

如果指定了 --logfile 和 --platform，则 --logsplit 选项允许最终用户将每个平台的日志文件拆分为以下格式的不同文件： ${logfile}_${platform-os}_${platform-arch}。此选项在远程客户端上不受支持，包括 Mac 和 Windows（不包括 WSL2）机器。

--manifest=manifest

要向其中添加图像的清单列表的名称。如果清单列表不存在，则创建它。此选项可用于构建多架构图像。

--memory, -m=number[unit]

内存限制。单位可以是 b（字节）、k（千字节）、m（兆字节）或 g（吉字节）。

允许限制容器可用的内存。如果主机支持交换内存，则 -m 内存设置可以大于物理 RAM。如果指定了 0 的限制（不使用 -m），则容器的内存没有限制。实际限制可能会向上取整到操作系统页面大小的倍数（该值非常大，即数百万兆兆字节）。

此选项在 cgroups V1 无根系统上不支持。

--memory-swap=number[unit]

等于内存加交换的限制值。单位可以是 b（字节）、k（千字节）、m（兆字节）或 g（吉字节）。

必须与 -m（--memory）标志一起使用。参数值必须大于 -m（--memory）的相应值。默认情况下，它设置为 --memory 值的两倍。

将 number 设置为 -1 以启用无限交换。

此选项在 cgroups V1 无根系统上不支持。

--network=mode, --net

在处理 RUN 指令时，设置网络命名空间的配置。

有效 mode 值为

  • none：无网络。

  • host：使用 Podman 主机网络栈。注意：主机模式会使容器完全访问本地系统服务，例如 D-bus，因此被认为是不安全的。

  • ns:path：要加入的网络命名空间的路径。

  • private：为容器创建一个新的命名空间（默认值）

  • <network name|ID>：加入具有给定名称或 ID 的网络，例如使用 --network mynet 加入名为 mynet 的网络。仅支持有根用户。

  • slirp4netns[:OPTIONS,…]：使用 slirp4netns(1) 创建用户网络栈。可以指定这些附加选项，它们也可以使用容器配置中的 network_cmd_options 设置。

    • allow_host_loopback=true|false：允许 slirp4netns 访问主机环回 IP（默认值为 10.0.2.2 或来自 slirp4netns cidr 子网的第二个 IP，如果已更改，请参阅 cidr 选项）。默认值为 false。

    • mtu=MTU：指定此网络要使用的 MTU。（默认值为 65520）。

    • cidr=CIDR：指定此网络要使用的 IP 范围。（默认值为 10.0.2.0/24）。

    • enable_ipv6=true|false：启用 IPv6。默认值为 true。（outbound_addr6 所必需）。

    • outbound_addr=INTERFACE：指定 slirp 绑定到的出站接口（仅限 ipv4 流量）。

    • outbound_addr=IPv4：指定 slirp 绑定到的出站 ipv4 地址。

    • outbound_addr6=INTERFACE：指定 slirp 绑定到的出站接口（仅限 ipv6 流量）。

    • outbound_addr6=IPv6：指定 slirp 绑定到的出站 ipv6 地址。

  • pasta[:OPTIONS,…]：使用 pasta(1) 创建用户模式网络栈。
    这是无根容器的默认值，并且仅在无根模式下受支持。
    默认情况下，IPv4 和 IPv6 地址和路由以及 pod 接口名称将从主机复制。如果未配置端口转发，则将在两侧（init 命名空间或容器命名空间）绑定服务时动态转发端口。端口转发会保留原始源 IP 地址。pasta(1) 中描述的选项可以作为逗号分隔的参数指定。
    在 pasta(1) 选项方面，默认情况下会给出 --config-net，以便在容器启动时配置网络，并且默认情况下还会假设 --no-map-gw，以避免容器使用网关地址直接访问主机。后者可以通过在 pasta 特定选项中传递 --map-gw 来覆盖（尽管它不是实际的 pasta(1) 选项）。
    此外，-t none 和 -u none 被传递以禁用基于绑定端口的自动端口转发。类似地，-T none 和 -U none 被传递以禁用从容器到主机的相同功能。
    一些示例

    • pasta:--map-gw：允许容器使用网关地址直接访问主机。

    • pasta:--mtu,1500：为容器中的 tap 接口指定 1500 字节的 MTU。

    • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp，等效于默认的 slirp4netns(1) 选项：禁用 IPv6，将 10.0.2.0/24 分配给容器中的 tap0 接口，网关为 10.0.2.3，启用 DNS 转发器，在 10.0.2.3 可达，将 MTU 设置为 1500 字节，禁用 NDP、DHCPv6 和 DHCP 支持。

    • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp，等效于使用 Podman 覆盖的默认 slirp4netns(1) 选项：与上面相同，但将 MTU 保留为 65520 字节

    • pasta:-t,auto,-u,auto,-T,auto,-U,auto：启用基于观察到的来自主机和容器两侧的绑定端口的自动端口转发

    • pasta:-T,5201：启用从容器到主机的 TCP 端口 5201 的转发，使用环回接口而不是 tap 接口，以提高性能

--no-cache

不要对容器构建使用现有的缓存图像。从一个新的缓存层集开始构建。

--no-hostname

不要为 RUN 指令在容器中创建 /etc/hostname 文件。

默认情况下，Buildah 管理 /etc/hostname 文件，并添加容器自己的主机名。当设置了 --no-hostname 选项时，如果图像的 /etc/hostname 存在，它将保持不变。

--no-hosts

不要修改容器中的 /etc/hosts 文件。

Podman 默认情况下会控制容器的 /etc/hosts 文件，并添加容器名称（请参阅 --name 选项）和主机名（请参阅 --hostname 选项）、内部 host.containers.internal 和 host.docker.internal 主机以及使用 --add-host 选项添加的任何主机名。有关详细信息，请参阅 --add-host 选项。传递 --no-hosts 会禁用此功能，因此图像的 /etc/hosts 文件将保持不变。通过在 containers.conf 中设置 no_hosts=true，可以实现相同的效果。

此选项与 --add-host 冲突。

--omit-history

省略构建图像中的构建历史信息。（默认值为 false）。

此选项适用于最终用户明确希望设置 --omit-history 以省略构建图像中的可选 History，或者在使用构建工具构建图像时，这些工具不会在其图像中包含 History 信息。

--os=string

设置要构建的镜像的操作系统，以及要拉取的基础镜像的操作系统（如果构建使用基础镜像），而不是使用构建主机当前的操作系统。除非覆盖，否则在本地存储中对同一镜像的后续查找将匹配此操作系统，而与主机无关。

--os-feature=feature

为构建的镜像设置所需的操作系统feature的名称。默认情况下，如果镜像不是基于scratch，则保留基础镜像的必需操作系统功能列表（如果基础镜像指定了任何功能）。此选项通常仅在镜像的操作系统为 Windows 时才有意义。

如果feature以-结尾，则从镜像中列出的所需功能集中删除feature。

--os-version=version

为构建的镜像设置所需的操作系统version的准确值。默认情况下，如果镜像不是基于scratch，则保留基础镜像的必需操作系统版本（如果基础镜像指定了版本）。此选项通常仅在镜像的操作系统为 Windows 时才有意义，并且通常在 Windows 基础镜像中设置，因此通常不需要使用此选项。

--output, -o=output-opts

输出目标（格式：type=local,dest=path）

--output（或 -o）选项通过允许用户将镜像的内容作为本地文件系统上的文件导出，扩展了构建容器镜像的默认行为，这对于生成本地二进制文件、代码生成等很有用。（此选项不适用于远程 Podman 客户端，包括 Mac 和 Windows（不包括 WSL2）机器）

--output 的值是一个用逗号分隔的键=值对序列，定义了输出类型和选项。

支持的keys是

  • dest：导出输出的目标路径。有效值为绝对路径或相对路径，-表示标准输出。

  • type：定义要使用的输出类型。有效值在下面有说明。

有效的type值是

  • local：将生成的构建文件写入客户端的目录。

  • tar：将生成的构建文件作为单个 tarball（.tar）写入。

如果没有指定类型，则该值默认为 local。或者，除了逗号分隔的序列之外，--output 的值也可以仅仅是目标路径（dest 格式）（例如 --output some-path，--output -），其中 --output some-path 被视为 type=local，而 --output - 被视为 type=tar。

--pid=pid

在处理RUN指令时设置 PID 命名空间的配置。配置的值可以是“” （空字符串）或“container”，表示创建一个新的 PID 命名空间，也可以是“host”，表示使用podman本身运行的 PID 命名空间，或者可以是另一个进程正在使用的 PID 命名空间的路径。

--platform=os/arch[/variant][,…]

将构建镜像（及其基础镜像，如果使用）的os/arch设置为提供的值，而不是使用主机的当前操作系统和体系结构（例如 linux/arm）。除非覆盖，否则在本地存储中对同一镜像的后续查找将匹配此平台，而与主机无关。

如果设置了--platform，则--arch、--os和--variant选项的值将被覆盖。

--platform选项可以多次指定，或者将其参数作为逗号分隔的值列表提供。当指定多个平台时，将使用--manifest选项，而不是--tag选项。

Os/arch 对是 Go 编程语言使用的那些。在很多情况下，平台的arch值与其他工具（如arch命令）生成的arch值不同。有效的操作系统和体系结构名称组合在 https://golang.ac.cn/doc/install/source#environment 中列为 $GOOS 和 $GOARCH 的值，也可以通过运行go tool dist list找到。

虽然podman build很乐意使用基础镜像并为任何存在的平台构建镜像，但RUN指令无法在没有像qemu-user-static这样的包提供的模拟帮助的情况下成功执行。

--pull=policy

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

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

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

  • never：从不拉取镜像，而是使用本地容器存储中的镜像。如果找不到镜像，则抛出错误。

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

--quiet, -q

抑制指示正在处理哪条指令的输出消息，以及从注册表拉取镜像和写入输出镜像时的进度。

--retry=attempts

在注册表和本地存储之间拉取或推送镜像时，如果出现故障，则重试的次数。默认值为 3。

--retry-delay=duration

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

--rm

在构建成功后删除中间容器（默认值为 true）。

--runtime=path

指向备用 OCI 兼容运行时的path，该运行时用于运行由 RUN 指令指定的命令。

注意：您还可以通过设置 BUILDAH_RUNTIME 环境变量来覆盖默认运行时。export BUILDAH_RUNTIME=/usr/local/bin/runc

--runtime-flag=flag

为容器运行时添加全局标志。要列出支持的标志，请参阅所选容器运行时的联机帮助页。

注意：不要将前导 -- 传递给标志。要将 runc 标志 --log-format json 传递给 buildah build，给出的选项是 --runtime-flag log-format=json。

--sbom=preset

通过使用命名组合的扫描器镜像、扫描器命令和合并策略，扫描工作容器和构建上下文来为输出镜像生成 SBOM（软件物料清单）。必须与 --sbom-image-output、--sbom-image-purl-output、--sbom-output 和 --sbom-purl-output 中的一个或多个选项一起指定。识别的预设和它们等效的一组选项

  • “syft”，“syft-cyclonedx”: --sbom-scanner-image=ghcr.io/anchore/syft --sbom-scanner-command=”/syft scan -q dir:{ROOTFS} --output cyclonedx-json={OUTPUT}” --sbom-scanner-command=”/syft scan -q dir:{CONTEXT} --output cyclonedx-json={OUTPUT}” --sbom-merge-strategy=merge-cyclonedx-by-component-name-and-version

  • “syft-spdx”: --sbom-scanner-image=ghcr.io/anchore/syft --sbom-scanner-command=”/syft scan -q dir:{ROOTFS} --output spdx-json={OUTPUT}” --sbom-scanner-command=”/syft scan -q dir:{CONTEXT} --output spdx-json={OUTPUT}” --sbom-merge-strategy=merge-spdx-by-package-name-and-versioninfo

  • “trivy”，“trivy-cyclonedx”: --sbom-scanner-image=ghcr.io/aquasecurity/trivy --sbom-scanner-command=”trivy filesystem -q {ROOTFS} --format cyclonedx --output {OUTPUT}” --sbom-scanner-command=”trivy filesystem -q {CONTEXT} --format cyclonedx --output {OUTPUT}” --sbom-merge-strategy=merge-cyclonedx-by-component-name-and-version

  • “trivy-spdx”: --sbom-scanner-image=ghcr.io/aquasecurity/trivy --sbom-scanner-command=”trivy filesystem -q {ROOTFS} --format spdx-json --output {OUTPUT}” --sbom-scanner-command=”trivy filesystem -q {CONTEXT} --format spdx-json --output {OUTPUT}” --sbom-merge-strategy=merge-spdx-by-package-name-and-versioninfo

--sbom-image-output=path

当生成 SBOM 时，将生成的 SBOM 存储在输出镜像中指定的路径中。没有默认值。

--sbom-image-purl-output=path

当生成 SBOM 时，扫描它们以查找 PURL (包 URL) 信息，并将找到的 PURL 列表保存到输出镜像中指定的路径。没有默认值。

--sbom-merge-strategy=method

如果使用多个 --sbom-scanner-command 值，则使用指定的 method 将后面命令的输出与前面命令的输出合并。识别的值包括

  • cat 连接文件。

  • merge-cyclonedx-by-component-name-and-version 合并 JSON 文档的“component”字段，忽略文档中的值（当它们的“name”和“version”值的组合已存在时）。文档按生成顺序进行处理，即生成它们的命令指定的顺序。

  • merge-spdx-by-package-name-and-versioninfo 合并 JSON 文档的“package”字段，忽略文档中的值（当它们的“name”和“versionInfo”值的组合已存在时）。文档按生成顺序进行处理，即生成它们的命令指定的顺序。

--sbom-output=file

当生成 SBOM 时，将生成的 SBOM 存储在本地文件系统中命名的文件中。没有默认值。

--sbom-purl-output=文件

在生成 SBOM 时，扫描它们以获取 PURL (包 URL) 信息，并将找到的 PURL 列表保存到本地文件系统中指定的文件。没有默认值。

--sbom-scanner-command=镜像

通过从扫描器镜像运行指定的命令来生成 SBOM。如果指定了多个命令，则按其指定的顺序运行它们。执行以下文本替换

  • {ROOTFS} 构建镜像的文件系统根目录，绑定挂载。

  • {CONTEXT} 构建上下文和额外的构建上下文，绑定挂载。

  • {OUTPUT} 临时输出文件的名称，用于读取并与其他文件合并或复制到其他位置。

--sbom-scanner-image=镜像

使用指定的扫描器镜像生成 SBOM。

--secret=id=id,src=路径

以安全的方式传递 Containerfile 中用于构建镜像的秘密信息，这些信息不会存储在最终镜像中，也不会在其他阶段被看到。秘密被安装在容器中的默认位置 /run/secrets/id。

要稍后使用秘密，请在 Containerfile 中的 RUN 指令中使用 --mount 选项

RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret

--security-opt=选项

安全选项

  • apparmor=unconfined : 关闭容器的 apparmor 限制

  • apparmor=alternate-profile : 设置容器的 apparmor 限制配置文件

  • label=user:USER : 设置容器进程的标签用户

  • label=role:ROLE : 设置容器进程的标签角色

  • label=type:TYPE : 设置容器进程的标签进程类型

  • label=level:LEVEL : 设置容器进程的标签级别

  • label=filetype:TYPE : 设置容器文件的标签文件类型

  • label=disable : 关闭容器的标签隔离

  • no-new-privileges : 不支持

  • seccomp=unconfined : 关闭容器的 seccomp 限制

  • seccomp=profile.json : 将用作容器的 seccomp 过滤器的 JSON 文件。

--shm-size=数字[单位]

/dev/shm 的大小。单位可以是 b（字节）、k（kibibytes）、m（mebibytes）或 g（gibibytes）。如果省略单位，则系统使用字节。如果省略大小，则默认值为 64m。当 大小 为 0 时，对容器使用 IPC 的内存量没有限制。此选项与 --ipc=host 冲突。

--sign-by=指纹

使用具有指定指纹的 GPG 密钥签署镜像。（此选项不可用于远程 Podman 客户端，包括 Mac 和 Windows（不包括 WSL2）机器，）

--skip-unused-stages

跳过多阶段构建中不影响目标阶段的阶段。（默认：true）。

--squash

将镜像的所有新层压缩到一个新的层中；任何现有的层都不会被压缩。

--squash-all

压缩新镜像的所有新层（包括从基础镜像继承的层）到一个新的层中。

--ssh=默认 | id[=套接字>

SSH 代理套接字或密钥，以公开到构建中。套接字路径可以留空以使用 default=$SSH_AUTH_SOCK 的值

要稍后使用 ssh 代理，请在 Containerfile 中的 RUN 指令中使用 --mount 选项

RUN --mount=type=ssh,id=id mycmd

--stdin

将 stdin 传递到 RUN 容器。有时在 Containerfile 中运行的命令希望从用户那里请求信息。例如，apt 要求确认安装。使用 --stdin 可以在构建期间从终端进行交互。

--tag, -t=镜像名称

指定如果构建过程成功完成，将分配给结果镜像的名称。如果 镜像名称 不包含注册表名称，则将注册表名称 localhost 添加到镜像名称之前。

--target=阶段名称

设置要构建的目标构建阶段。在构建具有多个构建阶段的 Containerfile 时，可以使用 --target 通过名称指定中间构建阶段作为结果镜像的最终阶段。跳过目标阶段后的命令。

--timestamp=秒

将创建时间戳设置为自纪元以来的秒数，以允许确定性构建（默认为当前时间）。默认情况下，创建时间戳会更改并写入到镜像清单中，每次提交都会导致镜像的 sha256 哈希不同，即使源代码完全相同。当设置 --timestamp 时，创建时间戳始终设置为指定的时间，因此不会更改，从而使镜像的 sha256 哈希保持不变。提交到镜像层的​​所有文件都将使用时间戳创建。

如果 Containerfile 中唯一的指令是 FROM，则此标志无效。

--tls-verify

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

--ulimit=类型=软限制[:硬限制]

指定在处理 RUN 指令时应用于启动的进程的资源限制。此选项可以指定多次。识别的资源类型包括：“core”：最大核心转储大小（ulimit -c）“cpu”：最大 CPU 时间（ulimit -t）“data”：进程数据段的最大大小（ulimit -d）“fsize”：新文件的大小（ulimit -f）“locks”：最大文件锁数量（ulimit -x）“memlock”：最大锁定的内存量（ulimit -l）“msgqueue”：消息队列中的最大数据量（ulimit -q）“nice”：好感度调整（nice -n，ulimit -e）“nofile”：最大打开文件数量（ulimit -n）“nproc”：最大进程数量（ulimit -u）“rss”：进程的最大大小（ulimit -m）“rtprio”：最大实时调度优先级（ulimit -r）“rttime”：阻塞系统调用之间最大实时执行时间“sigpending”：最大挂起信号数（ulimit -i）“stack”：最大堆栈大小（ulimit -s）

--unsetenv=环境

从最终镜像中取消设置环境变量。

--unsetlabel=标签

取消设置镜像标签，导致标签不会从基础镜像继承。

--userns=如何

设置处理 RUN 指令时用户命名空间的配置。配置的值可以是“” (空字符串) 或 “container”，表示创建新的用户命名空间，可以是 “host”，表示重新使用运行 podman 本身的用户命名空间，或者可以是另一个进程正在使用的用户命名空间的路径。

--userns-gid-map=映射

直接指定一个 GID 映射，用于在文件系统级别上设置工作容器内容的所有权。处理 RUN 指令时运行的命令默认在它们自己的用户命名空间中运行，使用 UID 和 GID 映射进行配置。

此映射中的条目采用一个或多个三元组的形式，包含容器内 GID 的起始值、相应的宿主级别 GID 的起始值以及映射条目表示的连续 ID 数量。

此选项会覆盖 /etc/containers/storage.conf 的 options 部分中的 remap-gids 设置。

如果未指定此选项，但提供了全局 --userns-gid-map 设置，则使用全局选项中的设置。

如果未指定 --userns-uid-map-user、--userns-gid-map-group 或 --userns-gid-map，但指定了 --userns-uid-map，则 GID 映射设置为使用与 UID 映射相同的数值。

--userns-gid-map-group=组

指定一个 GID 映射，用于在文件系统级别上设置工作容器内容的所有权，可以在与指定组对应的 /etc/subgid 文件中的条目中找到。处理 RUN 指令时运行的命令默认在它们自己的用户命名空间中运行，使用 UID 和 GID 映射进行配置。如果指定了 --userns-uid-map-user，但未指定 --userns-gid-map-group，则 podman 假定指定的用户名也是适合用作此选项的默认设置的组名。

注意： 当无根用户指定此选项时，指定的映射相对于容器中的无根用户命名空间，而不是相对于宿主，就像在有根环境中运行时那样。

--userns-uid-map=映射

直接指定一个 UID 映射，用于在文件系统级别上设置工作容器内容的所有权。处理 RUN 指令时运行的命令默认在它们自己的用户命名空间中运行，使用 UID 和 GID 映射进行配置。

此映射中的条目采用一个或多个三元组的形式，包含容器内 UID 的起始值、相应的宿主级别 UID 的起始值以及映射条目表示的连续 ID 数量。

此选项会覆盖 /etc/containers/storage.conf 的 options 部分中的 remap-uids 设置。

如果未指定此选项，但提供了全局 --userns-uid-map 设置，则使用全局选项中的设置。

如果未指定 --userns-uid-map-user、--userns-gid-map-group 或 --userns-uid-map，但指定了 --userns-gid-map，则 UID 映射将设置为使用与 GID 映射相同的数值。

--userns-uid-map-user=user

指定在工作容器内容的 文件系统 级别上设置所有权的 UID 映射，可以在与指定用户相对应的 /etc/subuid 文件中的条目中找到。处理 RUN 指令时运行的命令默认在它们自己的用户命名空间中运行，使用 UID 和 GID 映射配置。如果指定了 --userns-gid-map-group，但未指定 --userns-uid-map-user，则 podman 假设指定的组名称也是一个合适的用户名，可作为此选项的默认设置使用。

注意： 当无根用户指定此选项时，指定的映射相对于容器中的无根用户命名空间，而不是相对于宿主，就像在有根环境中运行时那样。

--uts=how

在处理 RUN 指令时设置 UTS 命名空间的配置。配置的值可以是 “” （空字符串）或 “container”，表示要创建一个新的 UTS 命名空间，也可以是 “host”，表示使用 podman 本身正在运行的 UTS 命名空间，或者可以是另一个进程正在使用的 UTS 命名空间的路径。

--variant=variant

将要构建的镜像的体系结构变体以及要拉取的基础镜像的体系结构变体（如果构建使用基础镜像）设置为提供的值，而不是使用构建主机的体系结构变体。

--volume, -v=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]

在构建过程中执行 RUN 指令时，将主机目录挂载到容器中。

The OPTIONS 是一个逗号分隔的列表，可以包含以下选项之一或多个：

  • [rw|ro]

  • [z|Z|O]

  • [U]

  • [[r]shared|[r]slave|[r]private][1]

The CONTAINER-DIR 必须是绝对路径，例如 /src/docs。The HOST-DIR 也必须是绝对路径。在处理 RUN 指令时，Podman 将 HOST-DIR 绑定挂载到指定的路径。

可以指定多个 -v 选项来挂载一个或多个挂载点。

可以向卷添加 :ro 或 :rw 后缀，分别以只读或读写模式挂载卷。默认情况下，卷以读写模式挂载。请参见示例。

Chowning Volume Mounts

默认情况下，Podman 不会更改挂载的源卷目录的所有者和组。在使用用户命名空间运行时，命名空间内的 UID 和 GID 可能对应于主机上的其他 UID 和 GID。

The :U 后缀告诉 Podman 根据命名空间内的 UID 和 GID，使用正确的主机 UID 和 GID 来递归更改源卷的所有者和组。

警告 谨慎使用，因为这会修改主机文件系统。

Labeling Volume Mounts

像 SELinux 这样的标记系统要求将适当的标记放在挂载到容器中的卷内容上。没有标记，安全系统可能会阻止容器内运行的进程使用该内容。默认情况下，Podman 不会更改操作系统设置的标记。

若要更改容器上下文中的标记，请向卷挂载添加以下两个后缀之一：:z 或 :Z。这些后缀告诉 Podman 重新标记共享卷上的文件对象。The z 选项告诉 Podman 两个容器共享卷内容。因此，Podman 将使用共享内容标记标记内容。共享卷标记允许所有容器读写内容。The Z 选项告诉 Podman 使用私有未共享标记标记内容。只有当前容器可以使用私有卷。

注意：不要重新标记系统文件和目录。重新标记系统内容可能会导致主机上的其他受限制服务失败。对于这些类型的容器，建议禁用 SELinux 分离。The --security-opt label=disable 选项会为容器禁用 SELinux 分离。例如，如果用户想要将整个主目录卷挂载到构建容器中，则需要禁用 SELinux 分离。

$ podman build --security-opt label=disable -v $HOME:/home/user .

Overlay Volume Mounts

The :O 标志告诉 Podman 使用 Overlay 文件系统将主机上的目录挂载为临时存储。允许 RUN 命令容器修改挂载点内的内容，并将这些内容存储在容器存储中的一个单独目录中。在 Overlay FS 术语中，源目录是 lower，容器存储目录是 upper。对挂载点的修改在 RUN 命令完成执行后会被销毁，类似于 tmpfs 挂载点。

任何后续执行的 RUN 命令都会看到原始的源目录内容，以前 RUN 命令的任何更改都不再存在。

The overlay 挂载的一种用例是将主机上的包缓存共享到容器中，以加快构建速度。

注意

  • Overlay 挂载当前在无根模式下不受支持。

  • The O 标志不允许与 Z 或 z 标志一起指定。挂载到容器中的内容将使用私有标记标记。在 SELinux 系统上，源目录中的标记需要对容器标记可读。如果不是，则必须禁用 SELinux 容器分离才能使容器正常工作。

  • 修改使用 Overlay 挂载挂载到容器中的目录卷可能会导致意外故障。在容器完成运行之前，请勿修改该目录。

默认情况下，绑定挂载的卷是 private。这意味着在容器内完成的任何挂载在主机上都不可见，反之亦然。可以通过指定卷挂载传播属性来更改此行为。

当挂载传播策略设置为 shared 时，在容器中完成的该卷上的任何挂载都对主机和容器都可见。当挂载传播策略设置为 slave 时，将启用单向挂载传播，对主机对该卷完成的任何挂载仅在容器内可见。若要控制卷的挂载传播属性，请使用 :[r]shared、 :[r]slave 或 :[r]private 传播标志。要使挂载传播在源挂载点（源目录挂载到的挂载点）上正常工作，该挂载点必须具有正确的传播属性。对于共享卷，源挂载点必须是共享的。对于从属卷，源挂载必须是共享的或从属的。[1]

使用 df <source-dir> 确定源挂载点，然后使用 findmnt -o TARGET,PROPAGATION <source-mount-dir> 确定源挂载点的传播属性，如果 findmnt 实用程序不可用，则可以通过查看 /proc/self/mountinfo 中的挂载条目来确定源挂载点。查看 optional fields 并查看是否指定了任何传播属性。 shared:X 表示挂载点是 shared， master:X 表示挂载点是 slave，如果没有，则表示挂载点是 private。[1]

要更改挂载点的传播属性，请使用 mount 命令。例如，要绑定挂载源目录 /foo，请执行 mount --bind /foo /foo 和 mount --make-private --make-shared /foo。这会将 /foo 转换为 shared 挂载点。源挂载的传播属性可以直接更改。例如，如果 / 是 /foo 的源挂载，则使用 mount --make-shared / 将 / 转换为 shared 挂载。

示例

使用本地 Containerfile 构建镜像

使用当前目录内容的 Containerfile 构建镜像

$ podman build .

使用指定 Containerfile 和当前目录内容构建镜像

$ podman build -f Containerfile.simple .

使用来自 stdin 的 Containerfile 和当前目录内容构建镜像

$ cat $HOME/Containerfile | podman build -f - .

使用多个 Containerfile 和当前目录内容构建镜像

$ podman build -f Containerfile.simple -f Containerfile.notsosimple .

使用指定 Containerfile 和 $HOME 目录的内容构建镜像。请注意，在处理为 Containerfile 之前，cpp 应用于 Containerfile.in

$ podman build -f Containerfile.in $HOME

使用指定标签、Containerfile 和当前目录内容构建镜像

$ podman build -t imageName .

构建镜像时忽略通过 Containerfile 拉取的任何镜像的注册表验证

$ podman build --tls-verify=false -t imageName .

使用指定的日志格式构建镜像

$ podman build --runtime-flag log-format=json .

使用调试模式进行日志记录构建镜像

$ podman build --runtime-flag debug .

从选定的 Containerfile 拉取镜像时，使用指定的注册表属性构建镜像

$ podman build --authfile /tmp/auths/myauths.json --cert-dir $HOME/auth --tls-verify=true --creds=username:password -t imageName -f Containerfile.simple .

使用指定的资源控制构建镜像，这些资源控制在构建期间运行容器

$ podman build --memory 40m --cpu-period 10000 --cpu-quota 50000 --ulimit nofile=1024:1028 -t imageName .

使用指定的 SELinux 标签和 cgroup 配置构建镜像，这些配置在构建期间运行容器

$ podman build --security-opt label=level:s0:c100,c200 --cgroup-parent /path/to/cgroup/parent -t imageName .

使用从主机挂载的只读和 SELinux 重新标记卷构建镜像，这些卷在构建期间运行容器

$ podman build --volume /home/test:/myvol:ro,Z -t imageName .

使用从主机挂载的覆盖卷构建镜像，这些卷在构建期间运行容器

$ podman build -v /var/lib/yum:/var/lib/yum:O -t imageName .

使用层构建镜像，然后即使构建失败也删除中间容器。

$ podman build --layers --force-rm -t imageName .

构建镜像时忽略缓存，即使构建成功也不删除中间容器

$ podman build --no-cache --rm=false -t imageName .

在构建期间运行容器时，使用指定的网络构建镜像

$ podman build --network mynet .

使用 --manifest 选项构建多架构镜像（需要仿真软件）

使用指定的架构构建镜像，并在成功完成时链接到单个清单

$ podman build --arch arm --manifest myimage /tmp/mysrc
$ podman build --arch amd64 --manifest myimage /tmp/mysrc
$ podman build --arch s390x --manifest myimage /tmp/mysrc

类似地，使用单个命令构建

$ podman build --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest myimage /tmp/mysrc

使用多个指定的架构构建镜像，并在成功完成时链接到单个清单

$ podman build --platform linux/arm64 --platform linux/amd64 --manifest myimage /tmp/mysrc

使用 URL、Git 仓库或存档构建镜像

构建上下文目录可以指定为指向 Containerfile 的 URL、Git 仓库或指向存档的 URL。如果 URL 是 Containerfile，则将其下载到临时位置并用作上下文。当 Git 仓库被设置为 URL 时，该仓库将在本地克隆到临时位置，然后用作上下文。最后，如果 URL 是存档，则将其下载到临时位置并在用作上下文之前进行提取。

使用指向 Containerfile 的 URL 构建镜像

从下载到用作构建上下文的临时位置的 Containerfile 构建镜像

$ podman build https://10.10.10.1/podman/Containerfile

使用 Git 仓库构建镜像

Podman 将指定的 GitHub 仓库克隆到临时位置，并将其用作上下文。使用仓库根目录处的 Containerfile，并且它仅在 GitHub 仓库是专用仓库时才有效。

从下载到用作构建上下文的临时位置的指定 git 仓库构建镜像

$ podman build -t hello  https://github.com/containers/PodmanHello.git
$ podman run hello

注意：由于最近在安全指南方面做出的更改，GitHub 不支持使用 git:// 进行 clone 操作（https://github.blog/2021-09-01-improving-git-protocol-security-github/）。如果源仓库托管在 GitHub 上，请使用 https:// URL。

使用指向存档的 URL 构建镜像

Podman 获取存档文件，对其解压缩，并使用其内容作为构建上下文。存档根目录处的 Containerfile 和其余存档被用作构建的上下文。传递 -f PATH/Containerfile 选项还告诉系统在存档内容中查找该文件。

$ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz

注意：支持的压缩格式为“xz”、“bzip2”、“gzip”和“identity”（无压缩）。

文件

.containerignore/.dockerignore

如果在上下文目录中存在 .containerignore 或 .dockerignore 文件，则 podman build 会读取其内容。使用 --ignorefile 选项覆盖 .containerignore 的路径位置。Podman 使用内容从上下文目录中排除文件和目录，在 Containerfile/Dockerfile 中执行 COPY 和 ADD 指令时

.containerignore 和 .dockerignore 文件使用相同的语法；如果两者都在上下文目录中，podman build 仅使用 .containerignore。

用户可以在 .containerignore 文件中指定一系列 Unix shell 通配符来标识要排除的文件/目录。

Podman 支持特殊的通配符字符串 **，它匹配任意数量的目录（包括零个）。例如，**/*.go 排除所有在所有目录中找到的以 .go 结尾的文件。

示例 .containerignore 文件

# exclude this content for image
*/*.c
**/output*
src

*/*.c 排除所有在任何顶层子目录中以 .c 结尾的名称的文件和目录。例如，源文件 include/rootless.c。

**/output* 从任何目录中排除以 output 开头的文件和目录。

src 排除名为 src 的文件和目录，以及其中的任何内容。

以 !（感叹号）开头的行可用于对排除项进行例外处理。以下是一个使用此机制的示例 .containerignore 文件

*.doc
!Help.doc

排除所有 doc 文件，但排除 Help.doc。

此功能与此处描述的 .containerignore 文件处理兼容

https://github.com/containers/common/blob/main/docs/containerignore.5.md

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

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

故障排除

lastlog 稀疏文件

在 Containerfile 中使用 useradd 命令，并且 UID/GID 很大，会创建一个大型稀疏文件 /var/log/lastlog。这会导致构建永远挂起。Go 语言无法正确支持稀疏文件，这会导致在容器镜像中创建一些巨大的文件。

在构建脚本中使用 useradd 命令时，请向 useradd 命令传递 --no-log-init or -l 选项。此选项告诉 useradd 停止创建 lastlog 文件。

另请参阅

podman(1), buildah(1), containers-certs.d(5), containers-registries.conf(5), crun(1), runc(8), useradd(8), podman-ps(1), podman-rm(1), Containerfile(5), containerignore(5)

故障排除

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

有关无根问题的解决方案，请参阅 podman-rootless(7)。

历史

2020 年 8 月，Dan Walsh <[email protected]> 添加了其他选项和 .containerignore

2018 年 5 月，Joe Doss <[email protected]> 添加了少量修订

2017 年 12 月，最初由 Tom Sweeney <[email protected]> 编译

脚注

1: Podman 项目致力于包容性，这是开源的核心价值观。这里使用的 master 和 slave 挂载传播术语存在问题，并且具有争议性，需要更改。但是，这些术语目前在 Linux 内核中使用，必须按现状使用。当内核维护者纠正这种用法时，Podman 将立即效仿。