grep

Engineering

API Management Platform 개발기: API 관리를 위한 플랫폼의 효율화 여정

야놀자

2025년 9월 12일

원문에서 보기 ↗

이 이미지는 생성형 AI를 활용해 제작하였습니다.

Yanolja의 Developer Platform Engineering 조직은 개발자들의 생산성 향상을 목표로, 플랫폼 엔지니어링 관점에서 다양한 제품을 개발 및 운영하고 있습니다.

이번 글에서는 오랜 시간 발전시켜 온 API Management Platform의 초기 버전부터 현재 버전에 이르기까지의 효율화 여정을 소개 합니다.

이 플랫폼을 통해 API 배포 시간을 기존 1–2일 에서 5분으로 단축 시키고, 개발자 셀프 서비스를 통해 운영팀 업무를 80% 이상 줄일수 있었습니다.

앞으로 이어질 내용에서는 API Management Platform이 어떤 과정으로 발전하고 효율화를 달성 했는지 살펴보겠습니다.

🌐 API Management Platform 이란?

API Management Platform은 API를 설계, 배포, 모니터링, 보안 관리에 필요한 다양한 도구와 기능을 제공하는 서비스 세트입니다. API의 전체 수명주기를 관리하고, 개발자와 비즈니스 사용자가 API를 효과적으로 개발, 배포, 보안, 모니터링 및 분석할 수 있도록 지원합니다.

🚀 API Management Platform, 왜 필요했을까요?

새로운 API Management Platform의 필요성을 이해하려면, 먼저 야놀자의 API 관리 방식이 어떻게 변화해 왔는지 그 역사를 돌아볼 필요가 있습니다.

Version 1: 중앙 집중 관리의 시작

야놀자의 API 관리 여정은 Spring Cloud Gateway를 통해 API를 중앙 관리하는 것으로 시작했습니다.

도입효과:

당시의 한계:

Version 2: Gateway 기능 중심의 상용 솔루션 도입

Version 1의 기능적 한계를 극복하기 위해, 오픈소스 기반의 API Gateway(Tyk, Kong, Krakend 등)를 검토했습니다.

그 결과, Go 언어 기반의 높은 성능을 제공하며 오픈소스 버전에서 Gateway의 모든 기능을 무료로 제공하여 확장성 측면에서 유리한 Tyk Gateway를 선택했습니다.

또한 사용성 개선을 위해 API를 GUI 기반으로 관리할 수 있는 유료 버전의 대시보드도 함께 도입하기로 최종 결정했습니다.

도입효과:

남은 한계 사항:

Version 3: 플랫폼 엔지니어링 관점에서의 발전

NOL Universe(야놀자, 인터파크, 트리플 등 B2C 중심의 통합)의 성장이라는 새로운 비즈니스 요구사항에 효과적으로 대응하고 이전 버전들의 한계를 극복하기 위해, Version 3는 플랫폼 엔지니어링 철학을 바탕으로 개발되었습니다.

플랫폼 엔지니어링은 단순히 API를 관리하는 시스템을 넘어, 개발자가 자율적으로 API를 설계·배포·운영할 수 있는 환경을 제공하고, 조직 전체가 공통된 플랫폼을 통해 생산성과 안정성을 동시에 확보하도록 돕는 접근 방식입니다.

이러한 관점에서 Version 3의 API Management Platform은 다음과 같은 목표를 지향합니다.

[설계 원칙과 목표]

비즈니스 가치 창출:

개발자의 생산성 극대화:

플랫폼의 안정성 및 확장성

비용 효율화

🏗️ 플랫폼 설계 깊이 보기: 핵심 개념과 아키텍처

핵심 도메인 설계

API 관리를 위한 핵심 도메인은 다음과 같습니다.

⚫ Organization (조직)

API 관리 경계를 정의하는 최상위 개념입니다.(예: NOL Universe, Y Next, …)

⚫ Environment (환경)

실제 Gateway가 물리적으로 구성되고 API가 배포되어 실행되는 단위입니다.

조직 > 목적(내부/외부) > 배포 환경(개발,운영)의 3단계 계층 구조로 각각 독립적으로 구성됩니다.

✔️ 구조 예시

✔️ 목적별 특징

⚫ Proxy

API 요청을 프록시하는 서비스 구성 요소이자, API 관리의 핵심 개체입니다.

✔️ Proxy Spec:

✔️ Deployed Proxy:

✔️ 버전 관리 예시

⚫ Key

⚫ Group

⚫ User

API 관리 라이프사이클

