EC2 Instance Metadata & User Data

Two related mechanisms let an instance configure itself and learn about itself. User data is a script you hand the instance at launch, run once on first boot. Instance metadata is a local service the running instance queries to discover its own id, region, IAM credentials, and more.

Both are central to automation: user data bootstraps the machine, and metadata is how code on the instance answers "who and where am I?" without any hardcoding. This page covers passing user data via the SDK and reading metadata through the modern IMDSv2 token flow.

Recipe

You supply user data when you launch, in the UserData field of RunInstances. A shell script begins with a shebang; a cloud-config document begins with #cloud-config. There is one important SDK difference: boto3 base64-encodes the string for you, but SDK v3 does not - you must encode it yourself.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
user_data = """#!/bin/bash
dnf install -y nginx
systemctl enable --now nginx
"""
 
resp = ec2.run_instances(
    ImageId="ami-0myimage",
    InstanceType="t3.micro",
    MinCount=1, MaxCount=1,
    UserData=user_data,   # boto3 base64-encodes this automatically
)
print(resp["Instances"][0]["InstanceId"])

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, RunInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const userData = `#!/bin/bash
dnf install -y nginx
systemctl enable --now nginx
`;
 
const resp = await ec2.send(new RunInstancesCommand({
  ImageId: "ami-0myimage",
  InstanceType: "t3.micro",
  MinCount: 1, MaxCount: 1,
  UserData: Buffer.from(userData).toString("base64"),   // v3: encode yourself
}));
console.log(resp.Instances?.[0].InstanceId);

User data runs as root during the first boot, before the instance is usable. Keep it small and idempotent; for anything substantial, have it pull a versioned script or configuration rather than embedding the whole thing.

Working Example

Once the instance is running, code on it reads facts from the Instance Metadata Service (IMDS) at the link-local address 169.254.169.254. Modern instances enforce IMDSv2, which requires a session token: you PUT to get a short-lived token, then send it as a header on each GET.

# --- Python (boto3) ---
import urllib.request
 
IMDS = "http://169.254.169.254"
 
def get_token():
    req = urllib.request.Request(
        f"{IMDS}/latest/api/token", method="PUT",
        headers={"X-aws-ec2-metadata-token-ttl-seconds": "21600"})
    return urllib.request.urlopen(req, timeout=1).read().decode()
 
def metadata(path, token):
    req = urllib.request.Request(
        f"{IMDS}/latest/meta-data/{path}",
        headers={"X-aws-ec2-metadata-token": token})
    return urllib.request.urlopen(req, timeout=1).read().decode()
 
tok = get_token()
print(metadata("instance-id", tok))
print(metadata("placement/availability-zone", tok))

// --- TypeScript (AWS SDK v3) ---
const IMDS = "http://169.254.169.254";
 
async function getToken(): Promise<string> {
  const r = await fetch(`${IMDS}/latest/api/token`, {
    method: "PUT",
    headers: { "X-aws-ec2-metadata-token-ttl-seconds": "21600" },
  });
  return r.text();
}
 
async function metadata(path: string, token: string): Promise<string> {
  const r = await fetch(`${IMDS}/latest/meta-data/${path}`, {
    headers: { "X-aws-ec2-metadata-token": token },
  });
  return r.text();
}
 
const tok = await getToken();
console.log(await metadata("instance-id", tok));
console.log(await metadata("placement/availability-zone", tok));

Note that reading metadata does not use an AWS SDK client - it is a plain HTTP call to a local address, because the code is asking the platform, not an AWS API endpoint. The SDK's own credential provider uses this same path under the hood to fetch role credentials.

Deep Dive

Useful Metadata Paths

The metadata tree exposes many facts about the instance. The ones you reach for most:

There is also a sibling ../user-data endpoint (not under meta-data) that returns the raw user data you passed, handy for a boot script that wants to re-read its own configuration.

Why IMDSv2 Exists

IMDSv1 was a simple unauthenticated GET. That made it a target: a server-side request forgery (SSRF) bug in an application could be tricked into fetching iam/security-credentials/... and leaking the instance's role credentials. IMDSv2's token requirement closes that hole, because an SSRF attacker generally cannot make the required PUT with a custom header, and the token is bound with a hop limit that stops it leaving the instance.

Enforcing IMDSv2

You should require IMDSv2, not just prefer it. Set MetadataOptions.HttpTokens to required at launch, or change it on a running instance with ModifyInstanceMetadataOptions. Setting HttpPutResponseHopLimit to 1 keeps the token from being routed beyond the instance itself.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
ec2.modify_instance_metadata_options(
    InstanceId="i-0abc123",
    HttpTokens="required",          # IMDSv2 only
    HttpPutResponseHopLimit=1,
    HttpEndpoint="enabled",
)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, ModifyInstanceMetadataOptionsCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
await ec2.send(new ModifyInstanceMetadataOptionsCommand({
  InstanceId: "i-0abc123",
  HttpTokens: "required",           // IMDSv2 only
  HttpPutResponseHopLimit: 1,
  HttpEndpoint: "enabled",
}));

Put the same MetadataOptions in your launch template so every instance and every ASG launch enforces IMDSv2 from birth, rather than fixing instances after the fact.

Gotchas

• Forgetting to base64-encode in SDK v3. boto3 encodes UserData for you; SDK v3 sends it verbatim, so an un-encoded string is rejected or misinterpreted.
• Expecting user data to re-run. By default cloud-init runs user data only on the first boot. A stop/start does not re-run it unless configured to.
• Using a plain GET against IMDSv2. When HttpTokens is required, a tokenless GET returns 401. Always do the PUT token step first.
• Leaving IMDSv1 enabled. HttpTokens: "optional" still allows the insecure v1 path. Set it to required to actually close the SSRF risk.
• Putting secrets in user data. User data is readable from within the instance and via DescribeInstanceAttribute. Fetch secrets from Secrets Manager or SSM at boot instead.
• A too-short token TTL. A one-second TTL forces a new token per call; use a longer TTL (up to six hours) and cache the token.

Alternatives

• Launch templates to store UserData and MetadataOptions once so every launch is consistent, rather than passing them on each RunInstances call.
• SSM Agent / Run Command to push configuration to running instances without baking it into boot-time user data.
• The ec2-metadata CLI or SDK credential provider when you only need role credentials - the SDK already reads them from IMDS for you, so you rarely fetch them by hand.
• Configuration management (Ansible, cloud-init modules) for complex bootstrapping that outgrows a shell script.

Use user data for lightweight first-boot setup; move heavier or ongoing configuration to SSM or a config-management tool.

FAQs

Related

• Launch Templates & Instance Configuration - storing user data and metadata options in a reusable template.
• Spot Instances & Interruption Handling - the interruption notice served over the same IMDSv2 flow.
• EC2's Instance Lifecycle Model - when in the boot sequence user data runs.
• EC2 via SDK Best Practices - enforcing IMDSv2 and avoiding secrets in user data as habits.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).