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 的 cgroup 路径。如果路径不是绝对路径，则该路径被认为是相对于 init 进程的 cgroup 路径。如果 cgroup 尚不存在，则会创建它们。 |
|
将在其下创建容器的 cgroup 的 cgroup 路径。 |
|
确定容器是否会创建 CGroup。有效值为 enabled 和 disabled，默认值为 enabled。disabled 选项将强制容器不创建 CGroup，因此与 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 系统上有效。 |
|
返回有助于调查的附加信息。 选项
|
|
用于解密映像的“密钥密码”。密钥可以指向密钥和/或证书。 |
|
删除所选容器并递归删除所有依赖于它的容器。适用于“delete”命令。 选项
|
|
强制停止容器前等待的秒数。使用 -1 表示无限等待。适用于“delete”命令。 |
|
删除与容器关联的匿名卷。这不包括使用 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） |
|
限制设备读取速率（每秒 IO 数）（例如 device-read-iops /dev/sda:1000） |
|
限制写入设备（例如 device-write-bps /dev/sda:1mb）的速率（每秒字节数） |
|
限制写入设备（例如 device-write-iops /dev/sda:1000）的速率（每秒 IO 数） |
|
设置自定义 DNS 服务器 |
|
设置自定义 DNS 选项 |
|
设置自定义 DNS 搜索域（如果不想设置搜索域，请将 dns_search 设置为 ''） |
|
覆盖镜像的默认 ENTRYPOINT |
|
设置环境变量。此选项允许您指定任意环境变量，这些变量可用于容器内部启动的进程。 |
|
读取以换行符分隔的环境变量文件。不支持幂等性。如果用户更改了包含环境变量的文件，则需要用户重新创建容器。该文件必须位于运行 podman 的远程计算机上，而不是 Ansible 执行的控制器计算机上。如果需要将文件从控制器复制到远程计算机，请使用 copy 或 slurp 模块。 |
|
在容器中使用所有当前主机环境变量。默认为 false。 选项
|
|
预处理容器的默认环境变量 |
|
主机到 IP 的映射字典，其中每个主机名都是字典中的一个键。每个主机名都将添加到容器的 ``/etc/hosts`` 文件中。 |
|
如果 默认值: |
|
暴露一个端口或一系列端口（例如，暴露 “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 之前称为 `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，该 init 会转发信号并回收进程。默认值为 false。 选项
|
|
（仅限 Pod）。当使用 Pod 时，创建一个 init 风格的容器，该容器在启动基础容器之后但在启动常规 Pod 容器之前运行。 选项
|
|
container-init 二进制文件的路径。 |
|
即使未附加，也保持 STDIN 打开。默认值为 false。当设置为 true 时，即使未附加，也保持 stdin 打开。默认值为 false。 选项
|
|
为容器指定静态 IP 地址，例如 ‘10.88.64.128’。只有当未通过 'network:' 指定要加入的其他 CNI 网络，并且容器没有通过 'network container: |
|
为容器指定静态 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，其中单位 = b、k、m 或 g）。注意 - 仅对整数支持幂等性。 |
|
内存软限制（格式为 100m，其中单位 = b、k、m 或 g）。注意 - 仅对整数支持幂等性。 |
|
等于内存加交换空间的限制值。必须与 -m (–memory) 标志一起使用。交换限制应始终大于 -m (–memory) 值。默认情况下，交换限制将设置为 –memory 值的两倍。注意 - 仅对整数支持幂等性。 |
|
调整容器的内存交换行为。接受 0 到 100 之间的整数。 |
|
将文件系统挂载到容器。绑定或 tmpfs。例如，挂载 "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。当容器在具有 infra-container 的 pod 中运行时，infra-container 将首先启动。 |
|
将逗号分隔列表中指定的其他文件描述符传递给进程。 |
|
将 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>。数字必须大于 0。单位是可选的，可以是 b（字节）、k（千字节）、m（兆字节）或 g（千兆字节）。如果省略单位，则系统使用字节。如果完全省略大小，则系统使用 64m |
|
系统特定的 tmpfs 挂载的大小，如 /run、/run/lock、/var/log/journal 和 /tmp。 |
|
将发送到 podman run 命令的信号代理到容器进程。不会代理 SIGCHLD、SIGSTOP 和 SIGKILL。默认值为 true。 选项
|
|
absent - 将停止并删除与指定名称匹配的容器。 present - 断言存在与名称和任何提供的配置参数匹配的容器。如果没有容器与名称匹配，将创建容器。如果容器与名称匹配，但提供的配置不匹配，则将更新容器（如果可以）。如果无法更新，将删除该容器并使用请求的配置重新创建。比较配置时会考虑镜像版本。使用 recreate 选项强制重新创建匹配的容器。 started - 断言存在与名称和任何提供的配置匹配的正在运行的容器。如果没有容器与名称匹配，将创建并启动容器。使用 recreate 始终重新创建匹配的容器，即使它正在运行。使用 force_restart 强制停止并重新启动匹配的容器。 stopped - 断言容器首先为 _present_，然后如果容器正在运行，则将其移动到停止状态。 创建 - 断言容器存在并具有给定的配置。如果容器不存在，则模块会创建它并将其保持在“创建”状态。如果配置不匹配或设置了“重新创建”选项，则将重新创建容器。 quadlet - 使用指定的配置写入一个 quadlet 文件。 选项
|
|
用于停止容器的信号。默认为 SIGTERM。 |
|
强制停止容器前等待的秒数。使用 -1 表示无限等待。应用于“已停止”状态。 |
|
停止容器的超时时间（以秒为单位）。默认为 10。 |
|
使用 /etc/subgid 文件中具有“名称”的映射，在新的用户命名空间中运行容器。 |
|
使用 /etc/subuid 文件中具有“名称”的映射，在新的用户命名空间中运行容器。 |
|
在运行时配置命名空间的内核参数 |
|
在 systemd 模式下运行容器。默认为 true。 |
|
在 conmon 发送 kill 信号之前，允许容器运行的最长时间（以秒为单位）。默认情况下，容器会运行直到退出或被“podman stop”停止。 |
|
在容器中设置时区。此标志采用基于区域的时区、GMT 时间以及本地时间，这将容器中的时区设置为与主机匹配。有关有效的时区，请参见 /usr/share/zoneinfo/。远程连接使用本地 containers.conf 中的默认值。 |
|
拉取镜像时需要 HTTPS 并验证证书。 选项
|
|
创建 tmpfs 挂载。例如：tmpfs “/tmp” “rw,size=787448k,mode=1777” |
|
分配一个伪终端。默认为 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 开始，事实是已注册的 vars 的一部分。出于兼容性原因，事实也可以直接作为 如果 返回: 始终 Sample: |