다음과 같이 API의 시작부터 폐기까지 전 생애 주기를 플랫폼 안에서 관리할 수 있도록 설계되었습니다.

  1. Design: API Design 단계로, 표출할 API의 엔드포인트, 요청 및 응답 형식 등을 정의하고 문서화하는 단계입니다.
  2. Development: Design 단계의 내용을 바탕으로 API Management Platform에서 Proxy를 생성하는 단계입니다.
  3. Testing: Development 단계에서 생성한 API가 예상대로 동작하는지 검증하는 단계입니다. API가 Target Server와 정상적으로 통합되는지 확인합니다.
  4. Deployment: API를 환경에 반영하는 단계입니다. 각 환경에서 API의 버전을 독립적으로 배포 및 관리할 수 있으며, 운영 중인 API의 새로운 버전을 무중단으로 반영할 수 있습니다.
  5. Operation and Monitoring: API가 배포된 이후 운영 단계에서 API가 안정적으로 작동하는지 모니터링하는 단계입니다.
  6. Decommissioning: 더 이상 사용되지 않는 API는 명확한 폐기 절차를 통해 안전하게 종료되는 단계입니다.

시스템 아키텍처 설계

시스템 아키텍처

API Management Platform은 세 가지 계층으로 구성됩니다.

⚫ Data Plane:

API 호출 시 요청과 응답이 오가는 실질적인 트래픽 처리를 담당하는 계층입니다. 조직(Organization)별, 목적(내부/외부)별, 배포 환경(개발/운영)별로 독립적으로 구성 됩니다.

⚫ Management Plane:

분산되어 있는 각 Data Plane을 중앙에서 일관되게 제어하고, 플랫폼의 핵심 비즈니스 인 API 관리와 관련된 로직을 수행하는 두뇌와 같은 계층입니다. 모든 API 관련 정보의 단일 소스(Single Source of Truth) 역할을 수행함으로써, 복잡한 분산 환경에서도 강력하고 일관된 API 거버넌스를 유지할 수 있도록 설계되었습니다.

✔️ Management Server (자체 구현): 플랫폼의 핵심 로직을 수행하며, 전체 API 관리 흐름을 제어하는 컨트롤러(Controller) 역할을 합니다. User Plane에는 API 관리를 위한 기능을 제공하고, Data Plane의 Synchronizer와 통신하며 API의 배포까지의 과정을 제어합니다.

✔️ Storage (MongoDB): 플랫폼의 모든 데이터를 저장하는 영구 저장소입니다.

⚫ User Plane:

개발자가 플랫폼과 상호작용하는 GUI 기반의 화면 계층입니다. 이 계층은 플랫폼 엔지니어링의 핵심 가치인 ‘개발자 경험(Developer Experience)’ 향상에 초점을 맞추어 설계되었습니다.

⚙️ 핵심 기능: 안정적인 API Deployment (배포)

새로운 API Management Platform 개발에서 가장 핵심적인 기능은 “개발자가 직접, 쉽고, 빠르게 그리고 안정적으로 API를 배포할 수 있는 환경”을 구축하는 것이었습니다. 이를 위해 먼저 해결해야 할 핵심 요구사항들을 정의했습니다.

핵심 요구 사항

⚫ 기능적 요구사항

⚫ 비기능적 요구사항

이러한 요구사항들을 만족시키기 위해 ‘Synchronizer’라는 핵심 컴포넌트를 설계하고 개발을 진행했습니다.

Synchronizer: API 배포의 핵심, 그 상세 설계

Synchronizer는 Management Plane으로부터 전달받은 API 명세를 각 Gateway에 안정적으로 반영하고 상태를 피드백하는 중요한 역할을 수행합니다.

⚫ Gateway의 API 반영 방식

사용할 오픈소스 버전의 Gateway는 API 반영을 위해 특정 경로의 FileSystem에 API 명세를 저장하고 Gateway로 load를 통해 반영이 됩니다.

⚫ Synchronizer 구성 방식: Shared vs Dedicated

Synchronizer를 어떻게 구성하여 배치할지에 대해 두 가지 방식을 검토했습니다.

synchronizer 구성 방식 예시

⚫ API 반영 방식: Push vs Pull 모델

Management Plane(server)에서 Synchronizer로 변경사항을 전달하는 방식에 대해 두 가지 방식을 검토했습니다.

✔️ Dedicated 구성 기반의 Pull 모델 방식 선택

시스템의 복잡도 최소화 하고 안정성과 확장성을 핵심 기준으로 삼아,

