containers.podman.podman_container 模块 – 管理 Podman 容器
注意
此模块是 containers.podman 集合 (版本 1.16.2) 的一部分。
如果您使用的是 ansible 包，则可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。
要安装它，请使用：ansible-galaxy collection install containers.podman。您需要其他要求才能使用此模块，请参阅 要求 获取详细信息。
要在 playbook 中使用它，请指定：containers.podman.podman_container。
containers.podman 1.0.0 中的新增功能
概要
启动、停止、重启和管理 Podman 容器
要求
在执行此模块的主机上需要以下要求。
podman
参数
参数 |
注释 |
|---|---|
向容器添加注释。格式为键值对，可多次使用。 |
|
设置容器的架构。覆盖将要拉取镜像的主机架构。例如，arm。 |
|
附加到 STDIN、STDOUT 或 STDERR。Podman 中的默认值为 false。 选项
|
|
身份验证文件的路径。默认为 ``${XDG_RUNTIME_DIR}/containers/auth.json``（远程命令不可用）您还可以通过设置 ``REGISTRY_AUTH_FILE`` 环境变量来覆盖身份验证文件的默认路径。 ``export REGISTRY_AUTH_FILE=path`` |
|
块 IO 权重（相对权重）接受 10 到 1000 之间的权重值 |
|
块 IO 权重（相对设备权重，格式为 DEVICE_NAME[:]WEIGHT）。 |
|
要添加到容器的功能列表。 |
|
要从容器中删除的功能列表。 |
|
在 cgroup v2 上运行时，指定要写入的 cgroup 文件及其值。 |
|
容器 cgroup 将在其下创建的 cgroups 路径。如果路径不是绝对路径，则该路径被认为相对于 init 进程的 cgroups 路径。如果 cgroups 不存在，则将创建它们。 |
|
容器 cgroup 将在其下创建的 cgroups 路径。 |
|
确定容器是否将创建 CGroups。有效值为 enabled 和 disabled，默认为 enabled。disabled 选项将强制容器不创建 CGroups，因此与 CGroup 选项 cgroupns 和 cgroup-parent 冲突。 |
|
容器内被视为 chroot 目录的目录路径。 |
|
将容器 ID 写入文件 |
|
您想要传递给 podman 命令本身的任何其他命令选项，例如 |
|
覆盖容器的命令。可以是字符串或列表。 |
|
将 conmon 进程的 pid 写入文件。conmon 在与 Podman 分开的进程中运行，因此在使用 systemd 重启 Podman 容器时这是必要的。 |
|
限制 CPU CFS（完全公平调度器）周期 |
|
限制 CPU CFS（完全公平调度器）配额 |
|
以微秒为单位限制 CPU 实时周期。限制容器的实时 CPU 使用率。此标志告诉内核将容器的实时 CPU 使用率限制为您指定的周期。 |
|
以微秒为单位限制 CPU 实时运行时间。此标志告诉内核限制给定 CPU 周期中实时任务可能消耗的时间量。 |
|
CPU 份额（相对权重） |
|
CPU 数量。默认为 0.0，表示没有限制。 |
|
允许执行的 CPU（0-3、0、1） |
|
允许执行的内存节点 (MEM)（0-3、0、1）。仅在 NUMA 系统上有效。 |
|
返回其他信息，这些信息可能有助于调查。 选项
|
|
用于解密镜像的“密钥密码”。密钥可以指向密钥和/或证书。 |
|
删除选定的容器并递归删除所有依赖它的容器。适用于“删除”命令。 选项
|
|
强制停止容器前等待的秒数。使用 -1 表示无限等待。适用于“删除”命令。 |
|
删除与容器关联的匿名卷。这并不包括使用 podman volume create 创建的命名卷，也不包括 podman run 和 podman create 的 –volume 选项。 选项
|
|
分离模式运行容器 选项
|
|
覆盖分离容器的按键序列。格式为单个字符或 ctrl-值 |
|
向容器添加主机设备。格式为 <主机上的设备>[:<容器上的设备>][:<权限>]（例如 device /dev/sdc:/dev/xvdc:rwm） |
|
向 cgroup 允许的设备列表添加规则。规则应采用 Linux 内核文档 admin-guide/cgroup-v1/devices 中指定的格式。 |
|
限制从设备读取速率（每秒字节数）（例如 device-read-bps /dev/sda:1mb） |
|
限制从设备读取速率（每秒 I/O 次数）（例如 device-read-iops /dev/sda:1000） |
|
限制写入设备的速率（每秒字节数）（例如 device-write-bps /dev/sda:1mb） |
|
限制写入设备的速率（每秒 I/O 次数）（例如 device-write-iops /dev/sda:1000） |
|
设置自定义 DNS 服务器 |
|
设置自定义 DNS 选项 |
|
设置自定义 DNS 搜索域（如果不想设置搜索域，请使用空字符串作为 dns_search） |
|
覆盖镜像的默认 ENTRYPOINT |
|
设置环境变量。此选项允许您指定任意环境变量，这些变量可用于将在容器内启动的进程。 |
|
读取由换行符分隔的环境变量文件。不支持幂等性。如果用户更改了包含环境变量的文件，则需要重新创建容器。该文件必须存在于运行实际 podman 的远程机器上，而不是运行 Ansible 的控制机器上。如果需要将文件从控制机器复制到远程机器，请使用 copy 或 slurp 模块。 |
|
在容器中使用所有当前主机环境变量。默认为 false。 选项
|
|
预处理容器的默认环境变量 |
|
主机到 IP 映射的字典，其中每个主机名都是字典中的一个键。每个主机名都将添加到容器的`/etc/hosts`文件中。 |
|
如果 podman 可执行文件不在运行 podman 的机器上的 `$PATH` 中，则指定其路径。 默认： |
|
公开端口或端口范围（例如 expose “3300-3310”）以在主机系统上设置端口重定向。 |
|
删除容器时强制删除。 选项
|
|
强制重启容器。 选项
|
|
为容器生成 systemd 单元文件。 默认： |
|
添加 systemd 单元 after (After=) 选项，用于对依赖项列表和此服务之间的排序进行依赖。 |
|
设置容器的 systemd 单元名称前缀。默认为“container”。 |
|
在单元文件中使用容器的名称作为启动、停止和描述。默认为 true。 选项
|
|
在单元启动时创建容器和 Pod，而不是期望它们已经存在。默认为“false”。有关更多信息，请参阅 podman-generate-systemd(1)。 选项
|
|
不生成包含元数据（例如 Podman 版本和时间戳）的标头。从 podman 3.1.0 版本开始。 选项
|
|
指定生成单元文件的目录的路径。此选项需要此参数。如果不存在，则将创建该目录。 |
|
设置 Pod 的 systemd 单元名称前缀。默认为“pod”。 |
|
设置 systemd 单元 requires (Requires=) 选项。类似于 wants，但声明更强的需求依赖关系。 |
|
指定服务的重启策略。重启策略必须是“no”、“on-success”、“on-failure”、“on-abnormal”、“on-watchdog”、“on-abort”或“always”之一。默认策略是“on-failure”。 选项
|
|
设置 systemd 服务 restartsec 值。 |
|
设置容器/Pod 的名称/ID 与前缀之间的 systemd 单元名称分隔符。默认为“-”（破折号）。 |
|
使用给定值覆盖容器的默认启动超时。 |
|
使用给定值覆盖容器的默认停止超时。在 4.0 版本之前称为 `time`。 |
|
添加 systemd 单元 wants (Wants=) 选项，表示此服务（弱）依赖于它。 |
|
使用提供的映射在新用户命名空间中运行容器。 |
|
要添加到容器的 GPU 设备。 |
|
添加要运行的附加组 |
|
使用 –user 时自定义写入容器内 /etc/group 文件的条目。 |
|
为容器设置启动健康检查命令。 |
|
设置启动健康检查的间隔。 |
|
启动健康检查在重启容器之前允许的尝试次数。如果设置为 0，则容器永远不会重启。默认为 0。 |
|
启动健康检查成功并开始定期健康检查之前所需的成功运行次数。值为 0 表示任何成功都将开始定期健康检查。默认为 0。 |
|
启动健康检查命令在标记为失败之前必须完成的最长时间。 |
|
设置或更改容器的健康检查命令。 |
|
容器被认为不健康时要采取的操作。操作必须是“none”、“kill”、“restart”或“stop”之一。默认策略是“none”。 选项
|
|
设置健康检查的间隔（值为 disable 将导致没有自动计时器设置）（默认“30s”） |
|
健康检查被认为不健康之前允许的重试次数。默认值为 3。 |
|
容器引导所需 的初始化时间。该值可以用时间格式表示，例如 2m3s。默认值为 0s |
|
在间隔被认为失败之前允许完成健康检查的最长时间。与 start-period 一样，该值可以用时间格式表示，例如 1m22s。默认值为 30s |
|
路径中的每个 .json 文件都为 Podman 容器配置一个钩子。有关 JSON 文件语法和钩子注入语义的更多详细信息，请参阅 oci-hooks(5)。可以多次设置。 |
|
容器主机名。设置在容器内可用的容器主机名。 |
|
将主机上的用户帐户添加到容器的 /etc/passwd。用户名或 UID 必须存在于主机系统上。 |
|
默认情况下，如果为 podman 进程设置了代理环境变量，则将其传递到容器中。可以通过将 http_proxy 选项设置为 false 来禁用此功能。传入的环境变量包括 http_proxy、https_proxy、ftp_proxy、no_proxy，以及这些变量的大写版本。默认为 true 选项
|
|
用于创建容器的存储库路径（或镜像名称）和标签。如果找不到镜像，则将从注册表中提取镜像。如果不包含标签，则将使用 也可以是镜像 ID。如果是这种情况，则假定镜像在本地可用。 |
|
是否通过考虑包含注册表和命名空间的完整名称来比较幂等性中的镜像。 选项
|
|
告诉 podman 如何处理内置镜像卷。选项为 bind、tmpfs 或 ignore（默认 bind） 选项
|
|
在容器内运行 init，它转发信号并收集进程。默认为 false。 选项
|
|
（仅限 Pod）。使用 Pod 时，创建一个 init 风格的容器，它在基础容器启动后但常规 Pod 容器启动之前运行。 选项
|
|
container-init 二进制文件的路径。 |
|
即使未附加，也保持 STDIN 打开。默认为 false。设置为 true 时，即使未附加，也保持 stdin 打开。默认为 false。 选项
|
|
为容器指定静态 IP 地址，例如“10.88.64.128”。只有在未通过“network:”指定要加入的其他 CNI 网络，并且容器未通过“network container:<name|id>”加入另一个容器的网络命名空间时才能使用。该地址必须位于默认 CNI 网络的池中（默认为 10.88.0.0/16）。 |
|
为容器指定静态 IPv6 地址 |
|
默认为为容器创建一个私有 IPC 命名空间（POSIX SysV IPC） |
|
内核内存限制（格式为 <number>[<unit>]，其中 unit = b、k、m 或 g）注意 - 仅整数支持幂等性。 |
|
向容器添加元数据，传递标签名称和值的字典 |
|
读取由换行符分隔的标签文件 |
|
日志驱动程序。用于设置容器的日志驱动程序。例如 log_driver “k8s-file”。 选项
|
|
Podman 的日志级别。高于指定级别（“debug”|“info”|“warn”|“error”|“fatal”|“panic”）的日志消息（默认值为 “error”） 选项
|
|
特定于日志驱动程序的选项。用于设置容器日志文件的路径。 |
|
指定日志文件的最大大小（例如 10mb）。 |
|
指定日志文件的路径（例如 /var/log/container/mycontainer.json）。 |
|
为容器指定自定义日志标签。 |
|
为容器指定 MAC 地址，例如 ‘92:d0:c6:0a:29:33’。请记住，它在同一个以太网网络中必须是唯一的。 |
|
内存限制（格式为 10k，其中 unit = b、k、m 或 g）注意 - 仅整数支持幂等性。 |
|
内存软限制（格式为 100m，其中 unit = b、k、m 或 g）注意 - 仅整数支持幂等性。 |
|
等于内存加交换空间的限制值。必须与 -m (–memory) 标志一起使用。交换空间限制应始终大于 -m (–memory) 值。默认情况下，交换空间限制将设置为 –memory 值的两倍。注意 - 仅整数支持幂等性。 |
|
调整容器的内存交换行为。接受 0 到 100 之间的整数。 |
|
将文件系统挂载附加到容器。bind 或 tmpfs 例如 mount “type=bind,source=/path/on/host,destination=/path/in/container” |
|
容器的名称 |
|
设置容器的网络模式 * bridge 在默认桥接器上创建网络栈 * none 无网络 * container:<name|id> 重用另一个容器的网络栈 * host 使用 podman 主机网络栈。 * <network-name>|<network-id> 连接到用户定义的网络 * ns:<path> 要加入的网络命名空间的路径 * slirp4netns 使用 slirp4netns 创建用户网络栈。这是无根容器的默认值 |
|
为容器添加网络范围的别名。容器只能访问其加入的第一个网络上的别名。这是一个限制，将在以后的版本中删除。 |
|
禁用容器的任何已定义的健康检查。 选项
|
|
不为容器创建 /etc/hosts 默认值为 false。 选项
|
|
是否禁用容器的 OOM Killer。默认值为 false。 选项
|
|
调整主机对容器的 OOM 偏好设置（接受 -1000 到 1000） |
|
覆盖要拉取的镜像的操作系统，默认为主机操作系统。例如，windows。 |
|
允许 Podman 在与 –user 选项结合使用时向 /etc/passwd 和 /etc/group 添加条目。这用于覆盖 Podman 提供的用户设置，以支持入口点配置，例如 libnss-extrausers。 选项
|
|
自定义使用 –passwd 时写入容器内 /etc/passwd 文件的条目。 |
|
Personality 通过 Linux personality(2) 设置执行域。 |
|
设置容器的 PID 模式 |
|
当指定 pidfile 位置时，容器进程的 PID 将写入 pidfile。 |
|
调整容器的 PIDs 限制。设置为 -1 以对容器具有无限的 PIDs。 |
|
指定用于选择镜像的平台。 |
|
在现有 pod 中运行容器。如果希望 podman 为您创建 pod，请在 pod 名称前加上 “new:” |
|
在现有 pod 中运行容器并从指定文件读取 pod 的 ID。当容器在具有基础容器的 pod 中运行时，基础容器会先启动。 |
|
将逗号分隔列表中指定的附加文件描述符传递给进程。 |
|
将 N 个附加文件描述符传递给进程（除了 0、1、2）。总 FD 为 3+N。 |
|
赋予此容器扩展权限。默认值为 false。 选项
|
|
将容器的端口或端口范围发布到主机。格式 - ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort 如果仅设置 containerPort，则 hostPort 将由 Podman 随机选择。 |
|
将所有公开的端口发布到主机接口上的随机端口。默认值为 false。 选项
|
|
拉取镜像策略。默认值为 ‘missing’。 选项
|
|
写入 quadlet 文件的目录路径。默认情况下，对于 root 用户将设置为 |
|
quadlet 文件的权限。 可以将 如果未指定 如果未指定 指定 |
|
要写入的 quadlet 文件的名称。默认情况下，它采用 |
|
quadlet 文件的选项。提供通常的容器参数选项中缺少的内容，作为要添加的行列表。 |
|
Rdt-class 设置容器运行的服务类别 (CLOS 或 COS)。需要 root 权限。 |
|
将容器的根文件系统以只读方式挂载。默认值为 false 选项
|
|
如果容器以 –read-only 模式运行，则在 /run、/tmp 和 /var/tmp 上挂载可读写的 tmpfs。默认值为 true 选项
|
|
与 present 和 started 状态一起使用以强制重新创建现有容器。 选项
|
|
指定一个或多个需求。需求是将在此容器之前启动的依赖容器。可以使用名称或 ID 指定容器。 |
|
容器退出时要遵循的重启策略。如果通过 podman kill 或 podman stop 命令停止容器，则重启策略将不会生效。有效值为 * no - 退出时不重启容器 * on-failure[:max_retries] - 当容器以非 0 退出代码退出时重启容器，无限重试或直到达到可选的 max_retries 次数 * always - 无论状态如何，容器退出时都重启容器，无限重试 |
|
重启时强制停止容器之前等待的秒数。使用 -1 表示无限等待。适用于“restarted”状态。 |
|
在出现故障的情况下，重试在注册表和本地存储之间拉取或推送镜像的次数。默认值为 3。 |
|
在出现故障的情况下，在注册表和本地存储之间拉取或推送镜像时，重试尝试之间的延迟持续时间。 |
|
容器退出时自动删除容器。默认值为 false。 选项
|
|
容器退出后，删除镜像，除非其他容器正在使用它。暗示在新容器上使用 –rm。默认值为 false。 选项
|
|
如果为 true，则第一个参数指的是文件系统上的已展开容器。默认值为 false。 选项
|
|
确定如何使用 NOTIFY_SOCKET，如 systemd 和 Type=notify 一起传递。可以是 container、conmon、ignore。 |
|
指定用于选择 seccomp 配置文件的策略。 |
|
将命名的密钥添加到容器中。格式为 |
|
安全选项。例如 security_opt “seccomp=unconfined” |
|
/dev/shm 的大小。格式为 <number><unit>。number 必须大于 0。Unit 可选，可以是 b（字节）、k（千字节）、m（兆字节）或 g（千兆字节）。如果省略单位，则系统使用字节。如果完全省略大小，则系统使用 64m |
|
systemd 专用 tmpfs 挂载点（例如 /run、/run/lock、/var/log/journal 和 /tmp）的大小。 |
|
将发送到 podman run 命令的信号代理到容器进程。SIGCHLD、SIGSTOP 和 SIGKILL 不会被代理。默认为 true。 选项
|
|
absent - 将停止并删除与指定名称匹配的容器。 present - 断言存在与名称和任何提供的配置参数匹配的容器。如果没有任何容器与名称匹配，则将创建一个容器。如果容器与名称匹配，但提供的配置不匹配，则将更新容器（如果可以）。如果无法更新，则将删除并使用请求的配置重新创建它。比较配置时将考虑镜像版本。使用 recreate 选项强制重新创建匹配的容器。 started - 断言存在一个与名称和任何提供的配置匹配的正在运行的容器。如果没有任何容器与名称匹配，则将创建一个容器并启动它。使用 recreate 始终重新创建匹配的容器，即使它正在运行。使用 force_restart 强制停止并重新启动匹配的容器。 stopped - 断言容器首先 present，然后如果容器正在运行则将其移至停止状态。 created - 断言容器存在且具有给定的配置。如果容器不存在，模块将创建它并将其保留在“created”状态。如果配置不匹配或设置了“recreate”选项，则将重新创建容器。 quadlet - 使用指定的配置编写 quadlet 文件。 选项
|
|
停止容器的信号。默认为 SIGTERM。 |
|
强制停止容器之前等待的秒数。使用 -1 表示无限等待。适用于“stopped”状态。 |
|
停止容器的超时时间（以秒为单位）。默认为 10。 |
|
使用 /etc/subgid 文件中具有“name”的映射在新用户命名空间中运行容器。 |
|
使用 /etc/subuid 文件中具有“name”的映射在新用户命名空间中运行容器。 |
|
在运行时配置命名空间内核参数 |
|
在 systemd 模式下运行容器。默认为 true。 |
|
在 conmon 发送终止信号之前，容器允许运行的最长时间（以秒为单位）。默认情况下，容器运行直到退出或被“podman stop”停止。 |
|
设置容器中的时区。此标志采用基于区域的时区、GMT 时间以及 local，local 将容器中的时区设置为与主机匹配。有关有效的时区，请参阅 /usr/share/zoneinfo/。远程连接使用本地 containers.conf 作为默认值。 |
|
拉取镜像时需要 HTTPS 并验证证书。 选项
|
|
创建 tmpfs 挂载点。例如 tmpfs “/tmp” “rw,size=787448k,mode=1777” |
|
分配一个伪 TTY。默认为 false。 选项
|
|
使用提供的映射在新用户命名空间中运行容器。 |
|
Ulimit 选项 |
|
设置容器内的 umask。默认为 0022。远程连接使用本地 containers.conf 作为默认值。 |
|
取消设置容器的默认环境变量。 |
|
取消设置容器的所有默认环境变量。 选项
|
|
设置使用的用户名或 UID，以及可选的指定命令的组名或 GID。 |
|
设置容器的用户命名空间模式。默认为 PODMAN_USERNS 环境变量。空值表示禁用用户命名空间。 |
|
设置容器的 UTS 模式 |
|
使用 VARIANT 代替容器镜像的默认架构变体。 |
|
创建绑定挂载。如果您指定 volume /HOST-DIR:/CONTAINER-DIR，podman 将主机上的 /HOST-DIR 绑定挂载到 podman 容器中的 /CONTAINER-DIR。 |
|
从指定的容器挂载卷。 |
|
容器内的工作目录。在容器内运行二进制文件的默认工作目录是根目录(/)。 |
示例
- name: Run container
containers.podman.podman_container:
name: container
image: quay.io/bitnami/wildfly
state: started
- name: Create a data container
containers.podman.podman_container:
name: mydata
image: busybox
volume:
- /tmp/data
- name: Re-create a redis container with systemd service file generated in /tmp/
containers.podman.podman_container:
name: myredis
image: redis
command: redis-server --appendonly yes
state: present
recreate: true
expose:
- 6379
volumes_from:
- mydata
generate_systemd:
path: /tmp/
restart_policy: always
stop_timeout: 120
names: true
container_prefix: ainer
- name: Restart a container
containers.podman.podman_container:
name: myapplication
image: redis
state: started
restart: true
etc_hosts:
other: "127.0.0.1"
restart_policy: "no"
device: "/dev/sda:/dev/xvda:rwm"
ports:
- "8080:9000"
- "127.0.0.1:8081:9001/udp"
env:
SECRET_KEY: "ssssh"
BOOLEAN_KEY: "yes"
- name: Container present
containers.podman.podman_container:
name: mycontainer
state: present
image: ubuntu:14.04
command: "sleep 1d"
- name: Stop a container
containers.podman.podman_container:
name: mycontainer
state: stopped
- name: Start 4 load-balanced containers
containers.podman.podman_container:
name: "container{{ item }}"
recreate: true
image: someuser/anotherappimage
command: sleep 1d
with_sequence: count=4
- name: remove container
containers.podman.podman_container:
name: ohno
state: absent
- name: Writing output
containers.podman.podman_container:
name: myservice
image: busybox
log_options: path=/var/log/container/mycontainer.json
log_driver: k8s-file
- name: Run container with complex command with quotes
containers.podman.podman_container:
name: mycontainer
image: certbot/certbot
command:
- renew
- --deploy-hook
- "echo 1 > /var/lib/letsencrypt/complete"
- name: Create a Quadlet file
containers.podman.podman_container:
name: quadlet-container
image: nginx
state: quadlet
quadlet_filename: custome-container
quadlet_file_mode: '0640'
device: "/dev/sda:/dev/xvda:rwm"
ports:
- "8080:80"
volumes:
- "/var/www:/usr/share/nginx/html"
quadlet_options:
- "AutoUpdate=registry"
- "Pull=newer"
- |
[Install]
WantedBy=default.target
返回值
常见的返回值已在 此处 记录，以下是此模块特有的字段
键 |
描述 |
|---|---|
表示容器当前状态的事实。与 podman 检查输出匹配。 请注意，自 Ansible 2.8 起，事实是已注册变量的一部分。出于兼容性原因，事实也可以直接作为 如果 返回：始终 Sample: |