github.com/taylorchu/nomad@v0.5.3-rc1.0.20170407200202-db11e7dd7b55/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      args        = ["-nodefaults", "-nodefconfig"]
    35    }
    36  }  
    37  ```
    38  
    39  The `qemu` driver supports the following configuration in the job spec:
    40  
    41  * `image_path` - The path to the downloaded image. In most cases this will just
    42    be the name of the image. However, if the supplied artifact is an archive that
    43    contains the image in a subfolder, the path will need to be the relative path
    44    (`subdir/from_archive/my.img`).
    45  
    46  * `accelerator` - (Optional) The type of accelerator to use in the invocation.
    47    If the host machine has `qemu` installed with KVM support, users can specify
    48    `kvm` for the `accelerator`. Default is `tcg`.
    49  
    50  * `port_map` - (Optional) A key-value map of port labels.
    51  
    52      ```hcl
    53      config {
    54        # Forward the host port with the label "db" to the guest VM's port 6539.
    55        port_map {
    56          db = 6539
    57        }
    58      }
    59      ```
    60  
    61  * `args` - (Optional) A list of strings that is passed to qemu as command line
    62    options.
    63  
    64  ## Examples
    65  
    66  A simple config block to run a `qemu` image:
    67  
    68  ```
    69  task "virtual" {
    70    driver = "qemu"
    71  
    72    config {
    73      image_path  = "local/linux.img"
    74      accelerator = "kvm"
    75      args        = ["-nodefaults", "-nodefconfig"]
    76    }
    77  
    78    # Specifying an artifact is required with the "qemu"
    79    # driver. This is the # mechanism to ship the image to be run.
    80    artifact {
    81      source = "https://internal.file.server/linux.img"
    82  
    83      options {
    84        checksum = "md5:123445555555555"
    85      }
    86    }
    87  ```
    88  
    89  ## Client Requirements
    90  
    91  The `qemu` driver requires Qemu to be installed and in your system's `$PATH`.
    92  The task must also specify at least one artifact to download, as this is the only
    93  way to retrieve the image being run.
    94  
    95  ## Client Attributes
    96  
    97  The `qemu` driver will set the following client attributes:
    98  
    99  * `driver.qemu` - Set to `1` if Qemu is found on the host node. Nomad determines
   100  this by executing `qemu-system-x86_64 -version` on the host and parsing the output
   101  * `driver.qemu.version` - Version of `qemu-system-x86_64`, ex: `2.4.0`
   102  
   103  Here is an example of using these properties in a job file:
   104  
   105  ```hcl
   106  job "docs" {
   107    # Only run this job where the qemu version is higher than 1.2.3.
   108    constraint {
   109      attribute = "${driver.qemu.version}"
   110      operator  = ">"
   111      value     = "1.2.3"
   112    }
   113  }
   114  ```
   115  
   116  ## Resource Isolation
   117  
   118  Nomad uses Qemu to provide full software virtualization for virtual machine
   119  workloads. Nomad can use Qemu KVM's hardware-assisted virtualization to deliver
   120  better performance.
   121  
   122  Virtualization provides the highest level of isolation for workloads that
   123  require additional security, and resource use is constrained by the Qemu
   124  hypervisor rather than the host kernel. VM network traffic still flows through
   125  the host's interface(s).