community.libvirt.virt – Manages virtual machines supported by libvirt

Note

This plugin is part of the community.libvirt collection (version 1.0.2).

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.

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

Parameters

Parameter Choices/Defaults Comments
autostart
boolean
    Choices:
  • no
  • yes
start VM at host startup.
command
string
    Choices:
  • create
  • define
  • destroy
  • freemem
  • get_xml
  • info
  • list_vms
  • nodeinfo
  • pause
  • shutdown
  • start
  • status
  • stop
  • undefine
  • unpause
  • virttype
In addition to state management, various non-idempotent commands are available.
name
string
name of the guest VM being managed. Note that VM must be previously defined with xml.
This option is required unless command is list_vms or info.

aliases: guest
state
string
    Choices:
  • destroyed
  • paused
  • running
  • shutdown
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. state and command are mutually exclusive except when command=list_vms. In this case all VMs in specified state will be listed.
uri
string
Default:
"qemu:///system"
libvirt connection uri.
xml
string
XML document used with the define command.
Must be raw XML content using lookup. XML cannot be reference to a file.

Examples

# a playbook task line:
- 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 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 Returned Description
list_vms
list / elements=string
success
The list of vms defined on the remote system

Sample:
['build.example.org', 'dev.example.org']
status
string
success
The status of the VM, among running, crashed, paused and shutdown

Sample:
success


Authors

  • Ansible Core Team
  • Michael DeHaan
  • Seth Vidal (@skvidal)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/libvirt/virt_module.html