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/qemu/".

• 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

  • 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.

  • 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.

  • 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'

        - 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)