Libvirt VM

This role sets up and manages virtual machines (VMs) on a KVM hypervisor, including creating and deleting VMs.

Requirements

The host system must have Virtualization Technology (VT) enabled and should be configured with libvirt/KVM beforehand.

Role Variables

• libvirt_vm_default_console_log_dir: Default folder for VM console logs if a specific log path is not provided. Default is "/var/log/libvirt/qemu/".

• libvirt_vm_image_cache_path: Folder to store cached downloaded images. Default is "/tmp/".

• libvirt_volume_default_images_path: Folder for storing instance images. Default is '/var/lib/libvirt/images'.

• libvirt_volume_default_type: Type of volume backing the instance. Default is volume.

• libvirt_volume_default_format: Format for volumes created, default is qcow2.

• libvirt_volume_default_device: Specifies how the device appears in the guest OS. Defaults to disk.

• libvirt_vm_engine: Virtualization engine. If not specified, the role will try to choose the best one automatically.

• libvirt_vm_emulator: Path to the emulator binary. If not specified, the role will try to detect it automatically.

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

• libvirt_vm_arch: CPU architecture, default is x86_64.

• libvirt_vm_uri: Override the libvirt connection URI. Refer to the libvirt documentation for details.

• libvirt_vm_virsh_default_env: Variables in this dictionary will be included in the environment when running virsh commands.

• libvirt_vm_clock_offset: If provided, sets the instance's clock offset. If not defined, sync is set to localtime.

• libvirt_vms: List of VMs to be created or deleted. Each VM can have the following attributes:

  • state: Set to present to create or absent to delete the VM. Default is present.

  • name: Name to assign to the VM.

  • memory_mb: Amount of memory for the VM in megabytes.

  • vcpus: Number of virtual CPU cores for the VM.

  • machine: Type of virtual machine. Default is None for libvirt_vm_engine as kvm, otherwise pc-1.0.

  • cpu_mode: Virtual machine CPU mode. Default is host-passthrough for kvm, otherwise host-model. Set to none to avoid configuring a CPU mode.

  • clock_offset: Overrides the default in libvirt_vm_clock_offset.

  • enable_vnc: If true, enables VNC listening on localhost for tools like VirtManager.

  • volumes: List of volumes to attach to the VM, defined with:

    • pool: Name or UUID of the storage pool for the volume.
    • name: Name for the volume being created; include an extension for file type volumes.
    • file_path: Location for file type volume images; defaults to libvirt_volume_default_images_path.
    • device: Either disk or cdrom.
    • capacity: Size of the volume (can use M,G,T or MB,GB,TB, etc.) (required for disk type).
    • format: Options include raw, qcow2, vmdk. Default is qcow2.
    • image: (optional) URL for initializing the volume image.
    • backing_image: (optional) Name of the backing volume; must be in the same pool (copy-on-write).
    • image and backing_image cannot be used together.
    • target: (optional) Manually specify volume type and order.

  • interfaces: List of network interfaces for the VM, defined with:

    • type: Type of the interface. Options:

      • network: Connects to a named Libvirt virtual network (default).
      • direct: Connects directly to a host's physical interface using macvtap.

    • network: Name of the network for the interface; required if type is network.

    • mac: "Hardware" address for the virtual instance; if not provided, one is created.

    • source: A dict defining the host interface for this VM interface; required if type is direct:

      • dev: Name of the host interface for this VM interface.
      • mode: Options are vepa, bridge, private, or passthrough. Default is vepa.

  • console_log_enabled: If true, logs console output to a file at the specified console_log_path; otherwise, directs output to a PTY. Default is false.

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

  • start: If true, starts the VM right after defining it. Default is true.

  • autostart: If true, starts the VM when the host starts. Default is true.

  • xml_file: Optionally provide a modified XML template for customization, based on the default vm.xml.j2 template.

Note: The following variables are outdated: 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 libvirt_vms is not set, it defaults to a list containing a VM specification using these outdated variables.

Dependencies

If using qcow2 formatted drives, qemu-img (included in qemu-utils package) is needed.

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