Documentation

virt - Manages virtual machines supported by libvirt

Synopsis

  • Manages virtual machines supported by libvirt.

Requirements (on host that executes module)

  • python >= 2.6
  • libvirt-python

Options

parameter required default choices comments
autostart
(added in 2.3)
no
  • True
  • False
start VM at host startup
command
no
  • create
  • status
  • start
  • stop
  • pause
  • unpause
  • shutdown
  • undefine
  • destroy
  • get_xml
  • freemem
  • list_vms
  • info
  • nodeinfo
  • virttype
  • define
in addition to state management, various non-idempotent commands are available. See examples
name
yes
name of the guest VM being managed. Note that VM must be previously defined with xml.
state
no no
  • running
  • shutdown
  • destroyed
  • paused
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
no qemu:///system
libvirt connection uri
xml
no
XML document used with the define command

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 Return Values, the following are the fields unique to this module:

name description returned type sample
status The status of the VM, among running, crashed, paused and shutdown success string success
list_vms The list of vms defined on the remote system success dictionary ['build.example.org', 'dev.example.org']


Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Support

This module is community maintained without core committer oversight.

For more information on what this means please read Module Support

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.