Cloud-init

Cloud-init is an industry-standard tool for configuring VMs at boot time. The evroc compute service includes cloud-init in all provided operating system images, allowing you to customize VMs automatically during their initial startup without manual intervention.

What is cloud-init?

Cloud-init is a widely-used initialization system for cloud instances. It runs during the first boot of a VM and can perform various configuration tasks by reading user-provided data (called "userdata"). This automation eliminates the need to manually configure each VM after creation.

All evroc-provided Linux VM images come with cloud-init pre-installed and configured to work with the evroc platform.

Common use cases

Cloud-init is particularly useful for:

• SSH key configuration - Install SSH public keys for user access
• Package installation - Install software packages automatically on first boot
• User management - Create users, configure passwords, set permissions
• File management - Write files, create directories, set permissions
• Disk configuration - Format and mount additional disks automatically
• Service configuration - Configure and start services like web servers or databases
• Running custom scripts - Execute bash or python scripts during initialization
• Network configuration - Set up additional network interfaces (advanced use cases)

How cloud-init works in evroc

When you create a VM in evroc, you can optionally provide a cloud-init userdata script. During the VM's first boot:

1. Cloud-init starts and retrieves the userdata you provided
2. Cloud-init parses the userdata and performs the specified configuration tasks
3. The VM completes its boot process with your custom configuration applied
4. On subsequent boots, cloud-init skips the userdata execution (unless configured otherwise)

Cloud-init datasource

Cloud-init retrieves its configuration from datasources, which provide the necessary configuration data including userdata and metadata. The evroc compute service uses the NoCloud datasource, specifically the "Drive with labeled filesystem" method.

evroc attaches a disk labeled cidata (/dev/disk/by-label/cidata) to the VM. Cloud-init mounts this disk and reads two files:

• user-data - Your custom cloud-init configuration
• meta-data - Instance metadata including VM name, instance ID, and SSH public keys

The metadata file includes information that cloud-init can use for configuration:

{
    "instance-id": "273dc45b-5674-56b2-a611-a615151d3305",
    "local-hostname": "<VM name>",
    "public-keys": {
      "0": "ssh-ed25519 AAAAC3Nz..."
    }
}

The SSH public keys in the metadata correspond to those specified in the VM's osSettings.ssh.authorizedKeys field when creating the VM through the CLI or API.

The instance ID changes whenever you modify the VM specification (including stopping and starting the VM), which can trigger cloud-init to re-run on the next boot.

Userdata formats

Cloud-init supports several data formats. The most common are:

Cloud-config (YAML)

The recommended format for most use cases. Cloud-config files start with #cloud-config and use YAML syntax:

#cloud-config
packages:
  - nginx
  - git
users:
  - name: deploy
    ssh-authorized-keys:
      - ssh-rsa AAAA...
runcmd:
  - systemctl start nginx

Shell scripts

For simple script execution, start your userdata with #!/bin/bash:

#!/bin/bash
apt-get update
apt-get install -y nginx
systemctl start nginx

Jinja2 templates

Use Jinja2 templates to dynamically incorporate data from the metadata file. Start with ## template: jinja:

## template: jinja
#cloud-config

users:
  - name: evroc-user
{% if public_ssh_keys %}
    ssh_authorized_keys:
{% for pubkey in public_ssh_keys %}
      - {{ pubkey }}
{% endfor %}
{% endif %}

This allows you to reference SSH keys from the metadata instead of hardcoding them in your userdata.

For a complete list of supported formats and modules, refer to the cloud-init documentation.

SSH keys and cloud-init

SSH keys can be configured through cloud-init or through the evroc API/CLI. When you specify SSH keys through the API or CLI, evroc automatically includes them in the metadata file that cloud-init reads.

If you provide custom cloud-init userdata, you must explicitly configure how SSH keys are handled. You can either:

1. Use Jinja2 templates to dynamically include SSH keys from the metadata (recommended)
2. Hardcode SSH keys directly in your cloud-init userdata
3. Skip specifying SSH keys in the API and define them only in your userdata

If you specify both osSettings.ssh.authorizedKeys in the API and custom cloud-init userdata, the SSH keys will only be applied if your userdata explicitly includes them (using Jinja2 templates or hardcoding).

At least one SSH key must be configured at VM creation time to enable access, as password authentication is disabled by default in evroc VMs.

Supported distributions

All evroc-provided Linux images include cloud-init. The following table shows verified cloud-init versions:

Debugging cloud-init

Cloud-init continues execution even if errors occur. To troubleshoot issues, SSH into the VM and check the log files:

• Main log: /var/log/cloud-init.log
• Output log: /var/log/cloud-init-output.log
• Status: Run cloud-init status to check if initialization completed successfully

Common issues:

• SSH access fails - Check for YAML syntax errors (incorrect indentation, tabs instead of spaces) in your cloud-config
• Permission denied errors - Verify SSH keys are correctly templated into your userdata if using custom cloud-init
• Configuration not applied - Check that cloud-init completed successfully and review the log files

Limitations and important behaviors

• Cloud-init userdata runs only during the first boot by default. If, for example, you later update the userdata to supply a new SSH key, the change will not be applied.
• The customCloudInitUserData field cannot be updated after VM creation
• If you need to fix cloud-init configuration errors, delete both the VM and its boot disk, then recreate them (keeping the boot disk may cause inconsistent provisioning)
• Complex configurations may take time to complete before the VM is fully ready
• Errors in userdata scripts can cause initialization to fail, but cloud-init will continue executing other modules

Next steps

• Learn how to use custom cloud-init userdata with step-by-step examples
• Learn about SSH Keys and how they enable VM access
• See how to create a VM with custom cloud-init configuration
• Read the official cloud-init documentation for advanced use cases