containers.podman.podman_pod 模块 – 管理 Podman Pod

注意

此模块是 containers.podman 集合（版本 1.16.2）的一部分。

如果您正在使用 ansible 包，则可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install containers.podman。您需要其他要求才能使用此模块，有关详细信息，请参阅要求。

要在 Playbook 中使用它，请指定：containers.podman.podman_pod。

containers.podman 1.0.0 中的新功能

概要

• 管理 podman pod。

要求

执行此模块的主机需要满足以下要求。

• podman

参数

参数	注释
add_host 列表 / 元素=字符串	将主机添加到 pod 中所有容器之间共享的 /etc/hosts 文件。
blkio_weight 字符串	块 IO 相对权重。该权重是 10 到 1000 之间的值。 此选项在 cgroups V1 无根系统上不受支持。
blkio_weight_device 列表 / 元素=字符串	块 IO 相对设备权重。
cgroup_parent 字符串	用于创建 pod 的 cgroup 的 cgroups 路径。如果路径不是绝对路径，则该路径被认为是相对于 init 进程的 cgroups 路径。如果 cgroups 尚不存在，则会创建它们。
cpu_shares 字符串	CPU 份额（相对权重）。
cpus 字符串	设置委托给 pod 的 CPU 总数。默认为 0.000，表示计算能力没有限制。
cpuset_cpus 字符串	限制 CPU 以支持执行。第一个 CPU 编号为 0。与 `cpus` 不同，它的类型为字符串，并被解析为数字列表。格式为 0-3,0,1
cpuset_mems 字符串	允许执行的内存节点（0-3, 0,1）。仅在 NUMA 系统上有效。
debug 布尔值	返回有助于调查的附加信息。 选择 false ←（默认） true
device 列表 / 元素=字符串	将主机设备添加到 pod。可选的权限参数可用于指定设备权限。它是 r（读取）、w（写入）和 m（mknod(2)）的组合
device_read_bps 列表 / 元素=字符串	限制从设备读取的速率（每秒字节数）（例如，device-read-bps=/dev/sda:1mb）
device_write_bps 列表 / 元素=字符串	限制写入设备的速度（以每秒字节数为单位）。
dns 列表 / 元素=字符串	在 /etc/resolv.conf 文件中设置自定义 DNS 服务器，该文件将在 pod 中的所有容器之间共享。允许使用特殊选项“none”，该选项禁用为 pod 创建 /etc/resolv.conf。
dns_opt 别名：dns_option 列表 / 元素=字符串	在 /etc/resolv.conf 文件中设置自定义 DNS 选项，该文件将在 pod 中的所有容器之间共享。
dns_search 列表 / 元素=字符串	在 /etc/resolv.conf 文件中设置自定义 DNS 搜索域，该文件将在 pod 中的所有容器之间共享。
executable 字符串	如果 podman 可执行文件不在运行 podman 的机器上的 $PATH 中，则为 podman 可执行文件的路径 默认值： "podman"
exit_policy 字符串	设置最后一个容器退出时 pod 的退出策略。支持的策略为 stop 和 continue 选择 "stop" "continue"
generate_systemd 字典	为容器生成 systemd 单元文件。 默认值： {}
after 列表 / 元素=字符串	添加 systemd 单元 after (After=) 选项，该选项将此服务和依赖项列表之间的排序依赖项。
container_prefix 字符串	设置容器的 systemd 单元名称前缀。默认为“container”。
names 布尔值	在单元文件中使用容器的名称作为启动、停止和描述。默认为 true。 选择 false true ←（默认）
new 布尔值	在启动单元时创建容器和 pod，而不是期望它们存在。默认值为“false”。有关详细信息，请参阅 podman-generate-systemd(1)。 选择 false ←（默认） true
no_header 布尔值	不生成包含元数据（如 Podman 版本和时间戳）的标头。从 podman 版本 3.1.0 开始。 选择 false ←（默认） true
path 字符串	指定将生成单元文件的目录的路径。此选项是必需的。如果它不存在，将创建该目录。
pod_prefix 字符串	设置 pod 的 systemd 单元名称前缀。默认为“pod”。
requires 列表 / 元素=字符串	设置 systemd 单元 requires (Requires=) 选项。与 wants 类似，但声明了更强的依赖项要求。
restart_policy 字符串	指定服务的重启策略。重启策略必须是“no”、“on-success”、“on-failure”、“on-abnormal”、“on-watchdog”、“on-abort”或“always”之一。默认策略为“on-failure”。 选择 “no” “on-success” “on-failure” “on-abnormal” “on-watchdog” “on-abort” “always”
restart_sec 整数	设置 systemd 服务的 restartsec 值。
separator 字符串	设置容器/Pod 的名称/ID 和前缀之间的 systemd 单元名称分隔符。默认为“-”（破折号）。
start_timeout 整数	使用给定值覆盖容器的默认启动超时时间。
stop_timeout 别名: time 整数	使用给定值覆盖容器的默认停止超时时间。在版本 4 之前称为 `time`。
wants 列表 / 元素=字符串	添加 systemd 单元 wants (Wants=) 选项，表示此服务（弱）依赖于该选项。
gidmap 列表 / 元素=字符串	用户命名空间的 GID 映射。使用此标志将以启用用户命名空间的方式运行容器。它与 `userns` 和 `subgidname` 标志冲突。
gpus 字符串	要添加到容器的 GPU 设备（使用“all”传递所有 GPU）。
hostname 字符串	为 Pod 设置主机名
infra 布尔值	创建一个基础容器并将其与 Pod 关联。基础容器是一个轻量级容器，用于协调 Pod 的共享内核命名空间。默认为 true。 选择 false true
infra_command 字符串	将运行以启动基础容器的命令。默认为“/pause”。
infra_conmon_pidfile 字符串	将基础容器的 conmon 进程的 PID 写入文件。由于 conmon 在与 Podman 不同的进程中运行，因此当使用 systemd 管理 Podman 容器和 Pod 时，这是必要的。
infra_image 字符串	将为基础容器创建的镜像。默认为“k8s.gcr.io/pause:3.1”。
infra_name 字符串	将用于 Pod 的基础容器的名称。
ip 字符串	为 Pod 的共享网络设置静态 IP。
ip6 字符串	为 Pod 的共享网络设置静态 IPv6。
label 字典	将元数据添加到 Pod，传递标签键和值的字典。
label_file 字符串	读取以行分隔的标签文件。
mac_address 字符串	为 Pod 的共享网络设置静态 MAC 地址。
memory 字符串	设置内存限制。 单位可以是 b（字节）、k（千字节）、m（兆字节）或 g（吉字节）。
memory_swap 字符串	设置等于内存加交换区的限制值。 单位可以是 b（字节）、k（千字节）、m（兆字节）或 g（吉字节）。
name 字符串 / 必需	为 Pod 分配一个名称。
network 列表 / 元素=字符串	设置 Pod 的网络模式。支持的值包括 bridge（默认）、host（不创建网络命名空间，Pod 中的所有容器将使用主机网络）或要加入的 CNI 网络名称列表。
network_alias 别名: network_aliases 列表 / 元素=字符串	为 Pod 添加网络范围的别名，为 Pod 加入的所有网络设置别名。要仅为特定网络设置名称，请使用 -`network` 选项下描述的 alias 选项。网络别名仅适用于桥接网络模式。此选项可以多次指定。
no_hosts 布尔值	禁用为 Pod 创建 /etc/hosts。 选择 false true
pid 字符串	设置 Pod 的 PID 模式。默认情况下，为 Pod 创建一个私有 PID 命名空间。需要通过 `share` 选项共享 PID 命名空间。
pod_id_file 字符串	将 Pod ID 写入文件。
publish 别名: ports 列表 / 元素=字符串	将端口或端口范围从 Pod 发布到主机。
quadlet_dir path	写入 quadlet 文件的目录路径。默认情况下，对于 root 用户，它将设置为 /etc/containers/systemd/，对于非 root 用户，它将设置为 ~/.config/containers/systemd/。
quadlet_file_mode 任意	quadlet 文件的权限。 quadlet_file_mode 可以指定为八进制数字或符号模式（例如，u+rwx 或 u=rw,g=r,o=r）。对于八进制数字格式，您必须添加前导零，以便 Ansible 的 YAML 解析器知道它是八进制数字（如 0644 或 01777），或者将其用引号引起来（如 '644' 或 '1777'），以便 Ansible 接收字符串并可以执行其自己的从字符串到数字的转换。如果 Ansible 获得的数字没有遵循这些规则之一，最终将得到一个十进制数，这将产生意想不到的结果。 如果未指定 quadlet_file_mode 且 quadlet 文件 不存在，则在设置新创建文件的模式时，将使用系统上的默认 umask。 如果未指定 quadlet_file_mode 且 quadlet 文件 存在，则将使用现有文件的模式。 指定 quadlet_file_mode 是确保使用正确权限创建文件的最佳方法。
quadlet_filename 字符串	要写入的 quadlet 文件名。默认情况下，它采用 name 值。
quadlet_options 列表 / 元素=字符串	quadlet 文件的选项。提供通常的容器参数选项中缺少的选项，作为要添加的行列表。
recreate 布尔值	与 present 和 started 状态一起使用，以强制重新创建现有的 Pod。 选择 false ←（默认） true
restart_policy 字符串	容器退出时要遵循的重启策略。
security_opt 列表 / 元素=字符串	Pod 的安全选项。
share 字符串	要共享的内核命名空间的逗号分隔列表。如果指定 none 或 ""，则不会共享任何命名空间。可供选择的命名空间有 ipc、net、pid、user、uts。
share_parent 布尔值	此布尔值确定所有进入 Pod 的容器是否使用 Pod 作为其 cgroup 父级。Podman 中此选项的默认值为 true。 选择 false true
shm_size 字符串	设置 /dev/shm 共享内存空间的大小。单位可以是 b（字节）、k（千字节）、m（兆字节）或 g（吉字节）。如果省略单位，则系统使用字节。如果省略大小，则默认值为 64m。当大小为 0 时，Pod 用于 IPC 的内存量没有限制。
shm_size_systemd 字符串	systemd 特有的 tmpfs 挂载的大小，例如 /run、/run/lock、/var/log/journal 和 /tmp。单位可以是 b（字节）、k（千字节）、m（兆字节）或 g（吉字节）。如果省略单位，则系统使用字节。如果省略大小，则默认值为 64m。当大小为 0 时，使用量限制为宿主机可用内存的 50%。
state 字符串	此变量设置为 state 选择 "created" ← （默认） “killed” “restarted” “absent” “started” “stopped” “paused” “unpaused” “quadlet”
subgidname 字符串	来自 /etc/subgid 文件的 GID 映射名称。使用此标志将以启用用户命名空间的方式运行容器。此标志与 `userns` 和 `gidmap` 冲突。
subuidname 字符串	来自 /etc/subuid 文件的 UID 映射名称。使用此标志将以启用用户命名空间的方式运行容器。此标志与 `userns` 和 `uidmap` 冲突。
sysctl 字典	为 Pod 设置内核参数。
uidmap 列表 / 元素=字符串	使用提供的映射在新用户命名空间中运行容器。此选项与 `userns` 和 `subuidname` 选项冲突。此选项提供了一种将主机 UID 映射到容器 UID 的方法。它可以传递多次以映射不同的范围。
userns 字符串	为 Pod 中的所有容器设置用户命名空间模式。它默认为 PODMAN_USERNS 环境变量。空值（“”）表示禁用用户命名空间。
uts 字符串	设置 Pod 的 UTS 命名空间模式。
volume 别名: volumes 列表 / 元素=字符串	创建一个绑定挂载。
volumes_from 列表 / 元素=字符串	从指定的容器挂载卷。

