github.com/smintz/nomad@v0.8.3/website/source/docs/drivers/qemu.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "Drivers: Qemu" 4 sidebar_current: "docs-drivers-qemu" 5 description: |- 6 The Qemu task driver is used to run virtual machines using Qemu/KVM. 7 --- 8 9 # Qemu Driver 10 11 Name: `qemu` 12 13 The `qemu` driver provides a generic virtual machine runner. Qemu can utilize 14 the KVM kernel module to utilize hardware virtualization features and provide 15 great performance. Currently the `qemu` driver can map a set of ports from the 16 host machine to the guest virtual machine, and provides configuration for 17 resource allocation. 18 19 The `qemu` driver can execute any regular `qemu` image (e.g. `qcow`, `img`, 20 `iso`), and is currently invoked with `qemu-system-x86_64`. 21 22 The driver requires the image to be accessible from the Nomad client via the 23 [`artifact` downloader](/docs/job-specification/artifact.html). 24 25 ## Task Configuration 26 27 ```hcl 28 task "webservice" { 29 driver = "qemu" 30 31 config { 32 image_path = "/path/to/my/linux.img" 33 accelerator = "kvm" 34 graceful_shutdown = true 35 args = ["-nodefaults", "-nodefconfig"] 36 } 37 } 38 ``` 39 40 The `qemu` driver supports the following configuration in the job spec: 41 42 * `image_path` - The path to the downloaded image. In most cases this will just 43 be the name of the image. However, if the supplied artifact is an archive that 44 contains the image in a subfolder, the path will need to be the relative path 45 (`subdir/from_archive/my.img`). 46 47 * `accelerator` - (Optional) The type of accelerator to use in the invocation. 48 If the host machine has `qemu` installed with KVM support, users can specify 49 `kvm` for the `accelerator`. Default is `tcg`. 50 51 * `graceful_shutdown` `(bool: false)` - Using the [qemu 52 monitor](https://en.wikibooks.org/wiki/QEMU/Monitor), send an ACPI shutdown 53 signal to virtual machines rather than simply terminating them. This emulates 54 a physical power button press, and gives instances a chance to shut down 55 cleanly. If the VM is still running after ``kill_timeout``, it will be 56 forcefully terminated. (Note that 57 [prior to qemu 2.10.1](https://github.com/qemu/qemu/commit/ad9579aaa16d5b385922d49edac2c96c79bcfb6), 58 the monitor socket path is limited to 108 characters. Graceful shutdown will 59 be disabled if qemu is < 2.10.1 and the generated monitor path exceeds this 60 length. You may encounter this issue if you set long 61 [data_dir](https://www.nomadproject.io/docs/agent/configuration/index.html#data_dir) 62 or 63 [alloc_dir](https://www.nomadproject.io/docs/agent/configuration/client.html#alloc_dir) 64 paths.) This feature is currently not supported on Windows. 65 66 * `port_map` - (Optional) A key-value map of port labels. 67 68 ```hcl 69 config { 70 # Forward the host port with the label "db" to the guest VM's port 6539. 71 port_map { 72 db = 6539 73 } 74 } 75 ``` 76 77 * `args` - (Optional) A list of strings that is passed to qemu as command line 78 options. 79 80 ## Examples 81 82 A simple config block to run a `qemu` image: 83 84 ``` 85 task "virtual" { 86 driver = "qemu" 87 88 config { 89 image_path = "local/linux.img" 90 accelerator = "kvm" 91 args = ["-nodefaults", "-nodefconfig"] 92 } 93 94 # Specifying an artifact is required with the "qemu" 95 # driver. This is the # mechanism to ship the image to be run. 96 artifact { 97 source = "https://internal.file.server/linux.img" 98 99 options { 100 checksum = "md5:123445555555555" 101 } 102 } 103 ``` 104 105 ## Client Requirements 106 107 The `qemu` driver requires Qemu to be installed and in your system's `$PATH`. 108 The task must also specify at least one artifact to download, as this is the only 109 way to retrieve the image being run. 110 111 ## Client Attributes 112 113 The `qemu` driver will set the following client attributes: 114 115 * `driver.qemu` - Set to `1` if Qemu is found on the host node. Nomad determines 116 this by executing `qemu-system-x86_64 -version` on the host and parsing the output 117 * `driver.qemu.version` - Version of `qemu-system-x86_64`, ex: `2.4.0` 118 119 Here is an example of using these properties in a job file: 120 121 ```hcl 122 job "docs" { 123 # Only run this job where the qemu version is higher than 1.2.3. 124 constraint { 125 attribute = "${driver.qemu.version}" 126 operator = ">" 127 value = "1.2.3" 128 } 129 } 130 ``` 131 132 ## Resource Isolation 133 134 Nomad uses Qemu to provide full software virtualization for virtual machine 135 workloads. Nomad can use Qemu KVM's hardware-assisted virtualization to deliver 136 better performance. 137 138 Virtualization provides the highest level of isolation for workloads that 139 require additional security, and resource use is constrained by the Qemu 140 hypervisor rather than the host kernel. VM network traffic still flows through 141 the host's interface(s).