访问 EC2 实例的实例元数据 - Amazon Elastic Compute Cloud
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

访问 EC2 实例的实例元数据

您可以从实例内或者从 EC2 控制台、API、SDK 或 Amazon CLI 访问 EC2 实例元数据。要从控制台或命令行获取实例的当前实例元数据设置,请参阅查询现有实例的实例元数据选项

您还可以修改具有 EBS 根卷的实例的用户数据。该实例必须处于已停止状态。有关控制台说明,请参阅 更新实例用户数据。有关使用 Amazon CLI 的 Linux 示例,请参阅 modify-instance-attribute。有关使用 Tools for Windows PowerShell 的 Windows 示例,请参阅 用户数据和 Tools for Windows PowerShell

注意

您无需为用于检索实例元数据和用户数据的 HTTP 请求付费。

实例元数据访问注意事项

为避免实例元数据检索出现问题,请考虑以下事项。

命令格式

根据使用的是实例元数据服务版本 1(IMDSv1)还是实例元数据服务版本 2 IMDSv2,命令格式会有所不同。默认情况下,您可以使用两个版本的实例元数据服务。要要求使用 IMDSv2,请参阅使用实例元数据服务访问实例元数据

(IMDSv2)如果需要 IMDSv2,则 IMDSv1 不起作用。

要检查是否需要 IMDSv2,请选择实例以查看其详细信息。IMDSv2 的值要么是必选(必须使用 IMDSv2),要么是可选(你可以使用 IMDSv2 或 IMDSv1)。

(IMDSv2)使用 /latest/api/token 来检索令牌

PUT 请求发放到任何版本特定的路径(例如 /2021-03-23/api/token)将导致元数据服务返回 403 禁止错误。这是预期行为。

IPv6 支持

如果要使用 IPv6 地址检索实例元数据,请确保启用并使用 [fd00:ec2::254] 而不是 IPv4 地址。该实例必须是在支持 IPv6 的子网中启动的基于 Nitro 的实例

(Windows)使用 Windows Sysprep 创建自定义 AMI

为了确保在您从自定义 Windows AMI 启动实例时 IMDS 能够正常工作,AMI 必须是使用 Windows Sysprep 创建的标准化映像。否则,IMDS 将无法正常运行。有关更多信息,请参阅 使用 Windows Sysprep 创建 Amazon EC2 AMI

在容器环境中,将跃点限制设置为 2

默认情况下,Amazon开发工具包使用 IMDSv2 调用。如果 IMDSv2 调用没有收到任何响应,SDK 将重新调用,如果仍然不成功,则使用 IMDSv1。这可能会导致延迟,尤其是在容器环境中。在容器环境中,如果跃点限制为 1,则 IMDSv2 响应不会返回,因为转到容器被视为额外的网络跃点。为避免出现回退到 IMDSv1 的流程以及由此产生的延迟,在容器环境中,我们建议您将跃数限制设置为 2。有关更多信息,请参阅 配置实例元数据服务选项

元数据版本

为避免每次 Amazon EC2 发布新的实例元数据构建时都必须更新您的代码,我们建议您在路径中使用 latest,而不是版本号。

每秒数据包(PPS)限制

对于使用本地链路地址的服务,每秒数据包数(PPS)限制为 1024 个。此限制是 Route 53 Resolver DNS 查询、实例元数据服务(IMDS)请求、Amazon Time Service 网络时间协议(NTP)请求和 Windows 许可服务(适用于基于 Microsoft Windows 的实例)请求的总和。

用户数据访问的其他注意事项
  • 用户数据会被视为非透明数据;您指定什么数据就会在检索时得到什么数据。由实例来解释用户数据并对其进行操作。

  • 用户数据必须采用 base64 编码。根据您使用的工具或 SDK,可能会为您执行 base64 编码。例如:

    • Amazon EC2 控制台可以为您执行 base64 编码或接受 base64 编码的输入。

    • 默认情况下,Amazon CLI 版本 2 会为您执行二进制参数的 base64 编码。Amazon CLI 版本 1 会为您执行 --user-data 参数的 base64 编码。

    • Amazon SDK for Python (Boto3) 会为您执行 UserData 参数的 base64 编码。

  • 用户数据在进行 base64 编码之前的原始格式的大小限制为 16 KB。长度为 n 的字符串在进行 base64 编码之后的大小为 ceil(n/3)*4。

  • 在检索用户数据时,必须对其进行 base64 解码。如果您使用实例元数据或控制台检索数据,则会自动对数据进行解码。

  • 如果您停止实例,修改用户数据,然后启动实例,则在启动实例时,不会自动运行更新后的用户数据。对于 Windows 实例,您可以配置设置,这样更新后的用户数据脚本在您启动实例时运行一次,或者在每次重启或启动实例时运行。

  • 用户数据是一种实例属性。如果您从实例创建 AMI,则实例用户数据不包含在该 AMI 中。

从 EC2 实例内访问实例元数据

由于您的正在运行的实例存在实例元数据,因此您无需使用 Amazon EC2 控制台或 Amazon CLI。这在您编写脚本以实现从实例运行时非常有用。例如,您可从实例元数据访问您的实例的本地 IP 地址来以管理与外部应用程序的连接。

以下所有内容均被视为实例元数据,但其访问方式不同。选择代表您要访问的实例元数据类型的选项卡,以查看更多信息。

Metadata

实例元数据属性分为几类。有关每个实例元数据类别的描述,请参阅实例元数据类别

要访问正在运行的实例内的实例元数据属性,请从以下 IPv4 或 IPv6 URI 获取数据。这些 IP 地址是链路本地地址,仅从该实例访问时有效。有关更多信息,请参阅 链路本地地址

