github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/drivers/qemu.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: 'Drivers: QEMU'
     4  description: The QEMU task driver is used to run virtual machines using QEMU/KVM.
     5  ---
     6  
     7  # QEMU Driver
     8  
     9  Name: `qemu`
    10  
    11  The `qemu` driver provides a generic virtual machine runner. QEMU can utilize
    12  the KVM kernel module to utilize hardware virtualization features and provide
    13  great performance. Currently the `qemu` driver can map a set of ports from the
    14  host machine to the guest virtual machine, and provides configuration for
    15  resource allocation.
    16  
    17  The `qemu` driver can execute any regular `qemu` image (e.g. `qcow`, `img`,
    18  `iso`), and is currently invoked with `qemu-system-x86_64`.
    19  
    20  The driver requires the image to be accessible from the Nomad client via the
    21  [`artifact` downloader](/docs/job-specification/artifact).
    22  
    23  ## Task Configuration
    24  
    25  ```hcl
    26  task "webservice" {
    27    driver = "qemu"
    28  
    29    config {
    30      image_path        = "/path/to/my/linux.img"
    31      accelerator       = "kvm"
    32      graceful_shutdown = true
    33      args              = ["-nodefaults", "-nodefconfig"]
    34    }
    35  }
    36  ```
    37  
    38  The `qemu` driver supports the following configuration in the job spec:
    39  
    40  - `image_path` - The path to the downloaded image. In most cases this will just
    41    be the name of the image. However, if the supplied artifact is an archive that
    42    contains the image in a subfolder, the path will need to be the relative path
    43    (`subdir/from_archive/my.img`).
    44  
    45  - `drive_interface` - (Optional) This option defines on which type of interface
    46    the drive is connected. Available types are: `ide`, `scsi`, `sd`, `mtd`,
    47    `floppy`, `pflash`, `virtio` and `none`. Default is `ide`.
    48  
    49  - `accelerator` - (Optional) The type of accelerator to use in the invocation.
    50    If the host machine has `qemu` installed with KVM support, users can specify
    51    `kvm` for the `accelerator`. Default is `tcg`.
    52  
    53  - `graceful_shutdown` `(bool: false)` - Using the [qemu
    54    monitor](https://en.wikibooks.org/wiki/QEMU/Monitor), send an ACPI shutdown
    55    signal to virtual machines rather than simply terminating them. This emulates
    56    a physical power button press, and gives instances a chance to shut down
    57    cleanly. If the VM is still running after `kill_timeout`, it will be
    58    forcefully terminated. This feature uses a Unix socket that is placed within
    59    the task directory and operating systems may impose a limit on how long these
    60    paths can be. This feature is currently not supported on Windows.
    61  
    62  - `guest_agent` `(bool: false)` - Enable support for the [QEMU Guest
    63    Agent](https://wiki.qemu.org/Features/GuestAgent) for this virtual machine.
    64    This will add the necessary virtual hardware and create a `qa.sock` file in
    65    the task's working directory for interacting with the agent. The QEMU Guest
    66    Agent must be running in the guest VM. This feature is currently not
    67    supported on Windows.
    68  
    69  - `port_map` - (Optional) A key-value map of port labels.
    70  
    71    ```hcl
    72    config {
    73      # Forward the host port with the label "db" to the guest VM's port 6539.
    74      port_map {
    75        db = 6539
    76      }
    77    }
    78    ```
    79  
    80  - `args` - (Optional) A list of strings that is passed to QEMU as command line
    81    options.
    82  
    83  ## Examples
    84  
    85  A simple config block to run a `qemu` image:
    86  
    87  ```
    88  task "virtual" {
    89    driver = "qemu"
    90  
    91    config {
    92      image_path  = "local/linux.img"
    93      accelerator = "kvm"
    94      args        = ["-nodefaults", "-nodefconfig"]
    95    }
    96  
    97    # Specifying an artifact is required with the "qemu"
    98    # driver. This is the # mechanism to ship the image to be run.
    99    artifact {
   100      source = "https://internal.file.server/linux.img"
   101  
   102      options {
   103        checksum = "md5:123445555555555"
   104      }
   105    }
   106  ```
   107  
   108  ## Capabilities
   109  
   110  The `qemu` driver implements the following [capabilities](/docs/concepts/plugins/task-drivers#capabilities-capabilities-error).
   111  
   112  | Feature              | Implementation |
   113  | -------------------- | -------------- |
   114  | `nomad alloc signal` | false          |
   115  | `nomad alloc exec`   | false          |
   116  | filesystem isolation | image          |
   117  | network isolation    | none           |
   118  | volume mounting      | none           |
   119  
   120  ## Client Requirements
   121  
   122  The `qemu` driver requires QEMU to be installed and in your system's `$PATH`.
   123  The task must also specify at least one artifact to download, as this is the only
   124  way to retrieve the image being run.
   125  
   126  ## Client Attributes
   127  
   128  The `qemu` driver will set the following client attributes:
   129  
   130  - `driver.qemu` - Set to `1` if QEMU is found on the host node. Nomad determines
   131    this by executing `qemu-system-x86_64 -version` on the host and parsing the output
   132  - `driver.qemu.version` - Version of `qemu-system-x86_64`, ex: `2.4.0`
   133  
   134  Here is an example of using these properties in a job file:
   135  
   136  ```hcl
   137  job "docs" {
   138    # Only run this job where the qemu version is higher than 1.2.3.
   139    constraint {
   140      attribute = "${driver.qemu.version}"
   141      operator  = ">"
   142      value     = "1.2.3"
   143    }
   144  }
   145  ```
   146  
   147  ## Plugin Options
   148  
   149  ```hcl
   150  plugin "qemu" {
   151    config {
   152      image_paths = ["/mnt/image/paths"]
   153      args_allowlist = ["-drive", "-usbdevice"]
   154    }
   155  }
   156  ```
   157  
   158  - `image_paths` (`[]string`: `[]`) - Specifies the host paths the QEMU
   159    driver is allowed to load images from.
   160  - `args_allowlist` (`[]string`: `[]`) - Specifies the command line
   161    flags that the [`args`] option is permitted to pass to QEMU. If
   162    unset, a job submitter can pass any command line flag into QEMU,
   163    including flags that provide the VM with access to host devices such
   164    as USB drives. Refer to the [QEMU documentation] for the available
   165    flags.
   166  
   167  ## Resource Isolation
   168  
   169  Nomad uses QEMU to provide full software virtualization for virtual machine
   170  workloads. Nomad can use QEMU KVM's hardware-assisted virtualization to deliver
   171  better performance.
   172  
   173  Virtualization provides the highest level of isolation for workloads that
   174  require additional security, and resource use is constrained by the QEMU
   175  hypervisor rather than the host kernel. VM network traffic still flows through
   176  the host's interface(s).
   177  
   178  Note that the strong isolation provided by virtualization only applies
   179  to the workload once the VM is started. Operators should use the
   180  `args_allowlist` option to prevent job submitters from accessing
   181  devices and resources they are not allowed to access.
   182  
   183  [`args`]: /docs/drivers/qemu#args
   184  [QEMU documentation]: https://www.qemu.org/docs/master/system/invocation.html