Lambda 프록시 통합 vs 표준 통합: API Gateway 이벤트 객체 구조 완전 분석

API Gateway를 처음 설정할 때 'Lambda 프록시 통합' 체크박스 하나가 이벤트 객체 구조 전체를 바꾼다는 사실을 모르고 넘어가면, Lambda 핸들러에서 event.body가 undefined로 찍히는 상황을 마주하게 된다. 이 글은 두 통합 방식의 내부 동작 차이와 그로 인한 이벤트 포맷 변화를 실제 운영 관점에서 정리한다.

TL;DR — Lambda 프록시 통합 핵심 요약

항목Lambda 프록시 통합Lambda 표준 통합
이벤트 구조API Gateway가 고정 포맷으로 전달매핑 템플릿으로 개발자가 직접 정의
요청 매핑 템플릿불필요 (자동 처리)필수 작성
응답 매핑 템플릿불필요 (Lambda 반환값 그대로)필수 작성
HTTP 상태코드 제어Lambda 반환 객체 내 statusCode 필드API Gateway 매핑 규칙
헤더 접근event.headers로 직접 접근매핑 템플릿에서 명시적으로 추출 필요
설정 복잡도낮음높음 (VTL 템플릿 작성)
유연성포맷 고정완전한 변환 제어 가능

Lambda 프록시 통합이란 무엇인가

API Gateway에서 Lambda를 백엔드로 사용할 때 두 가지 통합 방식을 선택할 수 있다. Lambda 프록시 통합(Lambda Proxy Integration)은 API Gateway가 HTTP 요청 전체 — 메서드, 경로, 쿼리스트링, 헤더, 바디 — 를 하나의 표준화된 JSON 이벤트 객체로 패키징해서 Lambda에 그대로 전달하는 방식이다. 반대로 Lambda 표준 통합(Lambda Non-Proxy Integration)은 개발자가 Velocity Template Language(VTL)로 작성한 매핑 템플릿을 통해 요청과 응답을 변환하는 방식이다.

프록시 통합에서 'Proxy'라는 단어는 API Gateway가 요청을 가공하지 않고 투명하게 통과시킨다는 의미다. 단, 실제로는 완전한 투과가 아니라 AWS가 정의한 고정 포맷으로 재구성해서 전달한다는 점을 정확히 이해해야 한다.

graph LR Client["클라이언트"] --> APIGW["API Gateway"] APIGW --> ProxyPath["프록시 통합 경로"] APIGW --> StdPath["표준 통합 경로"] ProxyPath -->|"고정 스키마 이벤트
매핑 템플릿 없음"| Lambda1["Lambda 함수"] StdPath -->|"요청 매핑 템플릿(VTL)"| Lambda2["Lambda 함수"] Lambda1 -->|"statusCode + body 반환"| ProxyResp["API Gateway
응답 변환 없음"] Lambda2 -->|"임의 객체 반환"| StdResp["응답 매핑 템플릿(VTL)"] ProxyResp --> Client StdResp --> Client
  1. 클라이언트 요청: HTTP 요청이 API Gateway 엔드포인트에 도달한다.
  2. 프록시 통합 경로: API Gateway가 요청 전체를 고정 포맷 이벤트 객체로 변환해 Lambda를 직접 호출한다. 매핑 템플릿 단계가 없다.
  3. 표준 통합 경로: 요청 매핑 템플릿(VTL)이 먼저 실행되어 이벤트 구조를 변환한 뒤 Lambda를 호출한다. 응답도 응답 매핑 템플릿을 거친다.
  4. Lambda 응답 처리: 프록시 통합은 Lambda 반환 객체를 그대로 HTTP 응답으로 변환한다. 표준 통합은 응답 매핑 템플릿이 HTTP 응답을 구성한다.

Lambda 프록시 통합 이벤트 객체 구조