IPv4

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

IPv6

http://[fd00:ec2::254]/latest/meta-data/
Dynamic data

要从正在运行的实例中检索动态数据,请使用以下 URI 之一。

IPv4

http://169.254.169.254/latest/dynamic/

IPv6

http://[fd00:ec2::254]/latest/dynamic/
示例:使用 cURL 访问

以下示例使用 cURL 检索高级实例身份类别。

IMDSv2

[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \ && curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/dynamic/instance-identity/ rsa2048 pkcs7 document signature dsa2048

IMDSv1

[ec2-user ~]$ curl http://169.254.169.254/latest/dynamic/instance-identity/ rsa2048 pkcs7 document signature dsa2048
示例:使用 PowerShell 访问

以下示例使用 PowerShell 检索高级实例身份类别。

IMDSv2

PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/dynamic/instance-identity/ document rsa2048 pkcs7 signature

IMDSv1

PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/dynamic/instance-identity/ document rsa2048 pkcs7 signature

有关动态数据的详细信息和如何对其进行检索的示例,请参阅 Amazon EC2 实例的实例身份文档

User data

要从实例中检索用户数据,请使用以下 URI 之一。要使用 IPv6 地址检索用户数据,必须将启用该功能,并且实例必须是在支持 IPv6 的子网中的基于 Nitro 的实例

IPv4

http://169.254.169.254/latest/user-data

IPv6

http://[fd00:ec2::254]/latest/user-data

请求用户数据时,按原样返回数据 (内容类型 application/octet-stream)。如果该实例没有任何用户数据,则请求将返回 404 - Not Found

示例:使用 cURL 访问以检索逗号分隔的文本

以下示例使用 cURL 检索以逗号分隔文本形式指定的用户数据。

IMDSv2

TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \ && curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/user-data 1234,john,reboot,true | 4512,richard, | 173,,,

IMDSv1

curl http://169.254.169.254/latest/user-data 1234,john,reboot,true | 4512,richard, | 173,,,
示例:使用 PowerShell 访问以检索逗号分隔的文本

以下示例使用 PowerShell 检索以逗号分隔文本形式指定的用户数据。

IMDSv2

[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/user-data 1234,john,reboot,true | 4512,richard, | 173,,,

IMDSv1

Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} ` -Method PUT -Uri http://169.254.169.254/latest/api/token} -Method GET -uri http://169.254.169.254/latest/user-data 1234,john,reboot,true | 4512,richard, | 173,,,
示例:使用 cURL 访问以检索脚本

以下示例使用 cURL 检索指定为脚本的用户数据。

IMDSv2

TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \ && curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/user-data #!/bin/bash yum update -y service httpd start chkconfig httpd on

IMDSv1

curl http://169.254.169.254/latest/user-data #!/bin/bash yum update -y service httpd start chkconfig httpd on
示例:使用 PowerShell 访问以检索脚本

以下示例使用 PowerShell 检索指定为脚本的用户数据。

IMDSv2

[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/user-data <powershell> $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm") New-Item $file -ItemType file </powershell> <persist>true</persist>

IMDSv1

Invoke-RestMethod -uri http://169.254.169.254/latest/user-data <powershell> $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm") New-Item $file -ItemType file </powershell> <persist>true</persist>

查询现有实例的实例元数据选项

您可以使用以下方法之一查询现有实例的实例元数据选项。

Console
使用控制台查询现有实例的实例元数据选项
  1. 通过以下网址打开 Amazon EC2 控制台:https://console.aws.amazon.com/ec2/

  2. 在导航窗格中,选择实例

  3. 选择实例。

  4. 依次选择操作实例设置修改实例元数据选项

  5. 修改实例元数据选项对话框中查看当前实例元数据选项。

Amazon CLI
使用 Amazon CLI 查询现有实例的实例元数据选项

使用 describe-instances CLI 命令。

aws ec2 describe-instances \ --instance-id i-1234567898abcdef0 \ --query 'Reservations[].Instances[].MetadataOptions'
PowerShell
使用 Tools for PowerShell 查询现有实例的实例元数据选项

使用 Get-EC2Instance Cmdlet。

(Get-EC2Instance ` -InstanceId i-1234567898abcdef0).Instances.MetadataOptions

响应和错误消息

所有实例元数据以文本形式返回(HTTP 内容类型 text/plain)。

特定元数据资源的请求返回相应的值;如果资源不可用,则返回 HTTP 错误代码 404 - Not Found

对通用元数据资源的请求 (以 / 结尾的 URI) 会返回一个可用资源列表,如果此类资源不存在,则会返回 HTTP 错误代码 404 - Not Found。列表中的各个项目位于被换行符 (ASCII 10) 终止的不同的行上。

对于使用 实例元数据服务版本 2 发出的请求,可能会返回以下 HTTP 错误代码:

  • 400 - Missing or Invalid ParametersPUT 请求无效。

  • 401 - UnauthorizedGET 请求使用无效的令牌。建议的措施是生成新的令牌。

  • 403 - Forbidden – 该请求不被允许,或者 IMDS 已关闭。

  • 503 – 无法完成请求。重试 请求。

查询限制

我们基于每个实例来限制对 IMDS 的查询,并且对从实例到 IMDS 的同时连接数进行限制。

如果您使用 IMDS 检索 Amazon 安全凭证,请避免在每个事务期间查询凭证或从大量线程或进程中并发查询凭证,因为这可能会导致节流。相反,我们建议您缓存凭证,直到凭证开始接近其到期时间。有关 IAM 角色以及与其关联的安全凭证的更多信息,请参阅 从实例元数据中检索安全凭证

如果在访问 IMDS 时受到限制,请使用指数回退策略重试查询。