# 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.console.zenlayer.com/welcome/elastic-compute/get-started/manage-instances/get-instance-metadata.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.