community.libvirt.virt module – Manages virtual machines supported by libvirt
Note
This module is part of the community.libvirt collection (version 1.2.0).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.libvirt
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.libvirt.virt
.
Synopsis
Manages virtual machines supported by libvirt.
Requirements
The below requirements are needed on the host that executes this module.
python >= 2.6
libvirt python bindings
Parameters
Parameter |
Comments |
---|---|
Start VM at host startup. Choices:
|
|
In addition to state management, various non-idempotent commands are available. Choices:
|
|
name of the guest VM being managed. Note that VM must be previously defined with xml. This option is required unless command is |
|
Note that there may be some lag for state requests like Choices:
|
|
Libvirt connection uri. Default: |
|
XML document used with the define command. Must be raw XML content using |
Examples
# 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: yes
# 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: yes
# 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
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
The list of vms defined on the remote system. Returned: success Sample: |
|
The status of the VM, among running, crashed, paused and shutdown. Returned: success Sample: |