Skip to content

Nomad Docs: Add new QEMU driver parameters #1416

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: nomad/1.11.1
Choose a base branch
from
+42 −5
Open

Nomad Docs: Add new QEMU driver parameters #1416

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6638bc3
add new config parameters to nomad qemu driver
mismithhisler Dec 1, 2025
5614aa8
add upgrade note for QEMU driver update
mismithhisler Dec 2, 2025
6abcd3d
update docs after PR refactor
mismithhisler Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 20 additions & 3 deletions content/nomad/v1.11.x/content/docs/deploy/task-driver/qemu.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,22 +43,35 @@ way to retrieve the image being run.
The `qemu` driver will set the following client attributes:

- `driver.qemu` - Set to `1` if QEMU is found on the host node. Nomad determines
this by executing `qemu-system-x86_64 -version` on the host and parsing the output
- `driver.qemu.version` - Version of `qemu-system-x86_64`, ex: `2.4.0`
this by executing the first found qemu binary with `--version` on the client and
parsing the output. Nomad does not get the version of each individual qemu emulator.
- `driver.qemu.version` - Version found running the command for `driver.qemu`, ex: `2.4.0`
- `driver.qemu.emulators` - A comma separated list of emulators detected on the client.

Here is an example of using these properties in a job file:

```hcl
job "docs" {
# Only run this job where the qemu version is higher than 1.2.3.
constraint {
attribute = "${driver.qemu.version}"
attribute = "${attr.driver.qemu.version}"
operator = ">"
value = "1.2.3"
}
}
```

```hcl
job "docs" {
# Only run this job where the the qemu-system-aarch64 emulator was detected.
constraint {
attribute = "${attr.driver.qemu.emulators}"
operator = "set_contains"
value = "aarch64"
}
}
```

## Plugin Options

```hcl
Expand All @@ -78,6 +91,10 @@ plugin "qemu" {
including flags that provide the VM with access to host devices such
as USB drives. Refer to the [QEMU documentation] for the available
flags.
- `emulators_allowlist` (`[]string`: `[]`) - Specifies the allowed emulators
tasks may use. When specified Nomad will only fingerprint this list, and
will not allow tasks to run using other emulators. Defaults to fingerprinting
and allowing all emulators.

## Resource Isolation

Expand Down
12 changes: 10 additions & 2 deletions content/nomad/v1.11.x/content/docs/job-declare/task-driver/qemu.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ host machine to the guest virtual machine, and provides configuration for
resource allocation.

The `qemu` driver can execute any regular `qemu` image (e.g. `qcow`, `img`,
`iso`), and is currently invoked with `qemu-system-x86_64`.
`iso`). Nomad uses the QEMU binary specified by the `emulator`
parameter (ex. If `x86_64` is specified, Nomad will use `qemu-system-x86_64`).

The driver requires the image to be accessible from the Nomad client via the
[`artifact` downloader](/nomad/docs/job-specification/artifact).
Expand All @@ -31,6 +32,8 @@ task "webservice" {

config {
image_path = "/path/to/my/linux.img"
emulator = "x86_64"
machine_type = "q35"
accelerator = "kvm"
graceful_shutdown = true
args = ["-nodefaults", "-nodefconfig"]
Expand All @@ -43,7 +46,12 @@ The `qemu` driver supports the following configuration in the job spec:
- `image_path` - The path to the downloaded image. In most cases this will just
be the name of the image. However, if the supplied artifact is an archive that
contains the image in a subfolder, the path will need to be the relative path
(`subdir/from_archive/my.img`).
(`subdir/from_archive/my.img`). This image is given an ID of "image0".

- `emulator` `(string: "x86_64")` - The architecture of the QEMU emulator used to
run the virtual machine.

- `machine_type` `(string: "pc")` - Used to select the emulated machine by name.

- `drive_interface` - (Optional) This option defines on which type of interface
the drive is connected. Available types are: `ide`, `scsi`, `sd`, `mtd`,
Expand Down
12 changes: 12 additions & 0 deletions content/nomad/v1.11.x/content/docs/upgrade/upgrade-specific.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,18 @@ upgrade. However, specific versions of Nomad may have more details provided for
their upgrades as a result of new features or changed behavior. This page is
used to document those details separately from the standard upgrade flow.

## Nomad 1.11.1

In Nomad 1.11.1, `emulator` and `machine_type` were added to the task config.
These default to the previously used values of `qemu-system-x86_64`, and `pc`.
The `emulators_allowlist` driver config was also added, which defaults to
allowing any emulator to run.

Previously, when using the `kvm` accelerator the machine type `host` was required.
This is no longer enforced. The value for `machine_type` will be used. Also, if using
resources.cores with the `kvm` accelerator, the `-smp` was hardcoded to resources.cores
value. This is now only done if the user has not specified a custom -smp flag.

## Nomad 1.11.0

#### Sysbatch jobs will no longer accept `reschedule` blocks
Expand Down
Loading