containers.podman.podman_container – Manage podman containers

From Get docs
Ansible/docs/2.11/collections/containers/podman/podman container module


containers.podman.podman_container – Manage podman containers

Note

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

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

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


New in version 1.0.0: of containers.podman


Synopsis

  • Start, stop, restart and manage Podman containers

Requirements

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

  • podman

Parameters

Parameter Choices/Defaults Comments

annotation

dictionary

Add an annotation to the container. The format is key value, multiple times.

authfile

path

Path of the authentication file. Default is ``${XDG_RUNTIME_DIR}/containers/auth.json`` (Not available for remote commands) You can also override the default path of the authentication file by setting the ``REGISTRY_AUTH_FILE`` environment variable. ``export REGISTRY_AUTH_FILE=path``

blkio_weight

integer

Block IO weight (relative weight) accepts a weight value between 10 and 1000

blkio_weight_device

dictionary

Block IO weight (relative device weight, format DEVICE_NAME[:]WEIGHT).

cap_add

list / elements=string

List of capabilities to add to the container.


aliases: capabilities

cap_drop

list / elements=string

List of capabilities to drop from the container.

cgroup_parent

path

Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist.

cgroupns

string

Path to cgroups under which the cgroup for the container will be created.

cgroups

string

  • default
  • disabled

Determines whether the container will create CGroups. Valid values are enabled and disabled, which the default being enabled. The disabled option will force the container to not create CGroups, and thus conflicts with CGroup options cgroupns and cgroup-parent.

cidfile

path

Write the container ID to the file

cmd_args

list / elements=string

Any additional command options you want to pass to podman command, cmd_args - ['--other-param', 'value'] Be aware module doesn't support idempotency if this is set.

command

raw

Override command of container. Can be a string or a list.

conmon_pidfile

path

Write the pid of the conmon process to a file. conmon runs in a separate process than Podman, so this is necessary when using systemd to restart Podman containers.

cpu_period

integer

Limit the CPU real-time period in microseconds

cpu_rt_period

integer

Limit the CPU real-time period in microseconds. Limit the container's Real Time CPU usage. This flag tell the kernel to restrict the container's Real Time CPU usage to the period you specify.

cpu_rt_runtime

integer

Limit the CPU real-time runtime in microseconds. This flag tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume.

cpu_shares

integer

CPU shares (relative weight)

cpus

string

Number of CPUs. The default is 0.0 which means no limit.

cpuset_cpus

string

CPUs in which to allow execution (0-3, 0,1)

cpuset_mems

string

Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.

debug

boolean

  • no ←

  • yes

Return additional information which can be helpful for investigations.

detach

boolean

  • no

  • yes ←

Run container in detach mode

detach_keys

string

Override the key sequence for detaching a container. Format is a single character or ctrl-value

device

list / elements=string

Add a host device to the container. The format is [:][:] (e.g. device /dev/sdc:/dev/xvdc:rwm)

device_read_bps

list / elements=string

Limit read rate (bytes per second) from a device (e.g. device-read-bps /dev/sda:1mb)

device_read_iops

list / elements=string

Limit read rate (IO per second) from a device (e.g. device-read-iops /dev/sda:1000)

device_write_bps

list / elements=string

Limit write rate (bytes per second) to a device (e.g. device-write-bps /dev/sda:1mb)

device_write_iops

list / elements=string

Limit write rate (IO per second) to a device (e.g. device-write-iops /dev/sda:1000)

dns

list / elements=string

Set custom DNS servers


aliases: dns_servers

dns_option

string

Set custom DNS options


aliases: dns_opts

dns_search

string

