How-to Get [Query] AWS EC2 Instance Metadata

In this tutorial we will learn how to get EC2 Instance Metadata from an AWS EC2 instance. We will get the metadata using ec2-metadata and ec2 metadata. This is not typo. The tools name is really similar but one of them using dash on its name.

Introduction

In this tutorial, we will learn how to get EC2 Instance Metadata from an AWS EC2 instance. We will get the metadata using ec2-metadata and ec2 metadata. This is not a typo. The tool’s name is really similar but one of them using dash on its name.

Using EC2 Instance Metadata Query Tool (ec2-metadata)

Install EC2 Instance Metadata Query Tool

First of all let’s install ec2-metadata tool.

Download the script using the command below.

$ wget http:<span class="hljs-regexp">//</span>s3.amazonaws.com<span class="hljs-regexp">/ec2metadata/</span>ec2-metadata

Move the script to the /usr/local/bin/ directory.

$ sudo mv ec2-metadata /usr/<span class="hljs-keyword">local</span>/bin

Change the permission of the script so we can use the script.

$ chmod u+x <span class="hljs-regexp">/usr/</span>local<span class="hljs-regexp">/bin/</span>ec2-metadata

Using EC2 Instance Metadata Query Tool Outside EC2 Instance

If you run ec2-metadata outside EC2 instance you will get the error message below.

[ERROR] Command <span class="hljs-keyword">not</span> valid outside EC2 <span class="hljs-keyword">instance</span>. Please run <span class="hljs-keyword">this</span> command <span class="hljs-keyword">within</span> a running EC2 <span class="hljs-keyword">instance</span>.

When we run ec2-metadata from an EC2 instance without any option, the help page will be printed.

$ ec2-metadata v0.1.1
Use to retrieve EC2<span class="hljs-built_in"> instance </span>metadata from within a running EC2 instance. 
e.g. to retrieve<span class="hljs-built_in"> instance </span>id: ec2-metadata -i
         to retrieve ami id: ec2-metadata -a
         to get help: ec2-metadata --help
For more information on Amazon EC2<span class="hljs-built_in"> instance </span>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<span class="hljs-built_in"> instance
</span>-l/--ami-launch-index     The index of this<span class="hljs-built_in"> instance </span>in the reservation (per AMI).
-m/--ami-manifest-path    The manifest path of the AMI with which the<span class="hljs-built_in"> instance </span>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<span class="hljs-built_in"> instance
</span>-t/--instance-type        The type of<span class="hljs-built_in"> instance </span>to launch. For more information, see Instance Types.
-h/--local-hostname       The local hostname of the instance.
-o/--local-ipv4           Public IP address<span class="hljs-built_in"> if </span>launched with direct addressing;<span class="hljs-keyword"> private</span> IP address<span class="hljs-built_in"> if </span>launched with<span class="hljs-keyword"> public</span> addressing.
-k/--kernel-id            The ID of the kernel launched with this instance,<span class="hljs-built_in"> if </span>applicable.
-z/--availability-zone    The availability zone in which the<span class="hljs-built_in"> instance </span>launched. Same as placement
-c/--product-codes        Product codes associated with this instance.
-p/--public-hostname      The<span class="hljs-keyword"> public</span> hostname of the instance.
-v/--public-ipv4          NATted<span class="hljs-keyword"> public</span> IP Address
-u/--public-keys          Public keys. Only available<span class="hljs-built_in"> if </span>supplied at<span class="hljs-built_in"> instance </span>launch time
-r/--ramdisk-id           The ID of the RAM disk launched with this instance,<span class="hljs-built_in"> if </span>applicable.
-e/--reservation-id       ID of the reservation.
-s/--security-groups      Names of the security groups the<span class="hljs-built_in"> instance </span>is launched in. Only available<span class="hljs-built_in"> if </span>supplied at<span class="hljs-built_in"> instance </span>launch time
-d/--user-data            User-supplied data.Only available<span class="hljs-built_in"> if </span>supplied at<span class="hljs-built_in"> instance </span>launch time.

Get The AMI ID used to launch this instance using ec2-metadata

