# containers.podman.podman_volume module – Manage Podman volumes

Note

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

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)

### Collection links

- Issue Tracker
- Repository (Sources)