How to get the metadata on an EC2 instance


Sometimes you might not have access to the AWS Console or just have direct access to an EC2 instance and would like to find out more information on the EC2 instance itself and where it’s hosted in AWS Cloud.

The quickest way to fetch or retrieve EC2 instance metadata from within a running EC2 instance is to log in and run the command:

Fetch metadata from IPv4:
curl -s http://169.254.169.254/latest/dynamic/instance-identity/document

Fetch metadata from IPv6:
curl -6 http://[fd00:ec2::254]/latest/dynamic/instance-identity/document

In this blog post, we’ll dive deeper into a couple of different methods that you can use to get the metadata on the EC2 instance and the steps that are required to run the commands successfully.

How to query and get the EC2 instance metadata

There are a couple of methods and tools available to find and query the metadata of the EC2 instance. However, they make use of the instance metadata that it is provided by AWS. The instance metadata is a document that stores information about the identity of the EC2 instance which can only be accessed from within the instance.

1. Use the instance metadata URL and filter manually

AWS provides a default IP address that can be used to query the EC2 instance metadata from within a running EC2 instance. The IP address is the same for all EC2 instances running in AWS Cloud and covers IPv4 and IPv6:

  • IPv4 instance metadata service address: 169.254.169.254
  • IPv6 instance metadata service address: fd00:ec2::254

You can then proceed to run a command tool like curl or wget to fetch and filter the metadata and get the information from your running instance.

The following command will return the identity of your EC2 instance with details such as instance type, region, and instance ID in JSON format.

curl -s http://169.254.169.254/latest/dynamic/instance-identity/document
{
  "accountId": "012345678901",
  "architecture": "x86_64",
  "availabilityZone": "eu-central-1c",
  "billingProducts": null,
  "devpayProductCodes": null,
  "marketplaceProductCodes": null,
  "imageId": "ami-01ff76477b9b30d59",
  "instanceId": "i-0b4ae3f67d725bbe7",
  "instanceType": "t3a.nano",
  "kernelId": null,
  "pendingTime": "2022-06-20T09:51:52Z",
  "privateIp": "172.29.40.136",
  "ramdiskId": null,
  "region": "eu-central-1",
  "version": "2017-09-30"
}

You can also filter specific items in the metadata, to know which options are available to query, run the following command:

curl -s http://169.254.169.254/latest/meta-data

This will return the following paths that you can query:

ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
events/
hostname
iam/
identity-credentials/
instance-action
instance-id
instance-life-cycle
instance-type
local-hostname
local-ipv4
mac
metrics/
network/
placement/
profile
public-hostname
public-ipv4
reservation-id
security-groups
services/
http://169.254.169.254/latest/meta-data/<metadata-path>

You can replace the metadata-path with one of the options that are displayed above to return the metadata of that specific option. For example the following query returns the security groups of this EC2 instance:

curl -s http://169.254.169.254/latest/meta-data/security-groups

test-cloudNation-skeletonVpc-SkeletonVpcNatSecurityGroup1C3FB3D3-158GQFX2P0NFA

2. Use the ec2-metadata tool from AWS to fetch the EC2 instance metadata

On the Amazon Linux AMI, there is a tool already pre-installed called ec2-metadata which can be run from the command line interface (CLI).

If you’re running another AMI on your EC2 instance, then you can download the tool from S3 and run it as a script, see the commands below:

# Download the ec2-metadata script
wget http://s3.amazonaws.com/ec2metadata/ec2-metadata

# Modify the permission to execute the bash script
chmod +x ec2-metadata

Essentially the script does the same thing as querying the metadata URL via curl or wget however, it’s just easier to navigate and display the options to request the corresponding data.

To return the identity document of the EC2 instance, run the following command:

./ec2-metadata --all

ami-id: ami-01ff76477b9b30d59
ami-launch-index: 0
ami-manifest-path: (unknown)
ancestor-ami-ids: not available
block-device-mapping:
	 ami: xvda
	 root: /dev/xvda
