使用 Containerfile 构建容器镜像

概述

podman build [选项][*上下文目录*]

podman image build [选项][*上下文目录*]

描述

podman build 命令使用来自一个或多个 Containerfile 或 Dockerfile 的指令，以及指定的构建上下文目录来构建镜像。Containerfile 在内部使用与 Dockerfile 相同的语法。在本文档中，提到的 Containerfile 可以是名为 'Containerfile' 或 'Dockerfile' 的文件。

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

当使用 -f 选项和 Containerfile 的路径，但没有明确指定 CONTEXT 目录时，Podman 会使用 Containerfile 的父目录作为其构建上下文。

以 ".in" 后缀结尾的 Containerfile 会通过 CPP(1) 进行预处理。这有助于将 Containerfile 分解为多个可重用的部分，可以通过 CPP 的 #include 指令使用它们。以 .in 结尾的 Containerfile 限制为不能有注释行，除非它们是 CPP 命令。 注意，Containerfile.in 文件仍然可以通过其他工具进行手动预处理，例如使用 cpp -E。

当 URL 是存档时，URL 的内容将被下载到临时位置并在执行前进行解压。

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

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

注意：podman build 使用从 Buildah 项目中获取的代码来构建容器镜像。这个 Buildah 代码在容器存储中为 RUN 选项创建 Buildah 容器。在某些情况下，当 podman build 崩溃或用户杀死 podman build 进程时，这些外部容器可能会留在容器存储中。可以使用 podman ps --all --storage 命令来查看这些容器。外部容器可以使用 podman rm --storage 命令进行删除。

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

选项

@@option add-host

--all-platforms

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

@@option annotation.image

--arch=arch

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

@@option authfile

@@option build-arg

@@option build-arg-file

@@option build-context

@@option cache-from

@@option cache-to

@@option cache-ttl

@@option cap-add.image

@@option cap-drop.image

@@option cert-dir

@@option cgroup-parent

@@option cgroupns.image

这些选项是用于 podman build 命令的各种参数，用于控制构建过程的不同方面。具体每个选项的详细解释和用法可以参考 podman build 的官方文档或通过命令行使用 --help 参数查看。请注意，这些选项的具体可用性和行为可能会因 Podman 版本的不同而有所变化。

--compress

此选项添加的目的是与其他容器命令行界面保持一致。但 Podman 不与守护进程或远程服务器通信，因此在发送数据之前对其进行压缩对于 Podman 来说是无关紧要的。（此选项在远程 Podman 客户端中不可用，包括 Mac 和 Windows（排除 WSL2）机器）

@@option cpp-flag

用于指定 C++ 编译器的标志。这允许用户为构建过程中的 C++ 源代码指定特定的编译选项。

@@option cpu-period

设置 CPU CFS 周期，这是 CPU 限制的基础。它必须与 --cpu-quota 一起使用。

@@option cpu-quota

为每个 CPU 时间片设置 CPU CFS quota，这限制了容器可以使用的 CPU 时间。必须与 --cpu-period 一起使用。

@@option cpu-shares

设置 CPU 使用权重。默认值为 1024。这可以是一个相对值（基于 1024），或者可以是绝对值（如 2048）。

@@option cpuset-cpus

指定容器可以使用的 CPU 集合。例如：0-3,0,1。

@@option cpuset-mems

指定容器可以使用的内存节点集合。

@@option creds

指定凭据的路径，用于访问私有仓库。这可以是包含认证信息的文件路径。

这些选项提供了对构建过程的更细粒度的控制，允许用户根据需求定制构建过程。请注意，具体选项的可用性和行为可能会因 Podman 版本的不同而有所变化。在使用这些选项时，建议查阅 Podman 的官方文档或运行 podman build --help 以获取最新的选项信息和用法说明。

--cw=options

使用 --cw 选项可以生成一个适合在受信任的执行环境（TEE）中作为机密工作负载运行的镜像，该环境使用 krun（即，带有 libkrun 功能并作为 krun 调用的 crun）。与常规内容不同，镜像的根文件系统将包含一个加密的磁盘映像和 krun 的配置信息。

options 的值是一个由逗号分隔的键值对列表，用于提供生成将包含在容器镜像中的附加数据所需的配置信息。

被识别的 键 包括：

