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

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

Lambda 메타데이터 엔드포인트를 사용하면 함수가 현재 실행 중인 가용 영역(Availability Zone, AZ)을 알아낼 수 있어요. 이를 활용해 Amazon ElastiCache와 Amazon RDS 엔드포인트 같은 같은 AZ의 리소스로 라우팅해 지연 시간을 최적화하고, AZ 인식 복원력(resilience) 패턴을 구현할 수 있죠.

이 엔드포인트는 실행 환경 내의 localhost HTTP API를 통해 간단한 JSON 형식으로 메타데이터를 반환하며, 런타임과 확장(extension) 모두 접근할 수 있어요.

출처: AWS Lambda 개발자 안내서

본문

Topics(주제)

시작하기

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 런타임이 메타데이터 엔드포인트를 지원해요. 커스텀 런타임과 컨테이너 이미지도 포함하죠. 다음 예제처럼 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_...KEN}" "$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 ID를 AZ 이름으로 변환:

AZ ID를 AZ 이름으로 변환하려면 Amazon 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 – AWS_LAMBDA_METADATA_TOKEN 환경 변수의 토큰 값에 Bearer 스킴을 붙인 것: Bearer <token>. 이 토큰 기반 인증은 SSRF(Server-Side Request Forgery) 취약점에 대한 심층 방어(defense in depth) 보호를 제공해요. 각 실행 환경은 초기화 시 고유하고 무작위로 생성된 토큰을 받아요.

응답

상태: 200 OK

Content-Type: application/json

Cache-Control: private, max-age=43200, immutable

응답은 실행 환경 내에서 변경 불가(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 – 서버 측 처리 오류예요.

더 알아보기 (Learn more)

  • 실행 환경이 어느 AZ인지 조회해 같은 AZ 리소스로 라우팅하거나, Powertools 유틸리티와 API를 직접 호출해 커스텀 런타임·컨테이너 이미지에서도 활용하세요.