Lambda 메타데이터 엔드포인트 사용
동일한 가용 영역 리소스(예: Amazon ElastiCache 및 Amazon RDS 엔드포인트)로 라우팅하여 지연 시간을 최적화하고 가용 영역을 인식하는 복원력 패턴을 구현할 수 있도록 Lambda 메타데이터 엔드포인트에서는 실행 중인 가용 영역(AZ)을 함수가 검색할 수 있습니다.
엔드포인트에서는 실행 환경 내 localhost HTTP API를 통해 간단한 JSON 형식으로 메타데이터를 반환하며 런타임과 확장 프로그램에 모두 액세스할 수 있습니다.
Sections
시작하기
Powertools for AWS Lambda에서는 Python, TypeScript, Java 및 .NET의 Lambda 메타데이터 엔드포인트 액세스용 유틸리티를 제공합니다. 유틸리티에서는 첫 번째 직접 호출 후 응답을 캐싱하고 SnapStart 캐시 무효화를 자동으로 처리합니다.
Powertools for AWS Lambda 메타데이터 유틸리티 사용 또는 메타데이터 엔드포인트 직접 호출
가용 영역 ID 이해하기
AZ ID(예: use1-az1)에서는 항상 모든 AWS 계정의 동일한 물리적 위치를 참조하는 반면에 AZ 이름(예: us-east-1a)은 특정 리전의 각 AWS 계정의 상이한 물리적 인프라에 매핑될 수 있습니다. 자세한 내용은 크로스 계정 일관성을 위한 AZ ID를 참조하세요.
AZ 이름으로 AZ ID 변환하기:
AZ ID를 AZ 이름으로 변환하려면 EC2 DescribeAvailabilityZones API를 사용합니다. 이 API를 사용하려면 함수의 실행 역할에 ec2:DescribeAvailabilityZones 권한을 추가합니다.
API 참조
환경 변수
Lambda에서는 모든 실행 환경에서 다음과 같은 환경 변수를 자동으로 설정합니다.
-
AWS_LAMBDA_METADATA_API-{ipv4_address}:{port}형식의 메타데이터 서버 주소입니다(예:169.254.100.1:9001). -
AWS_LAMBDA_METADATA_TOKEN- 현재 실행 환경의 고유 인증 토큰입니다. Lambda에서는 초기화 시 이 토큰을 자동으로 생성합니다. 모든 메타데이터 API 요청에 포함합니다.
엔드포인트
GET http://${AWS_LAMBDA_METADATA_API}/2026-01-15/metadata/execution-environment
요청
필수 헤더:
-
Authorization- 전달자 체계(Bearer <token>)가 있는AWS_LAMBDA_METADATA_TOKEN환경 변수의 토큰 값입니다. 이 토큰 기반 인증에서는 SSRF(서버 측 요청 위조) 취약성에 대한 심층 방어 보호를 제공합니다. 각 실행 환경에서는 초기화 시 무작위로 생성된 고유한 토큰을 수신합니다.
응답
Status: 200 OK
Content-Type: application/json
Cache-Control: private, max-age=43200, immutable
응답은 실행 환경 내에서 변경할 수 없습니다. 클라이언트에서는 응답을 캐싱하고 Cache-Control TTL을 준수해야 합니다. SnapStart 함수의 경우 실행 환경이 다른 AZ에 있을 수 있을 때 복원 후 클라이언트에서 메타데이터를 새로 고치도록 초기화 동안 TTL이 감소합니다. Powertools를 사용하는 경우 캐싱 및 SnapStart 무효화가 자동으로 처리됩니다.
본문:
{ "AvailabilityZoneID": "use1-az1" }
AvailabilityZoneID 필드에는 실행 환경이 실행 중인 가용 영역의 고유 식별자가 있습니다.
참고
향후 업데이트에서 응답에 추가 필드를 추가할 수 있습니다. 클라이언트는 알 수 없는 필드를 무시하고 새 필드가 나타나면 실패하지 않아야 합니다.
오류 응답
-
401 Unauthorized -
Authorization헤더가 누락되었거나 유효하지 않은 토큰이 있습니다.Bearer ${AWS_LAMBDA_METADATA_TOKEN}을 전달 중인지 확인합니다. -
405 Method Not Allowed - 요청 메서드가
GET이 아닙니다. -
500 Internal Server Error - 서버 측 처리 오류입니다.