# 获取实例元数据

## 实例元数据概述

实例元数据提供有关正在运行实例的信息，例如网络配置、实例标识符以及其他运行时属性。元数据服务可通过实例内部的链路本地 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>