AWS EC2 User Data Explained: Scripts, Cloud-Init, Examples

Simple explanation

Think of user data as a first-day instructions sheet you leave on the desk before a new employee arrives. The employee (your EC2 instance) reads it on day one and follows the steps. After that, the sheet is done. It does not run again on its own.

In practice: you write a shell script or a cloud-config YAML file, attach it to the instance at launch, and AWS runs it automatically as root before the instance starts serving traffic. No manual login. No SSH commands after the fact. No waiting for a configuration tool to connect.

Why EC2 user data matters

When you launch an EC2 instance from a base Amazon Machine Image (AMI), you get a clean operating system with nothing extra installed. Without user data, you would need to SSH in after launch and set everything up by hand. That is slow, error-prone, and impossible to automate at scale.

User data lets you define the setup once and run it automatically every time a new instance launches. This matters especially for Auto Scaling Groups: when AWS adds a new instance to handle increased load, the user data script runs and prepares it to serve traffic with no human involvement.

• Repeatability: the same script runs every time, producing a consistent instance.
• Speed: no manual SSH steps after launch.
• Version control: the bootstrap logic lives in your repo alongside your infrastructure code.

How EC2 user data works

When an EC2 instance boots for the first time, cloud-init (a standard Linux bootstrapping tool included in most AWS-provided AMIs) contacts the instance metadata service (IMDS) at http://169.254.169.254/ and retrieves the user data you attached at launch.

Cloud-init inspects the first line of the payload and decides how to process it:

• A line starting with #!/bin/bash (or any shebang) causes cloud-init to run it as a shell script, as root.
• A line starting with #cloud-config causes cloud-init to treat it as declarative YAML configuration.
• Multiple content types can be combined using MIME multi-part format (covered below).

Boot sequence at a glance

1. You launch an instance and attach user data.
2. AWS stores the user data and makes it available via IMDS.
3. cloud-init runs during the first boot and detects the content type.
4. Your script or cloud-config executes as root.
5. The instance finishes bootstrapping and becomes available.
6. All output is written to /var/log/cloud-init-output.log.

Key behaviors and limits

When to use EC2 user data

User data is a good fit for:

• Installing packages: install Nginx, Python, or any other dependency on a fresh AMI.
• Writing config files: write an app config or an Nginx virtual host before the service starts.
• Starting services: enable and start a systemd service so it is running on first boot.
• Bootstrapping Auto Scaling Group instances: register with a load balancer target group, or pull the latest app artifact from S3.
• Simple one-time application setup: clone a repo and run a setup script on a development or staging instance.

When not to use EC2 user data

User data is a simple tool. When the bootstrap gets complex, other approaches work better:

• Use a golden AMI when you want fast launches, predictable state, and no dependency on external package repositories at boot time. Pre-bake everything into the AMI and use user data only for last-mile configuration, like injecting an environment name or running a registration command.

• Use a systemd service for any logic that needs to run on every boot, not just the first. User data is not the right tool for recurring startup behavior.

• Use a CI/CD image-build pipeline (such as Terraform with Packer or CodeBuild) when your bootstrap is complex, needs automated testing, or must be reproducible across multiple regions.

If your user data script is over 60 lines and doing complex work, that is usually a sign you should pre-bake the heavy steps into a golden AMI instead.

User data vs cloud-init vs golden AMI vs systemd

User data vs golden AMI

A useful analogy: user data is like baking bread from scratch every time a new server launches. A golden AMI is like keeping a pre-baked loaf in the freezer and just defrosting it. The bread-from-scratch approach is flexible and easy to change. But it takes time, and if the oven (the package repository or the network) is unavailable, you get nothing.

User data is flexible: change the script and the next launch picks it up immediately. But it runs at boot, depends on external services, and is harder to test systematically.

A golden AMI snapshot has everything pre-installed. Launches are fast and predictable. The tradeoff is a pipeline to build and validate new AMI versions whenever your software changes.

How to add user data

In the AWS Console

1. Open the EC2 console and choose Launch Instance.
2. Scroll to Advanced details at the bottom of the form.
3. Paste your script into the User data text area.
4. The console base64-encodes the data automatically before launch.

To update user data on an existing instance: stop the instance, go to Actions → Instance Settings → Edit User Data, make your changes, then start the instance. The updated data is stored and attached, but on Linux, cloud-init will not re-run it automatically.

With the AWS CLI

Pass a local script file using the —user-data flag:

aws ec2 run-instances \
  --image-id ami-0abcdef1234567890 \
  --instance-type t3.micro \
  --key-name my-key \
  --security-group-ids sg-0abc123 \
  --subnet-id subnet-0abc123 \
  --user-data file://startup-script.sh

The file:// prefix reads the script from disk. The AWS CLI handles base64 encoding for you.

In a launch template

