Skip to content
Hands-on IT IT Drills

Day 4: virt-install and cloud-init

Goal: Create a VM from a base image and cloud-init files with a single virt-install command, fully set up after boot. · Duration: approx. 60 min · Prerequisite: Day 3

Briefing

  • virt-install writes the domain XML for you, creates the disk, builds the seed for cloud-init and starts the VM. What you built by hand on Days 1 to 3 becomes one command.
  • cloud-init reads two files: meta-data says who the VM is (instance-id, hostname), user-data says what should happen (users, packages, commands).
  • The instance-id decides whether cloud-init runs “for the first time”. Same ID means: already done.
 user-data + meta-data ──► virt-install ──► web1.qcow2 (overlay on basis/noble.qcow2)
                                        ├─► cloudinit.iso (first boot only)
                                        └─► domain web1 + qemu-guest-agent channel

Drill 1: What does libvirt know about operating systems?

sudo apt-get install -y libosinfo-bin
osinfo-query os | grep ubuntu24

Expected:

 ubuntu24.04          | Ubuntu 24.04 LTS                                   | 24.04    | …

With --osinfo ubuntu24.04, virt-install picks suitable devices (virtio, machine type) and knows the system’s minimum requirements.

Save your progress? Sign up for free

Drill 2: One base image for all

sudo mkdir -p /var/lib/libvirt/images/basis
sudo cp ~/kvm-lab/images/noble-server-cloudimg-amd64.img \
  /var/lib/libvirt/images/basis/noble.qcow2
sudo chmod 444 /var/lib/libvirt/images/basis/noble.qcow2

As on Day 2, the base is write-protected. From now on every VM gets a thin overlay on top of it.

Save your progress? Sign up for free

Drill 3: The cloud-init files

mkdir -p ~/kvm-lab/tag04 && cd ~/kvm-lab/tag04
cat > user-data <<EOF
#cloud-config
users:
  - name: ubuntu
    groups: [sudo]
    sudo: "ALL=(ALL) NOPASSWD:ALL"
    shell: /bin/bash
    lock_passwd: false
    plain_text_passwd: lab-console-pw-123
    ssh_authorized_keys:
      - $(cat ~/.ssh/id_ed25519.pub)
package_update: true
packages: [nginx, qemu-guest-agent]
runcmd:
  - echo "web1 aus cloud-init" > /var/www/html/index.html
  - systemctl enable --now qemu-guest-agent
EOF
cat > meta-data <<'EOF'
instance-id: web1-001
local-hostname: web1
EOF
  • users creates the user completely: sudo without a password, console password, SSH key.
  • packages installs nginx and the QEMU guest agent, a small service through which libvirt talks to the guest (Drill 7).
  • runcmd runs once, at the very end of the first boot.

Save your progress? Sign up for free

Drill 4: Look first, then build

virt-install --name web1 --memory 1024 --vcpus 2 --osinfo ubuntu24.04 --import \
  --disk size=10,backing_store=/var/lib/libvirt/images/basis/noble.qcow2 \
  --network network=default \
  --cloud-init user-data=user-data,meta-data=meta-data \
  --graphics none --noautoconsole \
  --print-xml --dry-run | head -20

Expected (shortened):

<domain type="kvm">
  <name>web1</name>
  <uuid>…</uuid>
  <metadata>
    <libosinfo:libosinfo xmlns:libosinfo="http://libosinfo.org/xmlns/libvirt/domain/1.0">
      <libosinfo:os id="http://ubuntu.com/ubuntu/24.04"/>
    </libosinfo:libosinfo>
  </metadata>
  <memory>1048576</memory>
  <currentMemory>1048576</currentMemory>
  <vcpu>2</vcpu>
  <os>
    <type arch="x86_64" machine="q35">hvm</type>
    <smbios mode="sysinfo"/>
  </os>
  <features>
    <acpi/>
    <apic/>
  </features>
  <cpu mode="host-passthrough"/>