$ ec2-metadata -a
ami-<span class="hljs-attribute">id:</span><span class="hljs-string"> ami</span><span class="hljs-number">-002</span>fe7e709bf81e3a

Get The index of this instance in the reservation (per AMI).

$ ec2-metadata -l
ami-<span class="hljs-built_in">launch</span>-index: <span class="hljs-number">0</span>

Get The manifest path of the AMI with which the instance was launched.

$ ec2-metadata -m
ami-manifest-<span class="hljs-built_in">path</span>: (unknown)

Get The AMI IDs of any instances that were rebundled to create this AMI.

<span class="hljs-variable">$ </span>ec2-metadata -n
ancestor-ami-<span class="hljs-symbol">ids:</span> <span class="hljs-keyword">not</span> available

Get Defines native device names to use when exposing virtual devices.

$ ec2-metadata -b
block-device-mapping: 
<span class="hljs-symbol">     ami:</span> <span class="hljs-meta-keyword">/dev/</span>sda1
<span class="hljs-symbol">     root:</span> <span class="hljs-meta-keyword">/dev/</span>sda1

Get EC2 Instance ID using ec2-metadata

$ ec2-metadata -<span class="hljs-built_in">i</span>
instance-id: <span class="hljs-built_in">i</span><span class="hljs-number">-043</span>c348f4bc24b818

Get Instance Type using ec2-metadata

$ ec2-metadata -t
<span class="hljs-title">instance</span>-<span class="hljs-keyword">type</span>: t2.nano

Get Private / Local Hostname of EC2 Instance

$ ec2-metadata -h
local-hostname: ip<span class="hljs-string">-172</span><span class="hljs-string">-31</span><span class="hljs-string">-16</span><span class="hljs-string">-47</span>.ap-southeast<span class="hljs-string">-1</span>.compute.internal

Get Private / Local IP of EC2 Instance

$ ec2-metadata -o
local-ipv4: <span class="hljs-number">172.31</span><span class="hljs-meta">.16</span><span class="hljs-meta">.47</span>

Get Kernel ID of the instance

$ ec2-metadata -k
kernel-<span class="hljs-built_in">id</span>: <span class="hljs-keyword">not</span> available

Get Availability Zone Of the EC2 Instance

$ ec2-metadata -<span class="hljs-built_in">z</span>
<span class="hljs-symbol">placement:</span> ap-southeast<span class="hljs-number">-1</span>a

Get Product Codes of the EC2 Instance

<span class="hljs-variable">$ </span>ec2-metadata -c
product-<span class="hljs-symbol">codes:</span> <span class="hljs-keyword">not</span> available

Get Public Hostname of the EC2 Instance

$ ec2-metadata -<span class="hljs-selector-tag">p</span>
public-hostname: ec2-<span class="hljs-number">13</span>-<span class="hljs-number">229</span>-<span class="hljs-number">225</span>-<span class="hljs-number">234</span><span class="hljs-selector-class">.ap-southeast-1</span><span class="hljs-selector-class">.compute</span><span class="hljs-selector-class">.amazonaws</span><span class="hljs-selector-class">.com</span>

Get Public IP of the EC2 Instance

$ ec2-metadata -v
<span class="hljs-meta">public</span>-ipv4: <span class="hljs-number">13.229</span><span class="hljs-meta">.225</span><span class="hljs-meta">.234</span>

Get Public Key of the EC2 Instance

$ ec2-metadata -u
<span class="hljs-keyword">public</span>-<span class="hljs-string">keys:</span> 
<span class="hljs-string">keyname:</span>testing
<span class="hljs-string">index:</span><span class="hljs-number">0</span>
<span class="hljs-string">format:</span>openssh-key
<span class="hljs-string">key:</span>(begins from next line)
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCV03OY7jrv<span class="hljs-regexp">/6rQyPL3ffsQcw7ENGixKFUpxaCXjIV1pD23rD9lb+mgX7OCBUsO4eXUUIPdr1ygh3o3AosM2CUv/</span>pUexb4L2Mg2NkNyHQdfcGPQod0OFiw<span class="hljs-regexp">/bOd02FOD/</span>oBxXQIl5UOuiXhfxEwZ5P3Hn1XaTwIMnT37e3gyfhif4XW9WKemCwCmSkPMvhEDYa0ymZElXvQ8YfkGWANktHj52de0b68D0Iwg6IVJbv9rqRcHVXk2Wp9V2X0cMLs8v9UYd4N0GmDB8FBC<span class="hljs-regexp">/ZAttWi6ESF0EKWv4jy/</span><span class="hljs-number">94</span>EDP1nw9jD8tZnWiGV69vk/wKAoYI3BpZ6tAOTd82NdtFCWngrt testing

