Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 35 ยท Automation and Terraform

cloud-init and Droplet User Data

Configure Droplets automatically on first boot with cloud-init: user data, #cloud-config, packages, users, write_files, runcmd, logs and debugging.

Creating a Droplet and then logging in to install packages by hand does not scale, and it cannot be repeated exactly. DigitalOcean images include cloud-init, the standard tool that reads a block of text called user data at the first boot and uses it to set up the machine: create users, install packages, write files, run commands. You paste it in the control panel ("Add initialization scripts"), pass it with doctl --user-data-file, or set user_data in Terraform.

A cloud server is not available here, so the YAML is shown as read-only text. The Python blocks are labelled stand-ins that check a configuration and show the order in which cloud-init performs steps.

Two flavours of user data

  1. A shell script starting with #!/bin/bash. Simple and flexible, but you write all the error handling.
  2. A cloud-config document starting with the line #cloud-config. Declarative YAML with modules for common tasks, which is easier to read and keep idempotent.
YAML
#cloud-config
package_update: true
package_upgrade: true

users:
  - name: deploy
    groups: [sudo]
    shell: /bin/bash
    sudo: "ALL=(ALL) NOPASSWD:ALL"
    ssh_authorized_keys:
      - ssh-ed25519 AAAA... laptop-2026

ssh_pwauth: false
disable_root: true

packages:
  - nginx
  - ufw
  - fail2ban
  - unattended-upgrades

write_files:
  - path: /etc/nginx/conf.d/health.conf
    permissions: "0644"
    content: |
      server {
        listen 8080;
        location /healthz { return 200 "ok\n"; }
      }

runcmd:
  - ufw allow OpenSSH
  - ufw allow 80/tcp
  - ufw allow 443/tcp
  - ufw allow 8080/tcp
  - ufw --force enable
  - systemctl enable --now nginx fail2ban
  - systemctl reload nginx

This does the hardening steps from SSH hardening automatically: a sudo user with your key, no password login, a firewall, fail2ban and a health endpoint for a Load Balancer.

Passing it:

Terminal
doctl compute droplet create web-1 \
  --region nyc1 --size s-1vcpu-1gb --image ubuntu-24-04-x64 \
  --ssh-keys 12345678 --user-data-file cloud-init.yaml --wait

Order of execution

cloud-init runs in stages, and inside the cloud-config stages modules run in a fixed order, not the order of the keys in your file. Roughly: network setup, then user and write_files modules, then package installation, then runcmd, which runs last, once, as root. runcmd and bootcmd entries run in the order listed. A step that depends on a package must therefore be in runcmd, not placed in write_files expecting the package to exist.

Python Stand-in: cloud-config module order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Validate before you boot

A typo in YAML means a half-configured server and a lot of confusion. Check the file first, on your machine: cloud-init schema --config-file cloud-init.yaml (on a machine with cloud-init installed) validates it against the schema. The stand-in below does a few of the same sanity checks with plain Python.

Python Stand-in: sanity-check a cloud-config

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second example fails twice: it lacks the #cloud-config header and it indents with a tab. The stand-in knows only a few keys, so the real schema check is the one to trust.

Debugging on the Droplet

When something did not happen, log in and look:

Terminal
cloud-init status --long
sudo less /var/log/cloud-init.log
sudo less /var/log/cloud-init-output.log
sudo cat /var/lib/cloud/instance/user-data.txt

cloud-init-output.log has the output of runcmd commands. Remember that user data runs once, on first boot only: editing the user data of an existing Droplet does nothing. To retest, create a fresh Droplet (or run sudo cloud-init clean --logs on a throwaway machine and reboot).

Good practice

  • Keep secrets out of user data: it is visible in the control panel, the metadata service and logs. Fetch secrets later from a secret store, or inject a short-lived token.
  • Keep user data short; install only the base, and let a configuration tool (Ansible) or a container pull the rest. Large setup scripts slow every boot.
  • Make commands idempotent and safe to read: apt-get install -y, not interactive prompts.
  • Use a custom image or snapshot (built with Packer, for example) when boot time matters, so Droplets start with software already installed.
  • Stay well below the size limit for user data (about 64 KiB at the time of writing); big payloads belong in an image or a download.
  • Droplets can read their own metadata at http://169.254.169.254/metadata/v1/, such as the hostname and IP, from inside the machine.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which first line identifies a cloud-config document?

    cloud-init recognises the #cloud-config header and parses the rest as YAML.
  2. 2. When does user data run?

    cloud-init applies user data on first boot; later edits do nothing on an existing Droplet.
  3. 3. Where can you read the output of runcmd commands?

    cloud-init-output.log captures the output of the commands it runs.
  4. 4. Why not put a database password in user data?

    User data is not a secret store; anyone with access can read it.

Summary

  • cloud-init configures a Droplet at first boot from user data: a shell script or a #cloud-config YAML document.
  • cloud-config modules (users, packages, write_files, runcmd) replace long hand-written scripts.
  • Validate the file, read the logs when something fails, and remember user data runs once.
  • Keep secrets out of it, make steps idempotent and use images for fast, repeatable boots.

Next: Monitoring and Alerts