Set custom DNS search domains (Use dns_search with if you don't wish to set the search domain)


aliases: dns_search_domains

entrypoint

string

Overwrite the default ENTRYPOINT of the image

env

dictionary

Set environment variables. This option allows you to specify arbitrary environment variables that are available for the process that will be launched inside of the container.

env_file

path

Read in a line delimited file of environment variables

env_host

boolean

  • no
  • yes

Use all current host environment variables in container. Defaults to false.

etc_hosts

dictionary

Dict of host-to-IP mappings, where each host name is a key in the dictionary. Each host name will be added to the container's ``/etc/hosts`` file.


aliases: add_hosts

executable

string

Default:

"podman"

Path to podman executable if it is not in the $PATH on the machine running podman

expose

list / elements=string

Expose a port, or a range of ports (e.g. expose "3300-3310") to set up port redirection on the host system.


aliases: exposed, exposed_ports

force_restart

boolean

  • no ←

  • yes

Force restart of container.


aliases: restart

gidmap

list / elements=string

Run the container in a new user namespace using the supplied mapping.

group_add

list / elements=string

Add additional groups to run as


aliases: groups

healthcheck

string

Set or alter a healthcheck command for a container.

healthcheck_interval

string

Set an interval for the healthchecks (a value of disable results in no automatic timer setup) (default "30s")

healthcheck_retries

integer

The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is 3.

healthcheck_start_period

string

The initialization time needed for a container to bootstrap. The value can be expressed in time format like 2m3s. The default value is 0s

healthcheck_timeout

string

The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the value can be expressed in a time format such as 1m22s. The default value is 30s

hostname

string

Container host name. Sets the container host name that is available inside the container.

http_proxy

boolean

  • no
  • yes

By default proxy environment variables are passed into the container if set for the podman process. This can be disabled by setting the http_proxy option to false. The environment variables passed in include http_proxy, https_proxy, ftp_proxy, no_proxy, and also the upper case versions of those. Defaults to true

image

string

Repository path (or image name) and tag used to create the container. If an image is not found, the image will be pulled from the registry. If no tag is included, latest will be used.

Can also be an image ID. If this is the case, the image is assumed to be available locally.

image_strict

boolean

  • no ←

  • yes

Whether to compare images in idempotency by taking into account a full name with registry and namespaces.

image_volume

string

  • bind
  • tmpfs
  • ignore

Tells podman how to handle the builtin image volumes. The options are bind, tmpfs, or ignore (default bind)

init

boolean

  • no
  • yes

Run an init inside the container that forwards signals and reaps processes. The default is false.

init_path

string

Path to the container-init binary.

interactive

boolean

  • no
  • yes

Keep STDIN open even if not attached. The default is false. When set to true, keep stdin open even if not attached. The default is false.

ip

string

Specify a static IP address for the container, for example '10.88.64.128'. Can only be used if no additional CNI networks to join were specified via 'network:', and if the container is not joining another container's network namespace via 'network container:'. The address must be within the default CNI network's pool (default 10.88.0.0/16).

ipc

string

Default is to create a private IPC namespace (POSIX SysV IPC) for the container


aliases: ipc_mode

kernel_memory

string

Kernel memory limit (format [], where unit = b, k, m or g) Note - idempotency is supported for integers only.

label

dictionary

Add metadata to a container, pass dictionary of label names and values


aliases: labels

label_file

string

Read in a line delimited file of labels

log_driver

string

  • k8s-file
  • journald
  • json-file

Logging driver. Used to set the log driver for the container. For example log_driver "k8s-file".

log_level

string

  • debug
  • info
  • warn
  • error
  • fatal
  • panic

Logging level for Podman. Log messages above specified level ("debug"|"info"|"warn"|"error"|"fatal"|"panic") (default "error")

log_opt

dictionary

Logging driver specific options. Used to set the path to the container log file.


aliases: log_options

max_size

string

Specify a max size of the log file (e.g 10mb).

path

string

Specify a path to the log file (e.g. /var/log/container/mycontainer.json).

tag

string

Specify a custom log tag for the container.

mac_address

string

Specify a MAC address for the container, for example '92:d0:c6:0a:29:33'. Don't forget that it must be unique within one Ethernet network.

memory

string

Memory limit (format 10k, where unit = b, k, m or g) Note - idempotency is supported for integers only.

memory_reservation

string

Memory soft limit (format 100m, where unit = b, k, m or g) Note - idempotency is supported for integers only.

memory_swap

string

A limit value equal to memory plus swap. Must be used with the -m (--memory) flag. The swap LIMIT should always be larger than -m (--memory) value. By default, the swap LIMIT will be set to double the value of --memory Note - idempotency is supported for integers only.

memory_swappiness

integer

Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.

mount

string

Attach a filesystem mount to the container. bind or tmpfs For example mount "type=bind,source=/path/on/host,destination=/path/in/container"

name

string / required

Name of the container

network

list / elements=string

Set the Network mode for the container * bridge create a network stack on the default bridge * none no networking * container: reuse another container's network stack * host use the podman host network stack. * | connect to a user-defined network * ns: path to a network namespace to join * slirp4netns use slirp4netns to create a user network stack. This is the default for rootless containers


aliases: net, network_mode

no_hosts

boolean

  • no
  • yes

Do not create /etc/hosts for the container Default is false.

oom_kill_disable

boolean

  • no
  • yes

Whether to disable OOM Killer for the container or not. Default is false.

oom_score_adj

integer

Tune the host's OOM preferences for containers (accepts -1000 to 1000)

pid

string

Set the PID mode for the container


aliases: pid_mode

pids_limit

string

Tune the container's PIDs limit. Set -1 to have unlimited PIDs for the container.

pod

string

Run container in an existing pod. If you want podman to make the pod for you, preference the pod name with "new:"

privileged

boolean

  • no
  • yes

Give extended privileges to this container. The default is false.

publish

list / elements=string

Publish a container's port, or range of ports, to the host. Format - ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort In case of only containerPort is set, the hostPort will chosen randomly by Podman.


aliases: ports, published, published_ports

publish_all

boolean

  • no
  • yes

Publish all exposed ports to random ports on the host interfaces. The default is false.

read_only

boolean

  • no
  • yes

Mount the container's root filesystem as read only. Default is false

read_only_tmpfs

boolean

  • no
  • yes

If container is running in --read-only mode, then mount a read-write tmpfs on /run, /tmp, and /var/tmp. The default is true

recreate

boolean

  • no ←

  • yes

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

restart_policy

string

Restart policy to follow when containers exit. Restart policy will not take effect if a container is stopped via the podman kill or podman stop commands. Valid values are * no - Do not restart containers on exit * on-failure[:max_retries] - Restart containers when they exit with a non-0 exit code, retrying indefinitely or until the optional max_retries count is hit * always - Restart containers when they exit, regardless of status, retrying indefinitely

rm

boolean

  • no
  • yes

Automatically remove the container when it exits. The default is false.


aliases: remove, auto_remove

rootfs

boolean

  • no
  • yes

If true, the first argument refers to an exploded container on the file system. The default is false.

security_opt

list / elements=string

Security Options. For example security_opt "seccomp=unconfined"

shm_size

string

Size of /dev/shm. The format is . number must be greater than 0. Unit is optional and can be b (bytes), k (kilobytes), m(megabytes), or g (gigabytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses 64m

sig_proxy

boolean

  • no
  • yes

Proxy signals sent to the podman run command to the container process. SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is true.

state

string

  • absent
  • present
  • stopped

  • started ←

absent - A container matching the specified name will be stopped and removed.

present - Asserts the existence of a container matching the name and any provided configuration parameters. If no container matches the name, a container will be created. If a container matches the name but the provided configuration does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed and re-created with the requested config. Image version will be taken into account when comparing configuration. Use the recreate option to force the re-creation of the matching container.

started - Asserts there is a running container matching the name and any provided configuration. If no container matches the name, a container will be created and started. Use recreate to always re-create a matching container, even if it is running. Use force_restart to force a matching container to be stopped and restarted.

stopped - Asserts that the container is first present, and then if the container is running moves it to a stopped state.

stop_signal

integer

Signal to stop a container. Default is SIGTERM.

stop_timeout

integer

Timeout (in seconds) to stop a container. Default is 10.

subgidname

string

Run the container in a new user namespace using the map with 'name' in the /etc/subgid file.

subuidname

string

Run the container in a new user namespace using the map with 'name' in the /etc/subuid file.

sysctl

dictionary

Configure namespaced kernel parameters at runtime

systemd

boolean

  • no
  • yes

Run container in systemd mode. The default is true.

tmpfs

dictionary

Create a tmpfs mount. For example tmpfs "/tmp" "rw,size=787448k,mode=1777"

tty

boolean

  • no
  • yes

Allocate a pseudo-TTY. The default is false.

uidmap

list / elements=string

Run the container in a new user namespace using the supplied mapping.

ulimit

list / elements=string

Ulimit options


aliases: ulimits

user

string

Sets the username or UID used and optionally the groupname or GID for the specified command.

userns

string

Set the user namespace mode for the container. It defaults to the PODMAN_USERNS environment variable. An empty value means user namespaces are disabled.


aliases: userns_mode

uts

string

Set the UTS mode for the container

volume

list / elements=string

Create a bind mount. If you specify, volume /HOST-DIR:/CONTAINER-DIR, podman bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the podman container.


aliases: volumes

volumes_from

list / elements=string

Mount volumes from the specified container(s).

workdir

string

Working directory inside the container. The default working directory for running binaries within a container is the root directory (/).


aliases: working_dir



Examples

- name: Run container
  containers.podman.podman_container:
    name: container
    image: quay.io/bitnami/wildfly
    state: started

- name: Create a data container
  containers.podman.podman_container:
    name: mydata
    image: busybox
    volume:
      - /tmp/data

- name: Re-create a redis container
  containers.podman.podman_container:
    name: myredis
    image: redis
    command: redis-server --appendonly yes
    state: present
    recreate: yes
    expose:
      - 6379
    volumes_from:
      - mydata

- name: Restart a container
  containers.podman.podman_container:
    name: myapplication
    image: redis
    state: started
    restart: yes
    etc_hosts:
        other: "127.0.0.1"
    restart_policy: "no"
    device: "/dev/sda:/dev/xvda:rwm"
    ports:
        - "8080:9000"
        - "127.0.0.1:8081:9001/udp"
    env:
        SECRET_KEY: "ssssh"
        BOOLEAN_KEY: "yes"

- name: Container present
  containers.podman.podman_container:
    name: mycontainer
    state: present
    image: ubuntu:14.04
    command: "sleep 1d"

- name: Stop a container
  containers.podman.podman_container:
    name: mycontainer
    state: stopped

- name: Start 4 load-balanced containers
  containers.podman.podman_container:
    name: "container{{ item }}"
    recreate: yes
    image: someuser/anotherappimage
    command: sleep 1d
  with_sequence: count=4

- name: remove container
  containers.podman.podman_container:
    name: ohno
    state: absent

- name: Writing output
  containers.podman.podman_container:
    name: myservice
    image: busybox
    log_options: path=/var/log/container/mycontainer.json
    log_driver: k8s-file

Return Values

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

Key Returned Description

container

dictionary

always

Facts representing the current state of the container. Matches the podman inspection output.

Note that facts are part of the registered vars since Ansible 2.8. For compatibility reasons, the facts are also accessible directly as podman_container. Note that the returned fact will be removed in Ansible 2.12.

Empty if state is absent.


Sample:

{ "AppArmorProfile": "", "Args": [ "sh" ], "BoundingCaps": [ "CAP_CHOWN", ... ], "Config": { "Annotations": { "io.kubernetes.cri-o.ContainerType": "sandbox", "io.kubernetes.cri-o.TTY": "false" }, "AttachStderr": false, "AttachStdin": false, "AttachStdout": false, "Cmd": [ "sh" ], "Domainname": "", "Entrypoint": "", "Env": [ "PATH=/usr/sbin:/usr/bin:/sbin:/bin", "TERM=xterm", "HOSTNAME=", "container=podman" ], "Hostname": "", "Image": "docker.io/library/busybox:latest", "Labels": null, "OpenStdin": false, "StdinOnce": false, "StopSignal": 15, "Tty": false, "User": { "gid": 0, "uid": 0 }, "Volumes": null, "WorkingDir": "/" }, "ConmonPidFile": "...", "Created": "2019-06-17T19:13:09.873858307+03:00", "Dependencies": [], "Driver": "overlay", "EffectiveCaps": [ "CAP_CHOWN", ... ], "ExecIDs": [], "ExitCommand": [ "/usr/bin/podman", "--root", ... ], "GraphDriver": { ... }, "HostConfig": { ... }, "HostnamePath": "...", "HostsPath": "...", "ID": "...", "Image": "...", "ImageName": "docker.io/library/busybox:latest", "IsInfra": false, "LogPath": "/tmp/container/mycontainer.json", "MountLabel": "system_u:object_r:container_file_t:s0:c282,c782", "Mounts": [ ... ], "Name": "myservice", "Namespace": "", "NetworkSettings": { "Bridge": "", ... }, "Path": "sh", "ProcessLabel": "system_u:system_r:container_t:s0:c282,c782", "ResolvConfPath": "...", "RestartCount": 0, "Rootfs": "", "State": { "Dead": false, "Error": "", "ExitCode": 0, "FinishedAt": "2019-06-17T19:13:10.157518963+03:00", "Healthcheck": { "FailingStreak": 0, "Log": null, "Status": "" }, "OOMKilled": false, "OciVersion": "1.0.1-dev", "Paused": false, "Pid": 4083, "Restarting": false, "Running": false, "StartedAt": "2019-06-17T19:13:10.152479729+03:00", "Status": "exited" }, "StaticDir": "..." ... }




Authors

  • Sagi Shnaidman (@sshnaidm)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/containers/podman/podman_container_module.html


Retrieved from "https://getdocs.org/index.php?title=Ansible/docs/2.11/collections/containers/podman/podman_container_module&oldid=63061"
Powered by MediaWiki