cloud-init, cloud image and Cloud Hypervisor

Three names that show up together and do different things. Mixing them up is the most common reason a VM boots and does nothing — or doesn't boot at all.

The three, in one sentence each

A container analogy helps more than any definition: the cloud image is the image, cloud-init is the ENTRYPOINT of the first run, and Cloud Hypervisor is the runtime — the equivalent of runc.

1 · Cloud image — the disk

Every distro publishes a small (a few hundred MB), pre-installed qcow2 with cloud-init already inside. The engine knows how to download three families and always verifies the checksum — it never accepts a download without checking it against one.

# In a VMfile
FROM ubuntu:24.04        # cloud-images.ubuntu.com
FROM debian:bookworm     # cloud.debian.org
FROM rocky:9             # dl.rockylinux.org

# Or directly, with no VMfile at all
delonix vm create dev --url-img https://.../image.qcow2

The three publish checksums differently, and that's handled: Ubuntu uses SHA256SUMS in GNU format, Debian publishes only SHA512SUMS (no SHA256 at all), and Rocky uses a per-file .CHECKSUM in BSD format (SHA256 (file) = hash). With --url-img, the engine looks for a <url>.sha256 next to it; if it doesn't exist, it says so — trusting TLS alone — instead of staying quiet.

The disk comes small on purpose — typically 2 GB. Grow it before installing anything, with SIZE 20G in the VMfile: growing it after a RUN has already filled the disk is too late.

2 · cloud-init — first-boot customization

A freshly downloaded cloud image has no account at all. cloud-init looks for a datasource at boot, reads user-data from it, and applies it. Delonix uses the NoCloud datasource: it generates a per-instance ISO and attaches it to the VM.

# The engine generates the seed on its own when you give it any of these
delonix vm create dev --hostname dev-01 --ssh-key ~/.ssh/id_ed25519.pub
delonix vm create dev --user-data ./user-data.yaml
delonix vm create dev --seed ./my-seed.iso   # ISO you already built yourself

A minimal, complete user-data:

#cloud-config
hostname: dev-01
users:
  - name: delonix
    groups: [sudo]
    shell: /bin/bash
    sudo: ['ALL=(ALL) NOPASSWD:ALL']
    ssh_authorized_keys:
      - ssh-ed25519 AAAA... your-email@example

package_update: true
packages: [nginx]

runcmd:
  - [systemctl, enable, --now, nginx]

final_message: "ready in $UPTIME seconds"

Two layers, and the distinction matters. A VMfile's CLOUDINIT is baked INTO THE IMAGE (it lands in /etc/cloud/cloud.cfg.d) — it's the default behavior of every VM made from it. vm create's --user-data is PER INSTANCE and sits on top. One is the image's recipe, the other is that particular VM's configuration.

Real trap, already paid for: a kind: VirtualMachine with no seed at all made cloud-init skip the networking phase, leaving the VM with no IP and no route (Network is unreachable inside). That's why the engine always generates a minimal seed, even when you ask for nothing — it isn't optional.

And cloud-init only runs once: it keeps a marker in /var/lib/cloud. A vm restart doesn't re-run it — to reapply it, either clear that state inside the VM or create another one.

3 · Cloud Hypervisor — the VMM

The thing that runs the VM. Delonix has two backends behind the same trait, and the choice isn't cosmetic:

delonix vm create micro --backend cloud-hypervisor --firmware /usr/share/hypervisor-fw
delonix vm create heavy --backend libvirt          # default when CH isn't installed

Which to use, and when

Where this breaks, and what to check

References

• cloud-init documentation — especially the user-data examples and the NoCloud datasource, which is what Delonix uses.
• Ubuntu cloud images · Debian's · Rocky's
• Cloud Hypervisor and rust-hypervisor-firmware (the --firmware a cloud image needs to boot under CH).
• libvirt domain format — useful if you use the kind: VirtualMachine escape hatches libvirtXml/libvirtXmlOverlay.