containers.podman.podman_pod – Manage Podman pods

Note

This plugin is part of the containers.podman collection (version 1.10.1).

To install it use: ansible-galaxy collection install containers.podman.

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

New in version 1.0.0: of containers.podman

Synopsis

  • Manage podman pods.

Requirements

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

  • podman

Parameters

Parameter Choices/Defaults Comments
add_host
list / elements=string
Add a host to the /etc/hosts file shared between all containers in the pod.
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.
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
debug
boolean
    Choices:
  • no ←
  • yes
Return additional information which can be helpful for investigations.
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)
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
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
Default:
"podman"
Path to podman executable if it is not in the $PATH on the machine running podman
generate_systemd
dictionary
Default:
{}
Generate systemd unit file for container.
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
    Choices:
  • no
  • yes ←
Use names of the containers for the start, stop, and description in the unit file. Default is true.
new
boolean
    Choices:
  • no ←
  • yes
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.
no_header
boolean
    Choices:
  • no ←
  • yes
Do not generate the header including meta data such as the Podman version and the timestamp. From podman version 3.1.0.
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
    Choices:
  • no
  • on-success
  • on-failure
  • on-abnormal
  • on-watchdog
  • on-abort
  • always
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".
separator
string
Set the systemd unit name separator between the name/id of a container/pod and the prefix. The default is "-" (dash).
time
integer
Override the default stop timeout for the container with the given value.
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.
hostname
string
Set a hostname to the pod
infra
boolean
    Choices:
  • no
  • yes
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.
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.
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.
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
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.

aliases: network_aliases
no_hosts
boolean
    Choices:
  • no
  • yes
Disable creation of /etc/hosts for the pod.
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
list / elements=string
Publish a port or range of ports from the pod to the host.

aliases: ports
recreate
boolean
    Choices:
  • no ←
  • yes
Use with present and started states to force the re-creation of an existing 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.
state
string
    Choices:
  • created ←
  • killed
  • restarted
  • absent
  • started
  • stopped
  • paused
  • unpaused
This variable is set for state
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`.
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.
volume
list / elements=string
Create a bind mount.

aliases: volumes

Examples

# What modules does for example
- 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"

Return Values

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

Key Returned Description
pod
dictionary
always
Pod inspection results for the given pod built.

Sample:
{'Config': {'cgroupParent': '/libpod_parent', 'created': '2020-06-14T15:16:12.230818767+03:00', 'hostname': 'newpod', 'id': 'a5a5c6cdf8c72272fc5c33f787e8d7501e2fa0c1e92b2b602860defdafeeec58', 'infraConfig': {'infraPortBindings': None, 'makeInfraContainer': True}, 'labels': {}, 'lockID': 515, 'name': 'newpod', 'sharesCgroup': True, 'sharesIpc': True, 'sharesNet': True, 'sharesUts': True}, 'Containers': [{'id': 'dc70a947c7ae15198ec38b3c817587584085dee3919cbeb9969e3ab77ba10fd2', 'state': 'configured'}], 'State': {'cgroupPath': '/libpod_parent/a5a5c6cdf8c72272fc5c33f787e8d7501e2fa0c1e92b2b602860defdafeeec58', 'infraContainerID': 'dc70a947c7ae15198ec38b3c817587584085dee3919cbeb9969e3ab77ba10fd2', 'status': 'Created'}}


Authors

  • Sagi Shnaidman (@sshnaidm)