EC2 インスタンスのインスタンスメタデータにアクセスする - Amazon Elastic Compute Cloud
インスタンスメタデータアクセス考慮事項EC2 インスタンス内からインスタンスメタデータにアクセスするインスタンスメタデータオプションのクエリリスポンスおよびエラーメッセージクエリスロットル

EC2 インスタンスのインスタンスメタデータにアクセスする

EC2 インスタンスメタデータにはインスタンス自体の内部から、または EC2 コンソール、API、SDK、または AWS CLI からアクセスできます。コンソールまたはコマンドラインからインスタンスの現在のインスタンスメタデータ設定を取得するには「既存インスタンスのインスタンスメタデータオプションのクエリ」を参照してください。

また、EBS ルートボリュームを持つインスタンスのユーザーデータを変更できます。インスタンスは停止状態である必要があります。コンソールの使用説明については「インスタンスのユーザーデータを更新する」を参照してください。AWS CLI を使用する Linux の例については「modify-instance-attribute」を参照してください。Tools for Windows PowerShell を使用する Windows の例については「ユーザーデータと Windows PowerShell用ツール」を参照してください。

注記

インスタンスメタデータおよびユーザーデータの取得に使用する HTTP リクエストに対しては課金されません。

インスタンスメタデータアクセス考慮事項

インスタンスメタデータの取得に関する問題を回避するには次の点を考慮してください。

コマンド形式

コマンド形式はインスタンスメタデータサービスバージョン 1 (IMDSv1) とインスタンスメタデータサービスバージョン 2 (IMDSv2) のどちらを使用するかによって異なります。デフォルトでは両方のバージョンのインスタンスメタデータサービスを使用できます。IMDSv2の使用を義務付けるにはインスタンスメタデータサービスを使用してインスタンスメタデータにアクセスするを参照してください。

IMDSv2 が必要な場合はIMDSv1 は動作しません。

IMDSv1 を使用していて、応答がない場合はIMDSv2 が必要になる可能性があります。IMDSv2 が必要かどうかを確認するにはインスタンスを選択して詳細を表示します。[IMDSv2] の値は[必須] (IMDSv2 を使用する必要がある) または [オプション] (IMDSv2 または IMDSv1 を使用可能) のいずれかです。

(IMDSv2) /latest/api/token を使用してトークンを取得する

バージョン固有の任意のパス (例: /2021-03-23/api/token) に PUT リクエストを発行した場合はメタデータサービスから 403 Forbidden エラーが返されます。この応答は意図されたものです。

メタデータのバージョン

Amazon EC2 が新しいインスタンスメタデータビルドをリリースするたびにコードを更新する必要をなくすために、バージョン番号ではなく、パス内の latest を使用することが推奨されます。

IPv6 サポート

IPv6 アドレスを使用してインスタンス メタデータを取得するには、IMDS [fd00:ec2::254] の IPv4 アドレスではなく169.254.169.254IPv6 アドレスを有効にして使用するようにしてください。インスタンスはIPv6 対応サブネットで起動された Nitro ベースのインスタンスである必要があります。

(Windows) Windows Sysprep を使用してカスタム AMI を作成する

カスタム Windows AMI からインスタンスを起動したときに IMDS が動作するようにするにはAMI は Sysprep を使用して作成された標準化されたイメージである必要があります。そうでない場合、IMDS は機能しません。詳細については、「Windows Sysprep を使用して Amazon EC2 AMI を作成する」を参照してください。

コンテナ環境では、再設定またはホップ制限を 2 に引き上げることを検討してください。

AWS SDK はデフォルトで IMDSv2 コールを使用します。IMDSv2 呼び出しに応答がない場合、一部の AWS SDK は呼び出しを再試行し、それでも失敗する場合はIMDSv1 を使用します。これにより、特にコンテナ環境では遅延が発生することがあります。IMDSv2 を 必要とする AWS SDK の場合、コンテナ環境でホップ制限が 1 の場合、コンテナへの移動は追加のネットワーク ホップとみなされ、呼び出しは応答をまったく受け取らない可能性があります。

コンテナ環境でこれらの問題を軽減するには、設定 (AWS リージョン など) をコンテナに直接渡すように設定を変更するか、ホップ制限を 2 に引き上げることを検討してください。ホップ制限の影響については、「EC2 Instance Metadata Service の拡張により、オープンファイアウォール、リバースプロキシ、および SSRF の脆弱性に対して多層防御を追加」を参照してください。ホップ制限の変更については、「PUT レスポンスホップリミットを変更する」を参照してください。

パケット/秒 (PPS) 制限

リンクローカルアドレスを使用するサービスには 1,024 パケット/秒 (PPS) の制限があります。この制限にはRoute 53 Resolver DNS クエリ、インスタンスメタデータサービス (IMDS) リクエスト、Amazon Time Service Network Time Protocol (NTP) リクエスト、および Windows Licensing Service (Microsoft Windows ベースのインスタンス向け) リクエストの総計が含まれます。

