# containers.podman.podman_pod module – Manage Podman pods

Note

This module is part of the containers.podman collection (version 1.16.2).

It is not included in `ansible-core`. To check whether it is installed, run `ansible-galaxy collection list`.

To install it, use: `ansible-galaxy collection install containers.podman`. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: `containers.podman.podman_pod`.

New in containers.podman 1.0.0

## Synopsis

- Manage podman pods.

## Requirements

The below requirements are needed on the host that executes this module.

- podman

## Parameters

Parameter | Comments
--- | ---
add_host list / elements=string | Add a host to the /etc/hosts file shared between all containers in the pod.
blkio_weight string | Block IO relative weight. The weight is a value between 10 and 1000. This option is not supported on cgroups V1 rootless systems.
blkio_weight_device list / elements=string | Block IO relative device weight.
cgroup_parent string | Path to cgroups under which the cgroup for the pod will be created. If the path is not absolute, he path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist.
cpu_shares string | CPU shares (relative weight).
cpus string | Set the total number of CPUs delegated to the pod. Default is 0.000 which indicates that there is no limit on computation power.
cpuset_cpus string | Limit the CPUs to support execution. First CPU is numbered 0. Unlike `cpus` this is of type string and parsed as a list of numbers. Format is 0-3,0,1
cpuset_mems string | Memory nodes in which to allow execution (0-3, 0,1). Only effective on NUMA systems.

debug

boolean

Return additional information which can be helpful for investigations.

Choices:

- `false` ← (default)

- `true`

device list / elements=string | Add a host device to the pod. Optional permissions parameter can be used to specify device permissions. It is a combination of r for read, w for write, and m for mknod(2)
device_read_bps list / elements=string | Limit read rate (bytes per second) from a device (e.g. device-read-bps=/dev/sda:1mb)
device_write_bps list / elements=string | Limit write rate (in bytes per second) to a device.
dns list / elements=string | Set custom DNS servers in the /etc/resolv.conf file that will be shared between all containers in the pod. A special option, “none” is allowed which disables creation of /etc/resolv.conf for the pod.
dns_opt aliases: dns_option list / elements=string | Set custom DNS options in the /etc/resolv.conf file that will be shared between all containers in the pod.
dns_search list / elements=string | Set custom DNS search domains in the /etc/resolv.conf file that will be shared between all containers in the pod.
executable string | Path to `podman` executable if it is not in the `$PATH` on the machine running `podman` Default: `"podman"`

exit_policy

string

Set the exit policy of the pod when the last container exits. Supported policies are stop and continue

Choices:

- `"stop"`

- `"continue"`

generate_systemd dictionary | Generate systemd unit file for container. Default: `{}`
after list / elements=string | Add the systemd unit after (After=) option, that ordering dependencies between the list of dependencies and this service.
container_prefix string | Set the systemd unit name prefix for containers. The default is “container”.

names

boolean

Use names of the containers for the start, stop, and description in the unit file. Default is true.

Choices:

- `false`

- `true` ← (default)

new

boolean

Create containers and pods when the unit is started instead of expecting them to exist. The default is “false”. Refer to podman-generate-systemd(1) for more information.

Choices:

- `false` ← (default)

- `true`

no_header

boolean

Do not generate the header including meta data such as the Podman version and the timestamp. From podman version 3.1.0.

Choices:

- `false` ← (default)

- `true`

path string | Specify a path to the directory where unit files will be generated. Required for this option. If it doesn’t exist, the directory will be created.
pod_prefix string | Set the systemd unit name prefix for pods. The default is “pod”.
requires list / elements=string | Set the systemd unit requires (Requires=) option. Similar to wants, but declares a stronger requirement dependency.

restart_policy

string

Specify a restart policy for the service. The restart-policy must be one of “no”, “on-success”, “on-failure”, “on-abnormal”, “on-watchdog”, “on-abort”, or “always”. The default policy is “on-failure”.

Choices:

- `"no"`

- `"on-success"`

- `"on-failure"`

- `"on-abnormal"`

- `"on-watchdog"`

- `"on-abort"`

- `"always"`

restart_sec integer | Set the systemd service restartsec value.
separator string | Set the systemd unit name separator between the name/id of a container/pod and the prefix. The default is “-” (dash).
start_timeout integer | Override the default start timeout for the container with the given value.
stop_timeout aliases: time integer | Override the default stop timeout for the container with the given value. Called `time` before version 4.
wants list / elements=string | Add the systemd unit wants (Wants=) option, that this service is (weak) dependent on.
gidmap list / elements=string | GID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `userns` and `subgidname` flags.
gpus string | GPU devices to add to the container (‘all’ to pass all GPUs).
hostname string | Set a hostname to the pod

infra

boolean

Create an infra container and associate it with the pod. An infra container is a lightweight container used to coordinate the shared kernel namespace of a pod. Default is true.

Choices:

- `false`

- `true`

