blog

API와 Kong Gateway 도입 배경

NEXTREE.

• 13 min read
API와 Kong Gateway 도입 배경

1. 신규 기능 요구사항: 이기종 시스템 간 데이터 연동과 통계 가공

최근 제가 담당하고 있는 서비스에 신규 기능이 추가되었습니다. 타 시스템에 분산되어 있는 데이터를 직접 가져와, 우리 서비스의 목적에 맞게 정제(정리)하고 통계 데이터를 산출하여 사용자에게 직관적으로 보여주는 기능이었습니다.

이 기능을 구현하기 위해서는 두 가지 핵심 과제가 있었습니다.

  • 데이터 신뢰성 확보: 타 시스템의 API를 안정적으로 호출하고, 대용량일 수 있는 데이터를 유실 없이 가져와 연동해야 했습니다.

  • 결합도 최소화: 타 시스템의 변화가 우리 서비스에 미치는 영향을 최소화하는 느슨한 결합(Loose Coupling) 구조가 필요했습니다.

1.1 왜 Kong API Gateway인가? (사내 아키텍처 표준의 수용)

새로운 API 엔드포인트를 노출하고 타 시스템과 통신을 설계할 때, 저희 팀은 회사의 표준 아키텍처 방침인 'Kong API Gateway'를 활용하기로 결정했습니다. 이미 잘 구축된 사내 인프라를 활용하는 것은 단순한 규칙 준수를 넘어 기술적으로 다음과 같은 강력한 이점을 제공하기 때문입니다.

  • 중앙 집중식 라우팅 관리: 신규 엔드포인트의 진입점을 Kong으로 단일화하여, 향후 서비스가 확장되거나 내부 URL 구조가 변경되더라도 외부 인터페이스를 안정적으로 유지할 수 있습니다.

  • 공통 기능의 위임: 인증(Authentication), 인가(Authorization), Rate Limiting(요청 제한) 등 API 보안 및 관리에 필요한 공통 기능을 애플리케이션 레벨에서 일일이 구현하지 않고, Kong의 플러그인 생태계에 위임하여 비즈니스 로직(데이터 정리 및 통계 계산)에만 집중할 수 있습니다.

  • 모니터링 및 트래픽 제어: 타 시스템으로부터 들어오거나 나가는 트래픽의 상태를 중앙에서 모니터링하고, 가용성을 확보하기에 최적의 선택이었습니다.

결과적으로 이번 작업은 "타 시스템의 데이터를 안전하게 가져와 내부에서 통계로 가공하는 비즈니스 로직 구현"과 "이를 사내 표준 아키텍처인 Kong Gateway와 매끄럽게 연결하여 안정적인 서비스 엔드포인트를 확보하는 과정"이 핵심이었습니다.

2. Kong API Gateway의 핵심 개념과 라우팅 설정 과정

2.1 백엔드 개발자가 알아야 할 Kong의 3대 핵심 객체

Kong Gateway는 복잡한 프록시 및 라우팅 설정을 개발자가 직관적으로 이해할 수 있도록 Service, Route, Consumer라는 3가지 핵심 객체(Entity)로 추상화하여 관리합니다. 이번 신규 기능을 연결하기 위해 이 개념들을 어떻게 매핑했는지 예시와 함께 살펴보겠습니다.

[외부/타 시스템 요청] ──> [ Route (/api/v1/realtime-analytics) ]

                      │ (토큰 검증: Consumer 인증)
                      ▼
            [ Service (internal-stats-cluster) ] ──> [실제 백엔드 API]

1) Service (내부 서비스 정의)

  • 개념: Kong이 트래픽을 전달할 실제 백엔드 애플리케이션(Upstream 주소)을 의미합니다. 내부 물리 서버의 IP나 도메인, 타임아웃 정책 등을 이 단계에서 설정합니다.

  • 예시: 타 시스템의 데이터를 수집하고 통계를 가공하는 내부 스프링부트/노드 서버(http://internal-stats-cluster.local)가 하나의 Service가 됩니다.

2) Route (외부 진입점 정의)

  • 개념: 외부 클라이언트나 타 시스템이 Kong Gateway에 접근할 때 사용할 엔드포인트(경로, 도메인, HTTP 메서드 등)를 뜻합니다. 하나의 Service는 여러 개의 Route를 가질 수 있습니다.

  • 예시: 외부 시스템이 실시간 통계를 요청하기 위해 접근하는 공개 URL 경로인 /api/v1/realtime-analytics가 Route가 됩니다.