Option Meaning
--import install nothing, the disk is already bootable
--disk size=10,backing_store=… new 10 GB overlay web1.qcow2 on the base
--cloud-init user-data=…,meta-data=… build the seed and insert it on first boot
--graphics none --noautoconsole serial console, do not connect automatically

Tried it: Without --dry-run, --print-xml still creates the disk. The real invocation afterwards finds web1.qcow2 already there and silently names the new disk web1-1.qcow2. What remains is an orphaned file that nobody uses anymore.

Save your progress? Sign up for free

Drill 5: Build

The same command without the last line:

virt-install --name web1 --memory 1024 --vcpus 2 --osinfo ubuntu24.04 --import \
  --disk size=10,backing_store=/var/lib/libvirt/images/basis/noble.qcow2 \
  --network network=default \
  --cloud-init user-data=user-data,meta-data=meta-data \
  --graphics none --noautoconsole

Expected:

WARNING  Requested memory 1024 MiB is less than the recommended 3072 MiB for OS ubuntu24.04

Starting install...
Allocating 'virtinst-0ngrwmyt-cloudinit.iso'                |    0 B  00:00 ... 
Transferring 'virtinst-0ngrwmyt-cloudinit.iso'              |    0 B  00:00 ... 
Allocating 'web1.qcow2'                                     |    0 B  00:00 ... 
Creating domain...                                          |    0 B  00:00     
Domain creation completed.

The warning comes from the osinfo database. For an nginx, 1 GB is enough.

virsh domblklist web1
sudo qemu-img info -U /var/lib/libvirt/images/web1.qcow2 | grep -E 'virtual|^disk|backing'

Expected:

 Target   Source
-----------------------------------------------------------------
 vda      /var/lib/libvirt/images/web1.qcow2
 sda      /var/lib/libvirt/boot/virtinst-0ngrwmyt-cloudinit.iso

virtual size: 10 GiB (10737418240 bytes)
disk size: 328 KiB
backing file: /var/lib/libvirt/images/basis/noble.qcow2

-U (force share) allows qemu-img info on a disk that is currently in use. Without it you get the lock error from Day 2.

Save your progress? Sign up for free

Drill 6: Fully set up?

After about a minute the guest has an IP:

virsh domifaddr web1

Expected:

 Name       MAC address          Protocol     Address
-------------------------------------------------------------------------------
 vnet4      52:54:00:5e:a8:8a    ipv4         192.168.122.110/24

The packages take longer. cloud-init status --wait waits until everything is done:

ssh -o StrictHostKeyChecking=no [email protected] cloud-init status --wait
ssh [email protected] cloud-init status --long

Expected (shortened, after two to three minutes):

……………………………………………
status: done
status: done
extended_status: done
boot_status_code: enabled-by-generator
…
detail: DataSourceNoCloud [seed=dmi,/dev/sr0][dsmode=local]
errors: []

errors: [] is the most important line. A typo in user-data ends up here, and the VM still starts.

curl http://192.168.122.110/

Expected:

web1 aus cloud-init

Save your progress? Sign up for free

Drill 7: The QEMU guest agent

virt-install has built a channel to the QEMU guest agent into the domain:

virsh dumpxml web1 | grep -A2 '<channel'

Expected:

    <channel type='unix'>
      <source mode='bind' path='/run/libvirt/qemu/channel/7-web1/org.qemu.guest_agent.0'/>
      <target type='virtio' name='org.qemu.guest_agent.0' state='connected'/>

state='connected': the QEMU guest agent is running. Now libvirt can ask the guest itself instead of looking it up in the DHCP server:

virsh domifaddr web1 --source agent

Expected:

 Name       MAC address          Protocol     Address
