containers.podman.podman_volume module – Manage Podman volumes

Note

This module is part of the containers.podman collection (version 1.18.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. 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)