Libvirt VM

This role configures and creates (or destroys) VMs on a KVM hypervisor.

Requirements

The host should have Virtualization Technology (VT) enabled and should be preconfigured with libvirt/KVM.

Role Variables

• libvirt_vm_default_console_log_dir: The default directory in which to store VM console logs, if a VM-specific log file path is not given. Default is "/var/log/libvirt-consoles".

• libvirt_vm_default_uuid_deterministic: Whether UUID should be calculated by hashing the VM name. If not, the UUID is randomly generated by libvirt when the VM is defined. Default is False.

• libvirt_vm_image_cache_path: The directory in which to cache downloaded images. Default is "/tmp/".

• libvirt_volume_default_images_path: Directory in which instance images are stored. Default is '/var/lib/libvirt/images'.

• libvirt_volume_default_type: What type of backing volume does the instance use? Default is volume. Options include block, file, network and volume.

• libvirt_volume_default_format: Format for volumes created by the role. Default is qcow2. Options include raw, qcow2, vmdk. See man virsh for the full range.

• libvirt_volume_default_device: Control how device appears in guest OS. Defaults to disk. Options include cdrom and disk.

• libvirt_vm_engine: virtualisation engine. If not set, the role will attempt to auto-detect the optimal engine to use.

• libvirt_vm_emulator: path to emulator binary. If not set, the role will attempt to auto-detect the correct emulator to use.

• libvirt_cpu_mode_default: The default CPU mode if libvirt_cpu_mode or vm.cpu_mode is undefined.

• libvirt_vm_arch: CPU architecture, default is x86_64.

• libvirt_vm_uri: Override the libvirt connection URI. See the libvirt docs docs for more details.

• libvirt_vm_virsh_default_env: Variables contained within this dictionary are added to the environment used when executing virsh commands.

• libvirt_vm_clock_offset. If defined the instances clock offset is set to the provided value. When undefined sync is set to localtime.

• libvirt_vm_trust_guest_rx_filters: Whether to trust guest receive filters. This gets mapped to the trustGuestRxFilters attribute of VM interfaces. Default is false