3) Consumer (사용자/대상 시스템 정의)

  • 개념: API를 소비하는 주체(클라이언트, 앱, 혹은 타 시스템)를 의미합니다. Kong은 Consumer 단위로 인증 토큰을 매핑하거나 트래픽 제한(Rate Limiting)을 걸 수 있습니다.

  • 예시: 우리 시스템의 API를 호출하여 실시간 통계 데이터를 가져가는 외부의 ‘데이터 소비 시스템(external-data-consumer)’이 Consumer로 등록됩니다.

2.2 애플리케이션 기반 토큰 발급과 게이트웨이 기반 검증의 협업 아키텍처

이번 실시간 통계 기능은 이기종 시스템 간의 안전한 데이터 송수신을 보장하기 위해, 선언적 구성(Declarative Configuration) 환경 위에서 "백엔드 로직 중심의 토큰 발급 및 게이트웨이 중심의 고속 검증" 하이브리드 아키텍처를 채택했습니다.

토큰의 발급과 만료 시간 관리 같은 정밀한 비즈니스 규칙은 백엔드 애플리케이션 내부 로직으로 직접 구현하여 제어합니다. 반면, 이미 발급된 토큰을 들고 들어오는 실시간 API 요청에 대한 유효성 검증은 최전선의 Kong Gateway 레이어(JWT 플러그인)에서 가로채어 수행하도록 구조화했습니다.

이 구조는 단순한 편리함을 넘어, 실시간 대용량 통계 연산을 수행해야 하는 우리 백엔드 시스템의 CPU 자원을 보호하고 가용성을 극대화하기 위한 아키텍처적 선택이었습니다.

  • 관심사의 분리 (Separation of Concerns): 토큰의 비즈니스 규칙은 커스텀 백엔드 로직이 담당하고, 네트워크 최전선에서의 패킷 필터링 및 서명 검증은 Kong이 담당합니다. 덕분에 백엔드는 오직 '통계 계산 및 데이터 정제'라는 본연의 비즈니스 로직에만 집중할 수 있습니다.

  • 공유 비밀키(Shared Secret)를 통한 신뢰 체인: 백엔드가 토큰을 서명할 때 사용하는 비밀키와 Kong Gateway가 서명을 검증할 때 사용하는 키를 동기화하여, 무거운 인증 서버를 매번 조회하는 오버헤드 없이 초고속 분산 인증 환경을 구현했습니다.

  • 실시간 통계를 위한 자원 최적화: 비정상적인 토큰을 가진 무효한 요청을 Kong이 전면에서 401 Unauthorized로 1차 차단해 주기 때문에, 대용량 통계 연산을 수행하는 백엔드 애플리케이션의 불필요한 자원 낭비를 원천 차단할 수 있었습니다.

3. 트러블슈팅: 인프라는 완벽한데 트래픽이 사라졌다? (애플리케이션 빈 등록 누락 디버깅)

3.1 인프라는 정상인데 백엔드에서 응답이 없는 이유

Kong Gateway에 가상의 선언적 설정을 마치고, 기존 사내 가이드라인과 로직 규칙에 맞추어 완벽하게 토큰 기반의 실시간 통계 API 백엔드 코드를 구현했습니다. 모든 인프라 라우팅 라인이 정렬되었으니 당연히 바로 연결될 줄 알았습니다.

하지만 로컬 개발 환경에서 Kong을 거쳐 API 엔드포인트를 호출하며 엔드 투 엔드(E2E) 테스트를 진행하는 순간, 기대했던 통계 결과 대신 요청이 중간에 증발하거나 백엔드 내부를 찾지 못하는 현상이 발생했습니다.

[클라이언트 요청] ──> [ Kong Gateway (통과) ] ──> [ 백엔드 애플리케이션 (연결 유실) ]

처음에는 Kong의 strip_path 설정이나 헤더 전달 문제, 혹은 공유 비밀키(Secret Key)가 일치하지 않아 발생한 게이트웨이 단의 라우팅 문제인 줄 알고 인프라 로그와 컨테이너 네트워크를 집중적으로 디버깅했습니다. 하지만 Kong은 정확하게 백엔드 타겟 서버로 패킷을 라우팅해 주고 있었습니다. 문제는 게이트웨이가 아닌 우리 백엔드 애플리케이션 내부에 있었습니다.

