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
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.

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

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