名称

podman-farm-build - 在 farm 节点上构建镜像,然后将它们捆绑到一个清单列表中

概要

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

描述

podman farm build 在 farm 中的所有节点上构建镜像,并将它们捆绑到一个清单列表中。它使用给定的 Containerfile 在 farm 中的节点上执行 podman build 命令。镜像在 farm 中所有节点上构建完成后,这些镜像将被推送到通过 --tag 标记指定的注册表。所有镜像都推送后,将在本地创建一个清单列表并将其推送到注册表。

清单列表将包含 farm 中存在的每个原生架构类型的镜像。

此命令的主要功能是创建多架构构建,这将比使用 podman build --arch --platform 通过模拟进行构建速度更快。

如果未指定 farm,构建将发送到 podman system connection 已知的​​所有节点。

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

选项

--add-host=hostname[;hostname[;…]]: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.internalhost.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 配置来配置不同的基础文件。

--annotation=annotation=value

向镜像元数据添加镜像 annotation(例如 annotation=value)。可以多次使用。

注意:此信息在 Docker 镜像格式中不存在,因此在 Docker 格式中写入镜像时会被丢弃。

--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 来完成。

--build-arg=arg=value

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

--build-arg-file=path

指定一个包含形式为 arg=value 的构建参数行的文件。建议的文件名为 argfile.conf

# 开头的注释行以及空白行将被忽略。所有其他行必须采用传递给 --build-argarg=value 格式。

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

--build-arg 选项提供的参数之前,会读取 --build-arg-file 选项中提供的任何文件。

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

--build-context=name=value

使用其简短名称及其位置指定额外的构建上下文。可以以与访问 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] 

[name] 的值将按以下优先级顺序匹配

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

  • 使用 AS [name] 在 Containerfile 内部定义的阶段

  • 镜像 [name],本地或在远程注册表中

--cache-from=image

用作潜在缓存源的存储库。当指定时,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=image

设置此标志以指定用于存储缓存镜像的远程存储库。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 的 cgroup 的路径。如果路径不是绝对路径,则该路径被视为相对于 init 进程的 cgroup 路径。如果 cgroup 不存在,则会创建 cgroup。

--cgroupns=how

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

--cleanup

在成功后从农场节点中删除构建的镜像(默认:false)。

--compat-volumes

处理使用 VOLUME 指令标记的目录(在本构建中以及从基础镜像继承的目录),以使它们的內容只能通过 ADD 和 COPY 指令修改。RUN 指令在这些位置进行的任何更改都将被恢复。在引入此选项之前,此行为是默认行为,但现在默认情况下已禁用。

--cpp-flag=flags

设置要传递给 C 预处理器 cpp(1) 的其他标志。以“.in” 后缀结尾的 Containerfile 会通过 cpp(1) 进行预处理。此选项可用于传递其他标志给 cpp。注意:您还可以通过设置 BUILDAH_CPPFLAGS 环境变量来设置默认 CPPFLAGS(例如,export BUILDAH_CPPFLAGS=”-DDEBUG”)。

--cpu-period=limit

设置完全公平调度器(CFS)的 CPU 周期,该周期以微秒为单位。一旦容器的 CPU 配额用完,它将不会被调度运行,直到当前周期结束。默认值为 100000 微秒。

在某些系统上,可能不允许非根用户更改资源限制。有关更多详细信息,请参见 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 控制)。

在某些系统上,可能不允许非根用户更改资源限制。有关更多详细信息,请参见 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,则第一个容器仅获得 33% 的 CPU。其余容器分别获得 16.5%、16.5% 和 33% 的 CPU。

在多核系统上,CPU 时间份额分布在所有 CPU 核心上。即使容器被限制为少于 100% 的 CPU 时间,它也可以使用每个单独 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%

在某些系统上,可能不允许非根用户更改资源限制。有关更多详细信息,请参见 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)。

在某些系统上,可能不允许非根用户更改资源限制。有关更多详细信息,请参见 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,那么容器中的进程将仅使用前两个内存节点的内存。

在某些系统上,可能不允许非根用户更改资源限制。有关更多详细信息,请参见 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) 文件。

--decryption-key=key[:passphrase]

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

--device=host-device[:container-device][:permissions]

向容器添加主机设备。可选的 permissions 参数可用于通过组合 r(读)、w(写)和 mmknod(2))来指定设备权限。

例如:--device=/dev/sdc:/dev/xvdc:rwm

注意:如果 host-device 是符号链接,则首先解析它。容器仅存储主机设备的主编号和次编号。

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,可以在所有情况下强制压缩。

--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=option

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

--dns-search=domain

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

--env=env[=value]

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

--farm

此选项指定构建过程中要使用的农场的名称。

此选项指定构建过程中要使用的农场的名称。

--file, -f=Containerfile

指定包含构建镜像指令的 Containerfile,可以是本地文件,也可以是 httphttps URL。如果指定了多个 Containerfile,则仅接受最后一个指定文件的 FROM 指令。

如果没有指定构建上下文,并且至少有一个 Containerfile 是本地文件,则它所在的目录将用作构建上下文。

指定选项 -f - 会导致从 stdin 读取 Containerfile 內容。

--force-rm

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

--format

控制构建镜像的清单和配置数据的格式。支持的格式包括 *oci*(OCI 镜像规范 v1.0,默认)和 *docker*(版本 2,使用模式格式 2 用于清单)。

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

