VPS Provisioning with Cloud-Init: A Working Configuration

A freshly provisioned VPS is a blank root prompt and a list of manual steps you have already performed a dozen times: create users, copy SSH keys, install packages, harden sshd, set the hostname, mount the data volume. Cloud-init turns that checklist into YAML that runs on first boot. This walkthrough covers a production-grade config for Ubuntu 24.04 and Debian 12 images, plus the failure modes that leave a server half-configured.

How cloud-init executes on first boot

cloud-init runs as a systemd generator and then as four sequential service stages: local, network, config and final. Data sources are evaluated in a fixed order — NoCloud, ConfigDrive, then provider-specific metadata services such as EC2 or DigitalOcean. User-data supplied through your provider’s panel or a mounted seed ISO lands in /var/lib/cloud/instance/user-data.txt.

Modules declared under cloud_config_modules and cloud_final_modules execute once per instance ID. A reboot does not re-run them; deleting /var/lib/cloud/ does. That distinction matters when you debug: re-running cloud-init clean --logs followed by cloud-init init replays the whole sequence, including SSH key injection, which can lock you out if user-data is stale.

A baseline user-data file

The config below covers users, SSH hardening, packages, a timezone, a hosts entry and a final runcmd block. It is idempotent: running it twice produces the same state because every directive is declarative.

#cloud-config
hostname: web01
fqdn: web01.example.net
timezone: UTC
manage_etc_hosts: true

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

ssh_pwauth: false
disable_root: true

package_update: true
package_upgrade: true
packages:
  - nginx
  - fail2ban
  - unattended-upgrades
  - chrony

write_files:
  - path: /etc/ssh/sshd_config.d/10-hardening.conf
    permissions: '0644'
    content: |
      PasswordAuthentication no
      PermitRootLogin no
      KbdInteractiveAuthentication no
      MaxAuthTries 3

runcmd:
  - systemctl restart ssh
  - ufw allow 22/tcp
  - ufw allow 80,443/tcp
  - ufw --force enable

final_message: "bootstrap complete after $UPTIME seconds"

Two details are easy to miss. ssh_pwauth: false only affects the sshd default config; a drop-in file in sshd_config.d/ is what actually enforces it on modern images, and drop-ins are read in lexical order so the 10- prefix keeps it ahead of later files. Restarting ssh before UFW is enabled prevents locking yourself out mid-boot.

Validating before you deploy

Never paste user-data straight into a provider panel. Validate locally first. cloud-init schema checks YAML against the module schema and catches typos such as packages_upgrade instead of package_upgrade, which fail silently at runtime. The schema check is cheap and runs offline, so wire it into pre-commit alongside a YAML parse test and a shell linter for embedded scripts.

$ cloud-init schema --config-file user-data.yaml
Valid schema user-data.yaml

$ python3 -c "import yaml,sys; yaml.safe_load(open('user-data.yaml'))" && echo YAML_OK
YAML_OK

# test in a disposable VM (no cloud-init installed on host)
$ cloud-localds seed.iso user-data.yaml
$ qemu-system-x86_64 -m 2048 -drive file=ubuntu.img,if=virtio \
    -drive file=seed.iso,media=cdrom -nographic

The local QEMU loop takes about three minutes and has saved more deployments than any review process. If you want to see the exact module order without booting, cloud-init single --name cc_ssh --frequency always runs one module against the current instance state.

Debugging a failed first boot

When a server comes up without your users or packages, read the logs in order. cloud-init status --long gives the overall result and the failing stage; /var/log/cloud-init.log has module-level tracebacks; /var/log/cloud-init-output.log holds stdout from every runcmd, which is where apt errors and script exits appear.

$ cloud-init status --long
status: error
extended_status: error
boot_status_code: enabled-by-generator
detail: DataSourceNoCloud [seed=/dev/sr0][dsmode=net]
errors:
	- cc_package_update: Failed to update packages

$ grep -n "Traceback\|ERROR" /var/log/cloud-init.log | tail -20

The most common root cause is a network race: package_update runs before DHCP finishes and apt fails with a temporary DNS error. Fix it by setting bootcmd: [cloud-init-per once wait-net sleep 10] or by moving package operations into a runcmd block that retries. On providers with hot-plugged volumes, also confirm the device name — /dev/sdb on one host can be /dev/vdb on another, which breaks a hardcoded mkfs line and can destroy the wrong disk.

Cloud-init versus configuration management

Cloud-init is a bootstrapper, not a configuration manager. It has no drift detection, no dependency ordering beyond stage sequence, and no reporting. Once the server is up, use Ansible or similar for ongoing state. The clean split is: cloud-init installs the management agent, sets the hostname and keys, and mounts volumes; everything beyond that belongs in a playbook.

If you are deciding between the two approaches for provisioning in general, our cloud-init vs Ansible comparison goes deeper on where each one breaks down. For the base image itself, a KVM plan with a stock cloud image is the least surprising starting point — see our VPS plans for images that ship with cloud-init preinstalled.

Adding a data volume and swap safely

Most cloud images leave secondary disks raw. The disk_setup and fs_setup modules format and mount them, but they will happily destroy an existing filesystem unless you guard them with overwrite: false. The pair below creates an ext4 filesystem on the second virtio disk only when it is unformatted, then adds a 2 GB swapfile and the fstab entries needed to survive a reboot.

disk_setup:
  /dev/vdb:
    table_type: gpt
    layout: true
    overwrite: false

fs_setup:
  - device: /dev/vdb1
    filesystem: ext4
    label: data
    overwrite: false

mounts:
  - ["LABEL=data", "/srv/data", "ext4", "defaults,nofail,noatime", "0", "2"]

swap:
  filename: /swapfile
  size: 2G
  maxsize: 2G

runcmd:
  - chmod 600 /swapfile
  - sysctl -w vm.swappiness=10
  - echo "vm.swappiness=10" > /etc/sysctl.d/90-swap.conf

The nofail flag is the important one. Without it, a missing or renamed volume leaves the instance in emergency mode and unreachable over SSH — a failure that looks like the provider lost your server. Label-based mounts survive device renaming across hosts and reboots; /dev/vdb1 does not.

Idempotency and re-running safely

Cloud-init marks each module run in /var/lib/cloud/instance/sem/. Per-instance modules such as cc_users_groups execute once; per-always modules run every boot. If you need a script to run on every start — mounting an encrypted volume that needs a key, for example — put it in bootcmd rather than runcmd, because bootcmd runs before the network stage on each boot.

To re-run a single module without wiping state, use cloud-init single --name cc_write_files --frequency always. Avoid cloud-init clean on a production host: it drops the instance ID, and on some data sources the next boot re-fetches vendor data and reapplies the vendor default user’s keys, overwriting changes you made deliberately.

Keeping images reproducible

Store user-data in version control alongside the Terraform or CLI call that creates the instance. Tag the commit hash into /etc/motd from a write_files entry so any server can report which revision built it. When a rebuild is needed, the same YAML reproduces the machine byte-for-byte, minus the parts you deliberately left to Ansible.

Treat user-data as immutable per release: change it by building a new template and rolling instances, not by editing a file that half the fleet already consumed. That discipline is what separates reproducible infrastructure from a pile of hand-tuned servers with a README. If you are choosing a host to run this on, our VPS comparison table lists which images and cloud-init data sources each plan supports.

Leave a Reply