infra_command string | The command that will be run to start the infra container. Default is “/pause”.
infra_conmon_pidfile string | Write the pid of the infra container’s conmon process to a file. As conmon runs in a separate process than Podman, this is necessary when using systemd to manage Podman containers and pods.
infra_image string | The image that will be created for the infra container. Default is “k8s.gcr.io/pause:3.1”.
infra_name string | The name that will be used for the pod’s infra container.
ip string | Set a static IP for the pod’s shared network.
ip6 string | Set a static IPv6 for the pod’s shared network.
label dictionary | Add metadata to a pod, pass dictionary of label keys and values.
label_file string | Read in a line delimited file of labels.
mac_address string | Set a static MAC address for the pod’s shared network.
memory string | Set memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).
memory_swap string | Set limit value equal to memory plus swap. A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).
name string / required | Assign a name to the pod.
network list / elements=string | Set network mode for the pod. Supported values are bridge (the default), host (do not create a network namespace, all containers in the pod will use the host’s network), or a list of names of CNI networks to join.
network_alias aliases: network_aliases list / elements=string | Add a network-scoped alias for the pod, setting the alias for all networks that the pod joins. To set a name only for a specific network, use the alias option as described under the -`network` option. Network aliases work only with the bridge networking mode. This option can be specified multiple times.

no_hosts

boolean

Disable creation of /etc/hosts for the pod.

Choices:

- `false`

- `true`

pid string | Set the PID mode for the pod. The default is to create a private PID namespace for the pod. Requires the PID namespace to be shared via `share` option.
pod_id_file string | Write the pod ID to the file.
publish aliases: ports list / elements=string | Publish a port or range of ports from the pod to the host.
quadlet_dir path | Path to the directory to write quadlet file in. By default, it will be set as `/etc/containers/systemd/` for root user, `~/.config/containers/systemd/` for non-root users.

quadlet_file_mode

any

The permissions of the quadlet file.

The `quadlet_file_mode` can be specied as octal numbers or as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). For octal numbers format, you must either add a leading zero so that Ansible’s YAML parser knows it is an octal number (like `0644` or `01777`) or quote it (like `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results.

If `quadlet_file_mode` is not specified and the quadlet file does not exist, the default `umask` on the system will be used when setting the mode for the newly created file.

If `quadlet_file_mode` is not specified and the quadlet file does exist, the mode of the existing file will be used.

Specifying `quadlet_file_mode` is the best way to ensure files are created with the correct permissions.

quadlet_filename string | Name of quadlet file to write. By default it takes name value.
quadlet_options list / elements=string | Options for the quadlet file. Provide missing in usual container args options as a list of lines to add.

recreate

boolean

Use with present and started states to force the re-creation of an existing pod.

Choices:

- `false` ← (default)

- `true`

restart_policy string | Restart policy to follow when containers exit.
security_opt list / elements=string | Security options for the pod.
share string | A comma delimited list of kernel namespaces to share. If none or “” is specified, no namespaces will be shared. The namespaces to choose from are ipc, net, pid, user, uts.

share_parent

boolean

This boolean determines whether or not all containers entering the pod use the pod as their cgroup parent. The default value of this option in Podman is true.

Choices:

- `false`

- `true`

shm_size string | Set the size of the /dev/shm shared memory space. A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes). If the unit is omitted, the system uses bytes. If the size is omitted, the default is 64m. When size is 0, there is no limit on the amount of memory used for IPC by the pod.
shm_size_systemd string | Size of systemd-specific tmpfs mounts such as /run, /run/lock, /var/log/journal and /tmp. A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes). If the unit is omitted, the system uses bytes. If the size is omitted, the default is 64m. When size is 0, the usage is limited to 50 percents of the host’s available memory.

state

string

This variable is set for state

Choices:

- `"created"` ← (default)

- `"killed"`

- `"restarted"`

- `"absent"`

- `"started"`

- `"stopped"`

- `"paused"`

- `"unpaused"`

- `"quadlet"`

subgidname string | Name for GID map from the /etc/subgid file. Using this flag will run the container with user namespace enabled. This flag conflicts with `userns` and `gidmap`.
subuidname string | Name for UID map from the /etc/subuid file. Using this flag will run the container with user namespace enabled. This flag conflicts with `userns` and `uidmap`.
sysctl dictionary | Set kernel parameters for the pod.
uidmap list / elements=string | Run the container in a new user namespace using the supplied mapping. This option conflicts with the `userns` and `subuidname` options. This option provides a way to map host UIDs to container UIDs. It can be passed several times to map different ranges.
userns string | Set the user namespace mode for all the containers in a pod. It defaults to the PODMAN_USERNS environment variable. An empty value (“”) means user namespaces are disabled.
uts string | Set the UTS namespace mode for the pod.
volume aliases: volumes list / elements=string | Create a bind mount.
volumes_from list / elements=string | Mount volumes from the specified container.

## Examples

    # 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

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Description
--- | ---

pod

dictionary

Pod inspection results for the given pod built.

Returned: always

Sample: `{"CgroupParent": "user.slice", "CgroupPath": "user.slice/user-1000.slice/user@1000.service/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"]}`

### Authors

- Sagi Shnaidman (@sshnaidm)

### Collection links

- Issue Tracker
- Repository (Sources)