跳到主要内容

在Farm节点上构建镜像

podman-farm-build 是一个命令，用于在Farm节点上构建镜像，并将它们捆绑成一个清单列表（manifest list）。这允许你生成包含多种原生架构镜像的单一清单，从而可以更容易地管理和分发多架构的容器镜像。

以下是关于 podman-farm-build 命令的详细解释：

SYNOPSIS（概要）​

podman farm build [options] [context]

DESCRIPTION（描述）​

Podman 通过读写位于XDG_CONFIG_HOME/containers下的podman-connections.json文件来管理 farm，如果未设置 env，则默认为HOME/.config/containers。 或者可以将PODMAN_CONNECTIONS_CONF环境变量设置为 podman 将使用的一个完整文件路径。此文件由 podman 命令管理，用户切勿直接编辑。要手动配置 farm，请使用containers.conf中的[farm]部分。podman farm build 命令在Farm中的所有节点上构建镜像，并将它们捆绑成一个清单列表。它使用给定的 Containerfile（类似于 Dockerfile，但用于 Podman）在Farm节点上执行 podman build 命令。一旦所有Farm节点上的镜像构建完成，这些镜像将被推送到通过 --tag 标志指定的注册表。当所有镜像都推送完毕后，将在本地创建一个清单列表，并将其也推送到注册表。

这个清单列表将包含Farm中存在的每种原生架构类型的镜像。这意味着，如果你有 ARM 和 x86_64 架构的节点，清单列表将包含针对这两种架构的镜像。

这个命令的主要功能是创建多架构构建，这比使用 podman build --arch --platform 通过仿真进行构建要快得多。

如果没有指定Farm，则构建任务将被发送到 podman 系统连接知道的所有节点。

注意：由于构建的镜像直接推送到注册表，因此用户必须使用 --tag 选项传递完整的镜像名称，格式为 registry/repository/imageName[:tag]。

这个命令对于需要在多种硬件架构上运行相同容器应用的情况非常有用，例如同时运行在 ARM 和 x86_64 服务器上。通过使用 podman-farm-build，你可以一次性构建和分发多架构的容器镜像，而无需分别为每种架构执行构建。

这些选项都是与容器构建和运行相关的配置参数，特别是在使用 Podman 或类似的容器工具时。我将为你解释这些选项的含义：

--add-host：在容器的 hosts 文件中添加自定义的主机名到 IP 地址的映射​

--annotation.image：为构建的镜像添加注解。注解通常用于为镜像提供元数据​

--authfile：指定认证文件的路径，用于访问私有仓库​

--build-arg：设置构建时的变量，这些变量可以在 Dockerfile 中通过 ARG 指令引用​

--build-arg-file：从一个文件中读取构建参数​

--build-context：指定构建上下文的位置，这通常是包含 Dockerfile 和其他构建文件的目录或压缩包​

--cache-from：指定一个或多个镜像，用于缓存已存在的层，以加速构建过程​

--cache-to：指定构建缓存的输出位置，通常用于将缓存导出到外部存储​

--cache-ttl：设置缓存的有效期​

--cap-add.image：为容器添加 Linux 功能（capabilities）​

--cap-drop.image：从容器中移除 Linux 功能（capabilities）​

--cert-dir：指定证书目录的路径，用于 TLS 验证​

--cgroup-parent：为容器设置 cgroup 的父组​

--cgroupns.image：为容器配置 cgroup 命名空间​

这些选项允许用户更精细地控制容器的构建和运行过程，以满足特定的需求和安全要求。具体的使用方法和参数值会根据 Podman 或其他容器工具的版本和配置有所不同，因此建议查阅相关文档以获取更详细的信息。

这些选项都是 Podman 或其他容器构建和运行工具中的参数，用于控制容器镜像的构建和容器的运行。我将为你解释这些选项的含义：

--cleanup​

这个选项用于指定在构建成功后是否从Farm节点（farm nodes）中删除构建的镜像。默认值是 false，意味着如果不设置这个选项或设置为 false，则构建的镜像会保留在Farm节点上。设置为 true 时，成功构建的镜像会被清理掉。

--cpp-flag​

这个选项允许用户为 C++ 编译器设置标志。通常用于在构建过程中为 C++ 代码指定编译选项。

--cpu-period​

这个选项用于设置 CPU 的周期，用于限制容器可以使用的 CPU 时间。它必须与 --cpu-quota 一起使用，以指定容器在每个周期中可以使用的 CPU 时间量。

--cpu-quota​

这个选项用于设置容器在每个 CPU 周期中可以使用的 CPU 时间量。它必须与 --cpu-period 一起使用。

--cpu-shares​

这个选项用于设置 CPU 的共享权重。当系统中有多个容器争用 CPU 时，这个值用于决定每个容器相对应获得的 CPU 时间片大小。值越高，容器获得的 CPU 时间就越多（相对于其他容器）。

--cpuset-cpus​