프록시 통합을 활성화하면 Lambda 핸들러가 수신하는 이벤트 객체는 AWS가 정의한 고정 스키마를 따른다. 이 구조를 모르면 event.body를 파싱하지 않고 객체로 접근하려다 런타임 오류가 발생한다.

🔽 프록시 통합 이벤트 객체 전체 예시 (클릭하여 펼치기) 
{
  "resource": "/users/{userId}",
  "path": "/users/42",
  "httpMethod": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer eyJ...",
    "Host": "abc123.execute-api.us-east-1.amazonaws.com"
  },
  "multiValueHeaders": {
    "Accept": ["text/html", "application/json"]
  },
  "queryStringParameters": {
    "page": "1"
  },
  "multiValueQueryStringParameters": {
    "tag": ["aws", "lambda"]
  },
  "pathParameters": {
    "userId": "42"
  },
  "stageVariables": {
    "env": "prod"
  },
  "requestContext": {
    "resourceId": "abc123",
    "resourcePath": "/users/{userId}",
    "httpMethod": "POST",
    "extendedRequestId": "Xyz123=",
    "requestTime": "01/Jan/2024:00:00:00 +0000",
    "path": "/prod/users/42",
    "accountId": "123456789012",
    "protocol": "HTTP/1.1",
    "stage": "prod",
    "requestId": "abc-def-ghi",
    "identity": {
      "sourceIp": "203.0.113.10",
      "userAgent": "Mozilla/5.0"
    },
    "domainName": "abc123.execute-api.us-east-1.amazonaws.com",
    "apiId": "abc123"
  },
  "body": "{\"name\": \"Alice\", \"email\": \"alice@example.com\"}",
  "isBase64Encoded": false
}

여기서 반드시 짚고 넘어가야 할 점이 있다. body 필드는 문자열이다. JSON 객체가 아니다. 클라이언트가 application/json으로 요청을 보냈더라도, Lambda 핸들러에서는 반드시 JSON.parse(event.body) 또는 json.loads(event.body)로 파싱해야 한다. 이걸 놓치면 event.body.name이 undefined로 나오는 이유를 한참 찾게 된다.

주요 필드 설명

필드타입설명
httpMethodstringHTTP 메서드 (GET, POST 등)
pathstring실제 요청 경로 (경로 파라미터 값 포함)
resourcestringAPI Gateway에 정의된 리소스 패턴
headersobject단일 값 헤더 맵
multiValueHeadersobject동일 키에 여러 값이 있는 헤더 맵
queryStringParametersobject | null단일 값 쿼리스트링 맵
pathParametersobject | null경로 파라미터 맵
bodystring | null요청 바디 (항상 문자열, Base64 인코딩 가능)
isBase64Encodedboolean바디가 Base64 인코딩된 경우 true
requestContextobjectAPI Gateway 컨텍스트 (스테이지, 요청 ID 등)
stageVariablesobject | nullAPI Gateway 스테이지 변수

Lambda 프록시 통합 응답 포맷

프록시 통합에서는 Lambda가 반환하는 객체 구조가 곧 HTTP 응답이 된다. API Gateway가 응답을 변환하지 않기 때문에, Lambda가 잘못된 구조를 반환하면 클라이언트는 502 Bad Gateway를 받는다.

// 올바른 프록시 통합 응답 구조 (Node.js)
exports.handler = async (event) => {
  const body = event.body ? JSON.parse(event.body) : {};

  return {
    statusCode: 200,
    headers: {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*'
    },
    // body는 반드시 문자열이어야 한다
    body: JSON.stringify({
      message: 'success',
      userId: event.pathParameters?.userId
    }),
    isBase64Encoded: false
  };
};

응답 객체에서 statusCode는 필수 필드다. headers와 body는 선택적이지만, body를 포함할 경우 반드시 문자열이어야 한다. 객체를 그대로 반환하면 API Gateway가 직렬화하지 않고 오류를 낸다.

표준 통합에서 이벤트 객체가 달라지는 이유

