Cloud-init tips and tricks for EC2 instances

Working extensively with RunsOn, I’ve spent considerable time with cloud-init, the industry-standard tool that automatically configures cloud instances on startup. Present on Ubuntu distributions on AWS, cloud-init fetches metadata from the underlying cloud provider and applies initial configurations. Here are some useful commands and techniques I’ve discovered for troubleshooting and inspecting EC2 instances.

Querying user-data content

When debugging instance startup issues, you often need to check what user-data was passed to your instance. Here are three ways to retrieve it:

1. Using cloud-init query (recommended)

The most reliable method is using the built-in cloud-init query command:

# View user data
sudo cloud-init query userdata

# View all instance data including user data
sudo cloud-init query --all

2. Reading from the filesystem

Cloud-init stores user-data locally after fetching it:

# User data is stored in
sudo cat /var/lib/cloud/instance/user-data.txt

3. Using the instance metadata service (IMDS)

You can also query the EC2 metadata service directly:

# IMDSv2 (recommended)
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

# IMDSv1 (legacy)
curl http://169.254.169.254/latest/user-data

Accessing all EC2 metadata without additional API calls

Here’s a powerful tip: cloud-init automatically fetches all relevant data from the EC2 metadata API at startup and caches it locally. Instead of making multiple API calls, you can read everything from a single JSON file:

sudo cat /run/cloud-init/instance-data.json

This file contains a wealth of information about your instance. Let’s explore some useful queries:

Instance identity document

Get comprehensive instance details:

sudo cat /run/cloud-init/instance-data.json | jq '.ds.dynamic["instance-identity"].document'

Output:

{
  "accountId": "135269210855",
  "architecture": "x86_64",
  "availabilityZone": "us-east-1b",
  "billingProducts": null,
  "devpayProductCodes": null,
  "imageId": "ami-0db4eca8382e7fc27",
  "instanceId": "i-00a3d21a80694c44b",
  "instanceType": "m7a.large",
  "kernelId": null,
  "marketplaceProductCodes": null,
  "pendingTime": "2025-04-25T12:00:18Z",
  "privateIp": "10.0.1.93",
  "ramdiskId": null,
  "region": "us-east-1",
  "version": "2017-09-30"
}

Complete metadata

Access all EC2 metadata fields:

sudo cat /run/cloud-init/instance-data.json | jq '.ds["meta-data"]'

This reveals extensive information including:

• Network configuration (VPC, subnet, security groups)
• IAM instance profile details
• Block device mappings
• Hostname and IP addresses
• Maintenance events

Extracting specific values

Need just the public IP? Or the instance type? Use jq to extract specific fields:

# Get public IPv4 address
sudo jq -r '.ds["meta-data"]["public-ipv4"]' /run/cloud-init/instance-data.json
# Output: 3.93.38.69

# Get instance type
sudo jq -r '.ds["meta-data"]["instance-type"]' /run/cloud-init/instance-data.json
# Output: m7a.large

# Get availability zone
sudo jq -r '.ds["meta-data"]["placement"]["availability-zone"]' /run/cloud-init/instance-data.json
# Output: us-east-1b

# Get VPC ID
sudo jq -r '.ds["meta-data"]["network"]["interfaces"]["macs"][.ds["meta-data"]["mac"]]["vpc-id"]' /run/cloud-init/instance-data.json
# Output: vpc-03460bc2910d2b4e6

Why this matters

Understanding cloud-init and how to query instance metadata is crucial for:

1. Troubleshooting: When instances fail to start correctly, checking user-data and metadata helps identify configuration issues
2. Automation: Scripts can use this cached data instead of making API calls, reducing latency and API throttling
3. Security: Accessing cached data avoids exposing credentials to the metadata service repeatedly
4. Performance: Reading from local files is faster than HTTP requests to the metadata service

Conclusion

Cloud-init does more than just run your user-data script. It provides a comprehensive interface to instance metadata that’s invaluable for debugging and automation. Next time you’re troubleshooting an EC2 instance or writing automation scripts, remember these commands - they’ll save you time and API calls.