Skip to main content
In this lesson we cover EC2 user data: what it is, when and how it runs, and practical examples for bootstrapping instances automatically. When you launch an Amazon EC2 instance you can supply “user data”: a script or set of instructions that the instance executes during its initial boot. This is useful for one-time setup tasks such as installing packages, pulling configuration, bootstrapping services, or writing files so the instance is immediately ready to serve traffic.
A slide titled "EC2 User Data" showing a flow from a computer icon to a "Software installed — Ready to use" box and then to a user icon that branches into three tasks: "Download Remote file", "Health Check API", and "Install Application Server."
What user data does and important constraints
  • User data is delivered to the instance at launch and interpreted by the instance (for example cloud-init on Linux or EC2Launch/EC2Config on Windows). EC2 treats the payload as opaque — it does not examine or validate the contents.
  • The raw (pre-Base64) user data size limit is 16 KB.
  • When launching via the AWS Console you can paste plain text; the console Base64-encodes it for you. When calling EC2 APIs or using SDKs, callers typically must provide Base64-encoded user data.
  • When retrieved from the instance metadata service it is returned in decoded (human-readable) form. Some EC2 API responses (e.g., DescribeInstanceAttribute/UserData) return Base64-encoded user data that you must decode.
Summary table: common behaviors and their impact
Behavior / ConstraintWhat it meansNotes / Action
Runs only on initial launchUser data executes during the instance’s first bootFor recurring boots, put scripts in per-boot hooks (cloud-init per-boot, systemd services, or OS-specific startup scripts)
Changing user data after creationModifying user data on a stopped instance does not cause it to run on next startTo apply new configuration, run scripts manually or bake new AMIs
Encoding requirementsConsole handles Base64; API/SDK may require Base64 inputCheck your SDK/CLI docs — AWS CLI or SDKs often accept plain text and encode for you, but the raw EC2 API expects Base64
Size limit16 KB rawKeep bootstrapping lightweight or use remote artifact downloads
Retrieval formatsMetadata service returns decoded text; some API responses return Base64Decode API responses before use
User data is best for one-time bootstrapping: installing packages, placing configuration files, registering with a service, or making the instance ready for traffic. For recurring or per-boot tasks, use cloud-init per-boot hooks, OS startup scripts, or configuration management tools like Ansible, Chef, or Puppet.
Example: a minimal Linux user data script
  • The following example updates packages, installs and starts Apache (httpd), ensures it is enabled at boot, and writes a simple index page. This is suitable for Amazon Linux/CentOS-based images that use yum and systemd:
#!/bin/bash
# Update packages, install and start Apache (Amazon Linux/CentOS style)
yum update -y
yum install -y httpd
systemctl enable httpd
systemctl start httpd

# Write a simple web page
echo "Hello from $(hostname -f)" > /var/www/html/index.html
How to view user data from inside an instance
  • IMDSv1 (not recommended for new deployments):
curl http://169.254.169.254/latest/user-data
  • IMDSv2 (recommended — requires a session token):
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
curl -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/user-data
Retrieve user data via the AWS CLI
  • Many EC2 API outputs provide the user data Base64-encoded; decode it after retrieval:
# Describe the instance attribute (userData) and decode the Base64 value
aws ec2 describe-instance-attribute \
  --instance-id i-0123456789abcdef0 \
  --attribute userData \
  --query 'UserData.Value' \
  --output text | base64 --decode
User data execution differs by OS and AMI:
  • Linux AMIs: usually processed by cloud-init (which supports multiple formats and modules).
  • Windows AMIs: processed by EC2Config or EC2Launch. If you require a script to run on every boot, configure the appropriate per-boot mechanism (cloud-init per-boot hooks, systemd units, or Windows Scheduled Tasks/Startup scripts) rather than relying on the one-time user data execution.
Links and references Further reading and patterns
  • Use user data to fetch larger config or artifacts from S3, Git, or an artifact repository if your bootstrap exceeds the 16 KB limit.
  • For immutable infrastructure, consider baking user data changes into a new AMI or using automation pipelines that rebuild instances with desired configuration.

Watch Video

Practice Lab