각 Gateway Node에 전용 Synchronizer를 배치하는 Dedicated 구성과, Synchronizer가 주기적으로 변경사항을 조회하는 Pull 모델을 결합한 방식을 채택 하였습니다.

이 방식은 특히 kubernetes 같은 환경에서 Gateway Node가 동적으로 확장 및 축소되는 상황에서 각 Gateway와 Synchronizer가 1:1 쌍(pair)으로 독립적으로 확장되어, 장애 격리와 유연한 스케일링이 가능한 구조적 이점을 제공합니다.

또한 API 변경사항 반영에 있어서도, 모든 Gateway Node에 즉시 반영하는 실시간성 보다는 Gateway Node 간의 일시적인 불일치를 허용하되 시간이 지나면 결국 동일한 상태로 수렴하는 최종적 일관성(Eventual Consistency) 모델이 더 적합하다고 판단했습니다.

이러한 판단에 따라, 네트워크 지연이나 일시적인 전송 실패와 같은 상황에서도

각 Synchronizer가 자가 복구(Self-healing)를 통해 동기화할 수 있는 Pull 방식이 운영 안정성 측면에서 더욱 유리하다는 결론에 도달했습니다.

⚫ Gateway와의 독립성 확보

✔️ API 명세 추상화

“Gateway 독립성” 요구사항을 만족하기 위해, Gateway 구현 기술과 무관한 표준화 된 API 명세인 ProxySpec을 보편적으로 사용할 수 있는 속성으로 추상화 하여 정의 했습니다.

✔️ 전략 패턴으로 구현한 Transformer 모듈

표준화 된 API 명세를 Gateway의 네이티브 설정으로 변환을 담당 하는 Transformer 모듈을 구현했습니다. Transformer 모듈은 Synchronizer 내장되어 사용됩니다.

Transformer는 전략 패턴(Strategy Pattern)을 적용하여 Gateway별 변환 로직을 독립적으로 구현함으로써 Gateway 구현 기술의 유연한 확장을 가능 하게 했습니다.

API 명세(Proxy Spec) 변환 흐름

다음과 같은 API 반영 흐름을 통해 API Management Platform에서 특정 Gateway 기술에 의존적이지 않게 되었습니다.

⚫ API 변경 감지 성능 최적화

Synchronizer와 Management Server는 주기적으로 통신하여 API에 대한 변경을 감지하여 동기화를 수행 합니다. 이때 전체 API 명세를 받는 방식은 네트워크 트래픽과 리소스 측면에서 비효율적이기 때문에 실제 API 명세가 바뀌었을때만 Gateway에 반영하는 것이 중요 합니다.

이 문제를 해결 하기 위해 해시(Hash) 기반 변경 감지 방식의 전략을 사용했고, 해시 계산은 Management Server에서 일원화해 JSON 직렬화 방식 차이로 인한 오탐(false positive)을 방지하도록 했습니다.

Management Server에서 API 명세(ProxySpec)를 표준화된 방식으로 직렬화한 뒤 해시값을 계산하고, 각 Synchronizer는 Gateway Node에 반영된 API 명세 해시값을 주기적으로 보고합니다.

Management Server는 이 해시값을 비교해 실제로 변경이 발생한 API 경우에만 새로운 API 명세를 응답 합니다.

이 방식의 장점은 해시값이 같으면 불필요한 동기화 과정을 생략하여 시스템 부하가 줄어들고 및 불필요한 네트워크 대역폭을 낮출수 있습니다.

Management Plane: Gateway 노드의 상태를 감시하고 제어하는 중앙 관제탑

Management Plane은 독립된 Gateway 단위로 노드 목록을 관리 합니다.

Gateway내 각 노드는 주기적으로 Management Server에 동기화 요청을 보냅니다.

Management Server는 동기화 주기의 2배 이상 기간 동안 동기화 요청이 수신되지 않은 Gateway 노드를 ‘비활성 상태(Inactive)’로 판단하고 목록에서 제거합니다.

API 반영이 완료 되기 위해서는 해당 Gateway의 모든 활성 노드에 반영이 완료되어야 합니다. 일부 노드에만 반영된 경우에는 API 반영이 완료된 것으로 처리되지 않습니다.

Data Plane의 Kubernetes 네이티브 아키텍처

Data Plane은 안정적으로 Gateway의 대규모 트래픽을 처리해야 하는 최전선입니다. 이를 Kubernetes 환경 위에 구축하기로 결정했고, Kubernetes가 제공하는 강력한 기능들을 최대한 활용하여 안정성과 운영 효율성을 극대화하고자 했습니다.

