AWS Section 23-1. AWS 서버리스 : API 게이트웨이

 

지금까지 AWS Lambda와 DynamoDB를 통해 서버리스 애플리케이션을 구축했다.
API Gateway를 통해 이 함수를 서버리스 상태에서 노출하기 위한 방법과 Rest API를 이용해 애플리케이션으로 액세스하게끔 하는 방법을 알아볼 것!! + Amazon Cognito로 사용자 인증하는 방법까지 배우게 된다.  

 

 

 

Example - Building a Serverless API

클라이언트는 Lambda 함수에 직접 접근하지 않고 API Gateway를 통해 접근

 

Lambda 함수는 DynamoDB 테이블을 활용해 데이터의 생성, 읽기, 업데이트, 삭제(CRUD)를 수행할 수 있다.

 

Lambda 함수 호출 방법:

• 직접 호출: 클라이언트에 IAM 권한을 부여해 Lambda 함수에 직접 접근할 수 있다.
• 애플리케이션 로드 밸런서(ALB): HTTP 엔드포인트로 Lambda 함수에 접근할 수 있도록 한다.
• API Gateway: 클라이언트가 접근할 수 있는 REST API를 제공하며, Lambda 함수로 요청을 프록시한다. 인증, 요금제, 개발 단계 설정 등 다양한 관리 기능을 지원해 서버리스 환경에서 가장 추천되는 방식이다.

 

 

AWS API Gateway의 기능

• Lambda와 결합하면 완전히 서버리스한 애플리케이션을 만들 수 있다. 즉 관리할 인프라가 없는 것이다.
• WebSocket 지원으로 실시간 스트리밍이 가능하며, 다양한 환경(dev, test, prod 등)을 지원한다.
• API 버저닝을 지원한다. v1, v2 등 다양한 버전으로 API를 관리하기 때문에, v1에서 v2,3으로 변경할 수 있고, 클라이언트를 중단하지 않는다.
• 인증과 권한 부여 기능이 있으며,  API 키 생성해 클라이언트가 API 게이트웨이에 요청을 많이 보낼 때 쓰로틀링을 요청할 수 있다.
• Swagger 및 OpenAPI 3.0을 통해 API를 정의하고 내보낼 수 있다.
• 요청 및 응답 변환, 검증, SDK 생성, 캐시 기능 등 다양한 옵션을 제공한다.

 

API Gateway – Integrations High Level

 

API Gateway는 Lambda 함수, HTTP, AWS 서비스와 통합될 수 있다:

• Lambda Function
  • Lambda 함수를 호출하여 REST API를 외부에 노출하는 방식으로 많이 사용된다.
• HTTP 통합
  • 모든 HTTP 엔드포인트를 백엔드로 노출할 수 있어 온프레미스 API나 로드 밸런서를 사용할 수 있다. 예를 들어, 속도 제한이나 사용자 인증이 필요한 HTTP 엔드포인트에 API Gateway를 사용하면 유용하다.
• AWS Service
  • Step Functions, SQS, Kinesis Data Streams 등과의 연동을 통해 데이터를 안전하게 전송하고 속도 제한, 인증 등을 수행할 수 있다.

 

API Gateway – AWS 서비스 통합 예시 (Kinesis Data Streams)

• 클라이언트 요청이 API Gateway로 전달되고, 이를 통해 Kinesis Data Streams에 데이터를 보낸다. 이 데이터는 Kinesis Data Firehose를 통해 변환/처리되며, 최종적으로 JSON 파일로 Amazon S3에 저장된다.

 

API Gateway 엔드포인트 타입

• Edge-Optimized (기본): 전 세계의 CloudFront Edge를 통해 지연 시간을 최소화하며 글로벌 사용자를 대상으로 한다.
• Regional: 특정 리전 내의 클라이언트를 위한 배포 방식이다. 필요에 따라 CloudFront와 수동으로 결합하여 캐싱과 배포 전략을 제어할 수 있다.
• Private: VPC 내에서만 접근 가능한 프라이빗 API 게이트웨이이다. VPC 엔드포인트를 사용해 안전하게 액세스를 제어하며, 리소스 정책으로 접근 권한을 정의할 수 있다.

 

API Gateway - 보안 및 인증 방식

