podman pod

PodCLI

create

create(name=None, *, add_hosts=(), cgroup_parent=None, cpus=None, cpuset_cpus=None, devices=(), device_read_bps=(), dns=(), dns_options=(), dns_search=(), exit_policy=None, gidmaps=(), hostname=None, infra=None, infra_command=None, infra_conmon_pidfile=None, infra_image=None, infra_name=None, ip=None, ip6=None, labels={}, label_files=(), mac_address=None, memory=None, networks=(), network_aliases=(), no_hosts=False, pid=None, pod_id_file=None, publish=(), replace=False, restart=None, security_options=(), share=None, shm_size=None, subgidname=None, subuidname=None, sysctl={}, uidmaps=(), userns=None, uts=None, volumes=(), volumes_from=())

Creates a pod, but does not start it.

Start it then with the .start() method.

PARAMETER	DESCRIPTION
`name`	The name to set the pod to. If not specified a name is generated. TYPE: `Optional[str]` DEFAULT: `None`
`add_hosts`	Add a custom host-to-IP mapping (format 'host:ip'), which adds a line to /etc/hosts. Conflicts with the no_hosts option. TYPE: `Iterable[Tuple[str, str]]` DEFAULT: `()`
`cgroup_parent`	Path to cgroups under which the cgroup for the pod is created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. TYPE: `Optional[str]` DEFAULT: `None`
`cpus`	Set the total number of CPUs delegated to the pod. The default is 0.0 indicating that there is no limit on computation power. TYPE: `Optional[float]` DEFAULT: `None`
`cpuset_cpus`	CPUs in which to allow execution. TYPE: `Optional[Iterable[int]]` DEFAULT: `None`
`devices`	List of device names to pass from the host to containers in the pod. TYPE: `Iterable[str]` DEFAULT: `()`
`device_read_bps`	Limit read rate (in bytes per second) from a device (e.g. device_read_bps=/dev/sda:1mb). TYPE: `Iterable[str]` DEFAULT: `()`
`dns`	Set custom DNS servers in the /etc/resolv.conf file that is shared between all containers in the pod. TYPE: `Iterable[str]` DEFAULT: `()`
`dns_options`	Set custom DNS options in the /etc/resolv.conf file that is shared between all containers in the pod. TYPE: `Iterable[str]` DEFAULT: `()`
`dns_search`	Set custom DNS search domains in the /etc/resolv.conf file that is shared between all containers in the pod. TYPE: `Iterable[str]` DEFAULT: `()`
`exit_policy`	Set the exit policy of the pod when the last container exits. Supported policies are 'continue' (default) and 'stop'. TYPE: `Optional[str]` DEFAULT: `None`
`gidmaps`	GID map for the user namespace. Using this flag runs all containers in the pod with user namespace enabled. It conflicts with the --userns and --subgidname flags. TYPE: `Iterable[Tuple[int, int, int]]` DEFAULT: `()`
`hostname`	Set the pod's hostname. TYPE: `Optional[str]` DEFAULT: `None`
`infra`	Whether to 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. TYPE: `Optional[bool]` DEFAULT: `None`
`infra_command`	Specify the command that is run to start the infra container. TYPE: `Optional[str]` DEFAULT: `None`
`infra_conmon_pidfile`	Write the pid of the infra container's conmon process to a file. TYPE: `Optional[ValidPath]` DEFAULT: `None`
`infra_image`	The custom image that is used for the infra container. TYPE: `Optional[ValidImage]` DEFAULT: `None`
`infra_name`	The name that is used for the pod's infra container. TYPE: `Optional[str]` DEFAULT: `None`
`ip`	Specify a static IPv4 address for the pod, for example 10.88.64.128. This option can only be used if the pod is joined to only a single network - i.e., network=network-name is used at most once - and if the pod is not joining another container's network namespace via network=container:id. The address must be within the network's IP address pool (default 10.88.0.0/16). TYPE: `Optional[str]` DEFAULT: `None`
`ip6`	Specify a static IPv6 address for the pod, for example fd46:db93:aa76:ac37::10. This option can only be used if the pod is joined to only a single network (see note on the ip argument). The address must be within the network's IPv6 address pool. TYPE: `Optional[str]` DEFAULT: `None`
`labels`	Add metadata labels to a pod. TYPE: `Mapping[str, str]` DEFAULT: `{}`
`label_files`	Read in a line-delimited file of labels. TYPE: `Iterable[ValidPath]` DEFAULT: `()`
`mac_address`	Pod network interface MAC address (e.g. 92:d0:c6:0a:29:33). This option can only be used if the pod is joined to only a single network (see note on the ip argument). TYPE: `Optional[str]` DEFAULT: `None`
`memory`	Memory limit for the pod. TYPE: `Union[int, str, None]` DEFAULT: `None`
`networks`	Specify networks to use for the pod. TYPE: `Iterable[ValidNetwork]` DEFAULT: `()`
`network_aliases`	Add network-scoped aliases for the pod, setting the alias for all networks that the container joins. TYPE: `Iterable[str]` DEFAULT: `()`
`no_hosts`	Do not create /etc/hosts for the pod. This option conflicts with --add-host. TYPE: `bool` DEFAULT: `False`
`pid`	Set the PID mode for the pod. The default is to create a private PID namespace for the pod. TYPE: `Optional[str]` DEFAULT: `None`
`pod_id_file`	Write the pod ID to the specified file. TYPE: `Optional[ValidPath]` DEFAULT: `None`
`publish`	Publish a container's port, or range of ports, within this pod to the host. TYPE: `Iterable[ValidPortMapping]` DEFAULT: `()`
`replace`	If another pod with the same name already exists, replace and remove it. TYPE: `bool` DEFAULT: `False`
`restart`	Restart policy for containers in the pod. TYPE: `Optional[str]` DEFAULT: `None`
`security_options`	Security options (AppArmor or SELinux). TYPE: `Iterable[str]` DEFAULT: `()`
`share`	Namespaces to share between containers in the pod. TYPE: `Optional[Iterable[str]]` DEFAULT: `None`
`shm_size`	Size of /dev/shm. TYPE: `Optional[Union[int, str]]` DEFAULT: `None`
`subgidname`	Run the container in a new user namespace using the map with name in the /etc/subgid file. TYPE: `Optional[str]` DEFAULT: `None`
`subuidname`	Run the container in a new user namespace using the map with name in the /etc/subuid file. TYPE: `Optional[str]` DEFAULT: `None`
`sysctl`	Configure namespaced kernel parameters for all containers in the pod. TYPE: `Mapping[str, str]` DEFAULT: `{}`
`uidmaps`	Run all containers in the pod in a new user namespace using the supplied UID mapping. This option conflicts with the userns and subuidname options. TYPE: `Iterable[Tuple[int, int, int]]` DEFAULT: `()`
`userns`	Set the user namespace mode for all the containers in a pod. TYPE: `Optional[str]` DEFAULT: `None`
`uts`	Set the UTS namespace mode for the pod. TYPE: `Optional[str]` DEFAULT: `None`
`volumes`	Specify volumes passed to all containers in the pod. TYPE: `Iterable[VolumeDefinition]` DEFAULT: `()`
`volumes_from`	Mount volumes from the specified container(s). TYPE: `Iterable[ValidContainer]` DEFAULT: `()`