3.2 원인 분석: 프레임워크의 생명 주기와 빈(Bean) 등록 누락

원인은 허무하게도 가장 기본적이고 핵심적인 백엔드 개념인 '빈(Bean) 등록 누락'이었습니다.

기존 사내 시스템의 아키텍처 규칙과 프레임워크 규격에 맞추어 실시간 통계를 가공하는 새로운 서비스 클래스와 토큰 검증 핸들러/인터셉터 로직을 작성하는 데만 집중하다 보니, 해당 객체를 스프링(Spring)의 제어 역전(IoC) 컨테이너가 관리할 수 있도록 등록하는 어노테이션(예: @Service, @Component)을 누락하거나 설정 파일에 빈(Bean)으로 명시하지 않았던 것입니다.

애플리케이션 구동 시점에 해당 도메인의 컨트롤러나 인터셉터가 정상적으로 로드되지 않으니, Kong Gateway가 아무리 올바른 내부 주소로 실시간 트래픽을 전달해 주어도 애플리케이션 레이어에서는 이를 받아줄 컨텍스트 자체가 존재하지 않아 요청이 유실될 수밖에 없었습니다.

3.3 해결 및 교훈

원인을 파악한 뒤, 새롭게 추가된 데이터 정제 및 통계 연산 비즈니스 로직 클래스에 누락된 @Service 어노테이션을 명시하여 IoC 컨테이너에 빈(Bean)으로 정상 등록해 주었습니다.

//Example:Register the misiing bean annotation in the IoC container
@Service
Public class RealtimeStateProcessingServie implements StateServie {
   //Logic for collecting data from external systems and processing real-time statistics

}

의존성 주입(DI)이 정상적으로 이루어지자, 로컬 환경에서 테스트용 API를 호출했을 때 Kong의 JWT 검증을 거쳐 백엔드 내부 로직까지 막힘없이 한 번에 트래픽이 흐르는 것을 확인했습니다.

이 트러블슈팅을 통해 아무리 인프라(Kong Gateway) 영역에서 통신 선로를 매끄럽게 뚫어 놓았더라도, 결국 이를 수용하는 백엔드 애플리케이션의 핵심 컴포넌트 스캔과 생명 주기 관리가 명확하게 맞아떨어져야 거대한 분산 시스템이 유기적으로 맞물려 돌아간다는 기본기를 다시금 상기할 수 있었습니다.

4. 결론: 첫 Kong Gateway 연동을 마치며 배운 점

이번 프로젝트는 저에게 '이미 구축된 사내 인프라를 활용하여 백엔드 아키텍처를 진화시키는 경험'을 선사해 준 뜻깊은 기회였습니다. 회사에 Kong Gateway 환경이 이미 설정되어 있었음에도 그동안은 직접 다뤄볼 기회가 없었기에, 처음으로 신규 URL을 라우팅하고 토큰 레이어를 연동하는 과정은 낯설고 신선한 도전이었습니다.

처음에는 단순히 "네트워크 경로를 연결해 주는 장비" 정도로만 생각했던 API Gateway가 백엔드 개발자 관점에서 얼마나 강력한 무기가 될 수 있는지 직접 체감할 수 있었습니다.

  • 백엔드가 직접 구현해야 했던 무거운 인증 검증 레이어를 최전선에서 대신 처리해 주어 애플리케이션의 CPU 자원을 효율적으로 보호할 수 있었고,

  • 그 덕분에 저는 오직 타 시스템의 데이터를 정제하고 정확한 통계를 계산하는 '핵심 비즈니스 로직'에만 집중할 수 있었습니다.

로컬 테스트 과정에서 빈 등록 누락이라는 사소한 시행착오도 겪었지만, 이 디버깅 과정을 통해 인프라 인지적 관점(Infrastructure-aware)에서 애플리케이션 프레임워크를 바라보는 시야를 넓힐 수 있었습니다.

인프라가 제공하는 강력한 공통 플러그인 생태계를 영리하게 활용하는 것 역시 백엔드 엔지니어의 핵심 역량임을 배웠습니다. 앞으로 구축될 다양한 신규 마이크로서비스 기능에서도 사내 표준인 Kong Gateway의 자원을 적극적으로 결합하여, 확장 가능하고 탄탄한 시스템 구조를 설계해 나가겠습니다.

kina.j

Site footer