containers.podman.podman_volume module – Manage Podman volumes

Note

This module is part of the containers.podman collection (version 1.18.0).

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

New in containers.podman 1.1.0

Synopsis

  • Manage Podman volumes

Requirements

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

  • podman

Parameters

Parameter

Comments

debug

boolean

Return additional information which can be helpful for investigations.

Choices:

  • false ← (default)

  • true

driver

string

Specify volume driver name (default local).

executable

string

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

Default: "podman"

label

dictionary

Add metadata to a pod volume (e.g., label com.example.key=value).

name

string / required

Name of volume.

options

list / elements=string

Set driver specific options. For example ‘device=tpmfs’, ‘type=tmpfs’. UID and GID idempotency is not supported due to changes in podman.

quadlet_dir

path

Path to the directory to write quadlet file in. By default, it will be set as /etc/containers/systemd/ for root user, ~/.config/containers/systemd/ for non-root users.

quadlet_file_mode

any

The permissions of the quadlet file.

The quadlet_file_mode can be specied as octal numbers or as a symbolic mode (for example, u+rwx or u=rw,g=r,o=r). For octal numbers format, you must either add a leading zero so that Ansible’s YAML parser knows it is an octal number (like 0644 or 01777) or quote it (like '644' or '1777') so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results.

If quadlet_file_mode is not specified and the quadlet file does not exist, the default '0640' mask will be used when setting the mode for the newly created file.

If quadlet_file_mode is not specified and the quadlet file does exist, the mode of the existing file will be used.

Specifying quadlet_file_mode is the best way to ensure files are created with the correct permissions.

quadlet_filename

string

Name of quadlet file to write. By default it takes name value.

quadlet_options

list / elements=string

Options for the quadlet file. Provide missing in usual network args options as a list of lines to add.

recreate

boolean

Recreate volume even if exists.

Choices:

  • false ← (default)

  • true

state

string

State of volume, default ‘present’

Choices:

  • "present" ← (default)

  • "absent"

  • "mounted"

  • "unmounted"

  • "quadlet"

Examples

# What modules does for example
- name: Create a volume
  containers.podman.podman_volume:
    state: present
    name: volume1
    label:
      key: value
      key2: value2
    options:
      - "device=/dev/loop1"
      - "type=ext4"

- name: Create a Quadlet file for a volume
  containers.podman.podman_volume:
    state: quadlet
    name: quadlet_volume
    quadlet_filename: custom-name
    quadlet_file_mode: '0640'
    quadlet_options:
      - Group=192
      - Copy=true
      - Image=quay.io/centos/centos:latest

Return Values

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

Key

Description

volume

dictionary

Volume inspection results if exists.

Returned: always

Sample: {"CreatedAt": "2023-11-30T16:41:31.310865559+02:00", "Driver": "local", "Labels": {}, "LockNumber": 18, "MountCount": 0, "Mountpoint": "/home/user/.local/share/containers/storage/volumes/volname/_data", "Name": "volname", "NeedsChown": true, "NeedsCopyUp": true, "Options": {}, "Scope": "local"}

Authors

  • Sagi Shnaidman (@sshnaidm)