# 获取实例元数据

## 实例元数据概述

实例元数据提供有关正在运行实例的信息，例如网络配置、实例标识符以及其他运行时属性。元数据服务可通过实例内部的链路本地 IP 地址访问。

元数据条目以类似目录树的层级结构进行组织。每个路径表示一个元数据项，或包含其他元数据条目的子目录。

当请求某个元数据目录时，服务会返回该路径下所有可用的子目录或元数据项列表。

### 1. 常见使用场景

实例元数据通常被自动化工具、初始化脚本以及云原生应用在运行时用于获取实例特定的配置。

典型使用场景包括：

* **初始化脚本** – 在启动期间获取实例信息，例如实例 ID、区域或 IP。

  ```http
  INSTANCE_ID=$(curl -s http://169.254.169.254/latest/meta-data/instance-id)
  ```
* **网络配置发现** – 在具有多个网络接口的实例上识别网络接口、IP 地址或子网信息。
* **临时凭证获取** – 通过元数据服务获取临时 API 凭证，而不是存储长期访问密钥。
* **云初始化** – 初始化工具（例如 `cloud-init`）可以获取 `user-data` 和 `meta-data`，在启动过程中配置实例。

### 2. 元数据服务端点

实例元数据服务可在实例内部通过以下基础 URL 访问：

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

在实例内部运行的应用程序或脚本可以通过向该端点发送 HTTP 请求来查询特定的元数据条目。

### 3. 示例：查询网络接口元数据

以下示例获取附加到实例的所有网络接口的 MAC 地址目录列表：

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

示例返回：

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

接下来，可以继续访问某个特定 MAC 地址的信息，例如：

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

即可获取该网络接口的 IP。

## 元数据详情

实例元数据以类似目录树的层级结构组织，并且可以逐级访问。当查询某个元数据目录时，服务会返回该路径下的子目录或元数据条目列表。

例如，查询 `network/interfaces/macs/` 目录会返回附加到实例的所有网络接口的 MAC 地址目录。

### 基础网络配置

<table><thead><tr><th width="284.2274169921875">元数据</th><th width="342.94970703125">说明</th><th width="402.4105224609375">示例</th></tr></thead><tbody><tr><td><code>network/interfaces/macs/</code></td><td>实例上所有网络接口的 MAC 地址。</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>指定网络接口（<code>{mac addr}</code>）的元数据目录，其中 <code>{mac addr}</code> 为该接口的 MAC 地址。</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。</td><td><code>161709631348749****</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/primary-ip-address</code></td><td>指定网络接口的主内网 IPv4 地址。</td><td><code>10.0.0.7</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/primary-ipv6-address</code></td><td>指定网络接口的主 IPv6 地址。</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>指定网络接口的辅内网 IPv4 地址（不包含主内网 IPv4 地址）。</td><td><code>["10.0.0.10"]</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/public-ipv4</code></td><td>指定网络接口的默认出站公网 IPv4 地址。</td><td><code>XX.XX.206.251</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/public-ipv4s</code></td><td>与指定网络接口关联的公网 IPv4 地址列表。</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。</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 网关地址。</td><td><code>10.0.0.1</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/ipv6-gateway</code></td><td>指定网络接口的 IPv6 网关地址。</td><td><code>fe80::1</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/subnet-cidr-block</code></td><td>指定网络接口所属子网的 IPv4 CIDR 列表。</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>指定网络接口所属子网的 IPv6 CIDR 列表。</td><td><code>XXXX:XXXX:0:d6c8::/64</code></td></tr><tr><td><code>network/interfaces/macs/{mac addr}/subnet-id</code></td><td>指定网络接口所属子网的子网 ID。</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/cn/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.