Micro-services & API Gateway Governance

1. Overview

마이크로서비스와 API 게이트웨이 거버넌스(Micro-services & API Gateway Governance)는 수십 개로 쪼개진 백엔드 서버(인증, 결제, 상품)들을 외부 세상(프론트엔드/모바일)으로부터 숨기고, 오직 단 하나의 거대한 대문(API Gateway)을 통해서만 트래픽을 통제하는 L7 네트워크 아키텍처의 끝을 해부합니다.

학습자는 프론트엔드가 백엔드 서버 50개의 IP를 전부 외우고 찔러야 했던 끔찍한 파스타(Spaghetti) 망을 버리고, 요청을 알맞은 서버로 토스하는 **API 라우팅(Routing)**의 본질을 뜯어봅니다. 나아가 디도스(DDoS) 공격과 악성 크롤러를 막기 위해 초당 요청 수를 제어하는 속도 제한(Rate Limiting - Token Bucket) 마법을 장악합니다. 마지막으로, 50개 서버가 각각 JWT를 검사하던 중복 코드를 지워버리고 대문에서 인증을 전담하는 Offloading, 그리고 REST의 한계를 부수며 필요한 필드만 골라 빼먹는 GraphQL 및 바이너리 고속 통신 gRPC의 API 패러다임 전환 역량을 확보합니다.

2. Scope & Boundaries

In-Scope

• API Gateway Pattern: Reverse Proxy, L7 Routing (Path-based, Host-based).
• Traffic Control (Rate Limiting): Token Bucket, Leaky Bucket, Sliding Window 알고리즘.
• Cross-Cutting Concerns Offloading: Authentication (JWT 엣지 검증), SSL Termination, API Versioning.
• API Paradigms: REST의 한계(Over-fetching, Under-fetching)와 GraphQL, gRPC (Protocol Buffers)의 등장 배경.

Out-of-Scope

• Service Mesh (Istio/Linkerd): 서버들 '내부'끼리의 통신 통제 $\rightarrow$ 07-06-03 Service Mesh 영역으로 위임.
• OAuth 2.0 / OIDC 암호학적 흐름: 인가(Authorization) 코드 발급과 DB 토큰 저장 등 구체적 플로우 $\rightarrow$ 10-03-01 Authentication & IAM 영역으로 분리.

Boundaries

• API Gateway (North-South) vs Service Mesh (East-West): API Gateway는 외부(프론트엔드, 유저)에서 우리 회사 내부망으로 들어오는 거대한 대문(North-South 트래픽)을 통제하며 캐싱, 유량 제어, SSL 복호화를 전담합니다. 반면 Service Mesh는 대문을 통과한 내부 서버들끼리(결제 서버 $\rightarrow$ 회원 서버)의 통신(East-West 트래픽)을 암호화하고 추적하는 데 특화되어 있습니다. 본 문서는 외부에서 쏟아지는 트래픽을 어떻게 방어하고 정리할 것인가(Gateway)에 맹렬히 집중하여 경계를 긋습니다.

3. Counterexample

• 인증 로직의 중복 지옥: 50개의 마이크로서비스 팀이 있습니다. Gateway가 없어서 각 팀이 자기 서버 코드에 JWT 토큰 검사 로직을 수천 줄씩 박아 넣었습니다. 보안팀에서 "JWT 서명 알고리즘을 바꿔라"라고 지시하자, 50개 팀이 일제히 야근을 하며 코드를 수정하다가 3개 팀이 실수를 하여 보안에 구멍이 뚫렸습니다. 인프라 공통 관심사(Cross-cutting Concerns)를 Gateway 앞단으로 오프로딩(Offloading)하지 않아 발생한 아키텍처 재앙입니다.
• 오버패칭(Over-fetching)과 모바일 데이터 폭탄: 모바일 앱에서 유저의 '이름' 하나만 보여주면 되는데, REST API 규격 상 GET /users/123을 호출해야 합니다. 서버는 유저의 이름, 주소, 전화번호, 지난 10년간의 결제 내역까지 5MB짜리 JSON을 응답합니다. 모바일 유저의 데이터 요금이 박살 나고 앱 로딩이 느려집니다. 뷰(View)가 원하는 필드만 정확히 가져오는 GraphQL 패러다임이 절실한, 구시대적 REST API 설계의 맹점입니다.

