Instance Metadata Service로 인스턴스 메타데이터 접근하기

Instance Metadata Service로 인스턴스 메타데이터 접근하기 (Use the Instance Metadata Service to access instance metadata)

실행 중인 인스턴스에서 다음 방법 중 하나로 인스턴스 메타데이터에 접근할 수 있어요. 기본적으로 IMDSv1과 IMDSv2를 모두(또는 둘 중 하나만) 사용할 수 있어요.

출처: 문서

본문

두 가지 방법이 있어요.

  • IMDSv2(Instance Metadata Service Version 2) – 세션 중심(session-oriented) 방식.
  • IMDSv1(Instance Metadata Service Version 1) – 요청/응답(request/response) 방식.

각 인스턴스에서 IMDS를 IMDSv2 호출만 받도록 구성할 수 있고, 그렇게 하면 IMDSv1 호출이 실패해요. PUT 또는 GET 헤더는 IMDSv2에만 있어요. 이 헤더가 요청에 있으면 IMDSv2용 요청이고, 헤더가 없으면 IMDSv1용으로 간주돼요.

IMDSv2의 동작 방식 (How Instance Metadata Service Version 2 works)

IMDSv2는 세션 중심 요청을 사용해요. 세션 중심 요청에서는 세션 기간을 정의하는 세션 토큰을 만들어요. 세션 기간은 최소 1초에서 최대 6시간이에요. 지정된 기간 동안에는 같은 세션 토큰을 후속 요청에 사용할 수 있어요. 토큰이 만료되면 새 세션 토큰을 만들어야 해요.

참고: 이 섹션의 예시는 IMDS의 IPv4 주소인 169.254.169.254를 사용해요. IPv6 주소로 메타데이터를 검색한다면 [fd00:ec2::254]를 사용하세요. IMDS의 IPv6 주소는 IMDSv2 명령과 호환되며, IPv6 지원 서브넷(dual stack 또는 IPv6 전용)의 Nitro 기반 인스턴스에서만 접근할 수 있어요.

다음 예시는 셸 스크립트와 IMDSv2로 최상위 인스턴스 메타데이터 항목을 검색해요. 각 예시는 PUT 요청으로 6시간(21600초) 지속되는 세션 토큰을 만들고, 토큰을 TOKEN 변수(Linux) 또는 token 변수(Windows)에 저장하고, 그 토큰으로 최상위 메타데이터 항목을 요청해요. 두 명령을 분리해서 실행하거나 결합할 수 있어요.

분리 명령 (Linux) — 먼저 토큰을 생성해요.

