KakaoPay v2 DynamoDB/KMS

KakaoPay v2 신규 구축 과정에서 DynamoDB 엔티티 설계와 KMS 키 관리를 어떻게 결정했는지를 기록한다. 데이터 저장 계층의 설계 결정이 이후 서비스 운영과 데이터 호환성에 어떤 영향을 미쳤는지, 그리고 공통 결제 라이브러리의 convention과 동기화해야 했던 이유를 남긴다.

왜 저장 구조와 암호화를 같이 봐야 했나

DynamoDB attribute naming을 Pascal Case로 통일한 것은 사소해 보이지만, 이전 시스템과 새 시스템 사이의 데이터 호환성, 공통 라이브러리와의 일관성, 그리고 팀 전체 코드베이스의 convention 통일이라는 관점에서 기록할 가치가 있는 결정이었다.

DynamoDB 기준에서 먼저 정해야 했던 것

KakaoPay v2도 DynamoDB를 주 저장소로 사용했다. 그래서 이 단계의 핵심은 DynamoDB를 새로 도입하는 것이 아니라, 기존에 쓰고 있던 데이터 구조와 공통 라이브러리 convention 위에서 엔티티 규칙을 다시 명확히 정하는 일이었다. 동시에 KMS(Key Management Service)를 통한 암호화도 필요했다. 결제 데이터는 민감 정보를 포함하므로 저장 시 암호화가 필수이고, KMS 키의 리전 배치가 서비스 배포 리전과 맞아야 한다.

이 시기에는 DynamoDB entity convention, KMS 키 설정, 테스트 커버리지 보강이 서로 얽혀 진행되었다. 하나를 바꾸면 나머지 둘에도 영향을 주는 구조였기 때문에 저장 구조와 보안 정책을 따로 떼어 볼 수 없었다.

핵심 체크포인트

• DynamoDB의 attribute naming을 어떤 convention으로 할 것인가는 팀 내에서 논의가 필요한 결정이었다. 선택지는 세 가지였다: camelCase(Java 표준), snake_case(Python/DB 관행), Pascal Case(기존 v1 및 공통 결제 라이브러리 convention).
• 결론적으로 Pascal Case를 선택했다. 가장 큰 이유는 기존 시스템과의 일관성이었다. v1의 데이터 구조와 공통 결제 라이브러리의 convention이 이미 Pascal Case를 사용하고 있었고, v2에서 다른 convention을 쓰면 두 시스템 간 데이터를 주고받을 때 변환 로직이 필요해진다. PartnerUserId, RegistrationStatus, PaymentMethodType 같은 attribute가 양쪽에서 같은 이름으로 존재해야 혼동이 없다.
• 같은 시기에 공통 결제 라이브러리에도 동일한 convention을 반영했다. 이것은 특정 서비스만의 규칙이 아니라 팀 전체 결제 서비스의 DynamoDB convention으로 굳히는 작업이었다.

convention과 보안 기준을 어떻게 고정했나

DynamoDB의 attribute naming을 어떤 convention으로 할 것인가는 팀 내에서 논의가 필요한 결정이었다. 선택지는 세 가지였다: camelCase(Java 표준), snake_case(Python/DB 관행), Pascal Case(기존 v1 및 공통 결제 라이브러리 convention).

결론적으로 Pascal Case를 선택했다. 가장 큰 이유는 기존 시스템과의 일관성이었다. v1의 데이터 구조와 공통 결제 라이브러리의 convention이 이미 Pascal Case를 사용하고 있었고, v2에서 다른 convention을 쓰면 두 시스템 간 데이터를 주고받을 때 변환 로직이 필요해진다. PartnerUserId, RegistrationStatus, PaymentMethodType 같은 attribute가 양쪽에서 같은 이름으로 존재해야 혼동이 없다.

같은 시기에 공통 결제 라이브러리에도 같은 convention을 반영했다. 이것은 신규 서비스만의 규칙이 아니라 팀 전체 결제 서비스에서 공유하는 기준으로 정착시키려는 선택이었다.

KMS 키는 서비스가 배포된 같은 리전에 두었다. KMS는 리전 단위로 관리되므로 저장 계층과 다른 리전에 키를 두면 지연과 운영 복잡도가 함께 늘어난다.

저장 정책 예시 코드

민감정보 저장 시에는 테이블/키 설계를 함께 두고, TTL/감사필드 정책을 명시해 운영 일관성을 확보한다.

Resources:
  PaymentStateTable:
    Type: AWS::DynamoDB::Table
    Properties:
      BillingMode: PAY_PER_REQUEST
      SSESpecification:
        SSEEnabled: true
      KeySchema:
        - AttributeName: PK
          KeyType: HASH
        - AttributeName: SK
          KeyType: RANGE

저장 구조와 보안 정책을 함께 고정한 이유

데이터 모델과 암호화는 따로 결정할 수 있는 주제가 아니었다. 저장 규칙이 흔들리면 운영 일관성이 깨지고, 보안 정책이 늦어지면 배포 기준 자체가 불안정해지기 때문에 이 단계에서는 둘을 같은 설계 결정으로 묶어 다루는 편이 맞았다.

다음 글에서는 이런 설계 결정을 실제 협업과 배포 흐름에 붙이기 위해 API 문서 빌드를 어떻게 자동화했는지 이어서 본다.