这个选项允许用户限制容器可以使用的 CPU 核心。例如，可以设置为 0-3 来限制容器只能在 CPU 的前四个核心上运行。

--cpuset-mems​

这个选项允许用户限制容器可以使用的内存节点。这在具有 NUMA（非统一内存访问）架构的系统上特别有用，可以帮助优化内存访问性能。

--creds​

这个选项用于指定认证信息，通常用于访问私有容器仓库。它可能是一个包含用户名和密码的文件路径。

--decryption-key​

这个选项用于指定解密密钥，用于解密构建上下文或镜像层中的加密数据。

--device​

这个选项用于将宿主机上的设备映射到容器中。它允许容器访问宿主机上的设备，这对于某些需要直接访问硬件的应用程序非常有用。

这些选项提供了对容器构建和运行的精细控制，可以根据具体的场景和需求进行配置。请注意，具体的选项名称和用法可能会因工具版本和配置的不同而有所差异，因此建议查阅相关工具的官方文档以获取最准确的信息。

注意：如果用户仅通过组拥有访问权限，则在无根容器中从内部访问设备会失败。 crun(1) 运行时提供了一个解决方法，通过添加选项

--annotation run.oci.keep_original_groups=1​

## --disable-compression​

这个选项用于禁用构建过程中的压缩功能。当设置为 true 或启用时，构建过程中将不会压缩某些数据，这可能会增加构建过程中的磁盘和网络I/O，但可能有助于调试或解决某些与压缩相关的问题。

## --dns​

--dns 选项不能与设置为 none 的 ## --network 选项同时使用，因为当网络被设置为无连接时，指定 DNS 服务器是没有意义的。此外，## --dns 选项仅在 Dockerfile 中的 RUN 指令执行时生效，用于构建过程中需要网络访问的操作的域名解析。然而，这个设置并不会影响最终构建的镜像中的 /etc/resolv.conf 文件，即生成的镜像本身不会包含这些 DNS 设置。因此，若想在容器运行时使用特定的 DNS 设置，需要在启动容器时再次指定这些设置​

这个选项用于设置容器使用的 DNS 服务器地址。这可以是一个或多个 IP 地址，容器在解析域名时将使用这些地址作为 DNS 查询的上游服务器。这有助于容器在需要网络访问时解析域名。此选项通常用于覆盖默认 DNS 设置或添加额外的 DNS 服务器。

需要注意的是，## --dns 选项通常只在容器的运行时配置中有效，而不是在构建镜像时。它影响的是容器运行时的网络配置，而不是构建过程中生成的镜像内容。这意味着如果你使用 ## --dns 选项启动一个容器，这个容器的 DNS 设置会按照你的指定进行，但这个设置不会保存在构建的镜像中，下次使用该镜像启动新容器时，除非你再次指定 ## --dns，否则容器将使用默认的 DNS 配置。

如果你需要在镜像中永久设置 DNS 配置，你需要在 Dockerfile 中使用适当的指令来修改镜像的网络配置，或者在容器启动脚本中设置环境变量（如 NAMESERVER）并在容器内部解析 DNS 时使用这些变量。

--dns-option.image

这个选项允许用户为镜像设置 DNS 选项。DNS 选项是附加到 DNS 查询的修饰符，可以影响 DNS 查询的行为。例如，你可以使用它来设置 EDNS0（扩展 DNS 0）选项或更改查询超时时间。这些选项是在构建镜像时设置的，并可能影响镜像中应用程序的 DNS 解析行为。

--dns-search.image

这个选项用于为镜像设置 DNS 搜索域。DNS 搜索域是当解析一个非完全限定域名（即没有包含点号的域名）时，系统附加到该域名以尝试解析的域后缀列表。通过设置这个选项，你可以为容器内的应用程序提供默认的域名搜索路径，从而简化域名解析过程。

--env.image

这个选项允许用户为镜像设置环境变量。环境变量是在容器运行时传递给应用程序的键值对，它们可以影响应用程序的行为。通过在构建镜像时设置环境变量，你可以确保容器在启动时具有必要的配置信息，或者为应用程序提供必要的运行时参数。

--farm

这个选项通常与分布式构建系统相关，如 Buildah 的Farm（farm）功能。Farm功能允许用户将构建任务分发到多个节点上并行执行，以加速构建过程。使用 --farm 选项时，通常需要指定Farm服务器的地址和相关的认证信息，以便将构建任务发送到Farm并执行。这可以帮助提高构建效率，特别是在构建大型或复杂的镜像时。

请注意，这些选项的具体语法和用法可能会因使用的容器构建工具或版本的不同而有所差异。因此，建议查阅相关工具的官方文档以获取最准确的信息和用法示例。

这些选项都是与 podman-farm-build 命令相关的，用于在构建镜像时指定各种参数。下面是这些选项的简要说明：

--farm 指定要用于构建过程的Farm名称。

--file 指定包含构建指令的文件路径，类似于 Dockerfile 或 Containerfile。

