목차
설정만으로 API를 여는 Uber Edge Gateway의 설계 (2021-05)
원문 정보
- 원문: The Architecture of Uber’s API gateway
- 매체 · 게시일: Uber Engineering Blog · 2021-05-19
- 저자: Madan Thangavelu(Director of Engineering), Abhishek Parwal(Sr. Software Engineer II), Rohit Patali(Sr. Software Engineer II)
- 원문 내용을 바탕으로 재구성한 요약입니다.
코드 대신 설정을 받는 UI
우버의 API 개발자는 게이트웨이 코드를 직접 고치지 않습니다. UI에서 API의 경로와 요청·응답 타입, 호출할 백엔드 서비스를 지정하고 설정을 공개합니다. 그다음은 게이트웨이 인프라의 일입니다. 설정을 실제 트래픽을 처리하는 API로 바꾸고, 앱에서 쓸 클라이언트 SDK도 만듭니다.
앱은 이 게이트웨이라는 단일 진입점에서 여러 백엔드 마이크로서비스의 데이터와 로직을 사용합니다. 라우팅, 프로토콜 변환, 속도 제한, 로드 셰딩, 헤더 보강과 전파 같은 공통 기능을 모으는 자리이기도 합니다. 게이트웨이를 단순한 로드밸런서로 만들 수도 있지만, 우버의 Edge Gateway는 요청·응답 본문에 복잡한 처리를 하는 쪽을 택했습니다. 여러 프로토콜을 넘나드는 처리가 이 선택에 포함됩니다. 앞선 글에서는 우버 게이트웨이의 세대별 변천과 이런 설계 선택의 배경을 다뤘습니다.
셀프서비스의 범위는 API 생성에 그치지 않습니다. 수정과 삭제, 버전 관리도 UI에서 처리합니다. 개발자는 단계별 안내를 따라 허용 호출 수와 앱, 통신 프로토콜, 허용 헤더, 필드 매핑과 검증을 설정합니다. 요청 타임아웃, 모니터링, 알림까지 같은 화면에서 정하며, UI는 각 단계에 필요한 검증을 강제합니다.
공개 전에는 설정 변경을 리뷰하는 관문을 둘 수 있습니다. 작성하던 세션을 저장해 다른 사람과 공유하거나 나중에 이어서 작업하는 기능도 갖췄습니다. API 개발자가 다루는 것은 끝까지 설정입니다. 요청 처리 코드와 빌드를 만드는 복잡성은 이 화면 뒤에 남습니다.
모든 API 앞에 모인 보호 장치
공통 진입점을 두면 인증 구현을 API마다 따로 고민하지 않아도 됩니다. 우버는 재사용 가능한 인증(AuthN)·인가(AuthZ) 구현을 미들웨어로 제공하고, 각 엔드포인트가 적어도 하나를 사용하도록 강제합니다. 모든 외부 API 요청은 인증이나 인가, 또는 둘 다를 거칩니다. 플랫폼 담당자가 구현을 수정하면 모든 엔드포인트에 반영됩니다.
우버가 소개한 공통 기능에는 이미 구현한 것과 준비 중인 것이 섞여 있습니다. 인증 외에도 백엔드 보호, 접근 기록, 사용자 차단처럼 여러 API가 함께 쓸 기능을 게이트웨이에 모았습니다.
백엔드를 호출하는 모든 클라이언트는 서킷 브레이커로 감쌉니다. 백엔드의 지연이나 에러율이 설정에 따라 브레이커를 작동시키면 연쇄 장애를 막고, 상태가 나빠진 서비스에 회복할 여유를 줍니다. 요청이 백엔드에 도착하기 전에는 엔드포인트별 속도 제한도 적용합니다. 기준은 userID나 user-agent, IP에 한정되지 않습니다. 경로·쿼리 파라미터, 헤더, 본문의 특정 필드나 요청 속성의 조합을 사용해 사용자 단위보다 세밀한 정책을 만들 수 있습니다.
이 제한값까지 매번 코드로 생성하는 방식은 불편했습니다. 값을 바꾸려면 빌드와 배포를 거쳐야 했기 때문입니다. 우버는 사용자 설정을 Git에 보관하되, 속도 제한처럼 동적으로 바뀌는 부분은 별도 config store로 옮겼습니다. 엔드포인트마다 재배포 없이 쿼터를 지정할 수 있게 된 배경입니다.
감사 파이프라인은 모든 앱에서 켜져 있습니다. 게이트웨이는 풍부한 메타데이터를 담은 접근 로그를 남겨 제품별 API 접근 패턴을 기록하고, 감사에 쓸 수 있도록 보관합니다. 악의적인 행위자가 자동화 시스템으로 API를 사용할 때 보안 감사를 지원하며, 제품을 버전·지역·앱별로 살펴보는 자료도 됩니다. 특정 SDK 버전이나 앱, 지역, 인터넷 사업자에서 나타나는 버그와 이상 징후를 포착하는 데도 이 기록을 씁니다.
계정 전체를 차단하는 것은 큰 망치입니다. 잠시 시스템을 남용하는 사용자에게는 짧은 기간 API 접근만 막는 장치를 제공합니다. 사기 탐지·보안 시스템이 사용자나 앱 버전 등의 식별자를 넘기면, 게이트웨이는 TTL이 있는 외부 캐시에 차단 정보를 저장하고 접근을 막습니다.
캐시는 요청을 적절한 데이터센터로 보내는 데도 쓰입니다. 이중화된 데이터센터와 존을 운영하는 환경에서 각 사업 단위는 워크로드를 데이터센터에 나누는 방식을 정합니다. Edge Gateway는 사용자·지역·버전을 특정 데이터센터에 연결하는 어피니티 정보를 캐시에 설정하도록 지원합니다. 들어오는 요청의 사용자, 기기, 앱이 이 조건에 해당하면 그 정보에 따라 요청을 다시 라우팅합니다.
region을 regionID로 옮기는 요청 경로
이런 기능을 설정만으로 조합하려면 요청 처리 과정부터 나눠야 합니다. Edge Gateway는 요청 경로를 핸들러에 연결하고, 프로토콜 매니저에서 미들웨어와 데이터 검증, 핸들러, 백엔드 클라이언트로 이어지는 스택을 실행합니다. 응답은 역순으로 돌아옵니다. 같은 구성요소가 들어오는 요청과 나가는 응답을 각각 처리하는 방식입니다.
UI에서 정한 내용은 Git 저장소의 YAML과 Thrift 파일에 담깁니다. YAML은 각 구성요소에 정보를 주고 서로 연결하는 접착제 역할을 합니다. Thrift는 요청·응답 데이터와 프로토콜의 의미를 정의합니다. 여러 기능과 프로토콜의 기준을 한곳에 두기 위해 Thrift IDL의 어노테이션을 적극적으로 사용합니다.
맨 앞의 프로토콜 매니저에는 JSON, Thrift, Protobuf 각각에 맞는 역직렬화기와 직렬화기가 있습니다. 입력과 출력의 형식이 같아야 하는 것은 아닙니다. JSON 요청을 받고 proto로 인코딩한 응답을 돌려주는 조합도 지원합니다.
이 계층의 YAML 설정은 3줄입니다. 프로토콜 종류와 Thrift 파일 경로, 사용할 메서드를 지정합니다. 예를 들어 HTTP API의 나머지 스키마와 프로토콜 정보는 apiSample.thrift에 둡니다. 이 파일에는 JSON 요청·응답의 데이터 타입뿐 아니라 HTTP 경로와 동사도 들어갑니다. HTTP 동작은 Thrift 어노테이션으로 표현하며, 핸들러의 에러를 알맞은 HTTP 응답으로 바꾸는 규칙도 여기에 둡니다. HTTP 동작을 제어하는 어노테이션은 이 밖에도 열두 개가 넘습니다.
다음은 미들웨어입니다. 엔드포인트는 인증이나 속도 제한 같은 로직을 하나 이상 골라 조합하며, 플랫폼이 모든 요청에 강제하는 미들웨어도 실행합니다. 각 미들웨어가 requestMiddleware와 responseMiddleware를 모두 구현해야 하는 것은 아닙니다. 요청 맥락에 따라 아무 일도 하지 않을 수 있고, 실패하면 나머지 스택을 건너뛰고 자신의 응답을 호출자에게 돌려줍니다.
미들웨어 설정의 구체적인 예가 header.x-user-uuid와 transformRequest입니다. 인증 미들웨어가 header.x-user-uuid를 읽도록 지정하고, transformRequest에는 요청의 region을 백엔드 호출의 regionID로 복사하도록 설정합니다. 새 미들웨어를 만드는 개발자는 사용자가 채워야 할 설정 파라미터의 스키마도 정의합니다. 플랫폼의 상위 기능을 API 개발자에게 노출하는 가장 유연한 구성요소가 이 미들웨어입니다.
핸들러는 요청을 검증하고 페이로드를 변환한 뒤, 엔드포인트의 요청 객체를 백엔드 클라이언트의 요청 객체로 바꿉니다. 들어온 필드가 백엔드의 필드와 정확히 일치하면 핸들러 설정만으로 충분합니다. 이름이 다를 때 앞서 본 transformRequest로 매핑합니다. 응답 쪽에서는 백엔드 응답을 엔드포인트 응답으로 바꾸고 필요한 변환을 적용한 다음, 스키마에 맞는지 검증하고 직렬화합니다.
실제 백엔드 호출은 설정에서 고른 프로토콜에 맞춰 생성한 클라이언트가 담당합니다. 클라이언트의 요청·응답 변환과 스키마 검증, 서킷 브레이킹과 재시도, 타임아웃·데드라인, 에러 처리도 설정 대상입니다. YAML과 Thrift를 나눠 쓰는 예로, TChannel 백엔드의 요청·응답은 backendSample.thrift에 정의하고 호출 가능한 메서드 두 개를 지정합니다. Backend::method가 반드시 TChannel 메서드여야 하는 것은 아닙니다. /backend/method 같은 HTTP API도 어노테이션을 사용해 같은 Thrift 정의에 표현할 수 있습니다.
앱까지 이어지는 Thrift 정의
요청 경로와 데이터 타입, 에러 응답까지 설정에 담겨 있으면 그 정의를 게이트웨이 밖에서도 쓸 수 있습니다. YAML과 Thrift가 API 전체를 기술하므로 API 문서를 일관된 형식으로 자동 생성합니다. 우버의 모든 모바일 앱도 Thrift IDL에서 서버와 통신할 서비스와 모델을 만듭니다.
모바일 클라이언트를 만드는 CI 잡은 게이트웨이에서 모든 엔드포인트의 IDL을 가져와 맞춤 코드 생성을 실행합니다. 이 과정은 데이터 타입뿐 아니라 예외의 상태 코드, URL 경로, HTTP 메서드를 담은 Thrift 어노테이션에도 의존합니다. 생성된 코드의 리뷰에서 실행하는 CI 잡은 하위 호환을 깨는 엔드포인트 스키마 변경을 막습니다. 게이트웨이와 앱이 같은 정의를 쓰면서 변경 검증까지 연결한 방식입니다.
백엔드가 돌려주는 필드를 앱에 전부 전달할 필요도 없습니다. 여러 엔드포인트가 같은 백엔드 클라이언트를 공유할 수 있고 API를 만드는 절차도 간단하므로, 특정 사용자 경험에 필요한 필드만 고르는 API를 만들 수 있습니다. 백엔드 응답 전체를 내보내는 대신 엔드포인트에서 응답 필드를 추립니다.
HTTP와 gRPC가 만나는 Zanzibar 빌드
설정 파일만으로 요청이 처리되지는 않습니다. 구성요소별 YAML과 Thrift를 모아 API 하나를 온전히 기술한 뒤에는, 이를 실행할 런타임으로 조립해야 합니다. Kong, Tyk나 Envoy·Nginx 같은 리버스 프록시처럼 실행 중에 설정을 읽어 API를 서비스하는 방식도 있습니다. 우버는 설정에서 코드를 생성해 빌드 산출물을 만드는 방식을 택했습니다.
빌드는 스키마 객체부터 만듭니다. 모든 스키마 파일을 처리기에 넣어 thriftrw와 protoc용 네이티브 Go 코드를 생성하며, 이 코드는 직렬화·역직렬화와 클라이언트 인터페이스 생성에 쓰입니다. 모바일 앱과 맺은 API 계약에는 별도 처리가 더 필요합니다. i64, enum, 여러 프로토콜을 다루기 위한 맞춤 직렬화 코드도 생성합니다.
그다음에는 구성요소 사이의 의존성을 풉니다. 백엔드 클라이언트는 독립적이어서 바로 생성할 수 있습니다. 미들웨어는 0개 이상의 클라이언트에 의존하고, 엔드포인트는 0개 이상의 미들웨어와 0개 또는 1개의 클라이언트에 의존합니다. 이 관계를 담은 의존성 그래프(DAG)는 빌드 시점에 해석합니다.
클라이언트를 엔드포인트와 독립적으로 생성한다는 점이 프로토콜 조합을 가능하게 합니다. 외부 엔드포인트는 HTTP여도 백엔드는 gRPC일 수 있습니다. 서로 다른 프로토콜을 쓰는 양쪽을 연결하는 작업이 Edge Gateway 빌드의 이 단계에서 이뤄집니다.
이제 DAG를 순회하며 엔드포인트를 생성합니다. 각 생성 단계는 템플릿을 불러와 엔드포인트 요청에서 클라이언트 요청으로 가는 매핑과 응답의 역방향 매핑을 만들고, 의존성을 주입합니다. 요청·응답 변환 정보로 IDL 객체를 채우는 작업도 여기서 수행합니다. 우버는 이 코드 생성 전체를 오픈소스 라이브러리 Zanzibar로 묶었습니다. 비슷한 게이트웨이를 만드는 팀이 확장해 사용할 수 있는 출발점입니다.
Go 링커의 한계에 닿은 생성 코드
코드를 생성하는 방식은 빌드에서 대가를 치렀습니다. 이전 세대의 게이트웨이는 IO 비중이 큰 작업에 잘 맞는 Node.js를 사용했습니다. 새 게이트웨이에서는 우버의 언어 플랫폼 팀이 지원하는 언어에 맞추기로 했고, 당시 선택지는 Go와 Java였습니다. Go를 선택한 뒤 성능은 크게 좋아졌습니다.
당시 Go에는 제네릭이 없었습니다. 그 때문에 생성 코드가 크게 늘었고, 결국 Go 링커의 한계에 닿았습니다. 바이너리를 컴파일할 때 심벌 테이블과 디버그 정보를 꺼야 할 정도였습니다. ID, HTTP 같은 명명 규칙도 문제를 만들었습니다. Thrift에서는 예약어가 아닌 이름이 Go에서는 예약어인 경우까지 겹쳐 빌드가 실패했고, API 개발자가 몰라도 될 내부 구현 세부가 사용자에게 드러났습니다.
UI에서도 단일 API를 만드는 일과 여러 API를 한꺼번에 바꾸는 일의 난도가 달랐습니다. Thrift 파일은 다른 Thrift 파일을 참조할 수 있고, 그 참조가 임의의 깊이까지 이어집니다. 이런 설정을 일괄 편집하는 흐름은 API 하나를 만드는 화면보다 다루기 어려웠습니다.
사용자가 설정을 제출한 뒤의 실패를 보여주는 일도 남았습니다. 빌드 시스템은 UI와 별개로 발전하므로, 빌드에서 생긴 에러를 UI에 전달하는 방식이 어긋날 수 있습니다. 사용자는 설정만 다루는데 실패 원인은 코드 생성과 빌드 안에 있습니다. 두 시스템 사이에 에러를 전달하는 일관된 계약이 있어야 UI에서도 빌드 실패를 제대로 드러낼 수 있습니다.
같은 프로토콜을 잇는 Envoy 런타임
여러 프로토콜을 지원하면서 생긴 문제는 코드의 양뿐이 아닙니다. JSON 스키마와 Thrift 스키마는 Union, Set, List, Map을 표현하는 타입이 맞지 않았습니다. 우버는 이 차이를 연결하는 자체 매핑 규칙을 만들어야 했습니다.
본문을 읽는 비용도 남습니다. 게이트웨이 기능 대부분은 요청·응답 페이로드를 역직렬화하지 않고도 구현할 수 있습니다. 하지만 프로토콜을 서로 변환하려면 본문을 해석해야 하므로 빌드 시스템이 복잡해지고 런타임에도 비용이 듭니다. 페이로드를 자유롭게 다루는 게이트웨이를 선택한 결과입니다.
백엔드와 모바일 앱이 같은 프로토콜을 쓴다면 선택이 달라질 수 있습니다. 본문을 역직렬화하지 않고 프로토콜 동사와 헤더만 다루도록 제한하면 도움이 될 수 있지만, 그만큼 복잡한 게이트웨이 기능에는 제약이 생깁니다. 본문을 어디까지 다룰지는 제공할 기능의 범위와 함께 결정되는 문제입니다.
우버는 원문 작성 시점에 앱에서 백엔드 서비스로 가는 gRPC 요청을 위한 Envoy 기반 게이트웨이 런타임을 개발 중이었습니다. 이 런타임에서도 API 개발자가 쓰는 셀프서비스 UI의 경험은 크게 바꾸지 않을 계획이었습니다.