Get Ramdisk ID of The EC2 Instance

$ ec2-metadata -r
ramdisk-<span class="hljs-built_in">id</span>: <span class="hljs-keyword">not</span> available

Get Reservation ID using ec2-metadata

$ ec2-metadata <span class="hljs-_">-e</span>
reservation-id: r-0589<span class="hljs-built_in">fc</span>9d835e37094

Get Security Groups

$ ec2-metadata -<span class="hljs-built_in">s</span>
security-groups: <span class="hljs-keyword">test</span>-<span class="hljs-keyword">cluster</span>

Get User-supplied data. Only available if supplied at instance launch time.

<span class="hljs-variable">$ </span>ec2-metadata -d
user-<span class="hljs-symbol">data:</span> <span class="hljs-keyword">not</span> available

Get all EC2 Metadata Using ec2-metadata

$ ec2-metadata --all

ami-<span class="hljs-string">id:</span> ami<span class="hljs-number">-002</span>fe7e709bf81e3a
ami-launch-<span class="hljs-string">index:</span> <span class="hljs-number">0</span>
ami-manifest-<span class="hljs-string">path:</span> (unknown)
ancestor-ami-<span class="hljs-string">ids:</span> not available
block-device-<span class="hljs-string">mapping:</span> 
<span class="hljs-symbol">     ami:</span> <span class="hljs-regexp">/dev/</span>sda1
<span class="hljs-symbol">     root:</span> <span class="hljs-regexp">/dev/</span>sda1
instance-<span class="hljs-string">id:</span> i<span class="hljs-number">-043</span>c348f4bc24b818
instance-<span class="hljs-string">type:</span> t2.nano
local-<span class="hljs-string">hostname:</span> ip<span class="hljs-number">-172</span><span class="hljs-number">-31</span><span class="hljs-number">-16</span><span class="hljs-number">-47.</span>ap-southeast<span class="hljs-number">-1.</span>compute.internal
local-<span class="hljs-string">ipv4:</span> <span class="hljs-number">172.31</span><span class="hljs-number">.16</span><span class="hljs-number">.47</span>
kernel-<span class="hljs-string">id:</span> not available
<span class="hljs-string">placement:</span> ap-southeast<span class="hljs-number">-1</span>a
product-<span class="hljs-string">codes:</span> not available
<span class="hljs-keyword">public</span>-<span class="hljs-string">hostname:</span> ec2<span class="hljs-number">-13</span><span class="hljs-number">-229</span><span class="hljs-number">-225</span><span class="hljs-number">-234.</span>ap-southeast<span class="hljs-number">-1.</span>compute.amazonaws.com
<span class="hljs-keyword">public</span>-<span class="hljs-string">ipv4:</span> <span class="hljs-number">13.229</span><span class="hljs-number">.225</span><span class="hljs-number">.234</span>
<span class="hljs-keyword">public</span>-<span class="hljs-string">keys:</span> 
<span class="hljs-string">keyname:</span>testing
<span class="hljs-string">index:</span><span class="hljs-number">0</span>
<span class="hljs-string">format:</span>openssh-key
<span class="hljs-string">key:</span>(begins from next line)
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCV03OY7jrv<span class="hljs-regexp">/6rQyPL3ffsQcw7ENGixKFUpxaCXjIV1pD23rD9lb+mgX7OCBUsO4eXUUIPdr1ygh3o3AosM2CUv/</span>pUexb4L2Mg2NkNyHQdfcGPQod0OFiw<span class="hljs-regexp">/bOd02FOD/</span>oBxXQIl5UOuiXhfxEwZ5P3Hn1XaTwIMnT37e3gyfhif4XW9WKemCwCmSkPMvhEDYa0ymZElXvQ8YfkGWANktHj52de0b68D0Iwg6IVJbv9rqRcHVXk2Wp9V2X0cMLs8v9UYd4N0GmDB8FBC<span class="hljs-regexp">/ZAttWi6ESF0EKWv4jy/</span><span class="hljs-number">94</span>EDP1nw9jD8tZnWiGV69vk/wKAoYI3BpZ6tAOTd82NdtFCWngrt testing
ramdisk-<span class="hljs-string">id:</span> not available
reservation-<span class="hljs-string">id:</span> r<span class="hljs-number">-0589</span>fc9d835e37094
security-<span class="hljs-string">groups:</span> test-cluster
user-<span class="hljs-string">data:</span> not available

