Using userdata in CloudCIX Compute Instances

CloudCIX allows you to customise your compute instances at first boot using cloud-init. Cloud-init is a standard Linux bootstrapping system used by most cloud providers.

In CloudCIX, you can provide cloud-init configuration through the userdata field in the VM creation payload.

This section explains how the userdata field works, what it supports, and shows practical examples.

What is userdata?

userdata is a text field where you supply a cloud-init configuration script. This script runs automatically the first time the VM boots and can:

• Create users

• Set passwords and SSH keys

• Install packages

• Configure services

• Run initialization commands

• Write configuration files

• Trigger remote installation scripts

CloudCIX will pass the content of userdata directly to cloud-init on the VM.

Format Requirements

• The content must begin with:

#cloud-config

• The format must follow YAML indentation rules.

• Always use spaces, never tabs.

• If the YAML is invalid, cloud-init will silently ignore parts of it.

Example: Creating an Administrator User

Below is the userdata used in the example VM creation payload:

#cloud-config
users:
  - name: administrator
    groups: sudo
    shell: /bin/bash
    lock_passwd: false
    passwd: $2a$12$GcOZ6Mh4GFyxABIhhDAt/eHk6mp1fXwOeyg0tPFLbTERhcFnxUR7.
    ssh_authorized_keys:
      - ssh-ed25519 AAAAC3NzaB2lzDI1NTE5AAAAIEc5NwoYuL3x0JF10TLCutzcNl0Gpv3L9oPg57pTu68I

chpasswd:
  expire: false

ssh_pwauth: true

What this configuration does

users:

Creates a Linux user when the VM boots

name: administrator

The username

groups: sudo

Gives the user administrator privileges

shell: /bin/bash

Sets the default shell

passwd:

Bcrypt-hashed password for SSH login

ssh_authorized_keys:

Adds your SSH public key for secure login

chpasswd:

Prevents the password from expiring on first login

ssh_pwauth: true

Enables SSH password login

Using this configuration, customers can log into the VM immediately via SSH using either:

• The provided SSH key

• The password corresponding to the bcrypt hash

Where userdata Goes in the VM Creation Payload

In a CloudCIX API request, userdata must be placed inside the metadata block:

'metadata': {
    'instance_type': 'virtual-machine',
    'dns': '8.8.8.8,8.8.4.4',
    'userdata': "<cloud-init YAML goes here>"
}

This exact text is delivered into the VM’s cloud-init system during first boot.

What Customers Typically Use userdata For

Here are common use-cases you may want to implement:

1. Create users

users:
  - name: devops
    groups: sudo
    ssh_authorized_keys:
      - ssh-ed25519 AAAA...

2. Install packages

packages:
  - nginx
  - htop
  - curl

3. Run commands after boot

runcmd:
  - apt update
  - apt install -y docker.io
  - systemctl enable docker

4. Download and run a startup script

runcmd:
  - curl -fsSL https://example.com/bootstrap.sh | bash

5. Write configuration files

write_files:
  - path: /etc/myapp/config.yaml
    content: |
      log_level: info
      port: 8080

Security Best Practices

✔ Recommended

• Use SSH keys instead of passwords

• Avoid embedding plaintext credentials

• Keep userdata short and maintainable

• Validate YAML before submitting to CloudCIX

✖ Avoid

• Plaintext passwords

• Long shell scripts (host them externally and curl them)

• Complex networking configurations inside cloud-init unless necessary

Testing Tips

You can test your cloud-init configuration locally:

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

Inside a running VM:

• Logs: /var/log/cloud-init.log

• Output: /var/log/cloud-init-output.log