ユーザーデータアクセスに関するその他の考慮事項

  • ユーザーデータは非透過的なデータとして取り扱われ、取得時には指定したものが返されます。ユーザーデータの解釈およびそれに基づくアクションはインスタンス次第です。

  • ユーザーデータはbase64 でエンコードされている必要があります。使用しているツールまたは SDK によってはbase64 エンコードが実行される場合があります。例：

    • Amazon EC2コンソールはbase64 エンコードを実行したり、base64 エンコード入力を受け入れたりできます。

    • AWS CLI バージョン 2 はユーザーに対しデフォルトでバイナリパラメータの base64 エンコードを実行します。AWS CLI バージョン 1 はユーザーに対し --user-data パラメータの base64 エンコードを実行します。

    • AWS SDK for Python (Boto3) はユーザーに対し UserData パラメータの base64 エンコードを実行します。

  • ユーザーデータは raw 形式の 16 KB に制限されます (以前は base64 エンコード)。base64 エンコード後の 文字列の長さサイズ n はceil(n/3)*4 です。

  • ユーザーデータを取得するときにユーザーデータを base64 デコードする必要があります。インスタンスのメタデータあるいはコンソールを使用してデータを取得する場合、自動的にデコードされます。

  • インスタンスを停止してユーザーデータを変更した後に、インスタンスを起動した場合でも、更新されたユーザーデータは自動的には実行されません。Windows インスタンスではインスタンスを起動したとき、またはインスタンスを再起動もしくは起動するたびに、更新されたユーザーデータスクリプトが 1 回実行されるように設定を構成することができます。

  • ユーザーデータはインスタンス属性です。インスタンスから AMI を作成する場合、インスタンスのユーザーデータは AMI に含まれません。

EC2 インスタンス内からインスタンスメタデータにアクセスする

インスタンスメタデータは実行中のインスタンスから取得できるため、Amazon EC2 コンソールまたは AWS 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 アドレスが有効で、インスタンスが 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. ナビゲーションペインで、[Instances] (インスタンス) を選択してください。

  3. インスタンスを選択してください。

  4. [アクション]、[インスタンスの設定]、[インスタンスメタデータのオプションを変更] の順に選択してください。

  5. [インスタンスメタデータオプションの変更] ダイアログボックスで現在のインスタンスメタデータオプションを確認します。

AWS CLI
AWS CLI を使用して既存のインスタンスのインスタンスメタデータオプションをクエリするには

describe-instances コマンドを使用します。

aws ec2 describe-instances \
    --instance-id i-1234567898abcdef0 \
    --query 'Reservations[].Instances[].MetadataOptions'
PowerShell
Tools for PowerShell を使用して既存のインスタンスのインスタンスメタデータオプションをクエリするには

Get-EC2Instance コマンドレットを使用します。

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

リスポンスおよびエラーメッセージ

すべてのインスタンスメタデータがテキスト (HTTP コンテンツタイプ text/plain) として返されます。

特定のメタデータリソースに対するリクエストは適切な値または 404 - Not Found HTTP エラーコード (リソースを使用できない場合) を返します。

一般的なメタデータリソースに対するリクエスト (/ で終わる URI) は使用可能なリソースのリストまたは 404 - Not Found HTTP エラーコード (使用可能なリソースがない場合) を返します。リスト項目は個別の行に表示され、各行の末尾には改行記号 (ASCII 10) が付いています。

IMDSv1 リクエストが応答を受信しない場合は、IMDSv2 が必要になる可能性があります。

IMDSv2 を使って行われたリクエストでは、次の HTTP エラーコードが返されます。

  • 400 - Missing or Invalid Parameters–PUTリクエストが無効である。

  • 401 - Unauthorized–GETリクエストが無効なトークンを使用している。推奨されるアクションは新しいトークンを生成することです。

  • 403 - Forbidden - リクエストが許可されていないか、あるいは IMDS がオフです。

  • 404 - Not Found – リソースが利用できないか、そのようなリソースがありません。

  • 503 - リクエストを完了できませんでした。リクエストを再試行します。

IMDS がエラーを返した場合、 はエラーメッセージを出力にcurl出力し、成功ステータスコードを返します。エラーメッセージは TOKEN変数に保存され、トークンを使用するcurlコマンドは失敗します。-f オプションcurlを指定して を呼び出すと、HTTP サーバーエラーが発生した場合にエラーステータスコードが返されます。エラー処理を有効にすると、シェルはエラーを検出してスクリプトを停止できます。

クエリスロットル

クエリは IMDS でインスタンスごとにスロットリングし、インスタンスから IMDS への同時接続数を制限します。

AWS セキュリティ認証情報を取得するために IMDS を使用している場合、毎回のトランザクションで、または高頻度のスレッドやプロセスから同時に認証情報をクエリしないようにします。スロットリングの原因となる可能性があります。代わりに、認証情報をキャッシュに格納して有効期限が近づくまで待つことをお勧めします。IAM ロールとロールに関連付けられたセキュリティ認証情報の詳細については「インスタンスメタデータからのセキュリティ認証情報の取得」を参照してください。

IMDS にアクセスする際にスロットリングした場合、エクスポネンシャルバックオフ戦略でクエリを再試行します。