• 사용자 인증
  • IAM 역할을 통한 내부 애플리케이션 접근 제어,
  • 모바일 및 웹 애플리케이션 사용자 등 외부 사용자에 대해 인증을 수행하는 Amazon Cognito,
  • Lambda 함수를 사용하여 고유한 인증 로직을 구현하는 Custom Authorizer 등을 지원한다.
• HTTPS 보안
  • AWS Certificate Manager(ACM)로 사용자 지정 도메인에 HTTPS 보안을 설정할 수 있다
  • Edge-Optimized와 Regional 엔드포인트에 따라 인증서 요구 사항이 달라지며,
  • Route 53에서 CNAME이나 A-alias 레코드를 통해 도메인과 API Gateway를 연결할 수 있다.

 

API Gateway – 배포

• API 변경과 배포
  • API Gateway에서 API 변경 후, 이를 배포해야 적용된다. 변경 사항이 배포되지 않으면 API는 갱신되지 않아 작동하지 않는다.
• 스테이지
  • 배포의 단위를 의미하며 원하는만큼 생성할 수 있다.
  • .각 스테이지는 독립된 환경으로, 예를 들어 dev, test, prod, 또는 v1, v2 등으로 이름을 지정할 수 있다. 
  • 스테이지는 배포 이력이 기록되므로 롤백이 가능하다.

 

스테이지를 이용해 각 Lambda 함수 버전을 독립적으로 관리하고, 클라이언트를 점진적으로 새로운 스테이지(v2)로 이동시키는 방식

 

API의 중요한 변경 사항이 있을 경우, 새로운 스테이지를 만들어 기존 클라이언트와의 호환성을 유지할 수 있다.

• v1 스테이지 URL을 사용하는 클라이언트는 V1 Lambda에 연결되고, v2 URL을 사용하는 클라이언트는 V2 Lambda에 연결된다.
• 스테이지별 버전 독립성 유지: 새로운 버전의 함수를 호출하는 새 스테이지(v2)를 생성하여 호환성 문제를 피할 수 있다. 이후 클라이언트를 점진적으로 새 스테이지로 이동시키고, 기존 스테이지(v1)를 종료할 수 있다.

 

API Gateway – 스테이지 변수

 

스테이지 변수(stage variables)는 API Gateway의 각 스테이지에서 사용하는 설정 값이다. API를 다시 배포하지 않고도 설정을 변경할 수 있다.

 

• Lambda 함수 ARN, HTTP 엔드포인트, 매개변수 매핑 템플릿 등을 스테이지 변수로 정의해 자동으로 환경에 따라 구성 값을 변경할 수 있다.
• dev, test, prod 스테이지에서 자동으로 다른 HTTP 엔드포인트를 지정 가능하다.
• 스테이지 변수는 Lambda 함수의 컨텍스트 객체에 전달되며, Lambda 함수 내부에서 로그를 통해 스테이지 변수에 접근할 수 있다.
  • API Gateway에서 스테이지 변수에 접근할 때는 ${stageVariables.variableName} 형식을 사용한다.

 

 

API Gateway Stage Variables & Lambda Aliases

특정 스테이지 변수를 생성해 Lambda의 별칭을 가리키도록 설정하면, 자동으로 올바른 Lambda 함수를 호출할 수 있다.

 

 

• Dev 스테이지는 DEV 별칭을 가리키고, 이는 최신(LATEST) Lambda 버전을 100% 호출한다.
• Test 스테이지는 TEST 별칭을 통해 Lambda 함수의 V2 버전을 호출한다.
• Prod 스테이지는 PROD 별칭 을 가리키며, 트래픽의 95%는 V1, 5%는 V2로 분배된다.

>> Lambda 별칭을 통한 트래픽 조정: 스테이지 변수와 별칭을 활용하면 API Gateway를 수정하지 않고도 Lambda 함수 버전을 변경하고 트래픽 비율을 조정할 수 있다.

 

 

API Gateway – Canary Deployment

Canary 배포는 API Gateway의 새로운 버전을 프로덕션 환경에서 소량의 트래픽으로 테스트하는 방법이다. 이를 통해 전체 트래픽에 영향을 주지 않고 새 버전의 변경 사항을 검증할 수 있다.

 

