ansible/rst/modules/virt.rst

virt

Manages virtual machines supported by libvirt. Requires that libvirt be installed on the managed machine.

parameter	required	default	comments
name	yes		name of the guest VM being managed
state			'running', 'shutdown', 'destroyed', or 'undefined'. 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.
command			in addition to state management, various non-idempotent commands are available. See examples below.

Example action from Ansible playbooks:

virt guest=alpha state=running
virt guest=alpha state=shutdown
virt guest=alpha state=destroyed
virt guest=alpha state=undefined

Example guest management commands from /usr/bin/ansible:

ansible host -m virt -a "guest=foo command=status"
ansible host -m virt -a "guest=foo command=pause"
ansible host -m virt -a "guest=foo command=unpause"
ansible host -m virt -a "guest=foo command=get_xml"
ansible host -m virt -a "guest=foo command=autostart"

Example host (hypervisor) management commands from /usr/bin/ansible:

ansible host -m virt -a "command=freemem"
ansible host -m virt -a "command=list_vms"
ansible host -m virt -a "command=info"
ansible host -m virt -a "command=nodeinfo"
ansible host -m virt -a "command=virttype"