• attestation_url：密钥代理/证明服务器的位置。如果指定了值，新镜像的工作负载 ID 以及用于加密磁盘映像的密码短语将被注册到服务器，并且服务器的位置将被存储在容器镜像中。在运行时，krun 预期将使用存储在容器镜像中的工作负载 ID 从服务器检索密码短语。如果没有指定值，则 必须 指定一个 passphrase 值。

• cpus：镜像期望在运行时运行的虚拟 CPU 数量。如果没有指定，将提供一个默认值。

• firmware_library：libkrunfw-sev 共享库的位置。如果没有指定，buildah 将在多个硬编码位置中检查其是否存在。

这个选项允许用户为机密工作负载生成定制化的镜像，以在受信任的执行环境中运行，并提供了额外的安全性和隔离性。请注意，使用这些高级功能需要对相关的技术和配置有深入的了解。在使用 --cw 选项时，建议查阅 Podman 和相关组件的官方文档以获取详细的说明和最佳实践。

memory：在运行时，镜像期望运行的内存量，以兆字节为单位。如果没有指定，将提供一个默认值。

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

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

type：镜像应标记为用于的受信任执行环境（TEE）的类型。接受的值是 "SEV"（AMD Secure Encrypted Virtualization - Encrypted State）和 "SNP"（AMD Secure Encrypted Virtualization - Secure Nested Paging）。如果没有指定，则默认为 "SNP"。

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

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

@@option decryption-key

指定用于解密私有仓库中镜像的密钥。

@@option device

注意：如果用户仅通过组访问权限访问设备，则在无根容器中访问设备会失败。crun(1) 运行时提供了一个解决此问题的选项（通过添加相应的选项）。 --annotation run.oci.keep_original_groups=1

此选项用于在构建镜像时，保留原始的用户组信息。当容器运行时，通常只保留容器内的用户的主组，但使用此选项可以确保其他组信息也被保留。这对于需要特定组权限的应用程序可能很有用。

@@option disable-compression

此选项用于禁用构建过程中的压缩。默认情况下，buildah 会压缩构建的层以减少镜像的大小。但有时为了调试或特殊需求，你可能希望禁用压缩。

@@option disable-content-trust

此选项用于禁用内容信任检查。内容信任是 Docker 提供的一种安全特性，用于确保镜像的完整性和来源。但在某些情况下，你可能希望禁用此检查。

@@option dns

设置构建过程中使用的 DNS 服务器。这仅影响构建过程中的 RUN 指令，不影响最终镜像中的 /etc/resolv.conf。

注意：此选项不能与设置为 none 的 --network 选项一起使用。

@@option dns-option.image

为最终镜像设置 DNS 选项。

@@option dns-search.image

为最终镜像设置 DNS 搜索域。

@@option env.image

设置最终镜像的环境变量。

@@option file

指定包含构建指令的 Dockerfile 的路径。

@@option force-rm

在构建过程中强制删除中间容器。这有助于清理构建过程中产生的临时容器，但可能会在某些情况下导致数据丢失。

@@option format

指定输出镜像的格式，如 docker、oci 等。

@@option from

指定基础镜像，即构建新镜像所依赖的镜像。

@@option group-add

将指定的一个或多个组添加到容器内的用户中。这对于需要特定组权限的应用程序可能很有用。

@@option help

显示帮助信息。

@@option hooks-dir

指定包含容器生命周期钩子脚本的目录。这些钩子可以在容器的不同生命周期阶段执行自定义操作。

@@option http-proxy

设置用于构建过程中的 HTTP 代理。

@@option identity-label

为构建过程添加标签，以标识构建的身份或来源。

@@option ignorefile

指定一个文件，其中包含应从构建上下文中排除的文件或目录的模式。

@@option iidfile

将镜像的完整 ID 写入指定的文件。这对于需要精确引用镜像 ID 的脚本或工具可能很有用。

@@option ipc.image

设置最终镜像的 IPC（进程间通信）模式。

@@option isolation

设置容器运行时使用的隔离技术，如 default、chroot、namespace 等。

@@option jobs

并行构建镜像的作业数。这可以加快构建速度，但也可能增加资源消耗。

@@option label.image

为最终镜像设置标签。

@@option layer-label

为构建过程中的每一层设置标签。

