You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

virt - Manages virtual machines supported by libvirt¶

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
- Status

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.