名称

podman-update - 更新给定容器的配置

简介

podman update [选项] 容器

podman container update [选项] 容器

描述

更新现有容器的配置,允许更改资源限制和健康检查。

选项

--blkio-weight=weight

块 IO 相对权重。weight 是介于 101000 之间的值。

在 cgroups V1 的无根(rootless)系统上不支持此选项。

--blkio-weight-device=device:weight

块 IO 相对设备权重。

--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 的无根(rootless)系统上不支持此选项。

--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 的无根(rootless)系统上不支持此选项。

--cpu-rt-period=microseconds

限制 CPU 实时周期(微秒)。

限制容器的实时 CPU 使用。此选项告诉内核将容器的实时 CPU 使用限制在指定的时间段内。

此选项仅在 cgroups V1 rootful 系统上受支持。

--cpu-rt-runtime=microseconds

限制 CPU 实时运行时间(微秒)。

限制容器的实时 CPU 使用。此选项告诉内核限制在给定 CPU 周期内实时任务可能消耗的时间量。例如:周期为 1,000,000us,运行时为 950,000us,意味着该容器可以消耗 95% 的可用 CPU,并将剩余的 5% 留给正常优先级任务。

所有容器的运行时总和不能超过分配给父 cgroup 的量。

此选项仅在 cgroups V1 rootful 系统上受支持。

--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%

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

在 cgroups V1 的无根(rootless)系统上不支持此选项。

--cpus=number

CPU 数量。默认值为 0.0,表示没有限制。这是 --cpu-period--cpu-quota 的简写,因此该选项不能与 --cpu-period--cpu-quota 一起指定。

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

在 cgroups V1 的无根(rootless)系统上不支持此选项。

--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 的无根(rootless)系统上不支持此选项。

--cpuset-mems=nodes

