Core tutorial with QEMU#
In this tutorial, we will launch an Ubuntu cloud image in a virtual machine
cloud-init to pre-configure the system during boot.
The goal of this tutorial is to provide a minimal demonstration of
cloud-init, which you can then use as a development environment to test
cloud-init configurations locally before launching to the cloud.
QEMU is a cross-platform emulator capable of running performant virtual machines. QEMU is used at the core of a broad range of production operating system deployments and open source software projects (including libvirt, LXD, and vagrant) and is capable of running Windows, Linux, and Unix guest operating systems. While QEMU is flexibile and feature-rich, we are using it because of the broad support it has due to its broad adoption and ability to run on *nix-derived operating systems.
How to use this tutorial#
In this tutorial, the commands in each code block can be copied and pasted
directly into the terminal. Omit the prompt (
$) before each command, or
use the “copy code” button on the right-hand side of the block, which will copy
the command for you without the prompt.
Each code block is preceded by a description of what the command does, and followed by an example of the type of output you should expect to see.
$ sudo apt install qemu-system-x86
If you are not using Ubuntu, you can visit QEMU’s install instructions for additional information.
Create a temporary directory#
You should run all commands from this temporary directory. If you run the commands from anywhere else, your virtual machine will not be configured.
Let’s create a temporary directory and make it our current working directory with cd:
$ mkdir temp
$ cd temp
Download a cloud image#
Cloud images typically come with
cloud-init pre-installed and configured to
run on first boot. You will not need to worry about installing
for now, since we are not manually creating our own image in this tutorial.
In our case, we want to select the latest Ubuntu LTS. Let’s download the server image using wget:
$ wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
Define our user data#
Now we need to create our
user-data file. This user data cloud-config
sets the password of the default user, and sets that password to never expire.
For more details you can refer to the
Set Passwords module page.
Run the following command, which creates a file named
containing our configuration data.
$ cat << EOF > user-data
What is user data?#
Before moving forward, let’s inspect our
$ cat user-data
You should see the following contents:
The first line starts with
#cloud-config, which tells
what type of user data is in the config. Cloud-config is a YAML-based
configuration type that tells
cloud-init how to configure the virtual
machine instance. Multiple different format types are supported by
cloud-init. For more information, see the
documentation describing different formats.
The second line,
password: password, as per
the Users and Groups module docs, sets the default
user’s password to
The third and fourth lines direct
cloud-init to not require a password
reset on first login.
Define our metadata#
Now let’s run the following command, which creates a file named
meta-data containing configuration data.
$ cat << EOF > meta-data
Define our vendor data#
Now we will create the empty file
vendor-data in our temporary
directory. This will speed up the retry wait time.
$ touch vendor-data
Start an ad hoc IMDS webserver#
Open up a second terminal window, change to your temporary directory and then start the built-in Python webserver:
$ cd temp
$ python3 -m http.server --directory .
What is an IMDS?#
Instance Metadata Service (IMDS) is a service provided by most cloud providers
as a means of providing information to virtual machine instances. This service
is used by cloud providers to expose information to a virtual machine. This
service is used for many different things, and is the primary mechanism for
some clouds to expose
cloud-init configuration data to the instance.
cloud-init use the IMDS?#
The IMDS uses a private http webserver to provide metadata to each operating
system instance. During early boot,
cloud-init sets up network access and
queries this webserver to gather configuration data. This allows
to configure your operating system while it boots.
In this tutorial we are emulating this workflow using QEMU and a simple Python
webserver. This workflow is suitable for developing and testing
cloud-init configurations prior to cloud deployments.
Launch a virtual machine with our user data#
Switch back to your original terminal, and run the following command so we can
launch our virtual machine. By default, QEMU will print the kernel logs and
systemd logs to the terminal while the operating system boots. This may
take a few moments to complete.
$ qemu-system-x86_64 \
-net nic \
-net user \
-machine accel=kvm:tcg \
-cpu host \
-m 512 \
-hda jammy-server-cloudimg-amd64.img \
If the output stopped scrolling but you don’t see a prompt yet, press Enter to get to the login prompt.
How is QEMU configured for
When launching QEMU, our machine configuration is specified on the command line. Many things may be configured: memory size, graphical output, networking information, hard drives and more.
Let us examine the final two lines of our previous command. The first of them,
-hda jammy-server-cloudimg-amd64.img, tells QEMU to use the cloud
image as a virtual hard drive. This will cause the virtual machine to
boot Ubuntu, which already has
The second line tells
cloud-init where it can find user data, using the
NoCloud datasource. During boot,
SMBIOS serial number for
ds=nocloud. If found,
cloud-init will use the specified URL to source its user data config files.
In this case, we use the default gateway of the virtual machine (
and default port number of the Python webserver (
8000), so that
cloud-init will, inside the virtual machine, query the server running on
cloud-init ran successfully#
After launching the virtual machine, we should be able to connect to our instance using the default distro username.
In this case the default username is
ubuntu and the password we configured
If you can log in using the configured password, it worked!
If you couldn’t log in, see this page for debug information.
Run the following command, which will allow us to check if
$ cloud-init status --wait
If you see
status: done in the output, it succeeded!
If you see a failed status, you’ll want to check
/var/log/cloud-init.log for warning/error messages.
In our main terminal, let’s exit the QEMU shell using ctrl-a x (that’s ctrl and a simultaneously, followed by x).
In the second terminal, where the Python webserver is running, we can stop the server using (ctrl-c).
In this tutorial, we configured the default user’s password and ran
cloud-init inside our QEMU virtual machine.
The full list of modules available can be found in our modules documentation. The documentation for each module contains examples of how to use it.
You can also head over to the examples page for examples of more common use cases.