Using ec2metadata

ec2metadata (without dash) should already installed on Ubuntu / Amazon Linux based instance.

To test whether this command already exist or not we can use the --help option.

$ ec2metadata --help
Syntax: /usr/bin/ec2metadata [options]

Query<span class="hljs-built_in"> and </span>display EC2 metadata.

If no options are provided, all options will be displayed

Options:
    -h --help               show this help

    --kernel-id             display the kernel id
    --ramdisk-id            display the ramdisk id
    --reservation-id        display the reservation id

    --ami-id                display the ami id
    --ami-launch-index      display the ami launch index
    --ami-manifest-path     display the ami manifest path
    --ancestor-ami-ids      display the ami ancestor id
    --product-codes         display the ami associated product codes
    --availability-zone     display the ami placement zone

    --instance-id           display the<span class="hljs-built_in"> instance </span>id
    --instance-type         display the<span class="hljs-built_in"> instance </span>type

    --local-hostname        display the local hostname
    --public-hostname       display the<span class="hljs-keyword"> public</span> hostname

    --local-ipv4            display the local ipv4 ip address
    --public-ipv4           display the<span class="hljs-keyword"> public</span> ipv4 ip address

    --block-device-mapping  display the block device id
    --security-groups       display the security groups

    --mac                   display the<span class="hljs-built_in"> instance </span>mac address
    --profile               display the<span class="hljs-built_in"> instance </span>profile
    --instance-action       display the<span class="hljs-built_in"> instance-action
