community.libvirt.virt_volume module – Manage libvirt volumes inside a storage pool

Note

This module is part of the community.libvirt collection (version 1.4.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 community.libvirt. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.libvirt.virt_volume.

New in community.libvirt 1.4.0

Synopsis

  • Manage libvirt volumes inside a storage pool.

Requirements

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

  • python >= 2.6
  • libvirt python bindings
  • lxml

Parameters

Parameter

Comments

command

string

In addition to state management, various non-idempotent commands are available. See examples.

Choices:

  • "create"
  • "create_from"
  • "delete"
  • "download"
  • "info"
  • "list_volumes"
  • "get_xml"
  • "resize"
  • "upload"
  • "wipe"
  • "facts"

mode

string

Pass additional parameters to ‘wipe’ command.

Choices:

  • "new"
  • "repair"
  • "resize"
  • "no_overwrite"
  • "overwrite"
  • "normal"
  • "zeroed"

name

aliases: volume

string

Name of the volume being managed. Note that the volume must be previously defined with xml.

pool

string / required

Name of the storage pool, where the volume is located.

state

string

Specify which state you want a volume to be in.

If present, ensure that the volume is present but do not change its state; if it’s missing, you need to specify xml argument.

If absent, volume will be removed from libvirt configuration (logically only!).

If deleted, volume will be wiped clean and then removed.

Choices:

  • "present"
  • "absent"
  • "deleted"

uri

string

Libvirt connection uri.

Default: "qemu:///system"

xml

string

XML document used with the define command.

Must be raw XML content using lookup. XML cannot be reference to a file.

Examples

- name: Define a new storage pool
  community.libvirt.virt_pool:
    command: define
    name: vms
    xml: '{{ lookup("template", "pool/dir.xml.j2") }}'

- name: Build a storage pool if it does not exist
  community.libvirt.virt_pool:
    command: build
    name: vms

- name: Start a storage pool
  community.libvirt.virt_pool:
    command: create
    name: vms

- name: List available pools
  community.libvirt.virt_pool:
    command: list_pools

- name: Get XML data of a specified pool
  community.libvirt.virt_pool:
    command: get_xml
    name: vms

- name: Stop a storage pool
  community.libvirt.virt_pool:
    command: destroy
    name: vms

- name: Delete a storage pool (destroys contents)
  community.libvirt.virt_pool:
    command: delete
    name: vms

- name: Undefine a storage pool
  community.libvirt.virt_pool:
    command: undefine
    name: vms

- name: Gather facts about storage pools. Facts will be available as 'ansible_libvirt_pools'
  community.libvirt.virt_pool:
    command: facts

- name: Gather information about pools managed by 'libvirt' remotely using uri
  community.libvirt.virt_pool:
    command: info
    uri: '{{ item }}'
  with_items: '{{ libvirt_uris }}'
  register: storage_pools

- name: Ensure that a pool is active (needs to be defined and built first)
  community.libvirt.virt_pool:
    state: active
    name: vms

- name: Ensure that a pool is inactive
  community.libvirt.virt_pool:
    state: inactive
    name: vms

- name: Ensure that a given pool will be started at boot
  community.libvirt.virt_pool:
    autostart: true
    name: vms

- name: Disable autostart for a given pool
  community.libvirt.virt_pool:
    autostart: false
    name: vms

Authors

  • Leonardo Galli (@galli-leo)
  • Niclas Kretschmer (@NK308)

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/libvirt/virt_volume_module.html