-------------------------------------------------------------------------------
 lo         00:00:00:00:00:00    ipv4         127.0.0.1/8
 -          -                    ipv6         ::1/128
 enp1s0     52:54:00:5e:a8:8a    ipv4         192.168.122.110/24
 -          -                    ipv6         fe80::5054:ff:fe5e:a88a/64

This also works with static IPs without DHCP. You will see what else the agent can do on Day 9.

Save your progress? Sign up for free

Drill 8: The first reboot

virsh reboot web1
virsh list --all

Expected (after a few seconds):

Domain 'web1' is being rebooted

 Id   Name    State
------------------------
 -    erste   shut off
 -    web1    shut off

Off instead of rebooted. Why?

virsh dumpxml --inactive web1 | grep on_reboot

Expected:

  <on_reboot>restart</on_reboot>

Tried it: During the “installation”, virt-install sets on_reboot to destroy in the running definition. Normally it waits for this first reboot, removes the seed and restarts the VM. With --noautoconsole, however, virt-install has long since exited, and nobody starts the VM again. The stored definition is fine; from now on restart applies again.

virsh start web1
virsh domblklist web1

Expected:

Domain 'web1' started

 Target   Source
----------------------------------------------
 vda      /var/lib/libvirt/images/web1.qcow2
 sda      -

The drive with the seed is empty. When creating the VM, virt-install only attached the ISO file to the running definition and deleted it afterwards. Good, because it contained the console password.

Save your progress? Sign up for free

Checkpoint

virsh list --all

Expected: web1 with running.

curl http://192.168.122.110/

Expected: web1 aus cloud-init. Your IP is shown by virsh domifaddr web1.

ssh [email protected] cloud-init status

Expected: status: done.

Challenge

Build a second VM web2 that serves web2 aus cloud-init. Check that it shares the same base with web1.

Hint: You need your own files with their own instance-id and their own hostname.

Solution

cd ~/kvm-lab/tag04
cat > meta-data-web2 <<'EOF'
instance-id: web2-001
local-hostname: web2
EOF
cat > user-data-web2 <<EOF
#cloud-config
users:
  - name: ubuntu
    groups: [sudo]
    sudo: "ALL=(ALL) NOPASSWD:ALL"
    shell: /bin/bash
    lock_passwd: false
    plain_text_passwd: lab-console-pw-123
    ssh_authorized_keys:
      - $(cat ~/.ssh/id_ed25519.pub)
package_update: true
packages: [nginx, qemu-guest-agent]
runcmd:
  - echo "web2 aus cloud-init" > /var/www/html/index.html
  - systemctl enable --now qemu-guest-agent
EOF
virt-install --name web2 --memory 1024 --vcpus 2 --osinfo ubuntu24.04 --import \
  --disk size=10,backing_store=/var/lib/libvirt/images/basis/noble.qcow2 \
  --network network=default \
  --cloud-init user-data=user-data-web2,meta-data=meta-data-web2 \
  --graphics none --noautoconsole

After two to three minutes:

virsh domifaddr web2 --source agent | grep enp
curl http://192.168.122.51/

Expected:

 enp1s0     52:54:00:51:cc:46    ipv4         192.168.122.51/24
web2 aus cloud-init
sudo qemu-img info -U /var/lib/libvirt/images/web2.qcow2 | grep backing

Expected:

backing file: /var/lib/libvirt/images/basis/noble.qcow2
backing file format: qcow2

Save your progress? Sign up for free

Enterprise Note

  • cloud-init is the standard: Proxmox, OpenStack, OpenNebula and the big clouds understand cloud-config. Your user-data carries over largely unchanged; only the datasource differs.
  • No secrets in user-data: In the guest, the file lives at /var/lib/cloud/instance/user-data.txt and is readable by root. Passwords belong in a secret store, not in the VM description.
  • Golden images: What every VM needs (agent, monitoring, hardening) goes into the base image, built for example with Packer. cloud-init then only handles what is individual.
  • Always the QEMU guest agent: Backups with a consistent file system, IP display and clean shutdown depend on it.