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