instance-id: i-0b4ae3f67d725bbe7
instance-type: t3a.nano
local-hostname: ip-172-29-40-136.eu-central-1.compute.internal
local-ipv4: 172.29.40.136
kernel-id: not available
placement: eu-central-1c
product-codes: not available
public-hostname: ec2-3-120-185-177.eu-central-1.compute.amazonaws.com
public-ipv4: 3.120.185.177
public-keys:
not available
ramdisk-id: not available
reservation-id: r-031e15d7b9edc1d38
security-groups: test-cloudNation-skeletonVpc-SkeletonVpcNatSecurityGroup1C3FB3D3-158GQFX2P0NFA
user-data: #!/bin/bash

Currently, the script is on version 0.1.1 and you can query the following options:

./ec2-metadata --help

ec2-metadata v0.1.1
Use to retrieve EC2 instance metadata from within a running EC2 instance.
e.g. to retrieve instance id: ec2-metadata -i
		 to retrieve ami id: ec2-metadata -a
		 to get help: ec2-metadata --help
For more information on Amazon EC2 instance meta-data, refer to the documentation at
http://docs.amazonwebservices.com/AWSEC2/2008-05-05/DeveloperGuide/AESDG-chapter-instancedata.html

Usage: ec2-metadata <option>
Options:
--all                     Show all metadata information for this host (also default).
-a/--ami-id               The AMI ID used to launch this instance
-l/--ami-launch-index     The index of this instance in the reservation (per AMI).
-m/--ami-manifest-path    The manifest path of the AMI with which the instance was launched.
-n/--ancestor-ami-ids     The AMI IDs of any instances that were rebundled to create this AMI.
-b/--block-device-mapping Defines native device names to use when exposing virtual devices.
-i/--instance-id          The ID of this instance
-t/--instance-type        The type of instance to launch. For more information, see Instance Types.
-h/--local-hostname       The local hostname of the instance.
-o/--local-ipv4           Public IP address if launched with direct addressing; private IP address if launched with public addressing.
-k/--kernel-id            The ID of the kernel launched with this instance, if applicable.
-z/--availability-zone    The availability zone in which the instance launched. Same as placement
-c/--product-codes        Product codes associated with this instance.
-p/--public-hostname      The public hostname of the instance.
-v/--public-ipv4          NATted public IP Address
-u/--public-keys          Public keys. Only available if supplied at instance launch time
-r/--ramdisk-id           The ID of the RAM disk launched with this instance, if applicable.
-e/--reservation-id       ID of the reservation.
-s/--security-groups      Names of the security groups the instance is launched in. Only available if supplied at instance launch time
-d/--user-data            User-supplied data.Only available if supplied at instance launch time.

EC2 instance metadata query examples

Here are some examples of the information that you can filter when getting the metadata from the EC2 instance.

  1. Get the instance id from within an EC2 instance

    Run the following command to get the ID of this instance:
    curl -s http://169.254.169.254/latest/meta-data/instance-id

  2. Get the public IP address from within an EC2 instance

    Run the following command to get the public IP address of this instance:
    curl -s http://169.254.169.254/latest/meta-data/public-ipv4

  3. Find the AWS region from within an EC2 instance

    Run the following command on the EC2 instance to get the AWS Region:
    curl -s http://169.254.169.254/latest/dynamic/instance-identity/document|grep region|cut -f2 -d ":"|sed 's/.$//'

  4. Get the AMI ID from within an EC2 instance

    Run the following command on the EC2 instance to get its AMI ID:
    curl -s http://169.254.169.254/latest/meta-data/ami-id

  5. Get the instance type from within the EC2 instance

    Run the following command on the EC2 instance to get its instance type:
    curl -s http://169.254.169.254/latest/meta-data/instance-type

Conclusion

In this blog post, you’ve seen how you can query the EC2 instance metadata using curl or the ec2-metadata tool that you’ve downloaded from the AWS S3 Bucket.

A couple of examples were included to get you familiarized with fetching the metadata from within the EC2 instance like getting the AWS Region, instance type, or instance ID.


Danny Steenman

Is a Principal Cloud Consultant with a background in DevOps Engineering and thorough hands-on experience in architecting and building highly scalable distributed systems on AWS Cloud using Infrastructure as Code.

A prominent leader who is passionate about sharing AWS technical expertise by writing technical articles.