• libvirt_vms: list of VMs to be created/destroyed. Each one may have the following attributes:

  • state: set to present to create or absent to destroy the VM. Defaults to present.

  • name: the name to assign to the VM.

  • uuid: the UUID to manually assign to the VM. If specified, neither uuid_deterministic nor libvirt_vm_default_uuid_deterministic are used.

  • uuid_deterministic: overrides default set in libvirt_vm_default_uuid_deterministic

  • memory_mb: the memory to assign to the VM, in megabytes.

  • vcpus: the number of VCPU cores to assign to the VM.

  • machine: Virtual machine type. Default is None if libvirt_vm_engine is kvm, otherwise pc-1.0.

  • cpu_mode: Virtual machine CPU mode. Default is host-passthrough if libvirt_vm_engine is kvm, otherwise host-model. Can be set to none to not configure a cpu mode.

  • clock_offset: Overrides default set in libvirt_vm_clock_offset

  • enable_vnc: If true enables VNC listening on localhost for use with VirtManager and similar tools

  • enable_spice: If true enables SPICE listening for use with Virtual Machine Manager and similar tools

  • enable_guest_virtio: If true enables guest virtio device for use with Qemu guest agent

  • volumes: a list of volumes to attach to the VM. Each volume is defined with the following dict:

    • type: What type of backing volume does the instance use? All options for libvirt_volume_default_type are valid here. Default is libvirt_volume_default_type.
    • pool: Name or UUID of the storage pool from which the volume should be allocated. Required when type is volume.
    • name: Name to associate with the volume being created; For file type volumes include extension if you would like volumes created with one.
    • file_path: Where the image of file type volumes should be placed; defaults to libvirt_volume_default_images_path
    • device: Control how device appears in guest OS. All options for libvirt_volume_default_device are valid here. Default is libvirt_volume_default_type.
    • capacity: volume capacity, can be suffixed with k, M, G, T, P or E when type is network or MB,GB,TB, etc when type is disk (required when type is disk or network)
    • auth: Authentication details should they be required. If auth is required, username, type, and uuid or usage will need to be supplied. uuid and usage should not be both supplied.
    • source: Where the remote volume comes from when type is network. protocol, name and hosts_list should be supplied. port is optional.
    • format: Format of the volume. All options for libvirt_volume_default_format are valid here. Default is libvirt_volume_default_format.
    • image: (optional) a URL to an image with which the volume is initalised (full copy).
    • checksum: (optional) checksum of the image to avoid download when it's not necessary.
    • backing_image: (optional) name of the backing volume which is assumed to already be the same pool (copy-on-write).
    • image and backing_image are mutually exclusive options.
    • target: (optional) Manually influence type and order of volumes
    • dev: (optional) Block device path when type is block.
    • remote_src: (optional) When type is file or block, specify wether image points to a remote file (true) or a file local to the host that launched the playbook (false). Defaults to true.

  • usb_devices: a list of usb devices to present to the vm from the host.

    Each usb device is defined with the following dict:

    • vendor: The vendor id of the USB device.
    • product: The product id of the USB device.

    Note - Libvirt will error if the VM is provisioned and the USB device is not attached.

    To obtain the vendor id and product id of the usb device from the host running as sudo / root with the usb device plugged in run lsusb -v. Example below with an attached Sandisk USB Memory Stick with vendor id: 0x0781 and product id: 0x5567

    lsusb -v | grep -A4 -i sandisk
    
      idVendor           0x0781 SanDisk Corp.
      idProduct          0x5567 Cruzer Blade
      bcdDevice            1.00
      iManufacturer           1 
      iProduct                2 
    

  • interfaces: a list of network interfaces to attach to the VM. Each network interface is defined with the following dict:

    • type: The type of the interface. Possible values:

      • network: Attaches the interface to a named Libvirt virtual network. This is the default value.
      • direct: Directly attaches the interface to one of the host's physical interfaces, using the macvtap driver.

    • network: Name of the network to which an interface should be attached. Must be specified if and only if the interface type is network.

    • mac: "Hardware" address of the virtual instance, if absent one is created

    • source: A dict defining the host interface to which this VM interface should be attached. Must be specified if and only if the interface type is direct. Includes the following attributes:

      • dev: The name of the host interface to which this VM interface should be attached.
      • mode: options include vepa, bridge, private and passthrough. See man virsh for more details. Default is vepa.

    • trust_guest_rx_filters: Whether to trust guest receive filters. This gets mapped to the trustGuestRxFilters attribute of VM interfaces. Default is libvirt_vm_trust_guest_rx_filters.

    • model: The name of the interface model. Eg. e1000 or ne2k_pci, if undefined it defaults to virtio.

    • alias: An optional interface alias. This can be used to tie specific network configuration to persistent network devices via name. The user defined alias is always prefixed with ua- to be compliant (aliases without ua- are ignored by libvirt. If undefined it defaults to libvirt managed vnetX.

  • console_log_enabled: if true, log console output to a file at the path specified by console_log_path, instead of to a PTY. If false, direct terminal output to a PTY at serial port 0. Default is false.

  • console_log_path: Path to console log file. Default is {{ libvirt_vm_default_console_log_dir }}/{{ name }}-console.log.

  • start: Whether to immediately start the VM after defining it. Default is true.

  • autostart: Whether to start the VM when the host starts up. Default is true.

  • boot_firmware: Can be one of: bios, or efi. Defaults to bios.

  • xml_file: Optionally supply a modified XML template. Base customisation off the default vm.xml.j2 template so as to include the expected jinja expressions the role uses.

N.B. the following variables are deprecated: libvirt_vm_state, libvirt_vm_name, libvirt_vm_memory_mb, libvirt_vm_vcpus, libvirt_vm_engine, libvirt_vm_machine, libvirt_vm_cpu_mode, libvirt_vm_volumes, libvirt_vm_interfaces and libvirt_vm_console_log_path. If the variable libvirt_vms is left unset, its default value will be a singleton list containing a VM specification using these deprecated variables.

Dependencies

If using qcow2 format drives qemu-img (in qemu-utils package) is required.

Example Playbook

---
- name: Create VMs
  hosts: hypervisor
  roles:
    - role: stackhpc.libvirt-vm
      libvirt_vms:
        - state: present
          name: 'vm1'
          memory_mb: 512
          vcpus: 2
          volumes:
            - name: 'data1'
              device: 'disk'
              format: 'qcow2'
              capacity: '400GB'
              pool: 'my-pool'
            - name: 'debian-10.2.0-amd64-netinst.iso'
              type: 'file'
              device: 'cdrom'
              format: 'raw'
              target: 'hda'  # first device on ide bus
            - name: 'networkfs'
              type: 'network'
              format: 'raw'
              capacity: '50G'
              auth:
                username: 'admin'
                type: 'ceph'
                usage: 'rbd-pool'
              source:
                protocol: 'rbd'
                name: 'rbd/volume'
                hosts_list:
                  - 'mon1.example.org'
                  - 'mon2.example.org'
                  - 'mon3.example.org'
            - type: 'block'
              format: 'raw'
              dev: '/dev/sda'

          interfaces:
            - network: 'br-datacentre'
          
          usb_devices:
            - vendor: '0x0781'
              product: '0x5567'

        - state: present
          name: 'vm2'
          memory_mb: 1024
          vcpus: 1
          volumes:
            - name: 'data2'
              device: 'disk'
              format: 'qcow2'
              capacity: '200GB'
              pool: 'my-pool'
            - name: 'filestore'
              type: 'file'
              file_path: '/srv/cloud/images'
              capacity: '900GB'
          interfaces:
            - type: 'direct'
              source:
                dev: 'eth123'
                mode: 'private'
            - type: 'bridge'
              source:
                dev: 'br-datacentre'

Author Information

• Mark Goddard (mark@stackhpc.com)