containers.podman.podman_pod – Manage Podman pods

Note

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

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.

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

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.

debug

boolean

Return additional information which can be helpful for investigations.

Choices:

  • no ← (default)

  • yes

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.

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”

generate_systemd

dictionary

Generate systemd unit file for container.

Default: {}

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:

  • no

  • yes ← (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:

  • no ← (default)

  • yes

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:

  • no ← (default)

  • yes

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”.

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

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.

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:

  • no

  • yes

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

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 comma-separated list of the names of CNI networks the pod should join.

no_hosts

boolean

Disable creation of /etc/hosts for the pod.

Choices:

  • no

  • yes

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.

recreate

boolean

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

Choices:

  • no ← (default)

  • yes

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

This variable is set for state

Choices:

  • created ← (default)

  • killed

  • restarted

  • absent

  • started

  • stopped

  • paused

  • unpaused

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

Description

pod

dictionary

Pod inspection results for the given pod built.

Returned: always

Sample: {“Config”: {“cgroupParent”: “/libpod_parent”, “created”: “2020-06-14T15:16:12.230818767+03:00”, “hostname”: “newpod”, “id”: “a5a5c6cdf8c72272fc5c33f787e8d7501e2fa0c1e92b2b602860defdafeeec58”, “infraConfig”: {“infraPortBindings”: null, “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)