Guest initialization

Configure first-boot users, packages, and services with cloud-init.

Guest initialization applies first-boot configuration from the selected image and droplet user data. Infra supplies the configuration; the guest executes it.

PrerequisitesCopy link

Use an image with cloud-init enabled and support for Infra's metadata source. The image details declare initialization support and the default login account. A running hypervisor does not prove that cloud-init completed successfully.

Add user dataCopy link

Open Create droplet → Initialization, choose cloud-init, and enter YAML. Infra validates the document format before creation. Package availability, guest commands, and service behavior are evaluated inside the guest.

To install nginx and write a static health endpoint, use this initialization document:

#cloud-config
package_update: true
packages:
  - nginx
write_files:
  - path: /var/www/html/healthz
    permissions: "0644"
    content: |
      ready
runcmd:
  - [systemctl, enable, --now, nginx]

This example requires an image whose package repositories contain nginx and whose service manager is systemd. Network egress and name resolution must be available for package installation. Add the droplet to a load balancer only after its application health check passes.

Execution and updatesCopy link

User data is attached to the droplet's creation revision. The image determines which cloud-init modules run once and which run on later boots. Editing the stored user data does not rerun initialization on an existing guest.

To change an existing deployment, use configuration management inside the guest or create a replacement droplet from a new template revision. Re-running initialization manually can repeat package changes and application commands.

Metadata and credentialsCopy link

The metadata service exposes the guest identity, hostname, and assigned network configuration through a guest-scoped token session. Only the intended guest should be able to reach its metadata endpoint. Do not route metadata access through a public load balancer or shared application proxy.

User data is visible to users with droplet configuration access and can appear in guest logs. Do not place long-lived API keys, private SSH keys, or organization credentials in it. Use short-lived credentials or an application secret manager after workload identity is established.

Observe initializationCopy link

The droplet Initialization tab shows the submitted configuration and guest agent status when available. Inside the guest, inspect cloud-init's status and logs before treating the deployment as ready. Run the status check there:

sudo cloud-init status --long

Wait for status: done without reported errors. To inspect the final-stage service log, run:

sudo journalctl -u cloud-final --no-pager

A syntax rejection prevents submission. A failed guest command leaves the droplet running with an initialization error; Infra does not roll back commands that already ran. Correct the template and replace the guest, or repair the existing guest according to application policy.

Use Guest access if network access is unavailable and Images if the initialization source is unsupported.