User Data (Startup Script) Documentation For VM on Spot

Overview

User Data allows you to pass a startup script when creating a virtual machine (VM). This script runs automatically during the first boot of the instance and is typically used to:

Install packages and dependencies
Configure applications and services
Set up environments (e.g., web servers, agents)
Perform initial system provisioning

This helps automate instance setup and reduces manual configuration.

How It Works

User Data is provided at the time of VM creation.
The script runs once during the initial boot.
It executes with root privileges.
The script is non-interactive, so it must not require user input.

Supported Format

Only shell scripts are supported.

Your script must start with a shebang:

#!/bin/bash

Example: Basic User Data Script For Ubuntu

#!/bin/bash # Update system packages apt-get update -y # Install Apache web server apt-get install -y apache2 # Start and enable Apache systemctl enable apache2 systemctl start apache2 # Create a simple web page echo "Hello from Spot VM" > /var/www/html/index.html # Log execution mkdir -p /opt/rackspace-userdata-test echo "Userdata execution confirmed at: $(date)" > /opt/rackspace-userdata-test/success.log # Append a login banner to the system profile echo "echo '======================================================'" >> /etc/profile echo "echo ' USERDATA SCRIPT RAN SUCCESSFULLY !!!!!!!!! '" >> /etc/profile echo "echo '======================================================'" >> /etc/profile

Example: Basic User Data Script For Rocky

#!/bin/bash dnf install -y httpd systemctl enable httpd systemctl start httpd

Execution Behaviour

Runs automatically when the VM boots for the first time
Runs as root user at boot time
Does not run again on reboot

Best Practices:

1. Handle non-critical failures safely:

Ensure your script can run safely without breaking if partially executed. Use || true only when failure is acceptable.

Example:

rm file.txt || true

2. Avoid Interactive Commands:

Do not use commands that require user input.

Example:

✔ Correct:

apt-get install -y nginx

✘ Incorrect:

apt-get install nginx

3. Add Logging for Debugging:

Redirect output to a log file:

#!/bin/bash exec > /var/log/user-data.log 2>&1 set -x

4. Handle Failures Gracefully:

Use error handling where needed:

if !systemctl start apache2; then echo "Failed to start apache2" >> /var/log/user-data.log fi

5. Keep Script Lightweight:

Large scripts increase boot time. For complex setups:

Download scripts from a remote source
Or use configuration management tools

Limitations

Script size may be limited (platform-dependent)
Runs only once during initial boot
No interactive input supported
Execution time impacts instance startup time

Advanced Usage Download and Execute External Script

#!/bin/bash set -e curl -f -o setup.sh https://example.com/setup.sh chmod +x setup.sh ./setup.sh

Install and Configure Docker

#!/bin/bash set -e apt-get update -y apt-get install -y docker.io systemctl start docker systemctl enable docker usermod -aG docker ubuntu

Common Issues

Issue	Cause	Fix
Script didn’t run	Missing `#!/bin/bash`	Add shebang
Command failed	Interactive prompt	Use non-interactive flags
Service not starting	Package not installed	Verify install step
Permission issues	Files owned by root / wrong permissions	Use `chown` / `chmod`

Security Considerations

Do not hardcode secrets (API keys, passwords) in user data
Scripts are visible via instance metadata depending on platform configuration

Summary

User Data is a simple and powerful way to automate VM initialization. By using shell scripts, you can ensure consistent, repeatable, and fast provisioning of infrastructure.

Last updated on

Was this page helpful?