Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 70 ยท Compute with EC2

AMIs, User Data and Instance Metadata

Learn how EC2 instances get their software: AMIs and golden images, user data and cloud-init, the instance metadata service with IMDSv2, and instance profiles.

Every EC2 instance starts from an Amazon Machine Image (AMI), and almost every real instance needs a little more than the image provides: a hostname, a config file, a service to start, credentials to talk to other AWS services. This lesson covers the four pieces that fill that gap: the AMI itself, user data scripts, the instance metadata service, and instance profiles. Together they let a freshly launched server configure itself without anyone logging in.

None of this can run on the site, because there is no real instance to boot. The AWS CLI commands, user data and metadata requests below are read-only. Two Python stand-ins let you watch the ideas work: a tiny user data runner and a model of the metadata service with its session tokens. They show the mechanism, not the real cloud-init or the real service.

What an AMI contains

An AMI is a template for the root volume of an instance, plus launch settings. It holds an operating system, installed software and configuration, a block device mapping that says which volumes to create, and permissions that say who may launch it. When you launch an instance, AWS copies the AMI's snapshot into a new EBS volume and boots from it. See EC2 Instances for the launch workflow and EBS Volumes, Snapshots and Instance Store for the snapshot mechanics behind it.

AMIs are regional. An image in one Region has an ID that does not exist in another; to use it elsewhere you copy it, which creates a new AMI ID. You can find images from AWS (for example Amazon Linux), from the AWS Marketplace, from the community, or your own. Treat community images with suspicion: you cannot know what is baked into them.

Baking versus bootstrapping

There are two ways to get your application onto a server, and most teams mix them.

  • Bootstrapping starts from a plain image and installs everything at first boot with a script. It is flexible, but slow to start, and a failure in a package download can leave an instance half configured.
  • Baking (a golden image) installs the software ahead of time and saves the result as a new AMI. Instances then boot in seconds, identical every time, with no dependency on external package servers at launch.

A common compromise is to bake the slow, stable parts (OS patches, runtime, agents) and bootstrap the fast, changing parts (which environment am I in, where is my config). Auto Scaling groups, covered in Auto Scaling Groups, benefit most from baked images because new capacity must appear quickly.

flowchart LR
    B["Base AMI"] --> I["Temporary instance<br/>install and configure"]
    I --> S["Snapshot of root volume"]
    S --> G["Golden AMI"]
    G --> L1["Instance 1<br/>user data adds env settings"]
    G --> L2["Instance 2<br/>user data adds env settings"]

Bake the stable parts once, then let each instance's user data supply what differs.

You can create an image from a running instance by hand, but a repeatable build is better. EC2 Image Builder is the AWS service for this, and Packer is a popular open-source tool that does the same job: it launches a temporary instance, runs your provisioning steps, creates the AMI and terminates the instance. A build definition is code you keep in version control, so a security patch means rebuilding an image, not editing servers.

Terminal
# read-only: save a running instance as an AMI by hand
aws ec2 create-image \
  --instance-id i-0abc123def4567890 \
  --name "web-golden-2026-03-01" \
  --no-reboot

The --no-reboot flag skips the reboot AWS normally performs to get a consistent file system, so use it only when you accept the small risk of an inconsistent image.

User data and cloud-init

User data is a block of text you pass at launch, up to 16 KB before encoding. On common Linux images a program called cloud-init reads it on first boot. If it starts with #! (a shebang line), cloud-init runs it as a script as root. If it starts with #cloud-config, it is treated as YAML describing packages, files and commands in a declarative way.

Terminal
#!/bin/bash
# read-only: a typical user data script
dnf install -y nginx
echo "<h1>Hello from $(hostname)</h1>" > /usr/share/nginx/html/index.html
systemctl enable --now nginx
YAML
#cloud-config
# read-only: the same idea, declarative
packages:
  - nginx
write_files:
  - path: /usr/share/nginx/html/index.html
    content: "<h1>Hello</h1>"
runcmd:
  - systemctl enable --now nginx

Three rules save a lot of debugging time:

  • User data runs once, at the first boot of an instance, by default. Stopping and starting the instance does not run it again.
  • It runs after the instance is reported as running, so a load balancer may see the instance before the script finishes. Health checks and lifecycle hooks exist for this.
  • User data is not secret. Anyone who can read the instance's metadata, or call DescribeInstanceAttribute, can read it. Never put passwords or keys in it; fetch secrets at boot from a secrets service using the instance's role, which you will see shortly.

Output goes to /var/log/cloud-init-output.log, the first place to look when a server did not configure itself.

