community.libvirt.virt – Manages virtual machines supported by libvirt

Note

This plugin is part of the community.libvirt collection (version 1.0.0).

To install it use: ansible-galaxy collection install community.libvirt.

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

Synopsis

• Manages virtual machines supported by libvirt.

Requirements

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

• python >= 2.6

• libvirt-python

Parameters

Parameter	Choices/Defaults	Comments
autostart boolean	Choices: no yes	start VM at host startup.
command string	Choices: create define destroy freemem get_xml info list_vms nodeinfo pause shutdown start status stop undefine unpause virttype	In addition to state management, various non-idempotent commands are available.
name string		name of the guest VM being managed. Note that VM must be previously defined with xml. This option is required unless command is list_vms or info. aliases: guest
state string	Choices: destroyed paused running shutdown	Note that there may be some lag for state requests like shutdown since these refer only to VM states. After starting a guest, it may not be immediately accessible. state and command are mutually exclusive except when command=list_vms. In this case all VMs in specified state will be listed.
uri string	Default: "qemu:///system"	libvirt connection uri.
xml string		XML document used with the define command. Must be raw XML content using lookup. XML cannot be reference to a file.

Examples

# a playbook task line:
- community.libvirt.virt:
    name: alpha
    state: running

# /usr/bin/ansible invocations
# ansible host -m virt -a "name=alpha command=status"
# ansible host -m virt -a "name=alpha command=get_xml"
# ansible host -m virt -a "name=alpha command=create uri=lxc:///"

# defining and launching an LXC guest
- name: define vm
  community.libvirt.virt:
    command: define
    xml: "{{ lookup('template', 'container-template.xml.j2') }}"
    uri: 'lxc:///'
- name: start vm
  community.libvirt.virt:
    name: foo
    state: running
    uri: 'lxc:///'

# setting autostart on a qemu VM (default uri)
- name: set autostart for a VM
  community.libvirt.virt:
    name: foo
    autostart: yes

# Defining a VM and making is autostart with host. VM will be off after this task
- name: define vm from xml and set autostart
  community.libvirt.virt:
    command: define
    xml: "{{ lookup('template', 'vm_template.xml.j2') }}"
    autostart: yes

# Listing VMs
- name: list all VMs
  community.libvirt.virt:
    command: list_vms
  register: all_vms

- name: list only running VMs
  community.libvirt.virt:
    command: list_vms
    state: running
  register: running_vms

Return Values

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

Key	Returned	Description
list_vms list / elements=string	success	The list of vms defined on the remote system Sample: ['build.example.org', 'dev.example.org']
status string	success	The status of the VM, among running, crashed, paused and shutdown Sample: success

Authors

• Ansible Core Team

• Michael DeHaan

• Seth Vidal (@skvidal)