Lambda 메타데이터 엔드포인트 사용 - AWS Lambda

Lambda 메타데이터 엔드포인트 사용

동일한 가용 영역 리소스(예: Amazon ElastiCache 및 Amazon RDS 엔드포인트)로 라우팅하여 지연 시간을 최적화하고 가용 영역을 인식하는 복원력 패턴을 구현할 수 있도록 Lambda 메타데이터 엔드포인트에서는 실행 중인 가용 영역(AZ)을 함수가 검색할 수 있습니다.

엔드포인트에서는 실행 환경 내 localhost HTTP API를 통해 간단한 JSON 형식으로 메타데이터를 반환하며 런타임과 확장 프로그램에 모두 액세스할 수 있습니다.

시작하기

Powertools for AWS Lambda에서는 Python, TypeScript, Java 및 .NET의 Lambda 메타데이터 엔드포인트 액세스용 유틸리티를 제공합니다. 유틸리티에서는 첫 번째 직접 호출 후 응답을 캐싱하고 SnapStart 캐시 무효화를 자동으로 처리합니다.

Powertools for AWS Lambda 메타데이터 유틸리티 사용 또는 메타데이터 엔드포인트 직접 호출

Python

Powertools 패키지 설치:

pip install "aws-lambda-powertools"

핸들러에서 메타데이터 유틸리티 사용:

예 Powertools로 AZ ID 검색하기(Python)
from aws_lambda_powertools.utilities.lambda_metadata import get_lambda_metadata def handler(event, context): metadata = get_lambda_metadata() az_id = metadata.availability_zone_id # e.g., "use1-az1" return {"az_id": az_id}
TypeScript

Powertools 패키지 설치:

npm install @aws-lambda-powertools/commons

핸들러에서 메타데이터 유틸리티 사용:

예 Powertools로 AZ ID 검색하기(TypeScript)
import { getMetadata } from '@aws-lambda-powertools/commons/utils/metadata'; const metadata = await getMetadata(); export const handler = async () => { const { AvailabilityZoneID: azId } = metadata; return azId; };
Java

pom.xml에 Powertools 종속성 추가:

<dependencies> <dependency> <groupId>software.amazon.lambda</groupId> <artifactId>powertools-lambda-metadata</artifactId> <version>2.10.0</version> </dependency> </dependencies>

핸들러에서 메타데이터 클라이언트 사용:

예 Powertools로 AZ ID 검색하기(Java)
import software.amazon.lambda.powertools.metadata.LambdaMetadata; import software.amazon.lambda.powertools.metadata.LambdaMetadataClient; public class App implements RequestHandler<Object, String> { @Override public String handleRequest(Object input, Context context) { LambdaMetadata metadata = LambdaMetadataClient.get(); String azId = metadata.getAvailabilityZoneId(); // e.g., "use1-az1" return "{\"azId\": \"" + azId + "\"}"; } }
.NET

Powertools 패키지 설치:

dotnet add package AWS.Lambda.Powertools.Metadata

핸들러에서 메타데이터 클래스 사용:

예 Powertools로 AZ ID 검색하기(.NET)
using AWS.Lambda.Powertools.Metadata; public class Function { public string Handler(object input, ILambdaContext context) { var azId = LambdaMetadata.AvailabilityZoneId; return $"Running in AZ: {azId}"; } }
All Runtimes

모든 런타임에서는 메타데이터 엔드포인트를 지원합니다(사용자 지정 런타임 및 컨테이너 이미지 포함). 다음 예제를 사용하여 Lambda가 실행 환경에서 자동으로 설정하는 환경 변수를 사용하는 함수에서 메타데이터 API에 직접 액세스합니다.

예메타데이터 엔드포인트에 직접 액세스하기
# Variables are automatically set by Lambda METADATA_ENDPOINT="http://${AWS_LAMBDA_METADATA_API}/2026-01-15/metadata/execution-environment" # Make the request RESPONSE=$(curl -s -H "Authorization: Bearer ${AWS_LAMBDA_METADATA_TOKEN}" "$METADATA_ENDPOINT") # Parse the AZ ID AZ_ID=$(echo "$RESPONSE" | jq -r '.AvailabilityZoneID') echo "Function is running in AZ ID: $AZ_ID"

가용 영역 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 - 서버 측 처리 오류입니다.