community / community.libvirt / 1.3.0 / module / virt Manages virtual machines supported by libvirt Authors: Ansible Core Team, Michael DeHaan, Seth Vidal (@skvidal)community.libvirt.virt (1.3.0) — module
Install with ansible-galaxy collection install community.libvirt:==1.3.0
collections: - name: community.libvirt version: 1.3.0
Manages virtual machines supported by I(libvirt).
# a playbook task line: - name: Start a VM community.libvirt.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:///" # defining and launching an LXC guest - name: Define a VM community.libvirt.virt: command: define xml: "{{ lookup('template', 'container-template.xml.j2') }}" uri: 'lxc:///'
- name: start vm community.libvirt.virt: name: foo state: running uri: 'lxc:///'
# setting autostart on a qemu VM (default uri) - name: Set autostart for a VM community.libvirt.virt: name: foo autostart: true
# Defining a VM and making is autostart with host. VM will be off after this task - name: Define vm from xml and set autostart community.libvirt.virt: command: define xml: "{{ lookup('template', 'vm_template.xml.j2') }}" autostart: true
# Undefine VM only, if it has no existing nvram or other metadata - name: Undefine qemu VM community.libvirt.virt: name: foo
# Undefine VM and force remove all of its related metadata (nvram, snapshots, etc.) - name: "Undefine qemu VM with force" community.libvirt.virt: name: foo force: true
# Undefine VM and remove all of its specified metadata specified # Result would the same as with force=true - name: Undefine qemu VM with list of flags community.libvirt.virt: name: foo flags: managed_save, snapshots_metadata, nvram, checkpoints_metadata
# Undefine VM, but keep its nvram - name: Undefine qemu VM and keep its nvram community.libvirt.virt: name: foo flags: keep_nvram
# Listing VMs - name: List all VMs community.libvirt.virt: command: list_vms register: all_vms
- name: List only running VMs community.libvirt.virt: command: list_vms state: running register: running_vms
uri: default: qemu:///system description: - Libvirt connection uri. type: str xml: description: - XML document used with the define command. - Must be raw XML content using C(lookup). XML cannot be reference to a file. type: str name: aliases: - guest description: - name of the guest VM being managed. Note that VM must be previously defined with xml. - This option is required unless I(command) is C(list_vms) or C(info). type: str flags: choices: - managed_save - snapshots_metadata - nvram - keep_nvram - checkpoints_metadata description: - Pass additional parameters. - Currently only implemented with command C(undefine). Specify which metadata should be removed with C(undefine). Useful option to be able to C(undefine) guests with UEFI nvram. C(nvram) and C(keep_nvram) are conflicting and mutually exclusive. Consider option C(force) if all related metadata should be removed. elements: str type: list force: description: - Enforce an action. - Currently only implemented with command C(undefine). This option can be used instead of providing all C(flags). If C(true), C(undefine) removes also any related nvram or other metadata, if existing. If C(false) or not set, C(undefine) executes only if there is no nvram or other metadata existing. Otherwise the task fails and the guest is kept defined without change. C(true) and option C(flags) should not be provided together. In this case C(undefine) ignores C(true), considers only C(flags) and issues a warning. type: bool state: choices: - destroyed - paused - running - shutdown description: - Note that there may be some lag for state requests like C(shutdown) since these refer only to VM states. After starting a guest, it may not be immediately accessible. state and command are mutually exclusive except when command=list_vms. In this case all VMs in specified state will be listed. type: str command: choices: - create - define - destroy - freemem - get_xml - info - list_vms - nodeinfo - pause - shutdown - start - status - stop - undefine - unpause - virttype description: - In addition to state management, various non-idempotent commands are available. type: str autostart: description: - Start VM at host startup. type: bool mutate_flags: choices: - ADD_UUID - ADD_MAC_ADDRESSES - ADD_MAC_ADDRESSES_FUZZY default: - ADD_UUID description: - For each mutate_flag, we will modify the given XML in some way - ADD_UUID will add an existing domain's UUID to the xml if it's missing - ADD_MAC_ADDRESSES will look up interfaces in the existing domain with a matching alias and copy the MAC address over. The matching interface doesn't need to be of the same type or source network. - ADD_MAC_ADDRESSES_FUZZY will try to match incoming interfaces with interfaces of the existing domain sharing the same type and source network/device. It may not always result in the expected outcome, particularly if a domain has multiple interface attached to the same host device and only some of those devices have <mac>s. Use caution, do some testing for your particular use-case! elements: str type: list
list_vms: description: The list of vms defined on the remote system. returned: success sample: - build.example.org - dev.example.org type: list status: description: The status of the VM, among running, crashed, paused and shutdown. returned: success sample: success type: str