EC2 인스턴스의 인스턴스 메타데이터 접근
EC2 인스턴스의 인스턴스 메타데이터 접근 (Access instance metadata for an EC2 instance)
EC2 인스턴스 메타데이터는 인스턴스 자체 내부에서, 또는 EC2 콘솔, API, SDK, AWS CLI에서 접근할 수 있어요. 콘솔이나 명령줄에서 인스턴스의 현재 인스턴스 메타데이터 설정을 보려면 기존 인스턴스의 인스턴스 메타데이터 옵션 쿼리하기를 참고하세요.
출처: 문서
본문
또한 EBS 루트 볼륨이 있는 인스턴스의 user data를 수정할 수 있어요. 인스턴스가 중지(stopped) 상태여야 해요. 콘솔 지침은 인스턴스 user data 업데이트하기를 참고하세요. AWS CLI를 사용하는 Linux 예시는 modify-instance-attribute를 참고하세요. Tools for Windows PowerShell을 사용하는 Windows 예시는 User data and the Tools for Windows PowerShell을 참고하세요.
참고 인스턴스 메타데이터와 user data를 검색하는 데 사용하는 HTTP 요청에는 요금이 부과되지 않아요.
인스턴스 메타데이터 접근 고려 사항 (Instance metadata access considerations)
인스턴스 메타데이터 문제를 피하려면 다음을 고려해요.
IMDSv2 강제 적용으로 인한 인스턴스 시작 실패 (HttpTokensEnforced=enabled)
IMDSv2 강제 적용을 활성화하기 전에 먼저 인스턴스의 모든 소프트웨어가 IMDSv2를 지원해야 해요. 그런 다음 IMDSv1을 비활성화하도록 기본값을 변경(httpTokens=required)할 수 있고, 그 후에 강제 적용을 활성화할 수 있어요. 자세한 내용은 Instance Metadata Service 버전 2로 전환하기를 참고하세요.
명령 형식 (Command format)
명령 형식은 Instance Metadata Service 버전 1(IMDSv1)을 사용하는지 버전 2(IMDSv2)를 사용하는지에 따라 달라져요. 기본적으로 두 버전의 Instance Metadata Service를 모두 사용할 수 있어요. IMDSv2 사용을 요구하려면 Instance Metadata Service로 인스턴스 메타데이터 접근하기를 참고하세요.
IMDSv2가 요구되면 IMDSv1은 작동하지 않음
IMDSv1을 사용하는데 응답이 없다면 IMDSv2가 요구되는 것일 가능성이 커요. IMDSv2가 요구되는지 확인하려면 인스턴스를 선택해 세부 정보를 봐요. IMDSv2 값은 Required(IMDSv2를 사용해야 함) 또는 Optional(IMDSv2 또는 IMDSv1 중 아무거나 사용 가능)을 나타내요.
(IMDSv2) 토큰을 검색하려면 /latest/api/token 사용
/2021-03-23/api/token 같은 버전별 경로에 PUT 요청을 보내면 메타데이터 서비스가 403 Forbidden 오류를 반환해요. 이 동작은 의도된 것이에요.
메타데이터 버전 (Metadata version)
Amazon EC2가 새 인스턴스 메타데이터 빌드를 릴리스할 때마다 코드를 갱신하지 않아도 되도록, 경로에 버전 번호가 아닌 latest를 사용할 것을 권장해요.
IPv6 지원 (IPv6 support)
IPv6 주소를 사용해 인스턴스 메타데이터를 검색하려면 IMDS의 IPv6 주소인 [fd00:ec2::254]를 IPv4 주소 169.254.169.254 대신 활성화하고 사용해요. 인스턴스는 IPv6를 지원하는 서브넷에서 시작된 Nitro 기반 인스턴스여야 해요.
(Windows) Windows Sysprep으로 커스텀 AMI 만들기
커스텀 Windows AMI에서 인스턴스를 시작할 때 IMDS가 작동하려면 AMI가 Windows Sysprep으로 만든 표준화된 이미지여야 해요. 그렇지 않으면 IMDS가 작동하지 않아요. 자세한 내용은 Windows Sysprep으로 Amazon EC2 AMI 만들기를 참고하세요.
컨테이너 환경에서는 재구성하거나 hop limit을 2로 늘리는 것을 고려
AWS SDK는 기본적으로 IMDSv2 호출을 사용해요. IMDSv2 호출이 응답을 받지 못하면 일부 AWS SDK는 호출을 재시도하고, 그래도 실패하면 IMDSv1을 사용해요. 이로 인해 특히 컨테이너 환경에서 지연이 발생할 수 있어요. IMDSv2를 요구하는 AWS SDK의 경우, 컨테이너 환경에서 hop limit이 1이면 컨테이너로 가는 것이 추가 네트워크 홉으로 간주되므로 호출이 전혀 응답을 받지 못할 수 있어요. 컨테이너 환경의 이런 문제를 완화하려면 AWS 리전 같은 설정을 컨테이너에 직접 전달하도록 구성 변경을 고려하거나, hop limit을 2로 늘리는 것을 고려해요. hop limit 영향에 대한 정보는 EC2 Instance Metadata Service 개선으로 개방형 방화벽, 리버스 프록시, SSRF 취약점에 대한 방어 심화하기를 참고하세요. hop limit 변경에 대한 정보는 PUT 응답 hop limit 변경을 참고하세요.
초당 패킷 수(PPS) 한도
링크-로컬 주소를 사용하는 서비스에는 초당 1024 패킷(PPS) 한도가 있어요. 이 한도에는 Route 53 Resolver DNS Queries, Instance Metadata Service(IMDS) 요청, Amazon Time Service Network Time Protocol(NTP) 요청, Windows Licensing Service(Microsoft Windows 기반 인스턴스용) 요청의 합계가 포함돼요.
- User data는 불투명한(opaque) 데이터로 취급돼요. 지정한 내용이 검색 시 그대로 반환돼요. user data를 해석하고 처리하는 것은 인스턴스의 몫이에요.
- User data는 base64로 인코딩되어야 해요. 사용하는 도구나 SDK에 따라 base64 인코딩이 자동으로 수행될 수 있어요. 예를 들어:
- Amazon EC2 콘솔은 base64 인코딩을 대신 수행하거나 base64로 인코딩된 입력을 받을 수 있어요.
- AWS CLI 버전 2는 기본적으로 이진 파라미터에 대한 base64 인코딩을 수행해요. AWS CLI 버전 1은
--user-data파라미터의 base64 인코딩을 수행해요. - AWS SDK for Python(Boto3)은
UserData파라미터의 base64 인코딩을 수행해요.
- User data는 base64 인코딩 전 원시 형태로 16KB로 제한돼요. 길이 n인 문자열의 base64 인코딩 후 크기는 ceil(n/3)*4예요.
- User data를 검색할 때는 base64로 디코딩해야 해요. 인스턴스 메타데이터나 콘솔로 데이터를 검색하면 자동으로 디코딩돼요.
- 인스턴스를 중지하고 user data를 수정한 다음 인스턴스를 시작하면, 인스턴스를 시작할 때 갱신된 user data가 자동으로 실행되지 않아요. Windows 인스턴스에서는 인스턴스를 시작할 때 한 번, 또는 재부팅하거나 시작할 때마다 갱신된 user data 스크립트가 실행되도록 설정을 구성할 수 있어요.
- User data는 인스턴스 속성이에요. 인스턴스에서 AMI를 만들면 인스턴스 user data는 AMI에 포함되지 않아요.
EC2 인스턴스 내부에서 인스턴스 메타데이터 접근 (Access instance metadata from within an EC2 instance)
인스턴스 메타데이터는 실행 중인 인스턴스에서 사용할 수 있으므로 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
인스턴스에서 user data를 검색하려면 다음 URI 중 하나를 사용해요. IPv6 주소로 user data를 검색하려면 활성화해야 하며, 인스턴스가 IPv6를 지원하는 서브넷의 Nitro 기반 인스턴스여야 해요.
IPv4 http://169.254.169.254/latest/user-data
IPv6 http://[fd00:ec2::254]/latest/user-data
user data에 대한 요청은 데이터를 있는 그대로 반환해요(콘텐츠 유형 application/octet-stream). 인스턴스에 user data가 없으면 요청이 404 - Not Found를 반환해요.
예시: cURL로 쉼표로 구분된 텍스트 접근 — 다음 예시는 cURL을 사용해 쉼표로 구분된 텍스트로 지정된 user data를 검색해요.
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을 사용해 쉼표로 구분된 텍스트로 지정된 user data를 검색해요.
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을 사용해 스크립트로 지정된 user data를 검색해요.
기존 인스턴스의 인스턴스 메타데이터 옵션 쿼리 (Query instance metadata options for existing instances)
기존 인스턴스의 인스턴스 메타데이터 옵션을 쿼리할 수 있어요.
콘솔 (Console)
기존 인스턴스의 인스턴스 메타데이터 옵션 쿼리하기: Amazon EC2 콘솔(https://console.aws.amazon.com/ec2/)을 엽니다. 탐색 창에서 Instances를 선택해요. 인스턴스를 선택하고 다음 필드를 확인해요.
- IMDSv2 – 값은
Required또는Optional이에요. - Allow tags in instance metadata – 값은
Enabled또는Disabled예요. 인스턴스를 선택한 상태에서 Actions, Instance settings, Modify instance metadata options을 선택해요. 대화 상자에 선택한 인스턴스에 대해 인스턴스 메타데이터 서비스가 활성화되어 있는지 비활성화되어 있는지 표시돼요.
AWS CLI
기존 인스턴스의 인스턴스 메타데이터 옵션 쿼리하기: describe-instances 명령을 사용해요.
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
응답 및 오류 메시지 (Responses and error messages)
모든 인스턴스 메타데이터는 텍스트(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 서버 오류가 발생한 경우 오류 상태 코드를 반환해요. 오류 처리를 활성화하면 셸이 오류를 잡아 스크립트를 중지할 수 있어요.
쿼리 스로틀링 (Query throttling)
IMDS에 대한 쿼리는 인스턴스별로 스로틀하고, 인스턴스에서 IMDS로의 동시 연결 수에 한도를 둬요.
IMDS로 AWS 보안 자격 증명을 검색하는 경우, 스로틀링이 발생할 수 있으므로 모든 트랜잭션에서 자격 증명을 쿼리하거나 많은 수의 스레드/프로세스에서 동시에 쿼리하지 마세요. 대신 자격 증명이 만료 시점에 가까워질 때까지 캐시할 것을 권장해요. 역할에 연결된 IAM 역할과 보안 자격 증명에 대한 자세한 내용은 인스턴스 메타데이터에서 보안 자격 증명 검색하기를 참고하세요.
IMDS 접근 중 스로틀되면 지수 백오프(exponential backoff) 전략으로 쿼리를 재시도해요.