Page History
...
이전활동 : CAFE24-API 호출 안전처리기 by 백프레셔기법 활용
로컬로 개발된 액터모델이 구현체의 큰 변경없이 클러스터로 전환이 용이 할수 있는것은 스레드로 개발되었다고하면 리모트로 확장하기위해
네트워크 프로그래밍 또는 외부장치를 이용해야 할수도 있지만 액터모델은 리모트를 포함 클러스터내 작동을 위한 위치투명성을 지원하기때문에
네트워크로의 분산확장에 유리합니다. AKKA의 클러스터는 다음 본방의 문서를 통해 더 잘 이해할수 있습니다이번장에서는 로컬로만 작성된 액터를 클러스터로 확장을 바이브를 통해 시도해보겠습니다.
왜 액터 모델은 클러스터 확장에 유리한가?
전통적인 스레드 기반 동시성 모델은 공유 메모리와 Lock을 사용하며, 이를 분산 환경으로 확장하려면 네트워크 프로그래밍, 분산 락(Distributed Lock), 메시지 큐(Kafka, RabbitMQ 등) 같은 외부 인프라를 별도로 구축해야 합니다. 반면 액터 모델은 설계 자체가 분산 환경을 전제하고 있어 근본적으로 다른 접근을 제공합니다.
...
액터 모델이 클러스터 확장에 유리한 4가지 핵심 이유:
| 특성 | 스레드 기반 모델 | 액터 모델 |
|---|---|---|
| 상태 관리 | 공유 메모리 + Lock → 데드락 위험, 분산 Lock 필요 | 메시지 패싱으로 상태 격리 → Lock-free, 분산 자연스러움 |
| 통신 방식 | 메서드 호출 (로컬 한정) → 원격 시 RPC/REST 필요 | 메시지 전달 (로컬/원격 동일) → ActorRef로 위치 무관 통신 |
| 장애 처리 | try-catch 중심 → 분산 환경 장애 전파 어려움 | 감독 계층구조(Supervision) → Let-it-crash, 자가치유 |
| 확장 방식 | 코드 변경 필수 → 네트워크 레이어 별도 구현 | 설정 변경만으로 확장 → 리모팅은 설정(HOCON)으로 구동 |
이전 활동에서 구현한 Cafe24 API 백프레셔(SafeApiCallerActor)는 Akka Streams 기반의 액터 모델로 구현되었기 때문에, 클러스터 환경으로의 전환 시 핵심 비즈니스 로직의 변경 없이 인프라 설정과 클러스터 패턴(Sharding, Singleton, PubSub 등)만 추가하면 됩니다.
...
로컬에서 잘 동작하는 액터 모델을 클러스터로 확장할 때 반드시 고려해야 할 사항들입니다:
| 항목 | 로컬(단일 JVM/CLR) | 클러스터(분산 노드) |
|---|---|---|
| 메시지 직렬화 | 불필요 (JVM 내부 참조 전달) | 필수 (Jackson JSON/CBOR/Protobuf 등) |
| 네트워크 지연 | 무시 가능 (나노초) | 고려 필수 (밀리초~초 단위) |
| 메시지 전달 보장 | 거의 확실 | at-most-once (유실 가능, 재시도 로직 필요) |
| 액터 위치 | 동일 프로세스 내 | 어떤 노드든 가능 (위치 투명성) |
| 상태 복구 | 프로세스 재시작 시 소멸 | Event Sourcing/Snapshot으로 영속화 |
| 장애 범위 | 전체 시스템 영향 | 노드 단위 격리, 자동 리밸런싱 |
Cafe24 API 백프레셔의 클러스터 전환 핵심 변경점:
...
이번 확장은 동일한 비즈니스 로직(Cafe24 API 백프레셔)을 3개 플랫폼에서 클러스터로 구현하는 것이 핵심입니다. 각 플랫폼의 클러스터 API 차이를 이해하는 것이 중요합니다.
| 항목 | Java (Akka Classic 2.7.x) | Kotlin (Pekko Typed 1.1.x) | C# (Akka.NET 1.5.x) |
|---|---|---|---|
| HOCON 네임스페이스 | akka { } | pekko { } | akka { } |
| 프로토콜 | akka:// | pekko:// | akka.tcp:// |
| Remoting 포트 | 2551 | 25520 | 4053 |
| Singleton API | ClusterSingletonManager + Proxy | ClusterSingleton.get().init(SingletonActor.of()) | ClusterSingletonManager + Proxy |
| Sharding API | ClusterSharding.get().start() + MessageExtractor | ClusterSharding.get().init(Entity.of()) + EntityTypeKey | ClusterSharding.Get().Start() + HashCodeMessageExtractor |
| PubSub API | DistributedPubSub.get().mediator() | Topic.create() 액터 기반 | DistributedPubSub.Get().Mediator |
| 트랜스포트 | Artery | Artery | dot-netty.tcp |
| 빌드 도구 | Gradle (Kotlin DSL) | Gradle (Kotlin DSL) | dotnet CLI / csproj |
쿠버네티스 배포 아키텍처
클러스터 테스트는 Docker Desktop Kubernetes에서 StatefulSet + seed-nodes 방식(Type C)으로 수행합니다. 이 방식은 Management/Bootstrap 의존성 없이 최소 의존성으로 멀티노드 클러스터를 검증할 수 있습니다.
...
이번 프로젝트의 핵심 가치는 바이브 코딩(Vibe Coding)으로 분산 시스템을 구축하는 것입니다. 사용자는 요구사항(Plan)만 작성하고, Claude Code 스킬이 액터 모델 코드부터 클러스터 설정, Docker/K8s 인프라까지 전체를 자동 생성합니다.
스킬 기반 자동화 파이프라인:
| 단계 | 활동 | 사용 스킬 |
|---|---|---|
| 1. Plan 작성 | 요구사항 정의 (TEST-Cafe24APILimit.md) | 사용자 직접 작성 |
| 2. 로컬 코드 생성 | SafeApiCallerActor + 유닛테스트 | java-akka-classic, kotlin-pekko-typed, dotnet-akka-net + test 스킬 |
| 3. 클러스터 확장 | Sharding/Singleton/PubSub 패턴 적용 | java-akka-classic-cluster, kotlin-pekko-typed-cluster, dotnet-akka-net-cluster |
| 4. 인프라 생성 | Dockerfile, K8s YAML, HOCON 설정 | java-akka-classic-infra, kotlin-pekko-typed-infra, dotnet-akka-net-infra |
| 5. 통합 테스트 | K8s 클러스터 배포 및 분산처리 검증 | 인프라 스킬의 Type C (StatefulSet) |
핵심 교훈:
① 로컬 우선 개발: 로컬에서 유닛테스트로 빠르게 검증 → 클러스터 확장은 검증 완료 후 진행. 로컬 개발이 훨씬 빠르게 디벨롭을 완성합니다.
...