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

Note

This module is part of the community.libvirt collection (version 2.0.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.

  • libvirt

  • libvirt python bindings

  • lxml

  • pycdlib

  • python >= 2.6

Parameters

Parameter

Comments

clone_source

string

Name of the volume to clone from.

Optionally provided with state present or command create.

cloudinit_config

dictionary

Ansible dict of cloud-init data to create a CIDATA CDROM.

The data should contain the keys METADATA, USERDATA, and/or NETWORK_CONFIG.

This is required if command is create_cidata_cdrom.

command

string

create - Analagous to state / present

delete - Analagous to state / absent

wipe - Performs a wipe *only* of the volume specified by name - *does not delete* the volume.

list_volumes - Lists all volumes in the storage pool.

get_xml - Retrieves the XML of the volume specified by name.

create_cidata_cdrom - Creates a CIDATA CDROM with the provided cloudinit_config data. Enables bootstrapping of cloud-init enabled VMs.

Mutually exclusive with state.

Choices:

  • "create"

  • "delete"

  • "wipe"

  • "list_volumes"

  • "get_xml"

  • "create_cidata_cdrom"

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

If present, Creates a new volume with the XML provided, optionally cloning from the image in clone_source. The name of the volume is specified in the XML (if a name parameter is provided, it is ignored). xml must be provided.

If absent, Deletes the volume specified by name from the storage pool. If wipe is set to true, the volume will be wiped before deletion.

Mutually exclusive with command.

Choices:

  • "present"

  • "absent"

uri

string

Libvirt connection uri.

Default: "qemu:///system"

wipe

boolean

Whether to wipe the volume before deleting it.

Choices:

  • false ← (default)

  • true

xml

string

XML definition of the volume to be created.

This is required if command is create

Examples

- name: Create volume in existing default pool
  community.libvirt.virt_volume:
    state: present
    pool: default
    xml: |
      <volume>
      <name>testing-volume</name>
      <allocation>0</allocation>
      <capacity unit="M">10</capacity>
      <target>
        <permissions>
          <mode>0644</mode>
          <label>virt_image_t</label>
        </permissions>
      </target>
      </volume>

- name: List volumes in default pool
  community.libvirt.virt_volume:
    pool: default
    command: list_volumes

- name: Get volume XML
  community.libvirt.virt_volume:
    pool: default
    command: get_xml
    name: testing-volume
  register: r__virt_volume__get_xml

- name: Wipe a volume
  community.libvirt.virt_volume:
    pool: default
    command: wipe
    name: testing-volume

- name: Delete volume from default pool, wiping it first (using state parameter)
  community.libvirt.virt_volume:
    pool: default
    state: absent
    name: testing-volume
    wipe: true

- name: Delete volume from default pool (using command parameter)
  community.libvirt.virt_volume:
    pool: default
    command: delete
    name: testing-volume

- name: Create a volume from an existing image (clone)
  community.libvirt.virt_volume:
    pool: default
    command: create
    clone_source: gold-ubuntu2404-base-image
    xml: |
      <volume type='file'>
        <name>testing_volume--boot</name>
        <capacity unit='G'>10</capacity>
        <target><format type='qcow2'/></target>
      </volume>

- name: Create CIDATA (cloud-init) cdrom
  community.libvirt.virt_volume:
    pool: default
    command: create_cidata_cdrom
    name: testing_cidata.iso
    cloudinit_config:
      NETWORK_CONFIG: {version: 2, ethernets: {eth0: {dhcp4: true}}}
      USERDATA: {users: [{name: testuser, lock_passwd: false, shell: /bin/bash, ssh_authorized_keys: ["ssh-rsa xxxxxxxxxxxxxxxxxxxxx=="]}]}
      METADATA: {local-hostname: my_host}
  register: r__virt_volume__create_cidata_cdrom

Authors

  • Leonardo Galli (@galli-leo)

  • Niclas Kretschmer (@NK308)

  • Dougal Seeley (@dseeley)