Returns

A `python_on_whales.Pod` object.

exists

exists(pod)

Returns True if the pod exists. False otherwise.

It's just calling podman.pod.inspect(...) and verifies that it doesn't throw a python_on_whales.exceptions.NoSuchPod.

Returns

A `bool`

inspect

inspect(x)

Creates a python_on_whales.Pod object.

Returns

`python_on_whales.Pod`, or `List[python_on_whales.Pod]` if the input
was a list of strings.

Raises

`python_on_whales.exceptions.NoSuchPod` if one of the pods does not exist.

kill

kill(x, /, *, signal=None)

Kill pods.

PARAMETER	DESCRIPTION
`x`	One or more pods to kill TYPE: `Union[ValidPod, Iterable[ValidPod]]`
`signal`	The signal to send the pods' containers TYPE: `Optional[Union[int, str]]` DEFAULT: `None`

Raises

`python_on_whales.exceptions.NoSuchPod` if a pod does not exist.

list

list(*, filters={})

List the pods on the host.

PARAMETER	DESCRIPTION
`filters`	Filters to apply when listing pods TYPE: `PodListFilters` DEFAULT: `{}`

Returns

A `List[python_on_whales.Pod]`

logs

logs(pod, container=None, *, names=False, since=None, tail=None, timestamps=False, until=None, follow=False, stream=False)

Returns the logs of a pod's containers as a string or an iterator.

