virt – Manages virtual machines supported by libvirt

From Get docs
Ansible/docs/2.8/modules/virt module


virt – Manages virtual machines supported by libvirt

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

added in 2.3

  • no
  • yes

start VM at host startup.

command

-

  • 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

-

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.

state

-

  • 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

-

Default:

"qemu:///system"

libvirt connection uri.

xml

-

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:
- 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
  virt:
    command: define
    xml: "{{ lookup('template', 'container-template.xml.j2') }}"
    uri: 'lxc:///'
- name: start vm
  virt:
    name: foo
    state: running
    uri: 'lxc:///'

# setting autostart on a qemu VM (default uri)
- name: set autostart for a VM
  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
  virt:
    command: define
    xml: "{{ lookup('template', 'vm_template.xml.j2') }}"
    autostart: yes

# Listing VMs
- name: list all VMs
  virt:
    command: list_vms
  register: all_vms

- name: list only running VMs
  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

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




Status

Authors

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

Hint

If you notice any issues in this documentation you can edit this document to improve it.


© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/virt_module.html