A cloud image is deliberately generic: no hostname, no users, no keys. cloud-init turns it into your machine, once, on first boot, before you ever connect.

The model

On first boot it looks for a datasource, reads meta-data describing the instance and user-data describing what you want, applies that configuration, and records that it is done.

That once-only behaviour explains both why it is useful and why testing it is awkward.

A working cloud-config

#cloud-config
hostname: web-01

users:
  - name: deploy
    groups: [sudo]
    shell: /bin/bash
    sudo: ['ALL=(ALL) NOPASSWD:ALL']
    ssh_authorized_keys:
      - ssh-ed25519 AAAAC3Nza... you@laptop

ssh_pwauth: false
disable_root: true

package_update: true
packages: [ufw, fail2ban]

runcmd:
  - ufw default deny incoming
  - ufw allow 22/tcp
  - ufw --force enable

The #cloud-config first line is mandatory. Without it the document is treated as something else and silently ignored, which is the standard first mistake.

This does most of what our first ten minutes on a new server guide describes, automatically.

Outside a cloud

The NoCloud datasource reads from an attached ISO, which is how libvirt and Proxmox setups use it:

cloud-localds seed.iso user-data meta-data

Attach it as a CD-ROM alongside the disk image and boot.

Debugging

cloud-init status --long
sudo cat /var/log/cloud-init-output.log     # what ran, and its output
cloud-init schema --system                  # validate
sudo cloud-init clean --logs && sudo reboot # re-run everything

cloud-init-output.log is the one to read first. It contains the actual output of your runcmd entries, which is where most failures are visible.

Our cloud-init explainer covers the whole model.

Where it stops

It runs once and is not configuration management. Use it to make a machine reachable with your key, a hostname, and a firewall, and use something that converges repeatedly for everything ongoing.

Verify Your Download

cloud-init ships with essentially every cloud image and is packaged by every distribution. Source is on GitHub.

Mirror	Region	Download
cloud-init Documentation Primary	Global	Download
GitHub Repository	Global	Download

cloud-init 26.2

Download Mirrors