4. Prerequisites

• L7 로드밸런서 (Basic): HTTP Path 기반 리버스 프록시 라우팅. (07-05-01 Scalability)
• RESTful API 철학 (Basic): 자원 중심의 API 구조. (08-04-02 RESTful Architecture)

5. Learning Map

6. Learning Topics

Basic

Core Topic 01: 거대한 대문, 리버스 프록시 (The Front Door - API Gateway)

• Why to Learn: 프론트엔드가 백엔드 서버들의 IP와 포트를 하드코딩하는 결합도를 박살 내고, 백엔드 아키텍처가 어떻게 변하든 외부에는 단 하나의 일관된 진입점을 제공하기 위함입니다.
• What to Learn:
  • Concepts: Reverse Proxy, API Gateway, Path-based Routing (/api/users $\rightarrow$ User Service), Single Entry Point.
  • Skills: Nginx나 Kong, AWS API Gateway를 사용하여 api.company.com/orders 요청은 주문 서버(8081)로, /payments 요청은 결제 서버(8082)로 포워딩하는 L7 라우팅 룰 작성.
• How to Learn:
  • 1단계: 거미줄 아키텍처: 클라이언트가 유저 정보는 10.0.0.1로, 결제 정보는 10.0.0.2로 각각 다르게 요청합니다. 결제 서버 IP가 바뀌면 앱을 업데이트해야 합니다. 끔찍한 구조입니다.
  • 2단계: 파사드(Facade) 대문: 클라이언트는 무조건 api.company.com 하나만 때립니다. API Gateway가 앞을 가로막고, URL Path를 까봅니다. "어? /orders네? 이건 주문팀 서버 3대로 로드밸런싱해 줘야지." 백엔드가 100대로 쪼개지든 말든, 외부(클라이언트)는 아무것도 몰라도 되는 완벽한 의존성 격리를 뜯어봅니다.
• Implement: 파이썬 L7 리버스 프록시 시뮬레이터. 클라이언트 요청 GET /api/v1/cart. 게이트웨이 라우팅 룰: if path.startswith('/api/v1/cart'): target = '192.168.1.50'. 게이트웨이가 본래의 헤더에 X-Forwarded-For: [클라이언트 원본 IP]를 찔러 넣고 백엔드로 요청을 토스하는 프록시 중계 애니메이션.

Recommended

Core Topic 02: 폭주 기관차 멈추기, 토큰 버킷 (Rate Limiting & Token Bucket)

• Why to Learn: 악의적인 공격자나 버그 난 클라이언트가 초당 1만 번의 API를 찔러 백엔드 DB를 녹여버리는 인프라 붕괴를 Gateway 최전방에서 저격수로 막아내기 위함입니다.
• What to Learn:
  • Concepts: Rate Limiting (속도 제한), Throttling, Token Bucket Algorithm, Leaky Bucket, 429 Too Many Requests.
  • Skills: 토큰 버킷 알고리즘의 원리(최대 버킷 크기, 초당 보충률)를 이해하고, 유저 IP 단위로 초당 API 호출을 5회로 제한하는 방어벽 설계.
• How to Learn:
  • 1단계: 토큰 버킷 알고리즘: 유저마다 가상의 바구니(Bucket)를 줍니다. 바구니엔 티켓(Token)이 최대 5장 들어갑니다. 유저가 API를 찌를 때마다 티켓을 1장씩 찢습니다. 티켓이 0장이 되면 Gateway가 429 Too Many Requests를 뱉고 요청을 걷어찹니다.
  • 2단계: 초당 보충 (Refill Rate): 바구니에 매초 1장씩 새 티켓을 몰래 채워줍니다(보충률). 유저가 1초에 10번을 찌르면 처음 5번은 통과되지만(Burst 허용), 나머지 5번은 튕깁니다. 그 유저가 1초 쉬면 다시 1번을 찌를 수 있습니다. 트래픽의 스파이크(순간 폭발)를 허용하면서도 장기적인 과부하를 통제하는 이 기막힌 수학적 유량 제어를 해부합니다.