[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"`

그다음 토큰으로 최상위 메타데이터 항목을 생성해요.

[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/

결합 명령 (Linux) — 토큰을 저장하고 명령을 결합할 수 있어요. 토큰 생성에 오류가 있으면 유효한 토큰 대신 오류 메시지가 변수에 저장되고 명령이 동작하지 않아요.

[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/meta-data/

토큰을 만들면 만료될 때까지 재사용할 수 있어요. 다음 예시는 인스턴스 시작에 사용한 AMI의 ID를 구하며 이전 예시에서 $TOKEN에 저장한 토큰을 재사용해요.

[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/ami-id

Windows(PowerShell) — 토큰 생성.

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/meta-data/

AMI ID 가져오기(토큰 재사용).

PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} `
	-Method GET -uri http://169.254.169.254/latest/meta-data/ami-id

IMDSv2로 인스턴스 메타데이터를 요청할 때 요청은 다음을 포함해야 해요.

  • PUT 요청으로 인스턴스 메타데이터 서비스에 세션을 시작해요. PUT 요청은 후속 GET 요청에 포함해야 하는 토큰을 반환해요. 토큰은 IMDSv2로 메타데이터에 접근하는 데 필요해요.
  • 모든 GET 요청에 토큰을 포함해요. 토큰 사용이 required로 설정되면 유효하거나 만료된 토큰이 없는 요청은 401 - Unauthorized HTTP 오류 코드를 받아요.
  • 토큰은 인스턴스 특정 키예요. 토큰은 다른 EC2 인스턴스에서 유효하지 않고, 생성된 인스턴스 밖에서 사용하려 하면 거부돼요.
  • PUT 요청에는 토큰의 TTL(시간, 초)을 최대 6시간(21600초)까지 지정하는 헤더가 포함되어야 해요. 토큰은 논리적 세션을 나타내고, TTL은 토큰이 유효한 시간, 즉 세션 기간을 지정해요.
  • 토큰이 만료된 후 메타데이터에 계속 접근하려면 다른 PUT으로 새 세션을 만들어야 해요.
  • 토큰을 재사용하거나 매 요청마다 새 토큰을 만들 수 있어요. 요청이 적으면 매번 토큰을 생성·즉시 사용하는 게 쉬울 수 있고, 효율성을 위해 더 긴 기간을 지정해 토큰을 재사용할 수도 있어요. 동시 토큰 수에 실질적 제한은 없지만, IMDSv2는 여전히 일반적인 IMDS 연결·제한(throttling) 한도에 제약을 받아요.

IMDSv2 인스턴스 메타데이터 요청에서는 HTTP GET과 HEAD 메서드가 허용돼요. X-Forwarded-For 헤더가 포함된 PUT 요청은 거부돼요.

기본적으로 PUT 요청에 대한 응답의 응답 홉 제한(TTL)은 IP 프로토콜 수준에서 1이에요. 더 큰 홉 제한이 필요하면 modify-instance-metadata-options AWS CLI 명령으로 조정할 수 있어요. 예를 들어 인스턴스에서 실행되는 컨테이너 서비스와의 이전 버전 호환성을 위해 더 큰 홉 제한이 필요할 수 있어요.

지원되는 AWS SDK 사용 (Use a supported AWS SDK)

IMDSv2를 사용하려면 EC2 인스턴스가 IMDSv2 사용을 지원하는 AWS SDK 버전을 사용해야 해요. 모든 AWS SDK의 최신 버전이 IMDSv2를 지원해요. SDK 릴리스로 최신 상태를 유지할 것을 권장해요. IMDSv2를 지원하는 최소 버전은 다음과 같아요.

  • AWS CLI – 1.16.289
  • AWS Tools for Windows PowerShell – 4.0.1.0
  • AWS SDK for .NET – 3.3.634.1
  • AWS SDK for C++ – 1.7.229
  • AWS SDK for Go – 1.25.38
  • AWS SDK for Go v2 – 0.19.0
  • AWS SDK for Java – 1.11.678
  • AWS SDK for Java 2.x – 2.10.21
  • AWS SDK for JavaScript in Node.js – 2.722.0
  • AWS SDK for Kotlin – 1.1.4
  • AWS SDK for PHP – 3.147.7
  • Botocore(AWS SDK for Python(Boto3)와 AWS CLI의 기반이 되는 저수준 라이브러리) – 1.13.25
  • AWS SDK for Python (Boto3) – 1.12.6
  • AWS SDK for Ruby – 3.79.0

IMDSv2 예시 (Examples for IMDSv2)

사용 가능한 메타데이터 버전 가져오기 — 각 버전은 새 메타데이터 범주가 출시된 인스턴스 메타데이터 빌드를 가리켜요. 빌드 버전은 Amazon EC2 API 버전과 연관되지 않아요. 이전 버전은 이전 버전의 구조·정보에 의존하는 스크립트가 있다면 사용할 수 있어요.

[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/
1.0
2007-01-19
2007-03-01
...
latest

최상위 메타데이터 항목 가져오기 — 응답의 항목에 대한 자세한 내용은 "Instance metadata categories"를 참고하세요. 태그는 접근을 허용한 경우에만 출력에 포함돼요.

[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/meta-data/    
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
events/
hostname
iam/
instance-action
instance-id
instance-life-cycle
instance-type
local-hostname
local-ipv4
mac
metrics/
network/
placement/
profile
public-hostname
public-ipv4
public-keys/
reservation-id
security-groups
services/
tags/

메타데이터 항목 값 가져오기 — 이전 예시에 있는 저장된 토큰을 사용해요. 토큰은 만료되지 않아야 해요.

[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/ami-id
ami-0abcdef1234567890

[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/reservation-id
r-0efghijk987654321

사용 가능한 공개 키 목록 가져오기:

[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/meta-data/public-keys/
0=my-public-key

공개 키 0이 제공되는 형식 표시:

[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/meta-data/public-keys/0/
openssh-key

공개 키 0 가져오기(OpenSSH 키 형식):

[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/meta-data/public-keys/0/openssh-key
ssh-rsa MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
... my-public-key

인스턴스의 서브넷 ID 가져오기:

[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/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id
subnet-be9b61d7

인스턴스 태그 가져오기 — 인스턴스 메타데이터에서 인스턴스 태그 접근이 켜져 있다면 태그를 가져올 수 있어요. 자세한 내용은 "Retrieve tags from instance metadata"를 참고하세요.

IMDSv1 예시 (Examples for IMDSv1)

Windows 인스턴스에서는 Windows PowerShell을 쓰거나 cURL 또는 wget을 설치할 수 있어요. 타사 도구를 설치할 때는 호출과 출력이 여기에 설명된 것과 다를 수 있으므로 문서를 잘 읽어보세요.

사용 가능한 버전 가져오기:

[ec2-user ~]$ curl http://169.254.169.254/
1.0
2007-01-19
2007-03-01
...
latest

최상위 메타데이터 항목 가져오기:

[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/    
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
...
tags/

메타데이터 항목 값 가져오기:

[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/ami-id
ami-0abcdef1234567890

[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/local-hostname
ip-10-251-50-12.ec2.internal

[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-hostname
ec2-203-0-113-25.compute-1.amazonaws.com

공개 키 목록 가져오기:

[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-keys/
0=my-public-key

공개 키 0 가져오기(OpenSSH 키 형식):

[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key
ssh-rsa MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
... my-public-key

서브넷 ID 가져오기:

[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id
subnet-be9b61d7

더 알아보기