Try SpotterManages virtual machines supported by libvirt
Authors: Ansible Core Team, Michael DeHaan, Seth Vidal (@skvidal)
Install with ansible-galaxy collection install community.libvirt:==1.3.0
collections:
- name: community.libvirt
version: 1.3.0Manages 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