@@option layers

控制是否将构建的输出格式化为单独的层。这对于分析和调试可能很有用。

@@option logfile

将构建日志写入指定的文件。这对于保留构建历史或进行后续分析可能很有用。

--logsplit=bool-value

当同时指定了 --logfile 和 --platform 时，--logsplit 选项允许最终用户将每个平台的日志文件拆分为不同的文件。拆分后的文件命名格式如下：${logfile}_${platform-os}_${platform-arch}。这对于跨多个平台构建镜像并希望将日志分开保存的情况非常有用。

注意：此选项在远程客户端上不受支持，包括 Mac 和 Windows（排除 WSL2）机器。

其他选项

@@option manifest

设置镜像的清单。

@@option memory

设置构建容器可以使用的内存限制。

@@option memory-swap

设置构建容器的内存和交换空间限制的总和。

@@option network.image

设置最终镜像的网络配置。

@@option no-cache

构建时不使用缓存。这可以确保每次构建都是从基础镜像开始的全新构建。

@@option no-hostname

构建时不设置容器的主机名。

@@option no-hosts

构建时不从宿主机的 /etc/hosts 文件中读取主机名映射。

注意：此选项与 --add-host 冲突。

@@option omit-history

在输出镜像时省略历史记录。这可以减小镜像的大小，但也会丢失构建历史信息。

@@option os

设置构建时使用的操作系统。

@@option os-feature

设置构建时需要的操作系统特性。

@@option os-version.image

设置最终镜像的操作系统版本。

--output, -o=output-opts

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

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

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

支持的 键 包括：

--output, -o=output-opts

输出目标（格式：type=类型,dest=目标路径）

--output（或 -o）选项扩展了构建容器镜像的默认行为。通过此选项，用户可以将镜像的内容导出为本地文件系统中的文件，这对于生成本地二进制文件、代码生成等场景非常有用。

--output 的值是一个由逗号分隔的键值对序列，其中每个键值对定义了一个输出选项。支持的键包括：

• dest：导出输出的目标路径。有效值可以是绝对路径或相对路径。如果设置为 -，则输出将发送到标准输出。
• type：定义要使用的输出类型。有效值如下文所述。

有效的 type 值包括：

• local：将构建结果文件写入客户端本地的一个目录。
• tar：将结果文件打包为一个单独的 tar 包（.tar）。

如果未指定类型，则默认值为 local。

另外，--output 的值也可以仅指定一个目标路径（以 dest 格式），例如 --output some-path 或 --output -。在这种情况下，--output some-path 等同于指定 type=local，而 --output - 等同于指定 type=tar。

使用 --output 选项时，可以灵活地控制构建输出的格式和位置，以满足不同的使用场景。

--pid.image

此选项用于设置镜像的 PID 命名空间配置。PID 命名空间允许容器进程看到一组独特的 PID，这对于隔离和管理容器进程非常重要。通过指定 --pid.image，您可以控制镜像的 PID 命名空间行为。

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

设置构建镜像的 os/arch（操作系统/架构），以及（如果使用基础镜像时）基础镜像的 os/arch。这允许您指定与当前主机的操作系统和架构不同的值，以便跨平台构建镜像。例如，您可以在 x86_64 架构的机器上构建针对 ARM 架构的镜像（如 linux/arm）。

除非被覆盖，后续在本地存储中查找相同的镜像时，将匹配此平台，而不管主机的平台如何。

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

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

os/arch 对应与 Go 编程语言中使用的那些。在某些情况下，arch 值可能与其他工具（如 arch 命令）产生的值不同。有效的操作系统和架构名称组合可以在 Go 的官方文档中找到，具体为 $GOOS 和 $GOARCH 的值，位于 https://golang.org/doc/install/source#environment。您也可以通过运行 go tool dist list 来获取这些值。 podman build 命令能够使用基础镜像并为任何存在的平台构建镜像。RUN 指令可以在没有像 qemu-user-static 这样的包提供的仿真帮助的情况下成功执行。

以下是一些 podman build 的其他选项说明：

--pull.image=policy

拉取镜像的策略。默认值为 missing，表示仅当本地缺少镜像时才拉取。

--quiet

静默模式，减少输出信息。

--retry

构建失败时重试。

--retry-delay