--from

覆盖 Containerfile 中的第一个 FROM 指令。如果 Containerfile 中有多个 FROM 指令,则只更改第一个。

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

--group-add=group | keep-groups

将附加组分配给在容器进程中运行的主要用户。

  • keep-groups 是一个特殊标志,指示 Podman 保留辅助组访问权限。

允许容器使用用户的辅助组访问权限。如果文件系统或设备只能由无根用户的组访问,则此标志指示 OCI 运行时将组访问权限传递到容器中。目前,此功能仅适用于 crun OCI 运行时。注意:keep-groups 是排他的,其他组不能与此标志一起指定。(不适用于远程命令,包括 Mac 和 Windows(不包括 WSL2)机器)

--help, -h

打印使用说明

--hooks-dir=path

路径中的每个 *.json 文件都为 buildah 构建容器配置一个钩子。有关 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=ImageIDfile

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

--ipc=how

在处理 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*(例如 label=value)。可以多次使用。

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

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

--layer-label=label[=value]

向中间镜像元数据添加中间镜像 *label*(例如 label=value)。它可以多次使用。

如果 *label* 被命名,但既没有提供 = 也没有提供 value,那么 *label* 被设置为一个空值。

--layers

在构建过程中缓存中间镜像(默认值为 true)。

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

--local, -l

在本地机器和农场节点上构建镜像。

--logfile=filename

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

--memory, -m=number[unit]

内存限制。unit 可以是 **b**(字节)、**k**(kibibytes)、**m**(mebibytes)或 **g**(gibibytes)。

允许限制容器可用的内存。如果主机支持交换内存,那么 **-m** 内存设置可以大于物理 RAM。如果指定了 0 的限制(不使用 **-m**),则容器的内存不受限制。实际限制可能会向上舍入到操作系统页面大小的倍数(该值非常大,即百万兆兆)。

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

--memory-swap=number[unit]

等于内存加交换的限制值。unit 可以是 **b**(字节)、**k**(kibibytes)、**m**(mebibytes)或 **g**(gibibytes)。

必须与 **-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 的网络。仅适用于 root 用户。

  • slirp4netns[:OPTIONS,…]: 使用 **slirp4netns**(1) 创建用户网络栈。可以指定这些附加选项,它们也可以在 containers.conf 中使用 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,为容器中的 tap0 接口分配 10.0.2.0/24,网关为 10.0.2.3,启用可达 10.0.2.3 的 DNS 转发器,将 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,相当于默认的 slirp4netns(1) 选项,带有 Podman 覆盖:与上述相同,但将 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.internalhost.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-feature=feature

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

如果 feature 结尾带有 -,则从镜像中列出的所需特性集中删除该 feature

--os-version=version

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

--pid=pid

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

--platforms=p1,p2,p3…

仅在与给定平台匹配的农场节点上构建。

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

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

--sbom-purl-output=文件

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

--sbom-scanner-command=镜像

通过运行扫描程序镜像中的指定命令来生成 SBOM。如果指定了多个命令,它们将按照指定的顺序运行。将执行以下文本替换

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

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

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

--sbom-scanner-image=镜像

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

--secret=id=id,src=path

以安全的方式传递用于构建镜像的 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 冲突。

--skip-unused-stages

跳过多阶段构建中不影响目标阶段的阶段。(默认:true)。

--squash

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

--squash-all

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

--ssh=默认 | id[=socket>

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

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

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

--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=用户

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

注意: 当无根用户指定此选项时,指定的映射相对于容器中的无根用户命名空间,而不是相对于主机,就像以根用户身份运行时一样。

--uts=方式

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

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

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

OPTIONS 是一个逗号分隔的列表,可以包含以下一个或多个选项:

  • [rw|ro]

  • [z|Z|O]

  • [U]

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

CONTAINER-DIR 必须是绝对路径,例如 /src/docsHOST-DIR 也必须是绝对路径。Podman 将 HOST-DIR 绑定挂载到指定的路径,以便在处理 RUN 指令时进行挂载。

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

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

Chowning Volume Mounts

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

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

警告 请谨慎使用,因为它会修改宿主文件系统。

Labeling Volume Mounts

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

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

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

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

Overlay Volume Mounts

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

后续执行任何 RUN 命令都将看到原始的源目录内容,之前 RUN 命令的任何更改都不复存在。

overlay 挂载的一个用例是将来自主机的包缓存共享到容器中,以便加快构建速度。

注意

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

  • O 标志不允许与 Zz 标志一起指定。挂载到容器中的内容使用私有标签进行标记。在 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 表示挂载点为 sharedmaster:X 表示挂载点为 slave,如果没有指定任何属性,则表示挂载点为 private[1]

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

示例

使用指定的 Containerfile 和默认的 farm 构建命名镜像和清单列表

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

使用指定的 farm 构建命名镜像和清单列表

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

使用指定的 farm 构建命名镜像和清单列表,在将它们推送到注册表后,从 farm 节点中删除所有镜像

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

使用默认的 farm 构建指定平台的命名镜像和清单列表

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

另请参阅

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 <[email protected]> 编写

脚注

1: Podman 项目致力于包容性,这是开源的核心价值。这里使用的 masterslave 挂载传播术语存在问题且具有争议性,需要更改。但是,这些术语目前在 Linux 内核中使用,并且必须在此时按原样使用。当内核维护人员纠正此用法时,Podman 将立即随之更改。