Improve qemu cmdline by cpaelzer · Pull Request #5540 · canonical/cloud-init

cpaelzer · 2024-07-24T13:12:15Z

I have signed the CLA: https://ubuntu.com/legal/contributors
I have added my Github username to tools/.github-cla-signers
I have included a comprehensive commit message using the guide below
[n/a] I have added unit tests to cover the new behavior under tests/unittests/
I have kept the change small, avoiding unnecessary whitespace or non-functional changes.
I have added a reference to issues that this PR relates to in the PR message
[n/a] I have updated the documentation with the changed behavior.

Proposed Commit Message

docs: improve qemu command line

The suggested qemu command line in our local execution example
is rather old.

Change the discouraged -hd* options to the new
-device instead.

Further add a chance to use KVM acceleration to speed up the
example.

Finally we had several occasions to be working on x86 only.
We dropped arguments that can not work on cross-arch and
furthermore added a hint at how one could again native
performance on these platforms.

Fixes GH-5050

Additional Context

n/a

Test Steps

Use the "How to run cloud-init locally" example

Merge type

Squash merge using "Proposed Commit Message"
Rebase and merge unique commits. Requires commit messages per-commit each referencing the pull request number (#<PR_NUM>)

From the qemu docs we know that the old arguments are not encouraged: "Older options like -hda are essentially macros which expand into -drive options for various drive interfaces. The original forms bake in a lot of assumptions from the days when QEMU was emulating a legacy PC, they are not recommended for modern configurations." Also by not specifying the format we get warnings like: WARNING: Image format was not specified for 'seed.img' and probing guessed raw. These warnings might one day get more aggressive and so might be the use of -hda. Instead let us avoid the current and the potential future by using the new format which is a bit more verbose, but also more correct.

The default acceleration is still tcg, which is slower than kvm. We can ask qemu to try kvm and only fall back to tcg - allowing many users to get this example done faster. By default /dev/kvm is only for root or group kvm, to make the example not more complex by adding group management we could instead increase the chance that kvm works by prepending sudo. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>

Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>

We do not want to focus on performance too much, rather on compatibility. Hence: - remove sudo as not all might be able to do that even if it increases the chance to use kvm - remove -cpu host as it would not work on TCG emulation from other architectures - drop machine ubuntu to work on non ubuntu systems Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>

We discussed and decided to keep the examples rather compatible. But at the same time that means on non x86 it might work, but be a bit slower. To help people on other architectures we now hint how they could execute natively. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>

blackboxsw · 2024-07-24T15:22:39Z

+.. note::
+   Please be aware, the example is written for x86. It works on non-x86 but
+   is slower as it will need to be emulated. You can change the image type and
+   qemu-system-<arch> command name to match your architecture to make it again


Suggested change

qemu-system-<arch> command name to match your architecture to make it again

qemu-system-<arch> command name to match your architecture to make it

holmanb · 2024-07-24T15:39:30Z


    wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img

+.. note::


Since this is already in a note, the "Please be aware" seems redundant.

is written for x86.

Correct, but this seems like unnecessary information.

Perhaps:

This example uses emulated CPU instructions on non-x86 hosts, so it may be slow. To make it faster on non-x86 architectures, one can change the image type and qemu-system- command name to match the architecture of your host machine.

pulled in a laid down this note suggestion for inclusion prior to merge.

holmanb · 2024-07-24T15:40:53Z

    $ wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img

+.. note::
+   Please be aware, the example is written for x86. It works on non-x86 but


Same comments as above, however the this is a tutorial, not an example, so suggest a one-word change over the previous suggestion:

This tutorial uses emulated CPU instructions on non-x86 hosts, so it may be slow. To make it faster on non-x86 architectures, one can change the image type and qemu-system- command name to match the architecture of your host machine.

a-dubs · 2024-07-24T16:55:52Z


    wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img

+.. note::


a-dubs · 2024-07-24T17:04:39Z

 orndorffgrant
 Oursin
 outscale-mdr
+cpaelzer


WAIT WHAT NO WAY THIS IS YOUR FIRST PR

Nope just wasn't pulled into our tools/.github-cla-signers.
First commit eeabe2e

a-dubs · 2024-07-24T17:05:09Z

-        -hdb seed.img
+        -drive file=jammy-server-cloudimg-amd64.img,index=0,format=qcow2,media=disk \
+        -drive file=seed.img,index=1,media=cdrom \
+        -machine accel=kvm:tcg


is there any benefit to explaining what each of the various args passed are?

i feel like that might be out of scope for this since this is just cloud-init specific docs.

such as:

Explanation

qemu-system-x86_64

Emulates a 64-bit x86 machine.

-m 1024

Allocates 1024 MB of RAM to the VM.

-net nic

Adds a network interface card to the VM.

-net user

Uses QEMU's user mode networking for basic network connectivity.

-hda jammy-server-cloudimg-amd64.img

Sets the primary hard disk using the specified image.

-hdb seed.img

Sets the secondary hard disk using the specified image, often for cloud-init data.

-drive file=jammy-server-cloudimg-amd64.img,index=0,format=qcow2,media=disk

Specifies the primary drive in detail:

file: Image file to use.

index: Drive index (0 for primary).

format: Image format (QCOW2).

media: Type of drive (disk).

-drive file=seed.img,index=1,media=cdrom

Specifies the secondary drive in detail:

file: Image file to use.

index: Drive index (1 for secondary).

media: Type of drive (CD-ROM).

-machine accel=kvm:tcg

Uses KVM for hardware acceleration if available, otherwise TCG for software emulation.

Yes, I think this is probably out of scope for this tutorial to tell folks how to use QEMU command line and it probably should be left as an exercise to the user to RTFM to better understand the implications of qemu commandline in this example.

blackboxsw

Minor spelling hint to avoid tox -e doc-spelling bailing on a word we don't need in our dictionary.

blackboxsw · 2024-07-24T17:14:11Z

+.. note::
+   Please be aware, the example is written for x86. It works on non-x86 but
+   is slower as it will need to be emulated. You can change the image type and
+   qemu-system-<arch> command name to match your architecture to make it again


spelling issues on qemu-system not being seen, we need the following in both places:

Suggested change

qemu-system-<arch> command name to match your architecture to make it again

:spelling:ignore:`qemu-system-<arch>` command name to match your architecture to make it again

blackboxsw · 2024-07-24T17:25:52Z


    wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img

+.. note::


pulled in a laid down this note suggestion for inclusion prior to merge.

Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>

The suggested qemu command line in our local execution example is rather old. Change the discouraged -hd* options to the new -device instead. Further add a chance to use KVM acceleration to speed up the example. Finally we had several occasions to be working on x86 only. We dropped arguments that can not work on cross-arch and furthermore added a hint at how one could again native performance on these platforms. Fixes canonicalGH-5050

The suggested qemu command line in our local execution example is rather old. Change the discouraged -hd* options to the new -device instead. Further add a chance to use KVM acceleration to speed up the example. Finally we had several occasions to be working on x86 only. We dropped arguments that can not work on cross-arch and furthermore added a hint at how one could again native performance on these platforms. Fixes GH-5050

cpaelzer added 4 commits July 24, 2024 15:02

github-cla-signers: add myself

1b25622

Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>

blackboxsw added the documentation This Pull Request changes documentation label Jul 24, 2024

github-actions Bot removed the documentation This Pull Request changes documentation label Jul 24, 2024

s-makin added the documentation This Pull Request changes documentation label Jul 24, 2024

blackboxsw reviewed Jul 24, 2024

View reviewed changes

Comment thread doc/rtd/howto/run_cloud_init_locally.rst Outdated

github-actions Bot removed the documentation This Pull Request changes documentation label Jul 24, 2024

cpaelzer mentioned this pull request Jul 24, 2024

[docs]: add tutorial support for apple silicon #5050

Closed

blackboxsw reviewed Jul 24, 2024

View reviewed changes

holmanb reviewed Jul 24, 2024

View reviewed changes

s-makin added the documentation This Pull Request changes documentation label Jul 24, 2024

a-dubs suggested changes Jul 24, 2024

View reviewed changes

blackboxsw force-pushed the improve-qemu-cmdline branch from 064759e to 42292c8 Compare July 24, 2024 17:16

github-actions Bot added documentation This Pull Request changes documentation and removed documentation This Pull Request changes documentation labels Jul 24, 2024

blackboxsw approved these changes Jul 24, 2024

View reviewed changes

blackboxsw force-pushed the improve-qemu-cmdline branch from 4c58f45 to 2406de5 Compare July 24, 2024 17:41

cpaelzer and others added 3 commits July 24, 2024 11:42

github-cla-signers: launchpad -> github user name

54f83db

Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>

doc: spelling ignore for qemu in notes. Drop Please be aware prefix

b1d71c8

doc: better suggestion for qemu note about emulation from holmanb

3352e66

blackboxsw force-pushed the improve-qemu-cmdline branch from 2406de5 to 3352e66 Compare July 24, 2024 17:42

blackboxsw merged commit 02beb9a into canonical:main Jul 24, 2024

	qemu-system-<arch> command name to match your architecture to make it again
	qemu-system-<arch> command name to match your architecture to make it


		wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img

		.. note::

	qemu-system-<arch> command name to match your architecture to make it again
	:spelling:ignore:`qemu-system-<arch>` command name to match your architecture to make it again

Conversation

cpaelzer commented Jul 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed Commit Message

Additional Context

Test Steps

Merge type

Uh oh!

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!

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

Explanation

qemu-system-x86_64

-m 1024

-net nic

-net user

-hda jammy-server-cloudimg-amd64.img

-hdb seed.img

-drive file=jammy-server-cloudimg-amd64.img,index=0,format=qcow2,media=disk

-drive file=seed.img,index=1,media=cdrom

-machine accel=kvm:tcg

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blackboxsw 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

cpaelzer commented Jul 24, 2024 •

edited

Loading

`qemu-system-x86_64`

`-m 1024`

`-net nic`

`-net user`

`-hda jammy-server-cloudimg-amd64.img`

`-hdb seed.img`

`-drive file=jammy-server-cloudimg-amd64.img,index=0,format=qcow2,media=disk`

`-drive file=seed.img,index=1,media=cdrom`

`-machine accel=kvm:tcg`