Spring Cloud Gateway 완전 가이드 3

9. Spring Security + JWT 인증

마이크로서비스 환경에서는 모든 서비스가 각각 인증 로직을 구현하면 중복 코드와 보안 관리 문제가 발생합니다.

일반적으로 API Gateway에서 인증을 담당하고, Backend 서비스에는 인증된 사용자 정보만 전달하는 구조를 사용합니다.

Client
  ↓
Spring Cloud Gateway
JWT 검증
권한 검사
Header 전달
  ↓
Microservice

JWT 인증 처리 흐름

1. 사용자가 로그인하여 JWT Token 발급
2. Client가 API 요청 시 Authorization Header 전달
3. Gateway Filter에서 JWT 검증
4. 검증 성공 시 Backend 서비스 호출
5. 사용자 정보 Header 전달

JWT Authentication Filter 예제

@Component

public class JwtAuthenticationFilter
implements GlobalFilter {


@Override

public Mono<Void> filter(

ServerWebExchange exchange,

GatewayFilterChain chain

){


String token =
exchange
.getRequest()
.getHeaders()
.getFirst(
"Authorization"
);



if(token == null){

return Mono.error(
new RuntimeException(
"Unauthorized"
)
);

}


return chain.filter(exchange);

}


}

인증 정보 Backend 전달

exchange
.getRequest()
.mutate()

.header(
"X-USER-ID",
userId
)

.build();

보안 주의사항

• JWT Secret Key는 Gateway 환경 변수 또는 Secret 관리 시스템에서 관리
• Client가 직접 전달한 사용자 Header는 신뢰하지 않음
• Gateway에서 새 Header를 생성하여 전달
• Token 만료와 Refresh Token 정책 필요

10. CORS 설정

SPA(Vue, React) 환경에서는 Frontend와 API Gateway Domain이 다르기 때문에 CORS 설정이 필요합니다.

application.yml CORS 설정

spring:

 cloud:

  gateway:

   globalcors:

    corsConfigurations:

     '[/**]':

      allowedOrigins:

      - https://frontend.example.com


      allowedMethods:

      - GET

      - POST

      - PUT

      - DELETE


      allowedHeaders:

      - "*"


      allowCredentials:
        true

운영 환경 CORS 권장 정책

항목	권장
allowedOrigins	전체(*) 사용 금지
Credentials	Cookie 인증 사용 시 활성화
Header	필요한 Header만 허용

11. Service Discovery와 Load Balancing

MSA 환경에서는 서비스 위치가 변경될 수 있기 때문에 IP 기반 호출보다 서비스 이름 기반 호출을 사용합니다.

Eureka 기반 구조

Client

 ↓

Gateway

 ↓

Eureka Server

 ↓

USER-SERVICE Instance 1

USER-SERVICE Instance 2

Kubernetes Service Discovery

Kubernetes 환경에서는 Service DNS를 이용합니다.

spring:

 cloud:

  gateway:

   routes:


   - id:
       user-service


     uri:
       http://user-service.default.svc.cluster.local:8080


     predicates:

     - Path=/users/**

실제 운영 환경에서는 Kubernetes Service + Spring Cloud LoadBalancer 조합을 많이 사용합니다.

12. WebSocket 지원

Spring Cloud Gateway는 WebSocket Routing도 지원합니다.

채팅, 실시간 알림, 모니터링 시스템 등에 활용됩니다.

spring:

 cloud:

  gateway:

   routes:


   - id:
       websocket-service


     uri:
       ws://chat-service:8080


     predicates:

     - Path=/ws/**

WebSocket 운영 고려사항

• Connection Timeout 설정
• Load Balancer Sticky Session 검토
• 장시간 연결 관리
• Session 장애 처리

13. 장애 처리와 안정성

Gateway는 모든 요청이 지나가는 진입점이므로 장애 대응 설계가 매우 중요합니다.

Retry 설정

filters:

- name:
    Retry


  args:

    retries:
      3


    statuses:

    - BAD_GATEWAY

    - SERVICE_UNAVAILABLE

Circuit Breaker 적용

filters:

- name:
    CircuitBreaker


  args:

    name:
      userCircuit


    fallbackUri:
      forward:/fallback

장애 대응 전략

• Timeout 설정
• Retry 제한
• Circuit Breaker 적용
• Fallback API 제공
• Slow Service 격리

14. Actuator + Prometheus + Grafana 모니터링

운영 환경에서는 Gateway 상태와 요청 지표를 지속적으로 확인해야 합니다.

Actuator 설정

management:

 endpoints:

  web:

   exposure:

    include:
    - health
    - metrics
    - prometheus

Prometheus Metrics

주요 모니터링 항목:

• Gateway 요청 수
• HTTP Response Time
• 5xx Error 비율
• Route별 Traffic
• Backend Latency

운영 Dashboard 구성 예

Client Traffic ↓ Gateway Request Count ↓ Route별 응답시간 ↓ Backend Error Rate ↓ Service Health

15. Kubernetes 운영 아키텍처

Cloud Native 환경에서는 Gateway를 Kubernetes Ingress 앞단 또는 API Gateway 계층으로 구성합니다.

Internet

 ↓

Cloud LoadBalancer

 ↓

Spring Cloud Gateway

 ↓

Kubernetes Service

 ↓

Pod

 ↓

Application

운영 권장 사항

• Replica 2개 이상 구성
• Rolling Update 적용
• Health Check 설정
• Resource Limit 지정
• Prometheus Monitoring 구성
• Log Aggregation 구성

Spring Cloud Gateway 운영 체크리스트

항목	확인
Route 관리	서비스별 Routing 정책 문서화
Security	JWT 검증 및 권한 관리
Performance	Timeout / Connection Pool 관리
Monitoring	Prometheus + Grafana 구성
Deployment	Kubernetes 운영 자동화

마무리

Spring Cloud Gateway는 단순한 URL 전달 도구가 아니라 MSA 환경에서 인증, 보안, 트래픽 제어, 장애 대응과 모니터링을 담당하는 핵심 플랫폼입니다.

실무에서는 Route 설계, Filter 구조, JWT 인증, Kubernetes Service Discovery, Observability 환경까지 함께 고려해야 안정적인 API Gateway를 운영할 수 있습니다.