--force-rm 在构建完成后强制删除中间容器。

--format 指定输出格式。

--from 设置基础镜像。

--group-add 向容器内添加额外的组。

--help 显示帮助信息。

--hooks-dir 指定包含构建钩子脚本的目录。

--http-proxy 设置用于构建过程的 HTTP 代理。

--identity-label 为构建的镜像设置标识标签。

--ignorefile 指定要忽略的文件或目录列表。

--iidfile 将镜像的镜像 ID 写入指定的文件。

--ipc.image 设置容器的 IPC 模式。

--isolation 设置容器的隔离技术。

--jobs 指定用于构建的并行作业数。

--label.image 为构建的镜像设置标签。

--layer-label 为构建的镜像的每一层设置标签。

--layers 指定构建时使用的层缓存策略。

--local, -l 除了在Farm节点上构建镜像外，还在本地机器上构建。

--logfile 指定构建过程的日志文件路径。

--memory 设置容器的内存限制。

--memory-swap 设置容器的内存加交换空间限制。

--network.image 设置容器的网络配置。

--no-cache 不使用构建缓存。

--no-hostname 不设置容器的主机名。

--no-hosts 不创建 /etc/hosts 文件。这与 --add-host 选项冲突。

--omit-history 在构建镜像时省略历史记录。

--os-feature, --os-version.image 设置与操作系统相关的功能或版本。

--pid.image 设置容器的 PID 命名空间模式。

--platforms 仅在与给定平台匹配的Farm节点上构建。

--pull.image 在构建前始终尝试拉取基础镜像。

--quiet 减少输出信息。

--retry, --retry-delay 设置构建失败时的重试次数和延迟。

--rm 构建完成后删除中间容器。

--runtime, --runtime-flag 设置容器的运行时及其标志。

--sbom 及相关的 sbom 选项 与软件物料清单（SBOM）生成相关的选项。

--secret.image 为容器设置秘密。

--security-opt.image 设置容器的安全选项。

--shm-size 设置容器的共享内存大小。

--skip-unused-stages 跳过未使用的构建阶段。

--squash, --squash-all 压缩镜像层。

--ssh 通过 SSH 连接进行构建。

--tag 为构建的镜像指定标签（包括仓库、名称和标签）。

--target 指定构建的多阶段 Dockerfile 中的目标构建阶段。

--timestamp 设置镜像的时间戳。

--tls-verify 验证 TLS 证书。

--ulimit.image 设置容器的 ulimit（用户限制）。

--unsetenv.image 在容器中取消设置环境变量。

--unsetlabel 取消设置镜像的标签。

--userns.image​

这个选项用于设置容器镜像的用户命名空间模式。它决定了容器内用户和组ID如何映射到宿主机上的用户和组ID。

--userns-gid-map​

这个选项用于设置全局组ID映射。它允许你指定一个或多个从容器内组ID到宿主机组ID的映射规则。格式通常是 container-id:host-id:size，其中 container-id 是容器内的组ID，host-id 是宿主机上的组ID，size 是映射的范围大小。

--userns-gid-map-group​

这个选项可能用于指定与组ID映射相关的组名或其他属性。具体用法可能依赖于 podman 的版本和配置。

--userns-uid-map​

这个选项用于设置全局用户ID映射。它允许你指定一个或多个从容器内用户ID到宿主机用户ID的映射规则。格式与 --userns-gid-map 类似，也是 container-id:host-id:size。

--userns-uid-map-user​

这个选项可能用于指定与用户ID映射相关的用户名或其他属性。具体用法可能依赖于 podman 的版本和配置。

--uts 设置容器的 UTS 命名空间模式。

--volume.image 设置容器的卷挂载。

通过正确配置这些选项，你可以确保容器内的进程以期望的用户和组身份运行，同时避免潜在的安全风险，比如容器内的进程获得不必要的宿主机权限。 需要注意的是，这些选项的具体行为和可用性可能因 podman 的版本和配置而异。在使用这些选项时，建议查阅最新的 podman 文档或帮助信息以获取最准确的信息。这些选项提供了构建镜像时的各种定制和配置功能，可以根据需要组合使用。具体的使用方法和效果可以参考 podman-farm-build 的官方文档或帮助信息。

示例 (EXAMPLES)​

使用默认的Farm和指定的 Containerfile 构建名为 name 的镜像和清单列表：

podman farm build --local -t name -f /path/to/containerfile .

使用指定的Farm构建名为 name 的镜像和清单列表：

podman farm build --farm myfarm -t name .

使用指定的Farm构建名为 name 的镜像和清单列表，并在推送到仓库后将Farm节点上的所有镜像删除：

podman farm build --farm myfarm --cleanup -t name .

使用默认Farm为指定的平台构建名为 name 的镜像和清单列表：

podman farm build --platforms arm64,amd64 -t name .

参见 (SEE ALSO)​

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

历史​

2023年9月，由Urvashi Mohnani最初整理。

后记​

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