containers.podman.podman_pod module – Manage Podman pods
Note
This module is part of the containers.podman collection (version 1.16.2).
You might already have this collection installed if you are using the ansible package.
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 a host to the /etc/hosts file shared between all containers in the pod. |
|
Block IO relative weight. The weight is a value between 10 and 1000. This option is not supported on cgroups V1 rootless systems. |
|
Block IO relative device weight. |
|
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 (relative weight). |
|
Set the total number of CPUs delegated to the pod. Default is 0.000 which indicates that there is no limit on computation power. |
|
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 |
|
Memory nodes in which to allow execution (0-3, 0,1). Only effective on NUMA systems. |
|
Return additional information which can be helpful for investigations. Choices:
|
|
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) |
|
Limit read rate (bytes per second) from a device (e.g. device-read-bps=/dev/sda:1mb) |
|
Limit write rate (in bytes per second) to a device. |
|
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. |
|
Set custom DNS options in the /etc/resolv.conf file that will be shared between all containers in the pod. |
|
Set custom DNS search domains in the /etc/resolv.conf file that will be shared between all containers in the pod. |
|
Path to Default: |
|
Set the exit policy of the pod when the last container exits. Supported policies are stop and continue Choices:
|
|
Generate systemd unit file for container. Default: |
|
Add the systemd unit after (After=) option, that ordering dependencies between the list of dependencies and this service. |
|
Set the systemd unit name prefix for containers. The default is “container”. |
|
Use names of the containers for the start, stop, and description in the unit file. Default is true. Choices:
|
|
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:
|
|
Do not generate the header including meta data such as the Podman version and the timestamp. From podman version 3.1.0. Choices:
|
|
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. |
|
Set the systemd unit name prefix for pods. The default is “pod”. |
|
Set the systemd unit requires (Requires=) option. Similar to wants, but declares a stronger requirement dependency. |
|
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:
|
|
Set the systemd service restartsec value. |
|
Set the systemd unit name separator between the name/id of a container/pod and the prefix. The default is “-” (dash). |
|
Override the default start timeout for the container with the given value. |
|
Override the default stop timeout for the container with the given value. Called `time` before version 4. |
|
Add the systemd unit wants (Wants=) option, that this service is (weak) dependent on. |
|
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. |
|
GPU devices to add to the container (‘all’ to pass all GPUs). |
|
Set a hostname to the pod |
|
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:
|
|
The command that will be run to start the infra container. Default is “/pause”. |
|
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. |
|
The image that will be created for the infra container. Default is “k8s.gcr.io/pause:3.1”. |
|
The name that will be used for the pod’s infra container. |
|
Set a static IP for the pod’s shared network. |
|
Set a static IPv6 for the pod’s shared network. |
|
Add metadata to a pod, pass dictionary of label keys and values. |
|
Read in a line delimited file of labels. |
|
Set a static MAC address for the pod’s shared network. |
|
Set memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes). |
|
Set limit value equal to memory plus swap. A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes). |
|
Assign a name to the pod. |
|
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. |
|
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. |
|
Disable creation of /etc/hosts for the pod. Choices:
|
|
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. |
|
Write the pod ID to the file. |
|
Publish a port or range of ports from the pod to the host. |
|
Path to the directory to write quadlet file in. By default, it will be set as |
|
The permissions of the quadlet file. The If If Specifying |
|
Name of quadlet file to write. By default it takes name value. |
|
Options for the quadlet file. Provide missing in usual container args options as a list of lines to add. |
|
Use with present and started states to force the re-creation of an existing pod. Choices:
|
|
Restart policy to follow when containers exit. |
|
Security options for the pod. |
|
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. |
|
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:
|
|
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. |
|
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. |
|
This variable is set for state Choices:
|
|
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`. |
|
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`. |
|
Set kernel parameters for the pod. |
|
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. |
|
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. |
|
Set the UTS namespace mode for the pod. |
|
Create a bind mount. |
|
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 inspection results for the given pod built. Returned: always Sample: |