W3cubDocs

/Ansible

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
command
 no
  • create
  • status
  • start
  • stop
  • pause
  • unpause
  • shutdown
  • undefine
  • destroy
  • get_xml
  • autostart
  • 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
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 Common 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']
contains:
name description returned type sample

This is an Extras Module

For more information on what this means please read Extras Modules

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

© 2012–2016 Michael DeHaan
© 2016 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/virt_module.html