github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/docs/drivers/qemu.mdx (about)

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