Launch templates store user data alongside the rest of your instance configuration, making it easy to reuse across Auto Scaling Groups and keep it versioned. When creating a launch template via the CLI, base64-encode the script first.

# Linux (GNU coreutils) — -w 0 disables line wrapping
USERDATA=$(base64 -w 0 startup-script.sh)

# macOS — omit -w 0, it is not supported by BSD base64
# USERDATA=$(base64 startup-script.sh)

aws ec2 create-launch-template \
  --launch-template-name web-template \
  --launch-template-data "{
    \"ImageId\": \"ami-0abcdef1234567890\",
    \"InstanceType\": \"t3.micro\",
    \"UserData\": \"$USERDATA\"
  }"

In the AWS Console, you can paste the script directly into the launch template editor and encoding is handled for you.

Example: working bash user data script

This script installs Nginx, fetches the instance ID from the metadata service using IMDSv2, writes a simple landing page, and starts Nginx:

#!/bin/bash
set -e

# Update package cache and install Nginx
dnf update -y
dnf install -y nginx

# Fetch the instance ID using IMDSv2 (required on newer instances)
TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
INSTANCE_ID=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/instance-id)

# Write a simple landing page.
# The heredoc uses <<EOF (unquoted) so $INSTANCE_ID expands in the body.
cat > /usr/share/nginx/html/index.html <<EOF
<!DOCTYPE html>
<html>
<head><title>Hello from EC2</title></head>
<body>
  <h1>Instance is running</h1>
  <p>Instance ID: ${INSTANCE_ID}</p>
</body>
</html>
EOF

# Enable and start Nginx in one step
systemctl enable --now nginx

echo "Bootstrap complete on ${INSTANCE_ID}"

A few things worth noting:

• set -e stops the script immediately if any command fails, so later steps never run against a broken environment.
• IMDSv2 requires a session token. The two-step curl pattern above is the current AWS-recommended approach. Plain IMDSv1 calls may be blocked on instances where IMDSv2-only mode is enforced.
• The heredoc uses <<EOF (unquoted) so ${INSTANCE_ID} expands. A quoted <<‘EOF’ would suppress all variable expansion and print the literal string ${INSTANCE_ID} in the HTML.
• systemctl enable —now nginx both enables the service for future reboots and starts it immediately.

This example uses dnf, the package manager on Amazon Linux 2023 and Fedora-based AMIs. On Ubuntu or Debian, replace dnf install with apt-get install -y and run apt-get update -y first.

Example: cloud-config version

The same setup expressed as cloud-config YAML:

#cloud-config
packages:
  - nginx

write_files:
  - path: /usr/share/nginx/html/index.html
    content: |
      <!DOCTYPE html>
      <html>
      <head><title>Hello from EC2</title></head>
      <body><h1>Instance is running</h1></body>
      </html>
    owner: root:root
    permissions: '0644'

runcmd:
  - systemctl enable --now nginx

Cloud-config is cleaner than bash for tasks that map naturally to its built-in directives: installing packages (with automatic retry on failure), writing files atomically, creating users, or setting the hostname. For anything that needs conditionals, loops, or complex error handling, a shell script is usually easier to reason about.

Example: combining cloud-config and a shell script

If you need both a cloud-config block and a shell script in the same user data payload, use MIME multi-part format. Cloud-init processes each part according to its declared content type.

Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0

--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit

#cloud-config
packages:
  - nginx

--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit

#!/bin/bash
TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
INSTANCE_ID=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/instance-id)
echo "Bootstrapped: $INSTANCE_ID" > /var/log/bootstrap-id.txt

--//--

The cloud-config part runs first (package installs, file writes), then the shell script runs. This pattern lets you use cloud-config for standard declarative setup and bash for anything that needs scripting logic, without mixing the two.

How to debug user data failures

User data failures are common, and cloud-init logs everything. When an instance launches but the software is not installed or configured correctly, start with the logs before relaunching.

# Main log: stdout and stderr from your script
sudo cat /var/log/cloud-init-output.log

# Detailed cloud-init log: module execution, timing, errors
sudo cat /var/log/cloud-init.log

# Quick status check: returns done, running, or error
cloud-init status

Access the instance via SSH to read these logs. If the instance is unreachable because the user data script failed before the SSH service started, use Session Manager instead. It does not depend on SSH or open inbound ports in your security group.

Common failure causes

Bootstrap time and Auto Scaling

User data scripts run synchronously during boot. If your script takes two minutes, the instance is not available for two minutes after launch. In an Auto Scaling Group, this delays scale-out events. If the health check grace period is shorter than the bootstrap time, the ASG will terminate the instance as unhealthy before it finishes starting.

You can track actual launch durations from Amazon CloudWatch metrics to spot patterns and set alarms if bootstrapping starts taking longer than expected.