특히 하나의 Gateway Pod를 단일 기능의 Container로 구성하는 대신, 여러 전문화된 Container들의 조합으로 설계하는 ‘Container 디자인 패턴’을 적극적으로 활용했습니다. 이를 통해 각 Container는 ‘하나의 일’만 책임지게 되어(단일 책임 원칙), 시스템 전체의 복잡도는 낮추고 유연성과 확장성을 높일 수 있었습니다. 이어지는 내용에서는 어떻게 Init Container와 Sidecar Container을 활용하여 Gateway Pod의 역할을 효율적으로 분리했는지 자세히 설명하겠습니다.

⚫ Data Plane Gateway Pod의 역할 분리

Kubernetes 환경에서 Data Plane는 Synchronizer를 Gateway Pod 안에서 Sidecar 패턴을 활용하여 역할을 효율적으로 분리 하도록 구성 했습니다. Sidecar 패턴은 Main Application Container 기능을 보조하거나 확장하기 위해 동일한 Pod 내에 추가 Container를 배치하는 디자인 패턴입니다. 이는 각 Container가 특정 단일 책임을 가지도록 하여 모듈성과 유지보수성을 높이며, Main Application의 코드를 수정하지 않고도 기능을 유연하게 추가/변경할 수 있게 합니다.

Gateway Pod는 다음과 같이 구성되어 있습니다:

[Init Container: API 초기 로드]

Gateway 서비스가 실제 트래픽을 처리하기 위한 초기 준비 단계에서는 Init Container가 중요한 역할을 수행합니다.

✔️ Init Container 설명 및 역할

✔️ Gateway Pod에서의 역할 적합성

[Sidecar Container: Synchronizer]

Gateway 서비스가 시작된 이후에도 API 정보는 지속적으로 최신 상태를 유지해야 합니다. 이를 위해 Sidecar Container를 활용합니다.

✔️ Sidecar Container 설명 및 역할:

✔️ Gateway Pod에서의 역할 적합성:

[Main Container: Gateway]

Gateway 서비스: 실제 클라이언트의 요청을 받아 API 라우팅, 인증, 인가 등 핵심 Gateway 기능을 수행하는 Container입니다.

⚫ Gateway의 API 반영 방식: Storage 공유를 통한 협력

이러한 Init Container와 Sidecar Container가 Main Container(Gateway)와 원활하게 협력할 수 있는 핵심은 Pod 내에서 Storage를 공유한다는 점입니다. Pod 내의 Container는 동일한 네트워크 네임스페이스뿐만 아니라 Volume(Storage)도 공유할 수 있습니다.

따라서, Init Container는 초기 API 로드 시 Shared Volume에 API 명세 파일을 저장하고, Sidecar Container는 지속적으로 변경된 API 정보를 이 Shared Volume에 업데이트할 수 있습니다. Main Gateway Container는 이 Shared Volume에 접근하여 최신 API 명세를 읽어들임으로써, Init Container와 Sidecar Container가 준비하고 동기화한 API 정보를 직접 활용하여 서비스에 반영합니다. 이 구조는 API 반영의 효율성과 안정성을 동시에 보장합니다.

⚫ Pod 안에서의 흐름

✔️ 초기화 흐름

  1. Pod 내 Init container 가 실행되고 Management Plane(server)로 Gateway Node 정보와 함께 대상 환경에 반영 되야할 API 동기화 요청 (synchronize)
  2. Management Plane(server)는 신규로 생성된 Gateway Node를 목록에 업데이트 후 대상 Gateway에 반영 되어야 할 API 동기화 정보 전달
  3. Init Container는 반영해야할 API 명세(ProxySpec)를 Native Gateway 명세로 변환 한 뒤 Pod 내 Shared Volume의 특정 경로에 저장
  4. Init Container는 반영한 API 목록을 Management Plane(server)에 피드백 (acknowledge)
  5. Management Plane(server)는 API가 반영된 Gateway Node 목록에 동기화 완료된 신규 Gateway Node 추가
  6. Init Container 종료
  7. Sidecar Container 및 Main Container 시작
  8. Main Container(gateway) 초기화(Shared Volume의 특정 경로에 있는 API 목록을 로드) 후 준비 완료 상태
  9. Sidecar Container(synchronizer)는 Main Container(gateway)가 준비 되면 준비 완료 (readiness probe: ok)

Pod 준비 완료

