Docs4dev
Docs
ansible / 2.4 / virt_module.html

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
list_vms
The list of vms defined on the remote system
success dictionary ['build.example.org', 'dev.example.org']
status
The status of the VM, among running, crashed, paused and shutdown
success string success

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–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/virt_module.html