在重试之前等待的时间间隔。

--rm

构建完成后移除中间容器。

--runtime

指定用于构建操作的容器运行时。

--runtime-flag

向容器运行时传递额外的标志。

--sbom=preset

为输出镜像生成 SBOMs（软件物料清单）。这通过扫描工作容器和构建上下文并使用指定的扫描器镜像、扫描器命令和合并策略来完成。必须与 --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 生成，而无需了解底层扫描器的详细配置。用户可以根据需要选择预设，也可以自定义扫描器镜像、命令和合并策略来生成 SBOMs。

--sbom-image-output=path

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

--sbom-image-purl-output=path

当生成 SBOMs 时，扫描它们以获取 PURL（package URL）信息，并将找到的 PURL 列表保存到输出镜像中的指定路径。没有默认值。

--sbom-merge-strategy=method

如果使用了多个 --sbom-scanner-command 值，则使用指定的方法将后续命令的输出与早期命令的输出合并。识别的值包括：

-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

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

--sbom-purl-output=file

当生成 SBOMs 时，扫描它们以获取 PURL（package URL）信息，并将找到的 PURL 列表保存到本地文件系统中的指定文件中。没有默认值。

--sbom-scanner-command=image

通过在扫描器镜像中运行指定的命令来生成 SBOMs（软件物料清单）。如果指定了多个命令，它们将按照指定的顺序运行。这些文本替换将被执行： {ROOTFS} 构建镜像文件系统的根目录，被绑定挂载。 {CONTEXT} 构建上下文和其他构建上下文，被绑定挂载。 {OUTPUT} 临时输出文件的名称，用于读取并与其他文件合并或复制到其他地方。

--sbom-scanner-image=image

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

@@option secret.image

@@option security-opt.image

@@option shm-size

--sign-by=fingerprint

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

@@option skip-unused-stages

@@option squash

@@option squash-all

@@option ssh

--ssh

启用 SSH 支持，以便在构建过程中通过 SSH 访问私有仓库或其他资源。通常与 --ssh-default-id 或 --ssh-identity 选项一起使用，以指定用于 SSH 连接的私钥。

这些选项提供了在构建镜像时更高级和灵活的控制，可以根据需要进行组合和配置。注意，某些选项可能不适用于所有类型的构建或所有环境。在使用这些选项时，请确保理解它们的作用和可能的影响。

--stdin

将标准输入（stdin）传递给 RUN 容器。有时，在 Containerfile 中运行的命令需要从用户那里请求信息。例如，apt 安装过程中可能需要用户确认。使用 --stdin 可以在构建过程中从终端进行交互。

@@option tag

@@option target

@@option timestamp

@@option tls-verify

@@option ulimit.image

@@option unsetenv.image

@@option unsetlabel

@@option userns.image

@@option userns-gid-map

@@option userns-gid-map-group

@@option userns-uid-map

@@option userns-uid-map-user

@@option uts

--variant=variant

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

@@option volume.image

示例

使用本地 Containerfiles 构建镜像

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

podman build .

使用指定名称的 Containerfile 和当前目录下的内容构建镜像：

podman build -f Containerfile.simple .

使用从标准输入（stdin）传入的 Containerfile 和当前目录下的内容构建镜像：

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

使用多个 Containerfiles 和当前目录下的内容构建镜像：

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

使用指定目录（如 $HOME）下的 Containerfile 构建镜像。注意 cpp 会在处理前应用于 Containerfile.in，作为 Containerfile：

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 配置运行容器来构建镜像

在构建过程中，使用指定的 SELinux 标签和 cgroup 父目录来运行容器，并构建镜像：

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

在构建过程中，将主机上的只读和 SELinux 重新标记的卷挂载到正在运行的容器中，并构建镜像

在构建过程中，将主机上的指定目录以只读方式挂载到容器中，并应用 SELinux 重新标记，然后构建镜像：

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

在构建过程中，将主机上的 overlay 卷挂载到正在运行的容器中，并构建镜像

在构建过程中，将主机上的目录以 overlay 方式挂载到容器中，并构建镜像：

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 命令可以为多个指定架构构建镜像，并在成功完成后将它们链接到单个清单中：

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