</span>
    --public-keys           display the openssh<span class="hljs-keyword"> public</span> keys
    --user-data             display the user data (not actually metadata)

    -u | --url URL          use URL (default: http://169.254.169.254/2009-04-04)

The the next sections we will learn to use each option of ec2metadata command to see the output sample.

Get Kernel ID of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--kernel-id</span>
unavailable

Get Ramdisk ID of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--ramdisk-id</span>
unavailable

Get Reservation ID of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--reservation-id</span>
r-<span class="hljs-number">0589</span>fc9d835e37094

Get AMI ID of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--ami-id</span>
ami-<span class="hljs-number">002</span>fe7e709bf81e3a

Get AMI Launch Index of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--ami-launch-index</span>
<span class="hljs-number">0</span>

Get AMI Manifest Path of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--ami-manifest-path</span>
(unknown)

Get Ancestor AMI ID of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--ancestor-ami-ids</span>
unavailable

Get Product Codes of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--product-codes</span>
unavailable

Get Availability Zone Info of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--availability-zone</span>
ap-southeast<span class="hljs-number">-1</span><span class="hljs-keyword">a</span>

Get Instance ID of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--instance-id</span>
i-<span class="hljs-number">043</span>c348f4bc24b818

Get Instance Type of an EC2 Instance

$ ec2metadata --instance-<span class="hljs-class"><span class="hljs-keyword">type</span></span>
t2.nano

Get Local Hostname of an EC2 Instance

$ ec2metadata --local-hostname
ip<span class="hljs-number">-172</span><span class="hljs-number">-31</span><span class="hljs-number">-16</span><span class="hljs-number">-47.</span>ap-southeast<span class="hljs-number">-1.</span>compute.internal

Get Public Hostname of an EC2 Instance

$ ec2metadata --public-hostname
ec2<span class="hljs-number">-13</span><span class="hljs-number">-229</span><span class="hljs-number">-225</span><span class="hljs-number">-234.</span>ap-southeast<span class="hljs-number">-1.</span>compute.amazonaws.com

Get Private IPv4 / Local IPv4 of an EC2 Instance

$ ec2metadata --local-ipv4
<span class="hljs-number">172.31</span><span class="hljs-number">.16</span><span class="hljs-number">.47</span>

Get Public IPv4 of an EC2 Instance

$ ec2metadata --public-ipv4
<span class="hljs-number">13.229</span><span class="hljs-number">.225</span><span class="hljs-number">.234</span>

Get Block Device Mapping Info of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--block-device-mapping</span>
ami
root

Get Security Groups of an EC2 Instance

$ ec2metadata --security-groups
<span class="hljs-keyword">test</span>-<span class="hljs-keyword">cluster</span>

Get Mac Address of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--mac</span>
unavailable

Get Instance Profile of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--profile</span>
<span class="hljs-keyword">default</span>-hvm

Get Instance Action of an EC2 Instance

$ ec2metadata --instance-<span class="hljs-keyword">action</span>
<span class="hljs-keyword">none</span>

Get Public Keys of an EC2 Instance

$ ec2metadata --public-keys
['ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCV03OY7jrv/6rQyPL3ffsQcw7ENGixKFUpxaCXjIV1pD23rD9lb+mgX7OCBUsO4eXUUIPdr1ygh3o3AosM2CUv/pUexb4L2Mg2NkNyHQdfcGPQod0OFiw/bOd02FOD/oBxXQIl5UOuiXhfxEwZ5P3Hn1XaTwIMnT37e3gyfhif4XW9WKemCwCmSkPMvhEDYa0ymZElXvQ8YfkGWANktHj52de0b68D0Iwg6IVJbv9rqRcHVXk2Wp9V2X0cMLs8v9UYd4N0GmDB8FBC/ZAttWi6ESF0EKWv4jy/94EDP1nw9jD8tZnWiGV69vk/wKAoYI3BpZ6tAOTd82NdtFCWngrt testing']

Get User Data of an EC2 Instance

$ ec2metadata <span class="hljs-comment">--user-data</span>

Which Package Providing ec2metadata In Ubuntu?

If you’re wondering which package providing the ec2metadata tool in Ubuntu, you can use the command below.

$ dpkg -S <span class="hljs-regexp">/usr/</span>bin<span class="hljs-regexp">/ec2metadata</span>

cloud-guest-utils: /usr/bin/ec2metadata

To see the cloud-guest-utils package installed we can use the command below

$ dpkg -l | grep cloud-guest-utils
ii  cloud-guest-utils              <span class="hljs-number">0.31</span><span class="hljs-number">-7</span>-gd99b2d76<span class="hljs-number">-0</span>ubuntu1         all          cloud guest utilities

We can also see the list of files in the cloud-guest-utils package using the command below.

$ dpkg -L cloud-guest-utils
/.
/usr
<span class="hljs-meta-keyword">/usr/</span>bin
<span class="hljs-meta-keyword">/usr/</span>bin/ec2metadata
<span class="hljs-meta-keyword">/usr/</span>bin/growpart
<span class="hljs-meta-keyword">/usr/</span>bin/vcs-run
<span class="hljs-meta-keyword">/usr/</span>share
<span class="hljs-meta-keyword">/usr/</span>share/doc
<span class="hljs-meta-keyword">/usr/</span>share<span class="hljs-meta-keyword">/doc/</span>cloud-guest-utils
<span class="hljs-meta-keyword">/usr/</span>share<span class="hljs-meta-keyword">/doc/</span>cloud-guest-utils/changelog.Debian.gz
<span class="hljs-meta-keyword">/usr/</span>share<span class="hljs-meta-keyword">/doc/</span>cloud-guest-utils/copyright
<span class="hljs-meta-keyword">/usr/</span>share/man
<span class="hljs-meta-keyword">/usr/</span>share<span class="hljs-meta-keyword">/man/</span>man1
<span class="hljs-meta-keyword">/usr/</span>share<span class="hljs-meta-keyword">/man/</span>man1/growpart<span class="hljs-number">.1</span>.gz

References