• 트래픽 비율 설정: 새로운 버전을 배포할 때 카나리 채널이 수신할 트래픽 양을 설정할 수 있다. 예를 들어, Prod 스테이지에서 기존 버전(v1)에 95%의 트래픽을 유지하면서, 나머지 5%의 트래픽을 새로운 버전(v2)에 보내도록 설정할 수 있다. >> 새로운 버전(v2)을 Canary 단계에서 테스트하면서도 대부분의 트래픽은 안정적인 기존 버전(v1)으로 유지된다.

 

• Metrics & Logs 분리: 5%의 트래픽으로 새로운 버전을 테스트하며, 이를 통해 지표와 로그를 수집해 변경 사항을 검토할 수 있다. (지표와 로그가 기존 프로덕션과 별도로 기록) 이 과정에서 발생하는 에러나 예상치 못한 동작을 확인하고 디버깅할 수 있다.
• 트래픽 점진적 이동: 테스트가 성공적이면, 점진적으로 더 많은 트래픽을 카나리 단계(새 버전)로 이동시킬 수 있다. 준비가 완료되면 100%의 트래픽을 새로운 버전으로 전환해 기존 버전을 대체한다.
• 모니터링 및 변수 재정의: 카나리 단계에서의 테스트가 끝나면 Prod 스테이지에 새로운 버전을 적용하면서, 필요에 따라 원하는 단계 변수를 재정의할 수 있다. 이를 통해 API Gateway와 Lambda를 사용한 블루/그린 배포와 유사한 방식으로 안전하게 새 버전을 배포할 수 있다.

 

 

API Gateway – Integration Types

API Gateway는 다양한 통합 유형을 지원하며, 이를 통해 백엔드와 클라이언트 간의 데이터를 효율적으로 처리할 수 있다.

• MOCK 통합
  
  • 백엔드로 요청을 전송하지 않고도 API Gateway가 응답을 반환한다.
  • 주로 백엔드가 완전히 구축되기 전 개발 및 테스트 용도로 사용된다.
  • 프로덕션보다는 개발과 테스트 단계에서 주로 사용한다.
• HTTP / AWS 통합 (Lambda 및 기타 AWS 서비스)
  • API Gateway 가 백엔드로 요청을 전달할 때 요청과 응답을 구성할 수 있다.
  • 요청 및 응답 매핑 템플릿을 사용하여 데이터 매핑을 할 수 있다. 이를 통해 백엔드로 전송되는 요청을 변경하거나, 백엔드 응답을 클라이언트에게 보내기 전에 수정할 수 있다.

 

클라이언트에서 API Gateway를 거쳐 SQS Queue로 전송되는 트래픽 흐름

• 클라이언트가 REST API로 요청을 보내면, API Gateway는 매핑 템플릿을 통해 이 요청을 SQS Queue가 이해할 수 있도록 변환하여 전달한다.

 

AWS_PROXY 통합 (Lambda 프록시 통합)

AWS_PROXY는 Lambda 프록시로, 클라이언트 요청을 Lambda로 직접 전달하는 방식이다.

• 클라이언트의 요청이 Lambda 함수의 입력이 되는 통합 유형이다.
• 요청이나 응답을 수정할 수 없고, 모든 요청과 응답 처리가 Lambda 함수 내에서만 이루어진다.
• 매핑 템플릿을 사용할 수 없으며, 모든 파라미터가 Lambda 함수에 인자로 직접 전달되며 함수는 요청 및 응답의 논리만 담당한다. .
• 예를 들어 Lambda 함수에서 API Gateway의 요청을 확인할 수 있으며, JSON 형태로 리소스, 경로, HTTP 메서드, 헤더 등이 포함된다.

• Lambda 요청 및 응답 형식
  • 요청은 JSON 형식으로 전달되며, resource, path, httpMethod, headers, queryStringParameters 등이 포함된다.
  • Lambda 함수가 작업을 처리하고 statusCode, headers, body 등의 정보를 담아 응답한다.

 

 

HTTP_PROXY 통합 (HTTP 프록시 통합)

HTTP_PROXY는 클라이언트의 HTTP 요청을 백엔드로 직접 전달하고, 백엔드의 응답을 그대로 클라이언트에 전달하는 방식이다.

