# Get Instance Metadata

## Instance Metadata Overview

Instance metadata provides information about a running instance, such as network configuration, instance identifiers, and other runtime attributes. The metadata service is accessible from within the instance through a link-local IP address.

The metadata entries are organized in a hierarchical structure similar to a directory tree. Each path represents either a metadata item or a subdirectory containing additional metadata entries.

When a metadata directory is requested, the service returns the list of all subdirectories or metadata items available under that path.

### 1. Common Use Cases

Instance metadata is commonly used by automation tools, initialization scripts, and cloud-native applications to retrieve instance-specific configuration at runtime.

Typical use cases include:

* **Initialization scripts** – Retrieve instance information such as instance ID, region, or IP during startup.

  ```http
  INSTANCE_ID=$(curl -s http://169.254.169.254/latest/meta-data/instance-id)
  ```
* **Network configuration discovery** – Identify network interfaces, IP addresses, or subnet information on instances with multiple network interfaces.
* **Temporary credentials retrieval** – Obtain temporary API credentials provided by the metadata service instead of storing long-term access keys.
* **Cloud initialization** – Initialization tools (such as `cloud-init`) can retrieve `user-data` and `meta-data` to configure the instance during boot.

### 2. Metadata Service Endpoint

The instance metadata service is available from within the instance at the following base URL:

```http
http://169.254.169.254/latest/meta-data/
```

Applications or scripts running inside the instance can query specific metadata entries by sending HTTP requests to this endpoint.

### 3. Example: Query Network Interface Metadata

The following example retrieves the list of MAC address directories for all network interfaces attached to the instance:

```http
curl -sf http://169.254.169.254/latest/meta-data/network/interfaces/macs/
```

Example response:

```http
52:54:00:8d:8c:3a/
52:54:00:3a:96:a8/
```

Next, you can continue to access information about a specific MAC, for example:

```http
network/interfaces/macs/52:54:00:8d:8c:3a/private-ipv4s
```

You can get the IP of this network interface.

## Metadata Details

Instance metadata is organized in a hierarchical structure similar to a directory tree and can be accessed level by level. When a metadata directory is queried, the service returns the list of subdirectories or metadata entries under that path.

For example, querying the `network/interfaces/macs/` directory returns the MAC address directories for all network interfaces attached to the instance.

### Basic Network Configuration

<table><thead><tr><th width="284.2274169921875">Metadata</th><th width="342.94970703125">Description</th><th width="402.4105224609375">Example</th></tr></thead><tbody><tr><td><code>network/interfaces/macs/</code></td><td>AC addresses of all network interfaces on the instance.</td><td><code>52:54:00:8d:XX:XX/</code><br><code>52:54:00:3a:XX:XX/</code></td></tr><tr><td><code>/network/interfaces/macs/{mac addr}/</code></td><td>Metadata directories for the specified network interface (<code>{mac addr}</code>), where <code>{mac addr}</code> is the MAC address of the interface.</td><td><code>ipv6-gateway</code><br><code>network-interface-id</code><br><code>primary-ip-address</code><br><code>public-ipv4</code><br><code>public-ipv4s</code><br><code>primary-ipv6-address</code><br><code>ipv6-prefix</code><br><code>gateway</code><br><code>subnet-cidr-block</code><br><code>subnet-ipv6-cidr-block</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/network-interface-id</code></td><td>ID of the specified network interface on the instance.</td><td><code>161709631348749****</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/primary-ip-address</code></td><td>Primary private IPv4 address of the specified network interface.</td><td><code>10.0.0.7</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/primary-ipv6-address</code></td><td>Primary IPv6 address of the specified network interface.</td><td><code>XXXX:XXXX:0:d6c8:0:1::2</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/private-ipv4s</code></td><td>Secondary private IPv4 addresses of the specified network interface (excluding the primary private IPv4 address).</td><td><code>["10.0.0.10"]</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/public-ipv4</code></td><td>Default outbound public IPv4 address of the specified network interface.</td><td><code>XX.XX.206.251</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/public-ipv4s</code></td><td>List of public IPv4 addresses associated with the specified network interface.</td><td><code>["XX.XX.206.251","XX.XX.214.234"]</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/ipv6-prefix</code></td><td>IPv6 CIDR of the specified network interface.</td><td><code>XXXX:XXXX:0:d6c8:0:1::/96</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/gateway</code></td><td>IPv4 gateway address of the specified network interface.</td><td><code>10.0.0.1</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/ipv6-gateway</code></td><td>IPv6 gateway address of the specified network interface.</td><td><code>fe80::1</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/subnet-cidr-block</code></td><td>List of IPv4 CIDRs of the subnet to which the specified network interface belongs.</td><td><code>10.0.0.0/24</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/subnet-ipv6-cidr-block</code></td><td>List of IPv6 CIDRs of the subnet to which the specified network interface belongs.</td><td><code>XXXX:XXXX:0:d6c8::/64</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/subnet-id</code></td><td>Subnet ID of the subnet to which the specified network interface belongs.</td><td><code>161709631348749****</code></td></tr></tbody></table>