Nomad Docs: Add new QEMU driver parameters #1416

mismithhisler · 2025-12-01T21:36:08Z

Description

Links

Code PR: hashicorp/nomad#27179

Contributor checklists

Review urgency:

ASAP: Bug fixes, broken content, imminent releases
3 days: Small changes, easy reviews
1 week: Default expectation
Best effort: No urgency

Pull request:

Verify that the PR is set to merge into the correct base branch
Verify that all status checks passed
Verify that the preview environment deployed successfully
Add additional reviewers if they are not part of assigned groups

Content:

I added redirects for any moved or removed pages
I followed the Education style guide
I looked at the local or Vercel build to make sure the content rendered correctly

Reviewer checklist

This PR is set to merge into the correct base branch.
The content does not contain technical inaccuracies.
The content follows the Education content and style guides.
I have verified and tested changes to instructions for end users.

github-actions · 2025-12-01T21:38:05Z

Vercel Previews Deployed

Name	Status	Preview	Updated (UTC)
Dev Portal	✅ Ready (Inspect)	Visit Preview	Tue Dec 2 22:26:36 UTC 2025
Unified Docs API	✅ Ready (Inspect)	Visit Preview	Tue Dec 2 22:21:07 UTC 2025

github-actions · 2025-12-01T22:01:25Z

Broken Link Checker

No broken links found! 🎉

aimeeu

Thanks! I left a few style guide suggestions.

content/nomad/v1.11.x/content/docs/job-declare/task-driver/qemu.mdx

aimeeu · 2025-12-02T16:07:31Z

content/nomad/v1.11.x/content/docs/upgrade/upgrade-specific.mdx

+In Nomad 1.11.1, `emulator` and `machine_type` were added to the task config,
+and `fingerprint_emulator` was added to the driver config. These default to the
+previously used values of `qemu-system-x86_64`, and `pc`. Previously, when using
+the `kvm` accelerator, the machine type `host` was forced. This is no longer true,
+the value for `machine_type` will be used. Additionally, if using resources.cores,
+with the `kvm` accelerator, the `-smp` was hardcoded to that number of cores. This
+is now only done if the user has not specified a custom -smp flag.


Suggested change

In Nomad 1.11.1, `emulator` and `machine_type` were added to the task config,

and `fingerprint_emulator` was added to the driver config. These default to the

previously used values of `qemu-system-x86_64`, and `pc`. Previously, when using

the `kvm` accelerator, the machine type `host` was forced. This is no longer true,

the value for `machine_type` will be used. Additionally, if using resources.cores,

with the `kvm` accelerator, the `-smp` was hardcoded to that number of cores. This

is now only done if the user has not specified a custom -smp flag.

In Nomad 1.11.1, we added `emulator` and `machine_type` to the task config and

`fingerprint_emulator` to the driver config. These default to the previously

used values of `qemu-system-x86_64` and `pc`. Previously, when using the `kvm`

accelerator, Nomad forced the machine type `host`. This is no longer true. Nomad

now uses the value for `machine_type` . Additionally, if using `resources.cores`

with the `kvm` accelerator, the `-smp` used that number of cores. Nomad now only

uses the `resources.cores` value when you have not specified a custom `-smp`

flag.

I had to refactor this paragraph a good bit after refactoring my PR

aimeeu

I left some style guide suggestions. Let me know if you'd like me to apply them directly.

aimeeu · 2025-12-03T13:19:53Z

content/nomad/v1.11.x/content/docs/upgrade/upgrade-specific.mdx

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


Suggested change

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.

In Nomad 1.11.1, we added `emulator` and `machine_type` to the task config.

These default to the previously used values of `qemu-system-x86_64`, and `pc`.

We also added the `emulators_allowlist` driver config, which defaults to

allowing any emulator to run.

style update to use active voice

aimeeu · 2025-12-03T13:25:44Z

content/nomad/v1.11.x/content/docs/upgrade/upgrade-specific.mdx

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


Suggested change

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.