The stand-in below mimics the shape of the idea: it takes a list of simple steps, runs them against a pretend file system and service table, and records what happened. Real cloud-init runs real commands; this runner only understands four.

Python A tiny user data runner

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that the failed line did not stop the later lines. A plain shell script behaves the same way unless you start it with set -e, which is why many broken servers look "mostly configured".

Instance metadata

Inside an instance, a link-local address, 169.254.169.254, answers questions about the instance itself: its ID, Region, Availability Zone, private IP, tags (if enabled), user data, and, importantly, temporary security credentials. This is the instance metadata service (IMDS). It is reachable only from the instance, not from the network.

Two versions exist:

  • IMDSv1 answers a plain GET request. That is dangerous: if an application has a server-side request forgery (SSRF) bug, an attacker can make it fetch the metadata URL and read the instance's credentials. This is a well-known real-world attack path.
  • IMDSv2 is session-oriented. The caller first sends a PUT request to get a token, then sends the token in a header with every metadata request. The PUT, the custom header and a default hop limit of 1 (so the response cannot easily cross a container or proxy boundary) all defeat the common SSRF patterns.
Terminal
# read-only: IMDSv2 from inside an instance
TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 300")

curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/instance-id

New instances should require IMDSv2, and you can enforce it per instance or in a launch template with the metadata option HttpTokens=required. Some newer account settings can make it the default for every launch.

Terminal
# read-only: require IMDSv2 on an existing instance
aws ec2 modify-instance-metadata-options \
  --instance-id i-0abc123def4567890 \
  --http-tokens required \
  --http-put-response-hop-limit 1

The model below imitates the two versions, so you can see why a token requirement blocks a naive request. It is a simplified model of the protocol, not the real service.

Python IMDSv1 versus IMDSv2 (model)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Instance profiles: credentials without keys

Programs on an instance often call other AWS services, for example reading from S3. Do not copy access keys onto the server. Instead you attach an IAM role through an instance profile, a small container that links one role to an instance. The role's temporary credentials appear in the metadata service, and every AWS SDK and the AWS CLI look there automatically when no other credentials are configured. The credentials rotate on their own, so there is nothing to leak into a repository and nothing to rotate by hand.

Role design is the same as for any role, covered in IAM Users, Groups and Roles: a trust policy that lets the EC2 service assume it, and a permissions policy that grants only what the application needs. When you create a role for EC2 in the console, AWS creates the instance profile with the same name for you. With the CLI you create both yourself.

Terminal
# read-only: give an instance a role
aws iam create-instance-profile --instance-profile-name web-app
aws iam add-role-to-instance-profile \
  --instance-profile-name web-app --role-name web-app-role
aws ec2 associate-iam-instance-profile \
  --instance-id i-0abc123def4567890 \
  --iam-instance-profile Name=web-app

One caution remains: every process on the instance can reach those credentials. If you run untrusted code, or several applications with different needs, on one instance, they share the instance's role. That is one reason containers use task roles, as you will see in Containers: ECR, ECS and Fargate.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the main advantage of baking a golden AMI compared with installing everything in user data?

    A baked image already contains the software, so boot is quick and repeatable. AMIs still cost snapshot storage, and they are regional, so they must be copied to other Regions.
  2. 2. When does user data run by default on a typical Linux instance?

    Cloud-init runs user data scripts on the first boot of an instance by default. Stopping and starting the instance does not repeat them.
  3. 3. Why should you not put a database password in user data?

    User data is not a secret store. Fetch secrets at runtime from a secrets service, using the instance's role.
  4. 4. What makes IMDSv2 harder to abuse through an SSRF bug than IMDSv1?

    A typical SSRF bug can only make the application issue simple GET requests. IMDSv2 needs a PUT to obtain a token and a header on later requests, so those attacks fail.
  5. 5. How should an application on an EC2 instance get credentials to call S3?

    An instance profile delivers short-lived, automatically rotated credentials through the metadata service, so no long-lived key is stored on the server.

Summary

  • An AMI is a regional template for an instance's root volume; bake stable software into a golden image and bootstrap only what differs per instance.
  • Packer and EC2 Image Builder make image builds repeatable and reviewable.
  • User data runs once at first boot through cloud-init; it is not secret and its output goes to /var/log/cloud-init-output.log.
  • The metadata service at 169.254.169.254 describes the instance; require IMDSv2 to blunt SSRF attacks.
  • An instance profile attaches an IAM role to an instance, giving it short-lived credentials without stored keys.

Next: VPC Fundamentals.