How to configure a VM with cloud-init

Write cloud-init user data, pass it when you launch an instance, and confirm the guest applied your baseline on first boot.

For background on formats and the one-shot boot model, see cloud-init and first-boot configuration. For a full production launch workflow, see How to provision a production-ready VM.

Step 1. Write a minimal cloud-config file#

Create cloud-init.yaml with a non-root sudo user, package updates, and a hostname:

#cloud-config
hostname: APP_HOSTNAME
users:
  - name: deploy
    groups: sudo
    shell: /bin/bash
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - YOUR_SSH_PUBLIC_KEY
package_update: true
package_upgrade: true

Replace APP_HOSTNAME and YOUR_SSH_PUBLIC_KEY. The #cloud-config header tells cloud-init to parse the file as cloud-config YAML, not a shell script.

Step 2. Use common cloud-config modules#

Add modules as your baseline grows. Each example is self-contained; merge the keys you need into one #cloud-config file.

users (shown above): creates login accounts and injects SSH public keys.

packages:

packages:
  - nginx
  - fail2ban

package_update / package_upgrade: refresh package indexes and apply upgrades on first boot (shown in Step 1).

write_files:

write_files:
  - path: /etc/motd
    content: |
      Managed by cloud-init baseline
    owner: root:root
    permissions: "0644"

bootcmd vs runcmd: bootcmd runs early every boot (rarely needed on first-boot baselines). runcmd runs late on first boot only:

runcmd:
  - systemctl enable nginx
  - systemctl start nginx

Step 3. Pass user data at launch#

Step 4. Debug first-boot failures#

When SSH fails or packages are missing, inspect cloud-init before you rebuild the instance.

SSH in (or open the virtual machine console if SSH is not up yet) and run:

cloud-init status --wait
sudo tail -n 100 /var/log/cloud-init.log
sudo tail -n 100 /var/log/cloud-init-output.log

status --wait blocks until cloud-init finishes or reports an error. The log files show module execution order and shell output from runcmd.

Validate cloud-config syntax locally:

cloud-init schema --config-file cloud-init.yaml

Fix YAML errors, then launch a new instance with corrected user data. cloud-init does not re-run the full first-boot sequence on an instance that already completed it.

Step 5. Verify the baseline landed#

After cloud-init status reports done:

hostname
id deploy
dpkg -l nginx 2>/dev/null || rpm -q nginx 2>/dev/null

Confirm the hostname, the deploy user, and any packages you declared are present. SSH as deploy@INSTANCE_ADDRESS with the matching private key.

See also#

• cloud-init and first-boot configuration
• How to provision a production-ready VM
• Configure a VM with Ansible