API 게이트웨이 & 리버스 프록시 전문가은(는) 무엇을 하나요?
라우팅, 인증, 속도 제한, 트래픽 관리를 위한 API 게이트웨이와 리버스 프록시를 구성하고 최적화합니다.
결정 지점
인증 전략 선택
트래픽 패턴 및 요구 사항
├── 내부 서비스 전용
│ └── API 키 인증
│ ├── 낮은 복잡성, 빠른 검증
│ └── Kong: key-auth 플러그인, Traefik: forwardAuth
├── 세션이 필요한 고객 대면 API
│ └── JWT 인증
│ ├── 상태 비저장, 사용자 클레임 포함
│ └── Kong: jwt 플러그인, Nginx: lua-resty-jwt
├── 엔터프라이즈 B2B 통합
│ └── mTLS 인증
│ ├── 인증서 기반, 최고 보안
│ └── Kong: mtls-auth, Nginx: ssl_verify_client
└── 타사 SaaS 통합
└── OAuth2 흐름
├── 토큰 교환, 위임 인증
└── Kong: oauth2 플러그인, AWS API Gateway: authorizer
게이트웨이 기술 선택
요구 사항 → 선택
├── 플러그인 생태계 및 GUI 필요
│ └── Kong Enterprise/OSS
├── Kubernetes 네이티브, 자동 검색
│ └── Traefik v3 또는 Ingress-NGINX
├── 최대 성능, 최소 기능
│ └── Nginx 또는 Envoy
└── 클라우드 관리형, 서버리스 스케일링
└── AWS API Gateway 또는 Azure Application Gateway
업스트림 라우팅 전략
서비스 아키텍처 → 라우팅 방법
├── 서비스 검색이 있는 마이크로서비스
│ └── 동적 업스트림 대상
│ ├── Consul/Eureka 통합
│ └── 상태 확인 기반 로드 밸런싱
├── 정적 백엔드 서비스
│ └── 고정 업스트림 풀
│ ├── 라운드 로빈 또는 최소 연결
│ └── 카나리 배포를 위한 가중치 라우팅
└── 다중 지역 배포
└── 지리적 라우팅
├── 지연 시간 기반 또는 Geo-IP
└── 보조 지역으로 폴백
실패 모드
게이트웨이 시간 초과 연쇄
증상: 부하 시 느린 API 응답(>10초)
탐지: 응답 시간이 급증하는 동안 업스트림 서비스는 정상 지연 시간 보고
근본 원인: 게이트웨이 시간 초과가 업스트림 시간 초과보다 커서 요청 큐잉 발생
수정: 게이트웨이 읽기 시간 초과를 업스트림 시간 초과보다 작게 설정 (게이트웨이: 30초, 업스트림: 25초)
인증 우회
증상: 승인되지 않은 요청이 백엔드 서비스에 도달
탐지: 백엔드 로그에 예상 인증 헤더 없는 요청 표시
근본 원인: 라우트 순서로 인해 허용 규칙이 인증 규칙보다 먼저 일치
수정: 인증 미들웨어를 전역 수준으로 이동하거나 특정 라우트가 설정에서 먼저 오도록 보장
회로 차단기 쓰래싱
증상: 트래픽 급증 시 간헐적 503 오류
탐지: 회로 차단기가 빠르게 열림/닫힘 (분당 여러 번)
근본 원인: 임계값이 너무 민감하거나 상태 확인이 잘못 구성됨
수정: 실패 임계값(5+ 실패) 및 복구 시간(최소 30초) 조정
SSL 인증서 만료
증상: HTTPS 핸드셰이크 실패, 브라우저 인증서 경고
탐지: SSL 인증서 확인 결과 30일 이내 만료
근본 원인: 수동 인증서 관리, 갱신 자동화 없음
수정: cert-manager(K8s) 또는 ACME 클라이언트를 통한 자동 갱신 구현
리소스 고갈
증상: 게이트웨이 연결 수락 중단, 메모리/CPU 100%
탐지: 연결 거부 오류, 게이트웨이 상태 확인 실패
근본 원인: 연결 제한 없음 또는 플러그인 메모리 누수
수정: worker_connections(Nginx) 또는 연결 풀 제한(Kong) 설정, 게이트웨이 재시작
작업 예제
시나리오: 전자상거래 API 게이트웨이 설정
컨텍스트: 주문, 재고, 결제를 처리하는 마이크로서비스에 Kong 배포, JWT 인증 사용
1단계: 라우트 정의
# 먼저 서비스 엔드포인트 식별
services:
- orders: /api/v1/orders/* → http://orders:8080
- inventory: /api/v1/inventory/* → http://inventory:8080
- payments: /api/v1/payments/* → http://payments:8080
2단계: 의사 결정 트리 적용
- 트래픽 패턴: 고객 대면 API → JWT 인증
- 아키텍처: 마이크로서비스 → 동적 업스트림 대상
- 요구 사항: 플러그인 생태계 필요 → Kong 선택
3단계: 플러그인 순서 지정
# 올바른 순서로 플러그인 적용
plugins:
1. cors (인증 전)
2. jwt (인증)
3. rate-limiting (인증 후)
4. request-transformer (마지막)
전문가 vs 초보자:
- 초보자 실수: 인증 전에 속도 제한 적용 (익명 사용자가 할당량 소비)
- 전문가 접근: 인증 먼저, 그 다음 인증된 사용자별 속도 제한
- 초보자 실수: 전역 CORS 정책 사용
- 전문가 접근: 라우트별로 다른 CORS (orders는 관리자 출처 허용, payments는 프론트엔드로만 제한)
장애 시나리오: 카나리 배포 실패
상황: 새 주문 서비스 버전에 20% 트래픽 배포, 500 오류 발생
탐지 과정:
- 게이트웨이 메트릭 확인: 500 오류율이 배포 시간과 일치
- 업스트림 상태 확인: 새 버전 상태 확인 실패
- 게이트웨이 로그: 업스트림 연결 시간 초과
롤백 절차:
# 1단계: 즉시 트래픽 전환
kong:
routes:
- service: orders-v1
weight: 100 # 이전 80
- service: orders-v2
weight: 0 # 이전 20
# 2단계: 롤백 검증
curl -H "Authorization: Bearer $JWT" \
https://api.company.com/orders/health
# 3단계: 실패한 업스트림 제거
kubectl scale deployment orders-v2 --replicas=0
근본 원인 분석: 새 버전에서 데이터베이스 연결 풀 설정 오류로 부하 시 시간 초과 발생
품질 관문
- 모든 라우트에 명시적 경로 일치 지정 (catch-all /* 라우트 없음)
- 비즈니스 로직 플러그인보다 먼저 인증 미들웨어 구성
- 상태 확인이 5초 이내에 정상 업스트림에 대해 2xx 반환
- 회로 차단기 임계값 설정: 60초 윈도우 내 5회 실패, 30초 복구
- TLS 인증서가 만료 30일 이상 전에 자동 갱신
- 속도 제한이 전역이 아닌 인증된 사용자별로 적용
- CORS 정책이 필요한 도메인으로만 출처 제한
- 게이트웨이 시간 초과(30초) < 업스트림 시간 초과(25초)로 연쇄 방지
- 액세스 로그에 요청 추적을 위한 상관관계 ID 포함
- 고가용성을 위해 최소 2개 복제본으로 게이트웨이 배포
NOT-FOR 경계
이 스킬은 다음을 처리합니다: 게이트웨이 구성, 라우팅 규칙, 인증 미들웨어, 리버스 프록시 설정
다음은 처리하지 않습니다:
- 속도 제한 알고리즘 설계 →
api-rate-limiting-throttling-expert사용 - 서비스 메시 데이터 플레인 구성 →
service-mesh-microservices-expert사용 - API 명세 및 설계 →
api-architect사용 - 데이터베이스 연결 풀링 →
database-performance-expert사용 - 컨테이너 오케스트레이션 →
kubernetes-expert또는docker-expert사용 - SSL 인증서 생성 →
security-infrastructure-expert사용
위임 규칙:
- 커스텀 속도 제한 알고리즘의 경우: "속도 제한 플러그인을 구성하겠지만, 커스텀 알고리즘이 필요하면 api-rate-limiting-throttling-expert를 사용하세요."
- 서비스 검색 설정의 경우: "업스트림 대상을 구성하겠지만, 서비스 메시 설정이 필요하면 service-mesh-microservices-expert를 사용하세요."