• 매핑 템플릿 없이 API Gateway가 요청을 백엔드로 직접 프록시하는 방식이다.
• 백엔드에서 응답이 오면 API Gateway는 요청을 프록시하고 응답을 다시 클라이언트에 전달하는 역할만 수행한다.
• 필요에 따라 HTTP 헤더를 추가할 수 있으며, API 키를 백엔드에 전달하여 보안을 강화할 수 있다.
• 예를 들어 클라이언트가 API Gateway에 HTTP 요청을 보내면 API Gateway가 이 요청을 백엔드로 전달하고, 백엔드가 응답을 반환하면 그대로 클라이언트로 전달한다.

•  

• 클라이언트에서 API Gateway를 거쳐 애플리케이션 로드 밸런서로 요청되는 흐름
  • HTTP 요청은 API Gateway를 통해 로드 밸런서로 전달되며, API 키와 같은 헤더를 추가해 요청을 보호할 수 있다.

 

 

Mapping Templates (AWS & HTTP Integration)

Mapping Templates는 AWS 서비스나 HTTP 통합에서 요청 및 응답을 수정하는 데 사용된다.

• 기능
  • 프록시 방식이 아닌 AWS 서비스나 HTTP 통합에서 요청과 응답을 수정하기 위해 매핑 템플릿을 사용할 수 있다.
  • 매핑 템플릿을 사용하여 쿼리 문자열 매개변수의 이름을 변경하거나, 본문 콘텐츠를 수정하거나, 헤더를 추가 또는 수정할 수 있다.
  • 이때 VTL(Velocity Template Language)를 사용해 if, for문 등의 로직을 통해 요청을 스크립트로 수정할 수 있다.
  • 특정 결과를 필터링하거나 불필요한 데이터를 제거할 수 있으며, 콘텐츠 유형을 application/json 또는 application/xml로 설정할 수 있다.

 

Mapping Example – JSON to XML with SOAP

 

• SOAP API는 XML을 사용하는 반면, REST API는 JSON을 사용한다.
• API Gateway는 JSON과 XML 간의 변환을 통해 클라이언트가 JSON 형식으로 상호작용할 수 있게 한다.

 

• 변환 과정 : 매핑 템플릿을 통해 JSON 요청을 XML로 변환해 SOAP API로 보내고, XML 응답을 JSON으로 변환해 클라이언트에 반환할 수 있다. 
  • API Gateway는 요청 경로, 페이로드, 헤더 등에서 데이터를 추출하여 SOAP 메시지를 생성하고, 이를 SOAP API에 전달한다.
  • SOAP 서비스에서 XML 응답을 받으면, 이를 JSON으로 변환해 클라이언트에 전달한다.

 

 

Mapping Example – Query String Parameters

API Gateway는 쿼리 문자열 매개변수를 Lambda에 전달하기 전에 매핑 템플릿을 사용해 변수 이름을 변경할 수 있다.

• 예시
  
  • 클라이언트가 ?name=foo&other=bar 형식으로 요청을 보낸 경우, API Gateway는 매핑 템플릿을 사용해 name을 my_variable, other를 other_variable로 변환해 Lambda에 전달할 수 있다.

클라이언트 요청의 쿼리 문자열이 매핑 템플릿을 통해 JSON 형식으로 변환되어 Lambda에 전달된다.

 

 

 

API Gateway – Open API Spec

• OpenAPI 스펙이란?
  • OpenAPI 스펙은 REST API를 정의하는 일반적인 방법이다. API 정의 자체가 코드의 역할을 한다.
  • OpenAPI 모델 3.0을 사용하여 스펙을 작성할 수 있으며, 이를 API Gateway로 임포트(import)할 수 있다.
  • 메서드, 메서드 요청, 통합 요청, 메서드 응답 등의 설정이 가능하며, API Gateway에서 사용하는 AWS 확장 옵션을 스펙 안에서 직접 정의할 수도 있다.
• 임포트 및 엑스포트 기능
  • OpenAPI 스펙을 API Gateway에 임포트하여 API 설정을 빠르게 구성할 수 있다.
  • 반대로 API Gateway에서 이미 설정한 API를 OpenAPI 스펙으로 엑스포트(export)할 수도 있다.
  • 스펙을 엑스포트하면 이를 기반으로 클라이언트 코드를 생성할 수 있고, 클라이언트 SDK를 YAML 또는 JSON 형태로 생성할 수 있다.

 

REST API – 요청 검증