示例

# What modules does for example
- containers.podman.podman_pod:
    name: pod1
    state: started
    ports:
      - "4444:5555"

# Connect random port from localhost to port 80 on pod2
- name: Connect random port from localhost to port 80 on pod2
  containers.podman.podman_pod:
    name: pod2
    state: started
    publish: "127.0.0.1::80"

# Full workflow example with pod and containers
- name: Create a pod with parameters
  containers.podman.podman_pod:
    name: mypod
    state: created
    network: host
    share: net
    userns: auto
    security_opt:
      - seccomp=unconfined
      - apparmor=unconfined
    hostname: mypod
    dns:
      - 1.1.1.1
    volumes:
      - /tmp:/tmp/:ro
    label:
      key: cval
      otherkey: kddkdk
      somekey: someval
    add_host:
      - "google:5.5.5.5"

- name: Create containers attached to the pod
  containers.podman.podman_container:
    name: "{{ item }}"
    state: created
    pod: mypod
    image: alpine
    command: sleep 1h
    loop:
      - "container1"
      - "container2"

- name: Start pod
  containers.podman.podman_pod:
    name: mypod
    state: started
    network: host
    share: net
    userns: auto
    security_opt:
      - seccomp=unconfined
      - apparmor=unconfined
    hostname: mypod
    dns:
      - 1.1.1.1
    volumes:
      - /tmp:/tmp/:ro
    label:
      key: cval
      otherkey: kddkdk
      somekey: someval
    add_host:
      - "google:5.5.5.5"

