virt – Manages virtual machines supported by libvirt

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
added in 2.3
    Choices:
  • no
  • yes
start VM at host startup.
command
-
    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
-
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.
state
-
    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.
uri
-
Default:
"qemu:///system"
libvirt connection uri.
xml
-
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:
- 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:///"

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

Return Values

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

Key Returned Description
list_vms
dictionary
 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


Status

Authors

  • Ansible Core Team
  • Michael DeHaan
  • Seth Vidal

Hint

If you notice any issues in this documentation you can edit this document to improve it.