API Gateway는 OpenAPI 스펙을 이용해 요청을 검증할 수 있다.

백엔드로 요청을 보내기 전에 API Gateway가 해당 요청이 올바른 스키마에 맞는지 확인할 수 있다.

• 검증 실패 시
  • 검증에 실패하면 API Gateway가 즉시 요청을 거부하고 400 오류를 반환하여 불필요한 백엔드 호출을 줄인다.

• 요청 검증을 통해 URI, 쿼리 문자열, 헤더의 존재 여부나 비어 있지 않은지 여부를 확인할 수 있다.
• 또한 JSON 스키마에 맞는 페이로드인지도 검증할 수 있다.

 

 

REST API – RequestValidation – OpenAPI

OpenAPI 정의 파일에서 x-amazon-apigateway-request-validator라는 필드를 설정하여 검증을 정의할 수 있다.

• 모든 메서드 또는 특정 메서드에서 요청의 본문(body)과 파라미터(parameter)를 검증할 수 있다.
• params-only 검증자를 설정하여 파라미터만 검증하거나, 특정 메서드에 대해 전체 검증을 적용할 수도 있다.

OpenAPI 정의 파일에서 x-amazon-apigateway-request-validator 속성을 사용해 API 메서드에 대해 params-only 또는 전체 검증을 설정한 예시

• 검증의 장점
  • 요청 검증을 통해 잘못된 요청이 백엔드로 전달되는 것을 방지하여 시스템 효율성을 높일 수 있다.
  • 페이로드가 백엔드가 기대하는 스키마를 따르는지 확인함으로써, 백엔드에서의 파싱 및 처리 오류를 줄일 수 있다.

 

 

API Gateway에서의 응답 캐싱

• 캐싱은 백엔드에 대한 호출 수를 줄여 백엔드에 가해지는 부담을 줄이는 데 사용된다.
• 클라이언트가 요청할 때 API Gateway는 먼저 캐시를 확인하고, 결과가 캐시에 있으면 백엔드 호출 없이 응답을 반환한다.'

 

• 기본 TTL (Time to Live)
  • 기본 TTL은 300초(5분)이며, 최소 0초(캐싱 없음)부터 최대 1시간까지 설정 가능하다.

• 캐시 적용 범위
  • 캐시는 단계(Stage) 수준에서 정의되며, 각 단계당 하나의 캐시가 생성된다.
  • 메서드별로 캐시 설정을 재정의할 수 있어 특정 메서드에 대해 캐싱을 비활성화할 수 있다.
• 캐시 크기와 비용
  • 캐시 크기는 0.5GB에서 237GB까지 설정 가능하다.
  • 캐싱 비용이 높기 때문에 운영 환경에서 사용하는 것이 효율적이며, 개발이나 테스트 환경에서는 불필요할 수 있다.

• 캐시 확인 흐름
  • 클라이언트 요청이 API Gateway로 전달되면, 먼저 Gateway Cache를 확인하고 캐시에 결과가 있으면 해당 데이터를 반환한다. 캐시가 없으면 백엔드와 통신하여 응답을 받는다.

 

 

캐시 무효화 방법

API Gateway에서 캐시를 무효화(Invalidate)하는 방법으로 전체 캐시를 즉시 삭제하거나, 특정 클라이언트가 특정 리소스의 캐시를 무효화할 수 있다.

• 전체 캐시 무효화
  • UI를 통해 전체 캐시를 즉시 무효화할 수 있다.
• 클라이언트 기반 캐시 무효화
  • 클라이언트가 Cache-Control: max-age=0 헤더를 포함한 요청을 보내 캐시를 무효화할 수 있으며, 이를 위해서는 적절한 IAM 인증이 필요하다.
• IAM 정책
  • 특정 리소스에 대한 캐시 무효화 권한을 부여하는 IAM 정책이 필요하다. 만약 이 정책이 없거나 인증 요구가 설정되지 않은 경우, 모든 클라이언트가 캐시를 무효화할 수 있어 예상치 못한 문제가 발생할 수 있다.

• IAM 정책 예시
  • execute-api:InvalidateCache 권한을 포함한 정책이 특정 리소스에 대해 정의되어 있으며, 이를 통해 특정 클라이언트가 해당 리소스의 캐시를 무효화할 수 있도록 한다.