# Create a Quadlet file for a pod
- containers.podman.podman_pod:
    name: qpod
    state: quadlet
    ports:
      - "4444:5555"
    volume:
      - /var/run/docker.sock:/var/run/docker.sock
    quadlet_dir: /custom/dir

返回值

通用返回值记录在此处，以下是此模块独有的字段

键

描述

pod 字典

为给定的构建 Pod 提供的 Pod 检查结果。 返回: 始终 示例: {"CgroupParent": "user.slice", "CgroupPath": "user.slice/user-1000.slice/[email protected]/user.slice/....slice", "Containers": [{"Id": "37f960e6c8accc6b5b41945b1dcf03a28d3a366f7f37049748f18b21c44f577e", "Name": "a99a49b8fa77-infra", "State": "created"}], "CreateCgroup": true, "CreateCommand": ["podman", "pod", "create", "--name", "pod_name", "--infra=True", "--userns", "auto", "--security-opt", "seccomp=unconfined", "--security-opt", "apparmor=unconfined", "--hostname", "mypod", "--dns", "1.1.1.2", "--label", "key=cval", "--label", "otherkey=kddkdk", "--label", "somekey=someval", "--add-host", "google:5.5.5.5", "--volume", "/tmp/test//:/data2"], "CreateInfra": true, "Created": "2024-05-28T20:41:09.946926613+03:00", "ExitPolicy": "continue", "Hostname": "mypod", "Id": "a99a41b8fa77d8c7ff1c432a7a21bc0c2afd8c13b94a9d9b9b19b66ae97920c1", "InfraConfig": {"DNSOption": null, "DNSSearch": null, "DNSServer": ["1.1.1.2"], "HostAdd": ["google:5.5.5.5"], "HostNetwork": false, "NetworkOptions": null, "Networks": null, "NoManageHosts": false, "NoManageResolvConf": false, "PortBindings": {}, "StaticIP": "", "StaticMAC": "", "pid_ns": "private", "userns": "host", "uts_ns": "private"}, "InfraContainerID": "37f960e6c8accc6b5b41945b1dcf03a28d3a366f7f37049748f18b21c44f577e", "Labels": {"key": "cval", "otherkey": "kddkdk", "somekey": "someval"}, "LockNumber": 1, "Name": "pod_name", "NumContainers": 1, "SharedNamespaces": ["user", "uts", "ipc", "net"], "State": "Created", "mounts": [{"Destination": "/data2", "Driver": "", "Mode": "", "Options": ["nosuid", "nodev", "rbind"], "Propagation": "rprivate", "RW": true, "Source": "/tmp/test", "Type": "bind"}], "security_opt": ["seccomp=unconfined", "apparmor=unconfined"]}

作者

• Sagi Shnaidman (@sshnaidm)

集合链接

• 问题跟踪器
• 存储库 (源代码)