在这个命令中，--platform 选项后面跟着的是要用于构建镜像的多个架构的列表，用逗号分隔。/tmp/mysrc 是包含构建指令的目录或文件路径。构建完成后，所有的镜像都会被链接到名为 myimage 的单个清单中。

在上述示例中，/tmp/mysrc 应包含用于构建镜像的 Containerfile 或其他构建指令。每次构建时都会为不同的架构生成一个镜像，并使用 --manifest 选项将它们链接到名为 myimage 的清单中。这样，你就可以得到一个包含多个架构镜像的清单，以便在不同的平台上使用。

使用多个指定架构构建镜像，并链接到单个清单

你还可以为多个指定的架构分别指定 --platform 选项，并使用 --manifest 选项将它们链接到同一个清单：

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

在这个例子中，podman 会为 linux/arm64 和 linux/amd64 这两个架构分别构建镜像，并将它们链接到名为 myimage 的清单中。同样，/tmp/mysrc 应该包含用于构建镜像的 Containerfile 或其他构建指令。

请注意，为了成功构建多架构镜像，你需要确保你的构建环境支持所有指定的架构，并且已经安装了必要的仿真软件或交叉编译工具链。在某些情况下，你可能需要在特定的硬件架构上执行构建，或者使用能够模拟这些架构的容器或虚拟机。

使用 URL、Git 仓库或归档文件构建镜像

构建上下文目录可以指定为一个指向 Containerfile 的 URL、Git 仓库或归档文件的 URL。如果 URL 是 Containerfile，它会被下载到一个临时位置并用作构建上下文。当 URL 设置为 Git 仓库时，仓库会被克隆到本地临时位置，然后用作构建上下文。最后，如果 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 最近的安全指南变更GitHub 不再支持使用 git:// 进行 clone 操作。如果源仓库托管在 GitHub 上，请使用 https:// URL。

使用指向归档文件的 URL 构建镜像

Podman 会获取归档文件，解压它，并使用其内容作为构建上下文。归档文件根目录下的 Containerfile 和归档文件的其余部分都被用作构建的上下文。通过传递 -f PATH/Containerfile 选项，可以告诉 Podman 在归档文件的内容中查找该文件。

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 文件：

# 排除这些内容以构建镜像
*/*.c
**/output*
src

解释：

*/*.c 排除所有以 .c 结尾的文件和目录，这些文件和目录位于任何顶级子目录中。例如，源文件 include/rootless.c。

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

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

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

*.doc
!Help.doc

从镜像中排除所有 .doc 文件，但保留 Help.doc。

这一功能兼容这里描述的 .containerignore 文件的处理方式：

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

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

registries.conf 是配置文件，用于指定在补全不包含注册表或域名部分的镜像名称时应该咨询的容器注册表。通过编辑这个文件，用户可以添加或删除特定的镜像仓库地址，从而定制 Podman 在构建、运行或推送镜像时所使用的镜像仓库列表。此外，这个文件还可以用于设置认证信息，以便在需要时自动登录到私有仓库。在构建镜像时，如果镜像名称中没有明确指定仓库地址，Podman 就会按照 registries.conf 中定义的顺序去查找和拉取所需的镜像层。

故障排查

lastlog 稀疏文件

在 Containerfile 中使用 useradd 命令时，如果指定了一个较大的 UID/GID，则会在 /var/log/lastlog 中创建一个大型的稀疏文件。这可能导致构建过程无限期地挂起。Go 语言对稀疏文件的支持存在问题，这可能导致在容器镜像中创建一些巨大的文件。

当在构建脚本中使用 useradd 命令时，应传递 --no-log-init 或 -l 选项给 useradd 命令。这个选项告诉 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)

历史

-2020年8月，Dan Walsh <dwalsh@redhat.com> 添加了额外的选项和 .containerignore 功能。 -2018年5月，Joe Doss <joe@solidadmin.com> 进行了小幅修订。 -2017年12月，最初由 Tom Sweeney <tsweeney@redhat.com> 整理。

脚注

Podman 项目致力于包容性，这是开源的核心价值之一。这里使用的“master”和“slave”挂载传播术语是有问题的，具有分裂性，需要改变。然而，这些术语目前仍被 Linux 内核使用，并且在此刻必须保持不变。当内核维护者纠正这种用法时，Podman 将立即跟进。