Previously, using the `kvm` accelerator required a machine type of `host`. This

is no longer enforced. Nomad now uses the value for `machine_type`. Also, if

using `resources.cores` with the `kvm` accelerator, Nomad set the `-smp` value

to the `resources.cores` value. Nomad now only does this when you do not specify

a custom `-smp` flag.

Style updates to use present tense and active voice.

aimeeu · 2025-12-03T13:27:51Z

content/nomad/v1.11.x/content/docs/deploy/task-driver/qemu.mdx

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


Suggested change

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

- `driver.qemu` - Set to `1` if QEMU is found on the host node. Nomad determines

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.

aimeeu · 2025-12-03T13:29:15Z

content/nomad/v1.11.x/content/docs/deploy/task-driver/qemu.mdx

+- `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.


Suggested change

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

- `emulators_allowlist` (`[]string`: `[]`) - Specifies the allowed emulators

tasks may use. When specified, Nomad only fingerprints this list and does not

allow tasks to run using other emulators. Defaults to fingerprinting and

allowing all emulators.

aimeeu · 2025-12-03T13:29:42Z

content/nomad/v1.11.x/content/docs/job-declare/task-driver/qemu.mdx

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


Suggested change

parameter (ex. If `x86_64` is specified, Nomad will use `qemu-system-x86_64`).

parameter (ex. If `x86_64` is specified, Nomad uses `qemu-system-x86_64`).

style update to use present tense

aimeeu · 2025-12-03T13:30:25Z

content/nomad/v1.11.x/content/docs/job-declare/task-driver/qemu.mdx

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


Suggested change

(`subdir/from_archive/my.img`). This image is given an ID of "image0".

(`subdir/from_archive/my.img`). Nomad give this image an ID of "image0".

style update to use active voice

add new config parameters to nomad qemu driver

6638bc3

mismithhisler self-assigned this Dec 1, 2025

mismithhisler added the Nomad label Dec 1, 2025

mismithhisler requested review from a team as code owners December 1, 2025 21:36

mismithhisler requested a review from aimeeu December 1, 2025 21:36

boruszak added the Runtime label Dec 1, 2025

add upgrade note for QEMU driver update

5614aa8

aimeeu changed the title ~~Nomad Docs~~ Nomad Docs: Add new QEMU driver parameters Dec 2, 2025

aimeeu approved these changes Dec 2, 2025

View reviewed changes

aimeeu added the Nomad-Minor PR for Nomad minor release label Dec 2, 2025

update docs after PR refactor

6abcd3d

aimeeu requested changes Dec 3, 2025

View reviewed changes

-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.
+Previously, using the `kvm` accelerator required a machine type of `host`. This
+is no longer enforced. Nomad now uses the value for `machine_type`. Also, if
+using `resources.cores` with the `kvm` accelerator, Nomad set the `-smp` value
+to the `resources.cores` value. Nomad now only does this when you do not specify
+a custom `-smp` flag.

	parameter (ex. If `x86_64` is specified, Nomad will use `qemu-system-x86_64`).
	parameter (ex. If `x86_64` is specified, Nomad uses `qemu-system-x86_64`).

	(`subdir/from_archive/my.img`). This image is given an ID of "image0".
	(`subdir/from_archive/my.img`). Nomad give this image an ID of "image0".

Nomad Docs: Add new QEMU driver parameters #1416

Are you sure you want to change the base?

Nomad Docs: Add new QEMU driver parameters #1416

Conversation

mismithhisler commented Dec 1, 2025 • edited by aimeeu Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Links

Contributor checklists

Reviewer checklist

Uh oh!

github-actions bot commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vercel Previews Deployed

Uh oh!

github-actions bot commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Broken Link Checker

Uh oh!

aimeeu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aimeeu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mismithhisler commented Dec 1, 2025 •

edited by aimeeu

Loading

github-actions bot commented Dec 1, 2025 •

edited

Loading

github-actions bot commented Dec 1, 2025 •

edited

Loading