EC2 Instance Metadata (IMDS) 정리

이 글은 AI가 작성했습니다.

개요

Amazon EC2는 실행 중인 인스턴스 내부에서 다양한 정보를 조회할 수 있는 Instance Metadata Service(IMDS) 를 제공한다.

이 기능은 애플리케이션이나 스크립트가 인스턴스 환경 정보를 동적으로 조회할 수 있도록 지원한다.

대표적으로 다음과 같은 정보를 조회할 수 있다.

• Instance ID
• AMI ID
• Local IP / Public IP
• IAM Role Credentials
• Network 정보
• User Data

IMDS는 인스턴스 내부에서만 접근 가능한 링크 로컬 주소를 통해 HTTP 요청으로 접근한다.

메타데이터 접근 주소

EC2 인스턴스 내부에서 다음 주소를 통해 메타데이터에 접근할 수 있다.

IPv4

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

IPv6

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

이 주소는 인스턴스 내부에서만 유효한 링크‑로컬 주소다.

IMDS 버전

EC2 메타데이터 서비스는 두 가지 버전을 제공한다.

IMDSv1

• 단순 HTTP GET 요청 방식
• 인증 과정 없음

IMDSv2

• 세션 기반 토큰 방식
• SSRF 공격 방지
• 보안 강화

AWS에서는 IMDSv2 사용을 권장한다.

IMDSv2 사용 방법

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

예시

curl -H "X-aws-ec2-metadata-token: $TOKEN" \
http://169.254.169.254/latest/meta-data/instance-id

주요 메타데이터 항목

IMDS는 여러 카테고리의 정보를 제공한다.

Metadata

인스턴스 기본 정보

• instance-id
• instance-type
• ami-id
• hostname

Dynamic Data

런타임 정보

• instance identity document
• IAM role credentials

User Data

인스턴스 시작 시 실행되는 초기화 스크립트

오류 코드

IMDS 요청 시 다음 HTTP 오류가 반환될 수 있다.

PPS 제한

EC2 링크 로컬 서비스에는 1024 PPS(Packet Per Second) 제한이 있다.

다음 서비스 요청이 합산된다.

• Instance Metadata Service
• Route53 Resolver DNS
• Amazon Time Service (NTP)
• Windows License Service

높은 요청 빈도는 제한을 유발할 수 있다.

컨테이너 환경 주의사항

컨테이너 환경에서 IMDS 요청이 실패할 수 있다.

기본 설정

hop limit = 1

컨테이너 환경에서는 다음 설정이 권장된다.

hop limit = 2

또는 필요한 환경 정보를 환경 변수로 직접 전달하는 방식도 사용된다.

권장 사용 방법

IMDS 사용 시 다음 사항을 권장한다.

• IMDSv2 사용
• /latest 경로 사용
• 자격 증명 요청 캐싱
• 과도한 메타데이터 호출 방지

Node.js 예시

Node.js에서도 HTTP 요청을 통해 Instance Metadata를 조회할 수 있다.

IMDSv1 예제

import http from "node:http";

const url = "http://169.254.169.254/latest/meta-data/instance-id";

http.get(url, (res) => {
  let data = "";

  res.on("data", chunk => data += chunk);

  res.on("end", () => {
    console.log("instance-id:", data);
  });
});

IMDSv2 예제

IMDSv2는 먼저 토큰을 요청한 후 해당 토큰으로 메타데이터를 조회해야 한다.

import http from "node:http";

function getToken() {
  return new Promise((resolve, reject) => {
    const req = http.request({
      method: "PUT",
      host: "169.254.169.254",
      path: "/latest/api/token",
      headers: {
        "X-aws-ec2-metadata-token-ttl-seconds": "21600"
      }
    }, res => {
      let data = "";
      res.on("data", chunk => data += chunk);
      res.on("end", () => resolve(data));
    });

    req.on("error", reject);
    req.end();
  });
}

async function getInstanceId() {
  const token = await getToken();

  const req = http.request({
    method: "GET",
    host: "169.254.169.254",
    path: "/latest/meta-data/instance-id",
    headers: {
      "X-aws-ec2-metadata-token": token
    }
  }, res => {
    let data = "";
    res.on("data", chunk => data += chunk);
    res.on("end", () => console.log("instance-id:", data));
  });

  req.end();
}

getInstanceId();

이 방식은 다음과 같은 상황에서 자주 사용된다.

• EC2 환경에서 애플리케이션이 자신의 instance-id 확인
• IAM Role credentials 조회
• Auto Scaling 환경에서 동적 설정

참고 자료

• https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html