Use the QEMU task driver in a job

Name: qemu

The qemu driver provides a generic virtual machine runner. QEMU can utilize the KVM kernel module to utilize hardware virtualization features and provide great performance. Currently the qemu driver can map a set of ports from the host machine to the guest virtual machine, and provides configuration for resource allocation.

The qemu driver can execute any regular qemu image (e.g. qcow, img, iso), and is currently invoked with qemu-system-x86_64.

The driver requires the image to be accessible from the Nomad client via the artifact downloader.

Refer to Configure the QEMU task driver for capabilities, client requirements, and plugin configuration.

Task Configuration

task "webservice" {
  driver = "qemu"

  config {
    image_path        = "/path/to/my/linux.img"
    accelerator       = "kvm"
    graceful_shutdown = true
    args              = ["-nodefaults", "-nodefconfig"]
  }
}

The qemu driver supports the following configuration in the job spec:

• image_path - The path to the downloaded image. In most cases this will just be the name of the image. However, if the supplied artifact is an archive that contains the image in a subfolder, the path will need to be the relative path (subdir/from_archive/my.img).

• drive_interface - (Optional) This option defines on which type of interface the drive is connected. Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio and none. Default is ide.

• accelerator - (Optional) The type of accelerator to use in the invocation. If the host machine has qemu installed with KVM support, users can specify kvm for the accelerator. Default is tcg.

• graceful_shutdown (bool: false) - Using the qemu monitor, send an ACPI shutdown signal to virtual machines rather than simply terminating them. This emulates a physical power button press, and gives instances a chance to shut down cleanly. If the VM is still running after kill_timeout, it will be forcefully terminated. This feature uses a Unix socket that is placed within the task directory and operating systems may impose a limit on how long these paths can be. This feature is currently not supported on Windows.

• guest_agent (bool: false) - Enable support for the QEMU Guest Agent for this virtual machine. This will add the necessary virtual hardware and create a qa.sock file in the task's working directory for interacting with the agent. The QEMU Guest Agent must be running in the guest VM. This feature is currently not supported on Windows.

• port_map - (Optional) A key-value map of port labels.

  config {
    # Forward the host port with the label "db" to the guest VM's port 6539.
    port_map {
      db = 6539
    }
  }
  

• args - (Optional) A list of strings that is passed to QEMU as command line options.

Examples

A simple config block to run a qemu image:

task "virtual" {
  driver = "qemu"
 
  config {
    image_path  = "local/linux.img"
    accelerator = "kvm"
    args        = ["-nodefaults", "-nodefconfig"]
  }
 
  # Specifying an artifact is required with the "qemu"
  # driver. This is the # mechanism to ship the image to be run.
  artifact {
    source = "https://internal.file.server/linux.img"
 
    options {
      checksum = "md5:123445555555555"
    }
  }