표준 통합(비프록시)에서는 Lambda가 수신하는 이벤트 구조를 개발자가 완전히 제어한다. API Gateway 콘솔에서 '통합 요청' 섹션의 매핑 템플릿에 VTL을 작성하면, 그 템플릿의 출력이 Lambda 이벤트 객체가 된다.

## 표준 통합 요청 매핑 템플릿 예시 (VTL)
{
  "userId": "$input.params('userId')",
  "name": $input.json('$.name'),
  "sourceIp": "$context.identity.sourceIp",
  "stage": "$context.stage"
}

이 템플릿을 사용하면 Lambda가 받는 이벤트는 다음과 같이 단순해진다:

{
  "userId": "42",
  "name": "Alice",
  "sourceIp": "203.0.113.10",
  "stage": "prod"
}

프록시 통합의 거대한 이벤트 객체 대신 Lambda가 필요한 데이터만 정제해서 받는다. 레거시 시스템 연동이나 Lambda 코드를 API Gateway 구조로부터 완전히 분리하고 싶을 때 표준 통합이 유리한 이유다.

graph TD Req["HTTP POST /users/42
body: JSON 객체"] --> APIGW["API Gateway"] APIGW --> ProxyEvt["프록시 통합 이벤트"] APIGW --> StdEvt["표준 통합 이벤트"] ProxyEvt --> P1["event.httpMethod: POST"] ProxyEvt --> P2["event.pathParameters.userId: 42"] ProxyEvt --> P3["event.body: 문자열 (JSON.parse 필요)"] ProxyEvt --> P4["event.headers: 전체 헤더"] ProxyEvt --> P5["event.requestContext: API GW 메타데이터"] StdEvt --> S1["event.userId: 42 (VTL 추출)"] StdEvt --> S2["event.name: Alice (VTL 파싱)"] StdEvt --> S3["개발자 정의 필드만 포함"]
  1. 프록시 통합 이벤트: headers, queryStringParameters, pathParameters, body(문자열), requestContext 등 HTTP 요청 전체가 포함된 고정 스키마 객체가 전달된다.
  2. 표준 통합 이벤트: VTL 매핑 템플릿이 정의한 필드만 포함된 커스텀 객체가 전달된다. 구조는 개발자가 완전히 결정한다.
  3. body 처리 차이: 프록시 통합에서는 Lambda가 직접 JSON.parse(event.body)를 수행해야 한다. 표준 통합에서는 VTL의 $input.json()이 이미 파싱된 값을 이벤트에 포함시킬 수 있다.

실제 장애 패턴: 잘못된 가정이 만드는 502 오류

프로덕션에서 자주 보이는 패턴이 있다. 로컬 테스트는 잘 되는데 API Gateway를 통하면 502 Bad Gateway가 간헐적으로 발생한다. CloudWatch 로그를 보면 Lambda 자체는 정상 실행됐다. 이 경우 십중팔구 응답 구조 문제다.

Lambda가 다음처럼 반환하면 프록시 통합에서 502가 발생한다:

// 잘못된 응답 — 502 유발
return {
  message: 'success',
  data: { userId: 42 }
};

// 올바른 응답
return {
  statusCode: 200,
  body: JSON.stringify({ message: 'success', data: { userId: 42 } })
};

처음에는 Lambda 코드 버그나 타임아웃을 의심하게 된다. 하지만 실제 원인은 API Gateway가 statusCode 필드를 찾지 못해서 응답을 구성할 수 없는 것이다. Lambda 실행 자체는 성공했으니 Lambda 오류 로그는 없고, API Gateway 액세스 로그에서 통합 응답 오류를 확인해야 원인을 찾을 수 있다.

프록시 통합에서 API Gateway는 Lambda 응답을 신뢰한다. Lambda가 올바른 HTTP 응답 구조를 반환할 책임이 완전히 Lambda 코드로 이동한다는 뜻이다. 표준 통합에서는 이 책임이 매핑 템플릿에 있다.

CLI로 통합 방식 확인 및 설정

기존 API의 통합 방식을 확인하거나 변경할 때 AWS CLI를 사용할 수 있다. REST API 기준으로 설명한다.

현재 통합 방식 확인

# 특정 리소스의 메서드 통합 정보 조회
aws apigateway get-integration \
  --rest-api-id abc123defg \
  --resource-id xyz789 \
  --http-method POST \
  --region us-east-1

응답의 type 필드가 AWS_PROXY이면 Lambda 프록시 통합, AWS이면 표준 통합이다.

프록시 통합으로 설정

# Lambda 프록시 통합 설정
aws apigateway put-integration \
  --rest-api-id abc123defg \
  --resource-id xyz789 \
  --http-method POST \
  --type AWS_PROXY \
  --integration-http-method POST \
  --uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:MyFunction/invocations \
  --region us-east-1

Lambda 호출 권한 부여

통합 방식과 무관하게, API Gateway가 Lambda를 호출하려면 리소스 기반 정책이 필요하다.

aws lambda add-permission \
  --function-name MyFunction \
  --statement-id apigateway-invoke \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn arn:aws:execute-api:us-east-1:123456789012:abc123defg/*/POST/users \
  --region us-east-1

언제 어떤 통합 방식을 선택해야 하는가

graph TD Start["새 API Gateway + Lambda 설계"] --> Q1{"Lambda 코드가 API Gateway
구조를 알아도 되는가?"} Q1 -->|"예"| Q2{"VTL 작성/유지 리소스가
있는가?"} Q1 -->|"아니오 (포터블 로직 필요)"| Std["표준 통합 선택
(VTL로 이벤트 정제)"] Q2 -->|"아니오 / 빠른 개발 우선"| Proxy["프록시 통합 선택
(AWS_PROXY)"] Q2 -->|"예 + 레거시 스키마 호환 필요"| Std Proxy --> Note1["body는 JSON.parse 필수
응답에 statusCode 필수"] Std --> Note2["요청/응답 매핑 템플릿
모두 작성 필요"]

실무에서 대부분의 신규 프로젝트는 Lambda 프록시 통합을 선택한다. 설정이 단순하고, Lambda 코드 안에서 요청 처리 로직을 모두 제어할 수 있기 때문이다. VTL 매핑 템플릿은 학습 곡선이 있고, 디버깅이 어렵다.

표준 통합이 유리한 경우는 다음과 같다:

  • Lambda 코드가 API Gateway 구조를 전혀 몰라야 하는 경우 (포터블한 비즈니스 로직)
  • 요청 데이터를 API Gateway 레이어에서 사전 검증하거나 변환해야 하는 경우
  • 레거시 Lambda 함수가 특정 이벤트 스키마를 기대하는 경우

Lambda 프록시 통합 관련 IAM 고려사항

통합 방식 자체는 IAM 실행 역할과 직접적인 관계가 없다. 그러나 API Gateway가 Lambda를 호출하는 권한 모델은 두 방식 모두 동일하게 적용된다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "apigateway.amazonaws.com"
      },
      "Action": "lambda:InvokeFunction",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction",
      "Condition": {
        "ArnLike": {
          "AWS:SourceArn": "arn:aws:execute-api:us-east-1:123456789012:abc123defg/*/*/*"
        }
      }
    }
  ]
}

Condition의 AWS:SourceArn을 특정 API와 스테이지로 제한하면 다른 API Gateway 인스턴스에서 동일 Lambda를 호출하는 것을 방지할 수 있다. 최소 권한 원칙 적용 시 와일드카드 *보다 구체적인 ARN을 사용하는 것이 권장된다.

Lambda 프록시 통합 마무리 및 다음 단계

Lambda 프록시 통합은 API Gateway와 Lambda를 연결하는 가장 직관적인 방법이다. 이벤트 객체의 고정 스키마를 이해하고, body가 문자열이라는 점, 응답에 statusCode가 필수라는 점만 정확히 파악하면 대부분의 운영 이슈를 예방할 수 있다.

HTTP API(API Gateway v2)를 사용하는 경우 이벤트 포맷이 REST API와 다르다. HTTP API의 Lambda 통합은 payload format version 1.0과 2.0을 지원하며, 2.0 포맷은 구조가 단순화되어 있다. 새 프로젝트라면 HTTP API와 payload format 2.0 조합도 검토할 가치가 있다.

핵심 용어 정리

용어설명
Lambda 프록시 통합 (AWS_PROXY)API Gateway가 HTTP 요청을 고정 스키마 이벤트 객체로 변환해 Lambda에 전달하는 통합 방식. 매핑 템플릿 불필요.
Lambda 표준 통합 (AWS)VTL 매핑 템플릿으로 요청/응답을 변환하는 통합 방식. 이벤트 구조를 개발자가 정의.
VTL (Velocity Template Language)API Gateway 표준 통합에서 요청/응답 변환에 사용하는 템플릿 언어.
isBase64Encoded프록시 통합 이벤트/응답에서 바디가 Base64 인코딩되었는지 나타내는 플래그. 바이너리 데이터 처리 시 사용.
requestContext프록시 통합 이벤트 내 API Gateway 메타데이터 객체. 스테이지, 요청 ID, 인증 컨텍스트 등 포함.

Related Posts

댓글

댓글 쓰기

이 블로그의 인기 게시물

EC2 SSH 연결 타임아웃 완전 해결 가이드: Security Group 인바운드 규칙부터 라우팅까지

새로 생성한 EC2 인스턴스에 SSH로 접속하려는데 'Connection timed out' 에러가 뜨는 상황은, AWS를 처음 쓰는 엔지니어뿐 아니라 경험 있는 운영자도 종종 마주친다. 문제는 단순히 Security Group 포트 하나가 아니라, Security Group → Network ACL → 라우팅 테이블 → 인스턴스 상태 까지 여러 레이어가 겹쳐 있다는 점이다. 이 글에서는 EC2 SSH 연결 타임아웃의 실제 원인을 레이어별로 진단하고, CLI 기반으로 빠르게 수정하는 방법을 다룬다. TL;DR — EC2 SSH 연결 타임아웃 빠른 진단표 진단 레이어 확인 항목 가장 흔한 원인 Security Group (인바운드) TCP 22 허용 여부, 소스 IP 포트 22 규칙 누락 또는 소스 0.0.0.0/0 미설정 Network ACL 인바운드 22 허용, 아웃바운드 임시 포트 허용 아웃바운드 임시 포트(1024-65535) 차단 라우팅 테이블 Internet Gateway 연결 여부 Public Subnet에 IGW 라우트 없음 퍼블릭 IP / EIP 인스턴스에 퍼블릭 IP 할당 여부 퍼블릭 IP 없이 직접 접속 시도 인스턴스 상태 Status Check 통과 여부 System/Instance reachability 실패 EC2 SSH 연결이 어떻게 동작하는가 SSH 연결 요청이 EC2에 도달하기까지 거치는 경로를 이해하지 않으면, 어느 레이어에서 막혔는지 추측에 의존하게 된다. 패킷은 인터넷 → IGW → 서브넷 → Network ACL → Security Group → 인스턴스 순서로 흐른다. 각 레이어는 독립적으로 동작하며, 하나라도 막히면 클라이언트 입장에서는 동일하게 타임아웃으로 보인다. graph LR Client["클라이언트"] ...
자세한 내용 보기

EC2 SSH 연결 시간 초과: 확인해야 할 보안 그룹(Security Group) 규칙

EC2 SSH 연결 시간 초과(Connection timeout)는 새 인스턴스를 시작할 때 가장 흔히 발생하는 장애물 중 하나입니다. 해결 방법은 거의 항상 보안 그룹(Security Group)의 인바운드 규칙이 누락되었거나 잘못 구성된 경우입니다. 요약 — 한눈에 보는 진단 단계 단계 확인할 사항 일반적인 해결 방법 1 보안 그룹(Security Group) 인바운드 규칙 사용자 IP로부터의 SSH (TCP 22) 추가 2 서브넷 라우팅 테이블(Route table) 0.0.0.0/0이 인터넷 게이트웨이(IGW)로 라우팅되는지 확인 3 네트워크 ACL(Network ACL) 규칙 인바운드 TCP 22 및 임시(ephemeral) 반환 포트 허용 4 인스턴스 퍼블릭 IP / 탄력적 IP(Elastic IP) 퍼블릭 IP가 할당되었는지 확인 5 키 페어(Key pair) 및 SSH 사용자 이름 올바른 프라이빗 키 및 AMI 전용 사용자 이름 사용 SSH 연결이 거부(Refused)되지 않고 시간 초과(Timeout)되는 이유 연결 거부(Connection refused) 오류는 TCP 핸드셰이크가 호스트에 도달했으나 대기 중인 서비스가 없음을 의미합니다. 반면 연결 시간 초과(Connection timed out) 오류는 패킷이 도달하지 못했거나 응답이 돌아오지 못했음을 의미합니다. EC2에서 이러한 무응답은 거의 항상 OS 수준의 문제가 아닌 네트워크 계층에서의 차단 때문입니다. 인스턴스 수준의 상태 저장(stateful) 방화벽인 보안 그룹(Security Group)이 가장 먼저 의심해야 할 빈번한 원인입니다. blockquote> 비유: 보안 그룹을 인스턴스 문 앞의 경비원이라고 생각해 보세요. SSH(포트 22)가 게스트 목록에 없으면 패킷은 거부 알림도 받지 못한 채 밖에서...
자세한 내용 보기

IAM User vs IAM Role 차이점 완전 정리 — EC2에서 S3 접근 시 무엇을 써야 하는가

IAM User와 IAM Role의 차이를 명확히 이해하지 못하면, EC2 인스턴스에서 S3에 접근할 때 자격증명을 하드코딩하거나 불필요하게 장기 키를 발급하는 실수를 반복하게 된다. 이 글은 두 개념의 구조적 차이와, EC2 인스턴스가 S3에 접근하는 실제 운영 시나리오 에서 어떤 선택이 올바른지를 명확히 설명한다. TL;DR — IAM User vs IAM Role 핵심 비교 EC2 인스턴스에서 S3에 접근할 때는 IAM Role(인스턴스 프로파일)을 사용하는 것이 AWS 공식 권장 방식이다. IAM User의 액세스 키를 인스턴스에 직접 저장하는 방식은 키 노출 위험이 있고, 자격증명 교체 비용이 높다. 항목 IAM User IAM Role 자격증명 유형 장기 액세스 키 (Access Key ID + Secret) 임시 보안 토큰 (STS 발급) 주체(Principal) 사람 또는 애플리케이션 AWS 서비스, 계정, 사람 등 자격증명 수명 명시적으로 삭제하기 전까지 유효 기본 1시간, 최대 12시간 (설정에 따라 다름) EC2 사용 권장 여부 ❌ 비권장 (키 하드코딩 위험) ✅ 권장 (인스턴스 프로파일) 자격증명 자동 교체 수동 교체 필요 STS가 자동 갱신 멀티 계정 접근 제한적 Cross-account Role Assumption 지원 IAM User와 IAM Role의 작동 원리 IAM User는 AWS 계정 내에 영구적으로 존재하는 자격증명 주체다. 콘솔 로그인용 패스워드와 API 호출용 액세스 키를 가지며, 이 키는 명시적으로 비활성화하거나 삭제하지 않는 한 계속 유효하다. 사람이 직접 AWS 콘솔이나 CLI를 사용하는 경우에 적합하다. IAM Role은 자격증명을 '소유'하는 개체가 아니라, 특정 조건에서 '위임'받아 사용하는 권한 집합이...
자세한 내용 보기