PARAMETER	DESCRIPTION
`pod`	The pod to get the container logs of TYPE: `ValidPod`
`container`	Filter logs by container TYPE: `Optional[ValidContainer]` DEFAULT: `None`
`names`	Output container names instead of IDs in the logs TYPE: `bool` DEFAULT: `False`
`since`	Use a datetime or timedelta to specify the lower date limit for the logs. TYPE: `Union[None, datetime, timedelta]` DEFAULT: `None`
`tail`	Number of lines to show from the end of the logs (default all) TYPE: `Optional[int]` DEFAULT: `None`
`timestamps`	Put timestamps next to lines. TYPE: `bool` DEFAULT: `False`
`until`	Use a datetime or a timedelta to specify the upper date limit for the logs. TYPE: `Union[None, datetime, timedelta]` DEFAULT: `None`
`follow`	If `False` (the default), the logs returned are the logs up to the time of the function call. If `True`, the logs of the container up to the time the container stopped are displayed. Which means that if the container isn't stopped yet, the function will continue until the container is stopped. Which is why it is advised to use the `stream` option if you use the `follow` option. Without `stream`, only a `str` will be returned, possibly much later in the future. With `stream`, you'll be able to read the logs in real time. TYPE: `bool` DEFAULT: `False`
`stream`	Similar to the `stream` argument of `docker.run`. This function will then return an iterator that will yield a tuple `(source, content)` with `source` being `"stderr"` or `"stdout"`. `content` is the content of the line as bytes. Take a look at the user guide to have an example of the output. TYPE: `bool` DEFAULT: `False`

Returns

`str` if `stream=False` (the default), `Iterable[Tuple[str, bytes]]`
if `stream=True`.

Raises

`python_on_whales.exceptions.NoSuchPod` if the container does not exist.

If you are a bit confused about follow and stream, here are some use cases.

If you want to have the logs up to this point as a str, don't use those args.
If you want to stream the output in real time, use follow=True, stream=True
If you want the logs up to this point, but you don't want to fit all the logs in memory because they are too big, use stream=True.

pause

pause(x)

Pauses one or more pods

PARAMETER	DESCRIPTION
`x`	One or more pods to pause TYPE: `Union[ValidPod, Iterable[ValidPod]]`

Raises

`python_on_whales.exceptions.NoSuchPod` if any pods does not exist.

prune

prune()

Remove pods that are not running.

remove

remove(x, /, *, force=False, ignore=False, time=None)

Remove one or more pods.

PARAMETER	DESCRIPTION
`x`	Single pod or list of pods to remove. TYPE: `Union[ValidPod, Iterable[ValidPod]]`
`force`	Force removal of the pods TYPE: `bool` DEFAULT: `False`
`ignore`	Ignore errors when specified pod is missing TYPE: `bool` DEFAULT: `False`
`time`	Seconds to wait for pod stop before killing the containers TYPE: `Optional[int]` DEFAULT: `None`

Raises

`python_on_whales.exceptions.NoSuchPod` if any of the pods do not
exist and `ignore` was not set.

restart

restart(x)

Restarts one or more pods

PARAMETER	DESCRIPTION
`x`	One or more pods to restart TYPE: `Union[ValidPod, Iterable[ValidPod]]`

Raises

`python_on_whales.exceptions.NoSuchPod` if any pods does not exist.

start

start(x)

Starts one or more pods

PARAMETER	DESCRIPTION
`x`	One or more pods to start TYPE: `Union[ValidPod, Iterable[ValidPod]]`

Raises

`python_on_whales.exceptions.NoSuchPod` if any pods does not exist.

stats

stats(x)

Get pods resource usage statistics

The data unit is the byte.

PARAMETER	DESCRIPTION
`x`	One or a list of pods TYPE: `Union[ValidPod, Iterable[ValidPod]]`

Returns

A `List[python_on_whales.PodStats]`.

stop

stop(x, /, *, time=None)

Stops one or more pods

PARAMETER	DESCRIPTION
`x`	One or more pods to stop TYPE: `Union[ValidPod, Iterable[ValidPod]]`
`time`	Seconds to wait for pods to stop before killing containers TYPE: `Optional[int]` DEFAULT: `None`

Raises

`python_on_whales.exceptions.NoSuchPod` if any pods does not exist.

top

top(pod)

Get the running processes of a pod

Not yet implemented

unpause

unpause(x)

Unpauses one or more pods

PARAMETER	DESCRIPTION
`x`	One or more pods to unpause TYPE: `Union[ValidPod, Iterable[ValidPod]]`

Raises

`python_on_whales.exceptions.NoSuchPod` if any pod do not exist.