Driving cloud-init on a fresh Debian or Ubuntu instance: user-data, status --wait, and safe re-runs

Goal

Confirm that cloud-init has finished configuring a Debian or Ubuntu cloud image, validate a user-data file before relying on it, and re-test it safely on the same instance.

Prerequisites

An instance booted from a cloud image with cloud-init installed (standard on Debian and Ubuntu cloud/server images); shell access, ideally via the provider's console for the first boot in case user-data breaks networking.

Steps

1. After boot, block any further automation until provisioning is done: cloud-init status --wait. The command reference describes --wait as blocking "until cloud-init completes", and the plain status subcommand reports whether cloud-init is running, done, disabled or in error, exiting 1 on a crash and 2 on recoverable errors.
2. On failure, read the two log files cloud-init itself points to for triage: /var/log/cloud-init.log (detailed module trace) and /var/log/cloud-init-output.log (captured stdout/stderr of what cloud-init ran).
3. Before attaching a new user-data file to an instance, validate it locally: cloud-init schema --system --annotate. The schema subcommand can "Validate cloud-config files using jsonschema", and --system points it at the user-data actually in use rather than a file argument; --annotate marks the offending lines in place.
4. To re-test provisioning on a running instance rather than launching a new one, reset cloud-init's state: cloud-init clean --logs --reboot. The clean subcommand removes cloud-init artifacts "to simulate a clean instance", and on the next boot cloud-init re-runs all stages as it did the first time; --logs also clears the previous log files so the new run's output is not mixed with the old one.
5. After the reboot, repeat step 1 to confirm the fresh run completed, and diff the new /var/log/cloud-init.log against the previous one if something changed.

Expected result

cloud-init status --wait returns after provisioning with exit code 0, and cloud-init schema --system reports no errors for the active user-data.

Limits and test basis

cloud-init clean on a production instance discards no user data itself but does reset host identity markers used to decide "is this the first boot" (with --machine-id, also /etc/machine-id), which is intended for golden-image cloning and testing, not routine operation — treat it as a lab step. --reboot is required for the re-run to start automatically; without it, a manual cloud-init init invocation is needed instead.