• Implement: Token Bucket Rate Limiter 알고리즘 모사. 룰: Capacity=3, Refill=1/sec. 0초: 유저가 API 4번 때림 $\rightarrow$ [OK, OK, OK, 429 Error (토큰 0)]. 1초: 토큰 1개 보충됨 $\rightarrow$ 유저가 2번 때림 $\rightarrow$ [OK, 429 Error]. 악성 트래픽이 백엔드로 넘어가지 않고 Gateway 엣지(Edge)에서 산화하는 방어 메커니즘 시각화.

Practical

Core Topic 03: 공통 관심사의 오프로딩, 인증과 로깅 (Authentication Offloading)

• Why to Learn: 각 백엔드 팀마다 중구난방으로 작성된 JWT 토큰 검증, SSL 복호화(HTTPS), 로깅 코드를 싹 다 지워버리고, Gateway 하나에서 통합 관리하는 엔터프라이즈 아키텍처를 세우기 위함입니다.
• What to Learn:
  • Concepts: Cross-Cutting Concerns (공통 관심사), Offloading (부하 덜어내기), SSL Termination, JWT Edge Validation.
  • Skills: 백엔드 서버들이 복잡한 비대칭 키(RSA) 연산이나 SSL 인증서 관리를 하지 않도록, Gateway가 앞단에서 이를 모두 처리(Termination)하고 내부망으로는 가벼운 HTTP/평문 토큰만 넘기는 구조 설계.
• How to Learn:
  • 1단계: SSL 터미네이션 (SSL Termination): 암호화된 HTTPS 트래픽을 까보는 건 CPU를 엄청나게 잡아먹습니다. 이걸 50대의 백엔드 서버가 각자 하게 놔두면 서버가 무거워지고 50대 서버에 인증서를 다 깔아야 합니다. Gateway가 앞단에서 암호를 싹 다 풀고(HTTPS $\rightarrow$ HTTP), 쾌적한 내부망(VPC)을 통해 쌩얼(HTTP) 트래픽만 백엔드로 넘겨줍니다.
  • 2단계: JWT 엣지 검증: 프론트엔드가 보낸 Authorization 토큰(JWT)이 위조되었는지, 만료되었는지 검사하는 것도 Gateway가 앞단에서 한 방에 컷합니다. 백엔드(결제 서버)는 토큰 검증 코드를 짤 필요 없이, Gateway가 "이거 정상 유저 123번이 맞다"고 헤더(X-User-Id: 123)에 찍어 넘겨주는 명찰만 믿고 핵심 비즈니스 로직(결제)만 집중하는 완벽한 역할 분담을 뜯어봅니다.
• Implement: JWT Offloading 플로우 모사. 외부 요청: GET /api/orders + Header: Bearer [Invalid_JWT]. 게이트웨이 로직: JWT 서명 불일치 감지 $\rightarrow$ HTTP 401 Unauthorized 뱉고 종료. (백엔드 서포트 없음, 안전). 외부 요청: GET /api/orders + Header: Bearer [Valid_JWT_for_User_55]. 게이트웨이 로직: 정상 확인 $\rightarrow$ 토큰 해제 후 Header: X-User-Id: 55를 주입하여 내부 주문 서버로 포워딩. 백엔드 코드의 복잡도가 0으로 수렴하는 구조 렌더링.

Advanced

Core Topic 04: REST의 족쇄를 부숴라, GraphQL과 gRPC (Beyond REST)

• Why to Learn: 자원(명사) 중심의 REST API가 가진 태생적 한계(데이터 오버패칭, 무거운 JSON 규격)를 깨닫고, 뷰(View) 중심의 쿼리 언어나 바이너리 통신으로 서버-클라이언트 통신 패러다임을 한 단계 진화시키기 위함입니다.
• What to Learn:
  • Concepts: REST Limitations (Over-fetching, Under-fetching), GraphQL, gRPC, Protocol Buffers (Protobuf).
  • Skills: 유저 정보와 최근 주문 정보 3개를 모바일 화면 한 장에 그리기 위해 REST API를 2번 호출해야 하는 문제를, GraphQL 쿼리 1방으로 해결하는 스키마 디자인.
