Documentation

virt - Manages virtual machines supported by libvirt

Synopsis

  • Manages virtual machines supported by libvirt.

Requirements (on host that executes module)

  • python >= 2.6
  • libvirt-python

Options

parameter required default choices comments
command
no
  • create
  • status
  • start
  • stop
  • pause
  • unpause
  • shutdown
  • undefine
  • destroy
  • get_xml
  • autostart
  • freemem
  • list_vms
  • info
  • nodeinfo
  • virttype
  • define
in addition to state management, various non-idempotent commands are available. See examples
name
yes
    name of the guest VM being managed. Note that VM must be previously defined with xml.
    state
    no no
    • running
    • shutdown
    • destroyed
    • paused
    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.
    uri
    no
      libvirt connection uri
      xml
      no
        XML document used with the define command

        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:///"
        
        ---
        # a playbook example of defining and launching an LXC guest
        tasks:
          - name: define vm
            virt:
                name: foo
                command: define
                xml: "{{ lookup('template', 'container-template.xml.j2') }}"
                uri: 'lxc:///'
          - name: start vm
            virt:
                name: foo
                state: running
                uri: 'lxc:///'
        

        Return Values

        Common return values are documented here Return Values, the following are the fields unique to this module:

        name description returned type sample
        status The status of the VM, among running, crashed, paused and shutdown success string success
        list_vms The list of vms defined on the remote system success dictionary ['build.example.org', 'dev.example.org']
        contains:
        name description returned type sample


        Status

        This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

        Support

        This module is community maintained without core committer oversight.

        For more information on what this means please read Module Support

        For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.