✔️ 동기화 흐름

  1. Sidecar Container(synchronizer)는 주기적으로 Management Plane(server)으로 현재 반영된 API 목록과 함께 동기화 요청 (synchronize)
  2. Management Plane(server)는 대상 Gateway에 변경된 동기화 대상 API 정보 응답
  3. Sidecar Container(synchronizer) 변경된 API 정보를 Shared Volume의 특정 경로에 반영
  4. Sidecar Container(synchronizer)는 Main Container(gateway)에 API Reload 요청
  5. 반영된 API 목록을 Management Plane에 피드백 (acknowledge)

1~5 과정 반복

📈 얻은 성과

야놀자의 API Management Platform (Version 3) 개발 여정은 다음과 같은 성과를 달성 했습니다.

개발자 생산성 향상

운영 효율성 극대화

플랫폼 안정성 및 확장성

비용 절감

개선 Scope 한눈에 보기

🎯 마치며

하나의 플랫폼을 만들기까지의 여정을 돌아보며, 단순히 새로운 제품을 개발한 것이 아니라 ‘어떻게 하면 개발자들이 더 가치 있는 일에 집중할 수 있을까?’라는 근본적인 질문에 대한 답을 찾고자 했습니다. 이 글을 마무리하며, 그 과정에서 얻은 교훈과 앞으로의 여정을 공유하고자 합니다.

왜 플랫폼 엔지니어링이 필요한가?

만약 모든 서비스 개발팀이 API Gateway와 같은 공통 서비스를 직접 개발하여 구축하고 운영 한다면 어떨까요?

아마도 많은 팀이 비슷한 기술적 문제를 해결하기 위해 각자의 소중한 리소스를 투입하게 될 것입니다. 한 팀의 성공적인 경험은 다른 팀으로 공유되지 못한 채 파편화되고, 조직 전체적으로는 중복된 노력과 관리 비용만 남게 됩니다.

플랫폼 엔지니어링은 바로 이 문제를 해결 하기 위해 존재합니다.

API Management Platform은 API Gateway의 ‘공통 기능’과 API를 안전하고 효율적으로 관리할 수 있는 기반을 제공합니다.

이를 통해 개발팀은 공통 기능과 API 관리에 대한 고민과 부담을 덜고, 검증된 성능과 안정성을 바탕으로 비즈니스 로직이라는 핵심에만 집중할 수 있습니다.

결과적으로 조직은 모든 팀이 더 빠르고 안전하게 가치를 전달할 수 있는 ‘골든 패스(Golden Path)’를 갖게 됩니다.

가장 중요했던 두 가지 교훈

이번 여정에서 얻은 가장 큰 교훈은 두 가지입니다.

첫째, 훌륭한 개발자 경험(Developer Experience)이 곧 플랫폼의 핵심 가치라는 점입니다. 아무리 뛰어난 기술도 사용하기 어렵다면 외면받습니다. 저희 조직은 개발자가 최소한의 노력으로 최대의 효과를 누릴 수 있도록, 모든 설계 결정의 중심에 개발자 경험을 두었습니다.

둘째, 변화에 유연한 아키텍처의 중요성 입니다. 특정 기술에 종속되지 않는 추상화 설계를 통해, 미래의 기술 변화에 흔들리지 않는 지속 가능한 플랫폼의 토대를 마련할 수 있었습니다. 이는 장기적인 안정성과 확장성 핵심입니다.

우리의 다음 여정

API Management Platform은 이제 막 첫발을 뗀 시작일 뿐입니다. 플랫폼을 적극적으로 알리고 개발자들의 생생한 피드백을 바탕으로 지속적으로 발전시켜 나갈 것입니다.

나아가 API Management Platform 뿐만 아니라 애플리케이션 레벨에서 인프라 레벨에 이르기 까지, 개발자들이 겪는 다양한 범위의 문제들을 해결하기 위한 여러 플랫폼을 함께 고민하며 만들어가고 있습니다.

궁극적으로 저희 조직이 만들어가는 이러한 플랫폼들을 통해 개별 팀의 노력이 조직 전체의 강력한 기술 자산으로 축적되고, 이를 바탕으로 모두가 함께 성장하는 선순환 구조를 만드는 것입니다. 기술을 통해 동료들의 성장을 돕고, 회사의 혁신을 가속하는 것. 그것이 저희 조직이 나아갈 방향입니다.

이 글을 읽어주신 모든 분께 감사드립니다.

누구나 마음 편히 놀 수 있는 세상을 함께 만들어갈 동료를 찾고 있어요 :)

지금 채용 중인 포지션 보러가기 >