• How to Learn:
  • 1단계: REST의 비극 (오버/언더패칭): 화면에 유저 '이름'만 필요한데 REST는 GET /users/1로 쓸데없는 1MB짜리 전체 정보를 다 줍니다(Over-fetching). 게다가 그 유저의 '주문 내역'도 띄우려면 GET /users/1/orders를 한 번 더 찔러야 합니다(Under-fetching).
  • 2단계: 클라이언트 주도권 (GraphQL): GraphQL은 대문 1개(/graphql)만 열어둡니다. 클라이언트가 "나 유저 1번의 이름이랑, 그 유저의 주문 내역 최신 3개만 딱 줘!"라고 쿼리(문장)를 써서 보냅니다. 서버는 정확히 그 쿼리대로만 데이터를 조립해서 줍니다. 한 방의 요청으로 모든 데이터 조립을 끝냅니다.
  • 3단계: 바이너리의 속도 (gRPC): 백엔드 서버끼리 통신할 때 텍스트(JSON)를 쓰는 건 너무 무겁습니다. 구글이 만든 gRPC는 데이터를 이진수(Protobuf)로 압축해버립니다. 용량이 1/10로 줄고 파싱 속도가 미친 듯이 빨라집니다. 마이크로서비스 내부(East-West) 통신의 제왕으로 군림하는 gRPC의 위엄을 뜯어봅니다.
• Implement: GraphQL vs REST 페이로드 비교 시뮬레이터. 목표: 유저 이름 + 최근 결제액 가져오기. REST 모드: GET /user/1 (10KB 응답) $\rightarrow$ GET /user/1/payments (50KB 응답). 총 2번 RTT, 60KB 트래픽. GraphQL 모드: POST /graphql { user(id:1) { name, payments(limit:1) { amount } } }. 서버가 정확히 필터링된 JSON: { name: "Bob", payments: [{amount: 50}] } 단 50바이트만 응답. 무선 네트워크에서 속도 10배 차이 렌더링.

7. Terminology

8. References

Primary

• [P1] CS2023 - Software Engineering (SE) - Distributed System Architectures (Microservices)
• [P5] SFIA - Solutions Architecture (ARCH) - API Management and Gateway Patterns

Secondary

• [Microservices Patterns] Chris Richardson - API Gateway pattern
• [Building Microservices] Sam Newman - Integrating Microservices (GraphQL, gRPC)

Industry

• [AWS Architecture Center] - API Gateway Pattern / Throttling limits
• [Nginx Documentation] - Rate Limiting with NGINX (Token Bucket)
• [GraphQL.org] - Introduction to GraphQL
• [gRPC.io] - What is gRPC?

9. Final Checklist

Primary

• 수십 개의 백엔드 마이크로서비스 IP를 클라이언트(앱/웹)가 하드코딩했을 때 발생하는 배포 및 유지보수의 지옥을, API Gateway 패턴(L7 Reverse Proxy)이 어떻게 추상화(숨김)하여 해결하는지 설명할 수 있는가?
• 외부망(HTTPS) 트래픽의 암호화를 API Gateway에서 풀고(SSL Termination), 내부망(VPC)에서는 평문(HTTP)으로 고속 포워딩하는 오프로딩(Offloading) 아키텍처의 CPU 최적화 효과를 증명할 수 있는가?

Secondary

• 특정 유저나 IP가 초당 허용치를 초과하여 API를 찌를 때, Token Bucket 알고리즘이 빈 버킷 상태를 인지하고 HTTP 429 Too Many Requests를 반환하여 백엔드 DB를 보호하는 유량 제어 메커니즘을 해부할 수 있는가?
• 각 백엔드 서비스(결제, 주문, 유저)에 중복 구현되어 있던 JWT 서명 검증 로직을 제거하고, Gateway 단에서 토큰 위조를 사전 차단한 뒤 안전한 유저 ID만 헤더(Header)에 담아 백엔드로 넘겨주는 신뢰 경계(Trust Boundary)를 설계할 수 있는가?

Industry

• 화면 하나를 그리기 위해 REST API를 여러 번 호출해야 하는 언더패칭(Under-fetching)과, 불필요한 데이터까지 받아오는 오버패칭(Over-fetching)의 비효율을 GraphQL의 클라이언트 주도적 쿼리로 타파할 수 있는가?
• 사람 눈에 보이는 텍스트(JSON) 직렬화의 무거운 오버헤드를 버리고, Protocol Buffers를 이용해 페이로드를 이진수(Binary)로 극도로 압축하여 마이크로서비스 간 내부 통신(East-West) 속도를 극대화하는 gRPC의 타당성을 평가할 수 있는가?