允许执行的内存节点(MEMs)(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 的无根(rootless)系统上不支持此选项。

--device-read-bps=path:rate

限制从设备读取速率(每秒字节数)(例如 --device-read-bps=/dev/sda:1mb)。

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

在 cgroups V1 的无根(rootless)系统上不支持此选项。

--device-read-iops=path:rate

限制从设备读取速率(每秒 IO 操作数)(例如 --device-read-iops=/dev/sda:1000)。

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

在 cgroups V1 的无根(rootless)系统上不支持此选项。

--device-write-bps=path:rate

限制写入设备速率(每秒字节数)(例如 --device-write-bps=/dev/sda:1mb)。

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

在 cgroups V1 的无根(rootless)系统上不支持此选项。

--device-write-iops=path:rate

限制写入设备速率(每秒 IO 操作数)(例如 --device-write-iops=/dev/sda:1000)。

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

在 cgroups V1 的无根(rootless)系统上不支持此选项。

--env, -e=环境变量

向容器添加一个值(例如 env=)。可以多次使用。如果该值已存在于容器中,则会被覆盖。要从容器中删除环境变量,请使用 --unsetenv 选项。

请注意,环境变量更新仅在下次启动后影响主容器进程。

--health-cmd=”command” | ‘[“command”, “arg1”, …]’

为容器设置或更改健康检查命令。该命令是一个将在容器内部执行的命令,用于确定容器的健康状况。应用其他健康检查选项需要该命令。值为 none 将禁用现有健康检查。

可以以 JSON 数组的形式传递多个选项;否则,该命令将被解释为 /bin/sh -c 的参数。

注意:即使在镜像中配置了健康检查,也会使用默认值。

--health-interval=interval

设置健康检查的间隔。intervaldisable 表示不自动设置计时器。默认值为 30s

注意:此参数将覆盖镜像中相关的健康检查配置。

更改此设置会重置计时器。

--health-log-destination=directory_path

设置 HealthCheck 日志的目标位置。目录路径,本地或 events_logger(本地使用容器状态文件)(默认:本地)

  • local:(默认)健康检查日志存储在叠加容器中。(例如:$runroot/healthcheck.log

  • directory:在指定目录中创建名为 <container-ID>-healthcheck.log 的日志文件,其中包含健康检查日志。

  • events_logger:日志将使用 events_logger 设置的日志机制写入。它还将日志保存到默认目录,以提高日志数量庞大的系统的性能。

警告:更改此设置可能会导致之前日志的丢失。

--health-max-log-count=number of stored logs

设置 HealthCheck 日志文件中的最大尝试次数。(“0”值表示日志文件中无限次尝试)(默认:5 次尝试)

--health-max-log-size=size of stored logs

设置存储的 HealthCheck 日志的最大字符长度。(“0”值表示无限日志长度)(默认:500 个字符)

--health-on-failure=action

容器转换为不健康状态后采取的操作。默认值为 none

  • none: 不采取任何行动。

  • kill: 杀死容器。

  • restart:重新启动容器。不要将 restart 动作与 --restart 标志结合使用。在 systemd 单元内部运行时,请考虑使用 killstop 动作,以利用 systemd 的重启策略。

  • stop: 停止容器。

--health-retries=retries

在健康检查被视为不健康之前允许的重试次数。默认值为 3

注意:此参数可以覆盖镜像中的健康检查配置。

--health-start-period=period

容器引导所需的初始化时间。该值可以用时间格式表示,例如 2m3s。默认值为 0s

注意:健康检查命令在容器启动后立即执行,如果健康检查成功,容器的健康状态将更新为 healthy。但是,如果健康检查失败,健康状态将保持为 starting,直到健康检查成功或 --health-start-period 时间结束。如果在 --health-start-period 时间结束后健康检查命令失败,健康状态将更新为 unhealthy。健康检查命令会根据 --health-interval 的值定期执行。

注意:此参数将覆盖镜像中相关的健康检查配置。

--health-startup-cmd=”command” | ‘[“command”, “arg1”, …]’

为容器设置启动健康检查命令。此命令在容器内部执行,用于控制常规健康检查。当启动命令成功时,常规健康检查开始,启动健康检查停止。可选地,如果命令失败达到设定的尝试次数,容器将重新启动。启动健康检查可用于确保具有延长启动期的容器在完全启动之前不会被标记为不健康。启动健康检查只能在同时设置了常规健康检查(来自容器镜像或 --health-cmd 选项)时使用。

--health-startup-interval=interval

设置启动健康检查的间隔。intervaldisable 会导致不自动设置计时器。默认值为 30s

更改此设置会根据容器状态重置计时器。

--health-startup-retries=retries

启动健康检查重新启动容器之前允许的尝试次数。如果设置为 0,则容器永远不会重新启动。默认值为 0

--health-startup-success=retries

启动健康检查成功并开始常规健康检查之前所需的成功运行次数。值为 0 表示任何成功都会开始常规健康检查。默认值为 0

--health-startup-timeout=timeout

启动健康检查命令完成前的最长时间,超过此时间将被标记为失败。该值可以用时间格式表示,例如 2m3s。默认值为 30s

--health-timeout=timeout

在间隔被视为失败之前,允许完成健康检查的最长时间。与 start-period 类似,该值可以用时间格式表示,例如 1m22s。默认值为 30s

注意:超时将健康检查标记为失败。如果健康检查命令本身运行时间超过指定的 timeout,它将被发送 SIGKILL 信号。

注意:此参数将覆盖镜像中相关的健康检查配置。

--latest, -l

不提供名称或 ID,而是使用最新创建的容器。注意:最新创建的容器可能来自主机上 Podman 的其他用户。(此选项不适用于远程 Podman 客户端,包括 Mac 和 Windows(WSL2 除外)机器)

--memory, -m=number[unit]

内存限制。unit 可以是 b (字节),k (千字节),m (兆字节),或 g (吉字节)。

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

在 cgroups V1 的无根(rootless)系统上不支持此选项。

--memory-reservation=number[unit]

内存软限制。unit 可以是 b(字节)、k(千字节)、m(兆字节)或 g(千兆字节)。

设置内存保留后,当系统检测到内存争用或内存不足时,容器将被强制将其消耗限制在其保留范围内。因此,始终将该值设置在 --memory 之下,否则硬限制将优先。默认情况下,内存保留与内存限制相同。

在 cgroups V1 的无根(rootless)系统上不支持此选项。

--memory-swap=number[unit]

一个等于内存加交换空间的限制值。unit 可以是 b (字节),k (千字节),m (兆字节),或 g (吉字节)。

必须与 -m (--memory) 标志一起使用。参数值必须大于 -m (--memory) 的值。默认情况下,它被设置为 --memory 值的两倍。

number 设置为 -1 以启用无限制的交换空间。

在 cgroups V1 的无根(rootless)系统上不支持此选项。

--memory-swappiness=number

调整容器的内存交换行为。接受介于 0100 之间的整数。

此标志仅在 cgroups V1 rootful 系统上受支持。

--no-healthcheck

禁用容器的任何已定义的健康检查。

--pids-limit=limit

调整容器的进程 ID 限制。设置为 -1 表示容器的进程 ID 无限制。在支持“pids”cgroup 控制器的系统上,默认值为 2048

--restart=policy

容器退出时遵循的重启策略。如果容器通过podman killpodman stop命令停止,重启策略不会生效。

有效的policy值为

  • no:容器退出时不重启

  • neverno的同义词;容器退出时不重启

  • on-failure[:max_retries]:当容器以非零退出代码退出时重启,无限重试或直到达到可选的max_retries计数

  • always:当容器退出时重启,无论状态如何,无限重试

  • unless-stopped:与always相同

Podman提供了一个systemd单元文件podman-restart.service,它在系统重启后重启容器。

在 systemd 服务中运行容器时,请使用 systemd 提供的重启功能。换句话说,不要在容器单元中使用此选项,而是在 [Service] 部分中设置 Restart= systemd 指令。请参阅 podman-quadlet(7) 和 systemd.service(5)。

--unsetenv=env

从容器中取消设置环境变量。

请注意,环境变量更新仅在下次启动后影响主容器进程。

示例

使用新的 cpu 配额和周期更新容器

podman update --cpus=0.5 ctrID

使用新的 cpu 值更新最新容器

podman update --latest --cpus=1

一次更新具有多个选项的容器

podman update --cpus 5 --cpuset-cpus 0 --cpu-shares 123 --cpuset-mems 0 \\
  --memory 1G --memory-swap 2G --memory-reservation 2G \\
  --blkio-weight-device /dev/sda:123 --blkio-weight 123 \\
  --device-read-bps /dev/sda:10mb --device-write-bps /dev/sda:10mb \\
  --device-read-iops /dev/sda:1000 --device-write-iops /dev/sda:1000 \\
  --pids-limit 123 ctrID

另请参阅

podman(1)podman-create(1)podman-run(1)

历史

2025 年 6 月,最新选项由 Hayato Kihara kai.21banana@gmail.com 添加。2022 年 8 月,最初由 Charlie Doern cdoern@redhat.com 撰写。