Core tutorial with QEMU¶
In this tutorial, we will launch an Ubuntu cloud image in a virtual machine
that uses 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
your cloud-init configurations locally before launching to the cloud.
Why QEMU?¶
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.
Install QEMU¶
$ 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¶
This directory will store our cloud image and configuration files for user data, metadata, and vendor data.
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 cloud-init
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
Note
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-<arch> command name to match the architecture of your host machine.
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 user-data
containing our configuration data.
$ cat << EOF > user-data
#cloud-config
password: password
chpasswd:
expire: False
EOF
What is user data?¶
Before moving forward, let’s inspect our user-data file.
$ cat user-data
You should see the following contents:
#cloud-config
password: password
chpasswd:
expire: False
The first line starts with #cloud-config, which tells cloud-init
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 password.
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
instance-id: someid/somehostname
EOF
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.
How does 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 cloud-init
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 \
-m 512 \
-nographic \
-hda jammy-server-cloudimg-amd64.img \
-smbios type=1,serial=ds='nocloud;s=http://10.0.2.2:8000/'
Note
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 cloud-init?¶
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 cloud-init installed.
The second line tells cloud-init where it can find user data, using the
NoCloud datasource. During boot, cloud-init
checks the 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 (10.0.2.2)
and default port number of the Python webserver (8000), so that
cloud-init will, inside the virtual machine, query the server running on
host.
Verify that 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
is password.
If you can log in using the configured password, it worked!
If you couldn’t log in, see this page for debug information.
Check cloud-init status¶
Run the following command, which will allow us to check if cloud-init has
finished running:
$ 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.
Tear down¶
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).
What’s next?¶
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.