@portone/mcp-server 0.13.0

package/assets/docs/blog/posts/2024-03/tgs.md

@@ -0,0 +1,238 @@
+---
+title: 포트원이 여러 PG사의 인터페이스를 연동하는 방법
+description: 여러 PG사의 인터페이스를 효율적으로 연동하기 위한 결정사항들을 소개합니다.
+author: ChanceKim
+date: 2024-03-11T15:00:00.000Z
+tags:
+  - Backend
+  - MSA
+  - gRPC
+  - DDD
+  - Typed Error
+---
+
+소프트웨어 엔지니어로서 새로운 서비스를 개발하다 보면 결제 기능을 구현해야 하는 경우가 생깁니다.
+일반적으로 엔지니어들은 결제 기능을 구현하기 위해 특정 PG사가 제공하는 연동 가이드를 따라가며 개발을 진행하고, 서비스를 런칭합니다.
+그러나 포트원은 여러 PG사의 인터페이스를 추상화하여 어떤 PG사를 사용하는지와 관계없이 통일된 인터페이스를 제공하는 것을 핵심 가치로 삼고 있습니다.
+따라서 포트원의 엔지니어들은 일반적인 PG 연동 작업과는 다른 차원의 문제들을 해결해 나가야 합니다.
+
+다른 한편으로 포트원은 현재 모놀리식 아키텍처(V1)에서 MSA(V2)로의 전환을 진행중입니다.
+V1을 완전히 버리고 V2로 넘어가는 것이 아니기 때문에 하나의 PG사를 새로 연동할 때, V1과 V2 모두에 연동해주어야 하죠.
+흔히 잘 운영되는 시스템의 특정 모듈을 변경하는 작업을 달리는 자동차의 바퀴를 갈아 끼우는 일에 빗대어 이야기하곤 하는데,
+포트원의 현재 상황은 나란히 달리고 있는 구형 자동차와 신형 자동차의 바퀴를 한꺼번에 갈아 끼워야 하는 상황입니다.
+
+이 글에서는 이와 같은 어려움 속에서 최적의 업무 효율을 달성하기 위해 선택한 아키텍처 레벨 및 단일 서비스 레벨의 결정사항에 대해 설명드리려 합니다.
+
+## PG사 간의 인터페이스 차이
+
+먼저, PG사 간의 인터페이스가 얼마나 다른지를 살펴보기 위해 예시를 들어 보겠습니다.
+아래는 대표적인 간편결제사 두 곳에서 결제창을 생성하기 위해 필요한 파라미터 목록입니다.
+
+- 카카오페이 결제 파라미터
+
+|       Name       |   타입   |필수여부|                                                         설명                                                         |
+|:----------------:|:--------:|:------:|:--------------------------------------------------------------------------------------------------------------------:|
+|        cid       |  String  |    O   |                                                   가맹점 코드, 10자                                                  |
+|    cid\_secret   |  String  |    X   |                                   가맹점 코드 인증키, 24자, 숫자와 영문 소문자 조합                                  |
+|partner\_order\_id|  String  |    O   |                                              가맹점 주문번호, 최대 100자                                             |
+| partner\_user\_id|  String  |    O   |                                              가맹점 회원 id, 최대 100자                                              |
+|    item\_name    |  String  |    O   |                                                  상품명, 최대 100자                                                  |
+|    item\_code    |  String  |    X   |                                                 상품코드, 최대 100자                                                 |
+|     quantity     |  Integer |    O   |                                                       상품 수량                                                      |
+|   total\_amount  |  Integer |    O   |                                                       상품 총액                                                      |
+| tax\_free\_amount|  Integer |    O   |                                                   상품 비과세 금액                                                   |
+|    vat\_amount   |  Integer |    X   |상품 부가세 금액 값을 보내지 않을 경우 다음과 같이 VAT 자동 계산 (상품총액 - 상품 비과세 금액)/11 : 소숫점 이하 반올림|
+|  green\_deposit  |  Integer |    X   |                                                       컵 보증금                                                      |
+|   approval\_url  |  String  |    O   |                                         결제 성공 시 redirect url, 최대 255자                                        |
+|    cancel\_url   |  String  |    O   |                                         결제 취소 시 redirect url, 최대 255자                                        |
+|     fail\_url    |  String  |    O   |                                         결제 실패 시 redirect url, 최대 255자                                        |
+| available\_cards |JSON Array|    X   |                             결제 수단으로써 사용 허가할 카드사를 지정해야 하는 경우 사용                             |
+
+- 네이버페이 결제 파라미터
+
+|           Name          |  타입 |필수여부|                                                                                                                                                                                                                                                         설명                                                                                                                                                                                                                                                         |
+|:-----------------------:|:-----:|:------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
+|      merchantPayKey     | String|    O   |                                                                                                                                                                                                                      가맹점 주문내역 확인 가능한 가맹점 결제번호 또는 주문번호를 전달해야 합니다                                                                                                                                                                                                                     |
+|merchantPayTransactionKey| String|        |                                                                                                                                                                                                      가맹점 주문내역 히스토리 확인이 가능한 가맹점 결제 트랜잭션 번호 또는 주문 트랜잭션 번호를 전달해야 합니다.                                                                                                                                                                                                     |
+|     merchantUserKey     | String|        |                                                                                                                                                                                                                   가맹점의 사용자 키(개인 아이디와 같은 개인정보 데이터는 제외하여 전달해야 합니다)                                                                                                                                                                                                                  |
+|       productName       | String|    O   |                                                                                                                                                                                                                                대표 상품명. 예: 장미의 이름 외 1건(X), 장미의 이름(O)                                                                                                                                                                                                                                |
+|       productCount      | Number|    O   |                                                                                                                                                                                                                         상품 수량 예: A 상품 2개 + B 상품 1개의 경우 productCount 3으로 전달                                                                                                                                                                                                                         |
+|      totalPayAmount     | Number|    O   |                                                                                                                                                                                                                                          총 결제 금액. 최소 결제금액은 10원                                                                                                                                                                                                                                          |
+|      taxScopeAmount     | Number|    O   |                                                                                                                                                                                                                과세 대상 금액. 과세 대상 금액 + 면세 대상 금액 + 컵 보증금 금액 (옵션) = 총 결제 금액                                                                                                                                                                                                                |
+|     taxExScopeAmount    | Number|    O   |                                                                                                                                                                                                                면세 대상 금액. 과세 대상 금액 + 면세 대상 금액 + 컵 보증금 금액 (옵션) = 총 결제 금액                                                                                                                                                                                                                |
+| environmentDepositAmount| Number|        |                                                                                                                                                                    1회용 컵에 담은 상품의 결제건인 경우에만 필수값이며, 그 외에는 전달할 필요가 없습니다.  컵 보증금 금액. 과세 대상 금액 + 면세 대상 금액 + 컵 보증금 금액 (옵션) = 총 결제 금액                                                                                                                                                                    |
+|        returnUrl        | String|    O   |                                                                                                                    결제 인증 결과 전달 URL, 결제 완료 후 이동할 URL(returnUrl + 가맹점 파라미터 전달이 가능합니다) 네이버페이는 결제 작업 완료 후, 가맹점이 등록한 returnUrl로 리디렉션을 수행합니다 가맹점은 이를 활용하여 내부 처리를 수행하거나 구매자에게 결제 결과 화면을 노출할 수 있습니다                                                                                                                    |
+|      purchaserName      | String|        |                                                                                                                                                                                                       구매자 성명. 결제 상품이 보험 및 위험 업종 등인 경우에만 필수 값입니다. 그 외에는 전달할 필요가 없습니다                                                                                                                                                                                                       |
+|    purchaserBirthday    | String|        |                                                                                                                                                                                                구매자 생년월일(yyyymmdd). 결제 상품이 보험 및 위험 업종 등인 경우에만 필수 값입니다. 그 외에는 전달할 필요가 없습니다                                                                                                                                                                                                |
+|      extraDeduction     |Boolean|        |                                                                                                                                              도서 / 공연 / 영화 소득공제 대상 여부. 문화체육관광부에서 인증한 소득공제 제공 사업자가 대상 상품을 판매하는 경우 필수 값입니다. 해당 파라미터를 사용하기 위해서는 별도 요청을 주셔야 합니다. true : 대상, false : 비 대상                                                                                                                                              |
+|        useCfmYmdt       | String|        |이용완료일(yyyymmdd) 가맹점 타입이 이용완료일 정산 또는 이용완료일 포인트 적립인 경우 필수 해당 값을 기준으로 이용완료일 정산의 경우 '정산기준일' 또는 이용완료일 포인트 적립인 경우 '포인트적립 기준일'이 지정됩니다. 이용완료일은 반드시 결제일과 같거나 결제일 이후여야 하며, 이용완료일이 결제일자 이전으로 적용될 경우 에러(InvalidUseCfmYmdt)가 발생됩니다. 이용완료일이 결제일자 기준으로 1년을 초과할 경우 별도 에러가 발생되지는 않으나 전달한 이용완료일(useCfmYmdt) 값이 결제일자 +365일로 조정 처리됩니다.|
+|  merchantExtraParameter | String|        |                                                                                                                                                                                            가맹점 자체적으로 추가 구분값으로 활용 가능한 별도의 예비 필드 (개인 아이디와 같은 개인정보 데이터는 제외하여 전달해야 합니다)                                                                                                                                                                                            |
+|       productItems      | Array |    O   |                                                                                                                                                                                                                                                   productItem 배열                                                                                                                                                                                                                                                   |
+|     subMerchantInfo     | Object|        |                                                                                                                                                                                                                                하부가맹점 정보. PG 업종 가맹점인 경우에만 필수값입니다                                                                                                                                                                                                                               |
+
+위처럼 같은 기능을 하는 인터페이스임에도 PG사에 따라 파라미터 명과 파라미터 타입, 필수 파라미터 목록 모두 상이한 것을 볼 수 있습니다.
+심지어 사용하는 통신 프로토콜마저 PG사마다 상이하죠.
+2개의 PG사만을 비교해도 이러한 차이가 뚜렷한데, 포트원은 30개가 넘는 PG사 모듈을 제공하고 있기 때문에 인터페이스를 효과적으로 추상화하는 것이 매우 중요한 과제입니다.
+
+## 아키텍처 레벨 결정사항
+
+### 추상화만을 담당하는 마이크로서비스
+
+앞서 설명드린 것처럼 현재 포트원은 모놀리식 아키텍처(V1)에서 MSA(V2)로의 전환 작업을 진행 중입니다.
+이러한 전환 과정에서 V1과 V2를 모두 운영하며 새로운 PG를 연동하려면 V1과 V2 양쪽에 모두 연동 작업을 수행해야 합니다.
+이는 개발 리소스를 두 배로 소모하는 일이며 매우 비효율적인 작업입니다.
+
+이러한 비효율을 최소화하기 위해 저희는 V1과 V2에서 모두 사용 가능한 PG 인터페이스 추상화용 마이크로서비스인
+TGS(Transaction Gateway Service)를 도입했습니다.
+이 서비스 도입을 통해 V1과 V2에서 고객사의 요청을 처리하는 서비스들은 어떤 PG사로 결제가 이루어지든 통일된 인터페이스를 이용해 결제를 발생시킬 수 있습니다.
+포트원이 고객사에게 주는 편리함을 포트원 내부에서는 TGS가 다른 서비스들에게 제공하는 것이죠.
+
+다만 TGS의 도입에 앞서 선행돼야 하는 작업이 있었습니다.
+모놀리식 서비스인 V1의 코드를 일부 수정하여 PG사의 인터페이스를 직접 호출하는 것이 아니라 TGS의 인터페이스를 호출하도록 변경해주어야 했습니다.
+이 작업 역시 작지 않은 작업이었지만 V1과 V2가 언제까지 함께 운영될지 모르는 상황에서
+서비스를 계속해서 발전시켜 나가려면 어느 정도 시간이 들더라도 반드시 해야만 하는 일이라는 결론에 도달했습니다.
+
+TGS가 PG의 인터페이스를 추상화하는 역할을 담당하게 되면서 외부로부터 결제 요청을 처리하는 서비스는 결제 데이터를 저장하고 서빙하는 본연의 역할에 충실할 수 있게 됐습니다.
+
+### gRPC를 통한 API 제공
+
+(이미지 첨부: 효율적인 PG사 연동을 위한 아키텍처)
+
+TGS가 API를 제공하는 방식 역시 아키텍처를 설계할 때의 주요 결정사항 중 하나였습니다.
+가장 흔히 사용되는 방식으로는 REST API가 있지만 저희는 gRPC를 이용하여 API를 제공하기로 결정했습니다.
+저희는 gRPC가 가지는 여러 장점 중 아래 두 가지에 집중했습니다.
+
+#### 1. 인터페이스 우선 개발
+
+TGS는 포트원의 내부 서비스와 PG사의 중간 다리 역할을 하는 만큼 신규로 연동할 PG사가 기존에 연동된 PG사에서 요구하던 파라미터 이외의 파라미터를 요구하거나,
+기존에 연동된 PG사가 새로운 파라미터를 제공하는 경우에는 인터페이스의 수정이 불가피합니다.
+만약 이런 수정 작업 중 TGS의 작업자가 변경된 인터페이스의 공유를 깜빡하는 경우에는 외부로 API를 제공하는 서비스들에서 해당 기능을 제공하기 어려워지기 때문에,
+TGS 작업자는 다른 서비스로 인터페이스를 공유하는 것이 매우 중요합니다.
+
+gRPC를 사용하는 경우 proto file로 인터페이스를 우선 정의하고 해당 파일을 기반으로 생성된 서버/클라이언트 코드를 사용하여 통신하게 됩니다.
+인터페이스가 먼저 정의가 돼야지만 서버 기능 추가가 가능하기 때문에, proto file에 수정이 있는 경우 클라이언트가 되는 서비스의 개발자들로부터
+반드시 리뷰를 받도록 PR 정책을 수립하면 인터페이스가 공유되지 않는 상황을 프로세스적으로 방지할 수 있습니다.
+
+#### 2. 언어별로 자동 생성되는 클라이언트
+
+위에서 언급했듯이 gRPC는 proto file로 작성된 인터페이스를 기반으로 클라이언트 코드를 생성할 수 있습니다.
+현재 V1, V2는 각각 PHP와 Scala를 사용하여 개발 돼 있기 때문에 proto file을 기반으로 클라이언트 코드를 생성할 수 있다면,
+TGS의 인터페이스가 변경되더라도 각기 다른 언어로 작성된 클라이언트 코드를 수정해주어야 한다는 부담이 사라지게 됩니다.
+
+물론 REST API의 경우 이미 널리 사용되고 있어 학습을 위한 기간이 거의 필요하지 않고, 다양한 라이브러리들이 지원된다는 장점이 있지만,
+포트원 내부 서비스와 PG사들 사이에서 인터페이스를 추상화해 주어야 한다는 목적에 맞춰 보았을 때
+위 2가지의 장점이 REST API가 가지는 장점보다 더 많은 이득을 준다고 판단되어 최종적으로 gRPC를 사용하고 있습니다.
+
+## 서비스 레벨의 결정사항
+
+### Domain Driven Design(DDD)
+
+TGS는 PG사마다 다른 용어와 개념을 공통화하여 도메인 영역을 최대한 간결하게 만들어야 합니다.
+만약 PG사에서 사용되는 용어가 도메인 영역에 침범하도록 개발을 진행한다면
+도메인 영역은 너무 많은 개념을 담게 되어 처음부터 개발을 해온 사람이 아니라면 도저히 이해할 수 없는 서비스가 돼버릴 것입니다.
+
+실제로 TGS의 초기 구현은 이와 같은 문제를 가진 채로 개발이 진행됐습니다.
+TGS는 프레젠테이션, 어플리케이션, 도메인, 인프라 레이어로 이루어진
+[레이어드 아키텍처](https://www.baeldung.com/cs/layered-architecture)를 따릅니다.
+아래 사진은 이런 구조에서 토스페이먼츠를 위한 클래스들이 도메인 레이어를 침범하여 포트원 도메인 클래스와 혼재되어 있는 모습을 보여주는 사진입니다.
+
+(이미지 첨부: 개발초기 TGS의 도메인 레이어)
+
+이대로 계속 개발을 진행했다면 TGS에 연동하는 PG사가 늘어남에 따라 도메인 레이어가 계속해서 비대해질 수밖에 없었을 것입니다.
+어플리케이션 레이어의 경우에는 상황이 더 심각합니다.
+비즈니스 로직은 포트원 도메인 엔티티에 정의돼 있기 때문에 어플리케이션 로직에서는 PG사별 객체를 포트원 엔티티로 전환한 후 비즈니스 로직을 실행하고,
+이를 다시 프레젠테이션 레이어로 올려보내주어야 하죠.
+이렇게 프레젠테이션 레이어를 제외한 모든 레이어에 구석구석 침투해 있는 PG사별 클래스로 인해 프로젝트 전체 구조를 파악하지 못한 경우에
+신규 기능 연동이 매우 어려운 상황이었습니다.
+
+이와 같은 문제를 해결하기 위해서 TGS에는 DDD 방법론을 도입하여,
+도메인 영역에서 사용되는 용어들을 정리하고 이를 기반으로 어플리케이션 및 프레젠테이션 영역을 보다 깔끔하게 만들어 주기로 결정했습니다.
+TGS에 DDD를 도입하는 과정은 크게 3단계로 나누어 진행됐습니다.
+
+#### 1. 보편 언어(Ubiquitous Language) 정리
+
+보편 언어를 정리하는 일은 DDD의 시작이라고 할 수 있습니다.
+명확하게 정리된 보편 언어는 도메인을 이해하기 쉽게 만들어주고, 구성원들간의 미스 커뮤니케이션이 일어나지 않도록 도움을 줍니다.
+TGS는 여러 PG사와의 통신을 담당하는 서비스인 만큼, 여러 PG 연동을 경험한 분들에게 도움의 받아 보편 언어를 정리했습니다.
+정리된 보편 언어는 항상 접근이 간편한 곳에 위치해 있어야 하기 때문에 저희는 이를 위한 레포지토리를 생성하고 용어들을 마크다운 파일로 정리했습니다.
+
+(이미지 첨부: 보편 언어를 위한 레파지토리)
+
+#### 2. 보편 언어를 이용해 도메인 엔티티와 값 객체(VO) 정의
+
+정리된 보편 언어는 코드에도 그대로 녹아들어야 합니다. 그래야만 엔지니어와 관련자 사이에 통일된 언어로 커뮤니케이션이 가능하기 때문이죠.
+리팩토링 전 KSNET의 API를 통해 발생한 거래를 저장하기 위한 클래스와 리팩토링 후의 클래스 모습입니다.
+변경 전에는 `aid`, `tid`, `tradeDate` 처럼 PG사에서 사용하는 언어를 이용해 데이터를 저장했다면,
+변경 후에는 포트원의 보편 언어로 모두 대체된 모습을 볼 수 있습니다.
+
+<div class="hint" data-style="info">
+
+클래스명에 PG사의 명칭이 들어가있어서 도메인 엔티티가 아니라고 느껴질 수 있지만,
+각 PG사와의 거래는 분명하게 TGS의 [bounded context](https://martinfowler.com/bliki/BoundedContext.html) 안에 존재하는 개념이기에 PG사의 명칭을 클래스명에 포함시켰습니다.
+
+</div>
+
+(이미지 첨부: 보편 언어를 사용하는 클래스)
+
+#### 3. 각 PG사를 위한 데이터 클래스는 인프라 레이어로 이동
+
+도메인 레이어를 보편 언어를 이용한 엔티티와 값 객체로 채우게 되면서 PG사를 위한 클래스들은 자연스럽게 인프라 레이어로 이동시켰습니다.
+그리고 인프라 레이어에서 PG사의 클래스를 도메인 엔티티와 값 객체로 변환하여 반환하게 만들었습니다.
+이제 PG사의 클래스들은 인프라 레이어에서 DTO로써만 존재하게 됐습니다.
+그리고 자연스럽게 PG사와 통신하는 Client 구현체는 부패 방지 계층의 역할을 띄게 됩니다.
+부패 방지 계층이란 연동하고자 하는 시스템과 기존 시스템 사이에 존재하는 도메인 모델의 차이를 기존 시스템에 맞게 변환하기 위한 계층으로,
+도메인 레이어를 외부의 용어와 완벽하게 분리할 수 있게 도와줍니다.
+
+(이미지 첨부: 인프라 레이어에 존재하는 PG사별 Client 구현체)
+
+도메인 레이어와 어플리케이션 레이어를 수정하는 개발자는 더 이상 인프라 레이어의 구현에 대해서 알 필요가 없습니다.
+그저 Client가 반환한 도메인 엔티티와 값 객체를 이용해 로직을 구성하기만 하면 되는 것이죠.
+
+3단계로 진행된 리팩토링 과정에서 사실 대단한 DDD 기법을 사용하지는 않았습니다.
+Aggregate, CQRS, 이벤트 소싱 등의 기법은 전혀 등장하지 않았죠.
+그렇지만 보편 언어를 정의하여 커뮤니케이션의 효율을 높이고,
+기술 의존도가 없는 도메인 레이어에 비즈니스 로직을 응축해 놓음으로써 이식성이 높아졌기에 DDD가 추구하던 본질적인 장점은 취할 수 있게 되었습니다.
+덤으로 간단해진 어플리케이션 레이어 로직 덕분에 PG 연동 속도도 빨라지게 되어 생산성도 비약적으로 증가했습니다.
+
+### Typed Error 활용
+
+결제 도메인에서 에러 처리는 다른 도메인보다 특히나 중요합니다. 잘못된 에러 처리로 인해 결제 내역이 사라진다거나 결제가 여러 번 처리된다면 매우 큰 혼란이 생길 것입니다.
+명확한 에러 처리를 위해서는 특정 함수에서 어떤 에러가 발생할 수 있는지 문서화하는 것이 중요하나,
+문서와 주석은 outdated 되기 쉽다는 단점이 있습니다.
+저희는 이런 문제를 해결하기 위한 방법으로 함수형 프로그래밍을 위한 Kotlin 라이브러리인
+[Arrow](https://arrow-kt.io/)의 typed error를 적극적으로 활용하고 있습니다.
+
+Typed error를 사용하면 특정 함수에서 발생할 수 있는 에러를 코드를 통해 문서화할 수 있기 때문에 outdated 될 염려가 없고,
+에러 처리가 강제되기 때문에 특정 에러 케이스를 놓친다거나 하는 문제가 발생할 염려가 적습니다.
+예를 들어, Arrow를 사용해 함수 시그니처에 typed error를 적용하면 아래와 같은 코드를 작성하게 됩니다.
+Typed error를 적용함으로써 예시 코드의 `pay()` 함수에선 `AmountTooBig`, `InvalidCardInfo`, `TransactionAlreadyExists`
+에러가 발생할 수 있다는 것을 코드 레벨에서 확인할 수 있습니다.
+
+```kotlin
+interface Example {
+    fun pay(): Effect<PayError, Unit>
+
+    sealed interface PayError {
+      data object AmountTooBig: PayError
+      data object InvalidCardInfo: PayError
+      data object TransactionAlreadyExists: PayError
+    }
+}
+```
+
+반면 typed error를 사용하는 코드는 이런 의문을 가지게 합니다. ‘Kotlin에서 의도적으로 삭제한 checked exception를 다시 되살리는 것 아닌가?’.
+네, typed error는 checked exception과 거의 동일한 의도로 사용됩니다.
+Kotlin에서 checked exception을 삭제한 주요 이유는 대부분의 exception은 처리할 수 없는 exception이기 때문입니다.
+하지만 저희는 꼭 처리해 주어야 하는 예외 케이스가 있다면 checked exception을 사용하는 것이 그렇지 않은 경우보다 코드 퀄리티를 높여줄 수 있다고 생각했으며,
+결제가 예외 처리에 매우 민감한 도메인이라는 점을 감안하여 checked exception을 대신할 수 있는 typed error를 사용하고 있습니다.
+
+물론 typed error를 잘못 사용할 경우에는 checked exception이 가지던 문제점들이 그대로 발생할 수 있습니다.
+때문에 올바른 방법으로 사용하는 것이 매우 중요하며, 이에 대한 내용은 추후 별도의 글에서 다뤄보도록 하겠습니다.
+
+## 마치며
+
+지금까지 포트원이 여러 PG사의 인터페이스를 효율적으로 연동하기 위해 논의했던 기술적 결정사항들에 대해 알아보았습니다.
+부디 이 글이 비슷한 문제를 해결하고자 하는 분들에게 작게나마 도움이 된다면 좋겠습니다.
+
+포트원은 지금도 고객사에게 더 좋은 결제 경험을 제공하기 위해 노력하고 있습니다.
+저희와 함께 간편한 결제 연동이라는 문제를 함께 풀어나가고 싶으신 분이 계시다면 포트원의 문을 두드려 주시면 감사하겠습니다!

package/assets/docs/blog/posts/2024-04/gcp-datastream.md

@@ -0,0 +1,307 @@
+---
+title: 'Data Evolution: The Shift from AWS DMS to GCP Datastream'
+description: >-
+  Gives an overview of the PortOne Data Infrastructure and the migration story
+  from AWS DMS to GCP Datastream.
+author: chandulal
+date: 2024-04-03T15:00:00.000Z
+tags:
+  - Data Infra
+  - Data Ingestion
+  - GCP
+  - Data Engineering
+---
+
+<div class="hint" data-style="info">이 글은 PortOne Global 소속 엔지니어가 작성한 글입니다.</div>
+
+## Introduction
+
+At PortOne, we use AWS DMS to capture changes from our service databases
+using Change Data Capture (CDC) and ingest them into our Data Lake.
+We store all our CDC data in AWS S3 and merge it with the BigQuery table
+every hour using Airflow as a scheduler.
+Our pipeline code, written in Python's Pandas library,
+merges incremental changes into the BigQuery table.
+We have multiple mart tables built on top of the raw tables in BigQuery.
+
+Although this solution has worked well for us, we encountered several challenges along the way:
+
+- **High Latency:** at least an hour.
+
+- **Manual Backfill:** requires multiple steps to backfill data
+  from the source database to the BigQuery table.
+
+- **Missing Rows:** There are instances of missing records if there are delays or complications
+  with the writing process of AWS DMS.
+
+- **High Maintenance:** the solution requires multiple components to maintain,
+  such as AWS DMS, Airflow, and a Kubernetes cluster to run all our pipelines.
+
+Our approach involves utilizing GCP Datastream as our Change Data Capture (CDC) solution
+to address and overcome the aforementioned challenges.
+
+### About GCP Datastream
+
+GCP Datastream is a managed CDC service provided by Google Cloud Platform (GCP)
+that enables real-time, automated, and reliable data replication
+from various sources to target destinations.
+It is a serverless and easy-to-use change data capture and replication service
+that directly ingests data from sources such as MySQL and Postgres into BigQuery.
+
+It supports integrating various Google Cloud services,
+including BigQuery, Cloud Storage, and Pub/Sub.
+
+## Data Infrastructure Change
+
+### Before
+
+(이미지 첨부: Architecture using AWS DMS)
+
+Here, we utilize AWS Database Migration Service(DMS) to capture changes in data
+from six to seven databases. The DMS consistently copies CDC data from RDS
+to Amazon S3 with hourly partitioning on S3.
+Next, Airflow initiates a DAG every hour to combine new CDC data from S3 to BigQuery.
+The underlying job, written in Pandas DataFrame,
+runs on Kubernetes and upserts the data in BigQuery.
+
+### After
+
+(이미지 첨부: Architecture using GCP Datastream)
+
+Here, we simplified the previous architecture
+by removing AWS DMS, AWS S3, and Data Pipelines run by Airflow.
+Instead, we utilize GCP Datastream, which directly connects to databases like PostgreSQL and MySQL,
+copies CDC data, and merges it into BigQuery.
+It provides the option to specify the staleness
+to balance BigQuery query performance and cost versus data freshness.
+Further details will be covered later in this blog.
+
+## Data Partitioning
+
+Data partitioning allows for more efficient and scalable data processing
+by dividing data into smaller, manageable segments.
+This can lead to faster query performance, reduced costs, and improved data availability.
+It also allows for easier data management by providing the ability
+to load or delete data partitions selectively.
+Data partitioning plays a crucial role as we pay for the data
+scanned by the queries we run in BigQuery.
+
+The main challenge with GCP Datastream is its lack of support
+for partitioning when writing data into BigQuery.
+As a result, all mart tables, which build incrementally every hour,
+must scan the full table ingested by Datastream, causing our BigQuery costs to skyrocket.
+
+We manually created a partition for all large tables to mitigate this issue.
+Although this solution worked for us, we do not recommend it
+because it can affect your data ingestion.
+Please use it cautiously and consult GCP support if you encounter any issues.
+
+Here are the steps we took to add a partition to the table ingested using Datastream.
+For example, we have a _**transaction**_ table with over 100 million rows
+being ingested via Datastream and want to add a partition.
+
+- Pause the Datastream that ingests the _**transaction**_ table.
+
+- Create a new _**transaction\_v2**_ table using the same Data Definition Language (DDL)
+  as the original _**transaction**_ table but by appending the partition clause.
+
+  Find the DDL for the existing _**transaction**_ table.
+
+  ```sql
+  SELECT
+    ddl
+  FROM
+    `<project-id>`.`region-<region-anme>`.INFORMATION_SCHEMA.TABLES
+  WHERE
+    table_name="transaction" and table_schema='<dataset name>'
+  ```
+
+  Use the DDL statement retrieve from above query
+  and add your partition using `PARTITION BY` clause.
+
+  ```sql
+  CREATE TABLE transaction_v2
+  (
+    id INT64,
+    amount NUMERIC
+  )
+  PARTITION BY DATE(updated_at)
+  CLUSTER BY id;
+  ```
+
+- Insert data from the _**transaction**_ into _**transaction\_v2**_.
+
+- Drop the _**transaction**_ table.
+
+- Create a new _**transaction**_ table using the DDL of _**transaction\_v2**_,
+  which has the partition clause.
+
+- Insert data from _**transaction\_v2**_ into the new _**transaction**_ table.
+
+- Drop the _**transaction\_v2**_ table.
+
+- Resume the Datastream.
+
+Using **updated\_at** as a partition column in the raw tables
+allows us to retrieve any new changes from the raw table
+without scanning the entire table for mart table updates.
+
+## Data Transformation
+
+**Key Features**
+
+We started using GCP Dataform for data transformation,
+enabling users to define, test, and deploy data models in a reproducible and modular manner.
+It helps data teams manage complex pipelines and maintain data quality efficiently.
+
+- **SQL-based Data Transformations:** Define and run SQL transformations on your data,
+  and build complex pipelines with reusable scripts.
+
+- **Dependency Management:** Ensure transformations are executed in the right order
+  and manage dependencies among them.
+
+- **Version Control:** Version control your data transformation code with Git,
+  track changes, collaborate, and revert to previous versions if needed.
+
+- **Testing and Validation:** Write tests and validations for your data,
+  and define rules and expectations to ensure quality and integrity.
+
+- **Incremental Builds:** Optimize the execution time of your data pipelines
+  by processing only changed data since the last build.
+
+- **Collaboration and Sharing:** Share and reuse data transformation code with your team,
+  create and manage projects, grant access, and promote code reuse across projects.
+
+- **Scheduler Integration:** Automate execution of your data pipelines at specified intervals
+  with scheduling tools like Airflow or Google Cloud Scheduler.
+
+- **Extensibility:** Extend Dataform through plugins and custom JavaScript code,
+  write custom logic, integrate with external systems,
+  or implement advanced data processing tasks using JavaScript.
+
+We haven't used GCP Dataform extensively at this time.
+We will share more information in the future after using it more.
+
+## Security
+
+### Datastream security
+
+GCP Datastream is designed with security in mind and provides several features
+to ensure the security of data replication.
+Key features include encryption at rest and in transit, VPC service control,
+IAM roles and permissions, and audit logging.
+
+### PII column security
+
+Our GCP Datastream-based pipeline uses two methods to handle
+Personally Identifiable Information (PII) columns.
+The first method completely blocks specific PII column(s) from being included in the Datastream.
+This ensures that Datastream does not ingest PII columns into BigQuery.
+
+In some cases, our customer support or marketing team needs the PII of our customers,
+such as email, phone number, etc.
+In those cases, we ingest the PII column(s) into BigQuery and mask them
+using the dynamic data masking feature of BigQuery.
+
+**About Dynamic Data Masking**
+
+BigQuery provides dynamic data masking at the column level,
+enabling access to a column while obscuring its data for privileged user groups.
+Combining data masking with column-level access control allows you to configure
+access to column data at different levels based on user privileges.
+This simplifies data sharing, eliminates the need to modify existing queries,
+allows scalability when applying data access policies, and enables attribute-based access control.
+
+Here are the benefits of using BigQuery for dynamic data masking at the column level:
+
+- Simplifies data sharing with larger groups by masking sensitive columns.
+
+- Existing queries automatically mask column data based on user roles,
+  eliminating the need to exclude inaccessible columns.
+
+- Enables scalability of data access policies by writing a policy tag once
+  and applying it to any number of columns.
+
+- Provides contextual data access based on data policy and associated principals
+  through attribute-based access control.
+
+## Cost
+
+### Ingest required columns only
+
+When using GCP Datastream, it is important to be mindful of the volume of data
+being ingested into BigQuery.
+Datastream charges based on the amount of data processed through it,
+so ensure to ingest only necessary tables and columns.
+
+### Use staleness settings
+
+Data staleness in Datastream refers to the amount of time between
+when a change is made in the source database and when that change is captured
+and replicated in the target destination.
+Datastream provides an option to specify the staleness
+to balance BigQuery query performance and cost versus data freshness.
+By setting the staleness settings, merging costs can be reduced.
+However, setting too low of a staleness value can result in higher costs
+due to more frequent querying of the target destination.
+
+To increase or decrease the staleness in the existing tables ingesting via Datastream.
+
+```sql
+ALTER TABLE <dataset-name>.<table_name>
+SET OPTIONS (
+  max_staleness = INTERVAL 30 MINUTE
+);
+```
+
+### Use BigQuery reservation for backfill
+
+Setting reservation pricing before starting the backfill of large tables
+is important to reduce high backfill costs.
+In our case, we started the backfill of a large table without using BigQuery reservation,
+and the cost was 2 times higher than it would have been with reservation pricing.
+
+(이미지 첨부: BigQuery Cost during the Backfill without Reservation)
+
+(이미지 첨부: BigQuery Cost during the Backfill with Reservation)
+
+## The bottleneck of GCP Datastream
+
+### Lack of data partitioning
+
+GCP Datastream is a powerful tool for real-time data replication,
+but it can still be improved in some areas.
+One major bottleneck is the lack of built-in partitioning.
+When a large table is ingested through Datastream,
+there should be an option to create a partition in the target table.
+
+### Lack of pre-transformation
+
+Another challenge with GCP Datastream is the absence of pre-transformation.
+There is no option to transform the data before it is sent to the target system.
+This feature can help encrypt source columns, create derived columns, etc.
+
+### Full table scan while merging incremental changes
+
+GCP Datastream scans the full table to apply a few incremental rows.
+This approach can be inefficient and expensive.
+To optimize the performance of GCP Datastream,
+developing a more efficient way of scanning the table and applying incremental rows is essential.
+
+## What’s Next?
+
+We have made significant changes in our latest solution for ingesting real-time data
+from our source database to BigQuery.
+We have replaced AWS DMS with GCP Datastream.
+This has allowed us to take advantage of the unique features that GCP Datastream offers.
+
+Additionally, we have implemented GCP Dataform for data modelling and mart tables.
+This has given us more flexibility and control over our data.
+
+However, we have encountered a few challenges with GCP Datastream.
+It does not support pre-transformation, which is essential for our use case.
+To address this, we are considering using Dataflow for real-time pre-transformation.
+This would allow us to apply transformations to the data before it is ingested into BigQuery,
+giving us more control over the quality and consistency of our data.
+Overall, we believe that these changes have greatly improved the efficiency and effectiveness
+of our data ingestion process.