🌌
Apache Pulsar 치트시트

Apache Pulsar 3.x/4.x 최신 기준 초보자 완벽 가이드: Docker Standalone 1초 설치, 브로커-BookKeeper 컴퓨트/스토리지 분리 아키텍처, 멀티 테넌시 토픽 네임스페이스, 4대 구독 모드(Exclusive/Failover/Shared/Key_Shared), 지연 메시지(Delayed Delivery), Tiered Storage, Spring Boot 연동 및 pulsar-admin CLI 치트시트
#pulsar#apache-pulsar#messaging#streaming#pubsub#bookkeeper#kafka#spring-boot#backend#cloud-native최종 업데이트: 2026-10-06
Apache Pulsar 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 환경 구성 (Prerequisites)

Apache Pulsar는 차세대 클라우드 네이티브 분산 메시징 및 이벤트 스트리밍 플랫폼입니다. 초보자도 1분 안에 자신의 로컬 PC에서 즉시 실습할 수 있도록 가장 권장되는 Docker Standalone 구동부터 시작합니다.

### 🐳 1. Docker로 1초 만에 실행하기 (강력 추천)
Pulsar 공식 올인원 Standalone 이미지를 사용하면 브로커, BookKeeper(저장소), ZooKeeper(메타데이터)가 단일 컨테이너로 즉시 기동됩니다.

```bash
# Apache Pulsar Standalone 컨테이너 백그라운드 실행
docker run -d --name pulsar-standalone \
  -p 6650:6650 \
  -p 8080:8080 \
  apachepulsar/pulsar:3.3.0 \
  bin/pulsar standalone
```

- **6650 포트**: 바이너리 프로토콜 통신 포트 (Producer, Consumer 애플리케이션 연결)
- **8080 포트**: REST Admin 관리자 API 및 메트릭 조회 포트
- **정상 기동 확인**:
  ```bash
  # REST API 헬스체크 ➔ "ok" 응답 확인
  curl http://localhost:8080/admin/v2/clusters
  ```

---

### 💻 2. 로컬 바이너리 직접 설치 (Docker 미사용 시)
Pulsar는 **Java 17 또는 21+** 런타임 환경이 사전에 설치되어 있어야 합니다.

```bash
# 1. 공식 압축 아카이브 다운로드 및 압축 해제
wget https://archive.apache.org/dist/pulsar/pulsar-3.3.0/apache-pulsar-3.3.0-bin.tar.gz
tar -xzf apache-pulsar-3.3.0-bin.tar.gz
cd apache-pulsar-3.3.0

# 2. Standalone 모드로 로컬 서비스 시작
bin/pulsar standalone
```

---

### 📦 3. 클라이언트 라이브러리 설치
실습에 사용할 언어의 공식 Pulsar 드라이버를 설치합니다:

```bash
# Python 클라이언트
pip install pulsar-client

# Node.js 클라이언트
npm install pulsar-client

# Java / Spring Boot (Gradle build.gradle)
# implementation 'org.springframework.boot:spring-boot-starter-pulsar'
# 또는 implementation 'org.apache.pulsar:pulsar-client:3.3.0'
```

---

## 2. Apache Pulsar 핵심 개념 & 아키텍처 (Mental Model)

기존 Kafka와의 가장 결정적인 차이는 **컴퓨트 계층(Stateless Broker)**과 **스토리지 계층(Stateful BookKeeper)**이 물리적으로 완전히 분리되어 있다는 점입니다.

```text
[Apache Pulsar 계층 분리 아키텍처]
┌──────────────────────────────────────────────────────────────────┐
│                    Serving / Compute Layer                       │
│  ┌───────────────────────┐              ┌─────────────────────┐  │
│  │   Pulsar Broker 1     │              │   Pulsar Broker 2   │  │ (Stateless: 상태 없음)
│  │ (메시지 수신 & 라우팅)│              │ (트래픽에 따라 스케일) │ │
│  └───────────┬───────────┘              └──────────┬──────────┘  │
└──────────────┼─────────────────────────────────────┼─────────────┘
               │                                     │
┌──────────────▼─────────────────────────────────────▼─────────────┐
│                    Storage Layer (Apache BookKeeper)             │
│  ┌─────────────────┐    ┌─────────────────┐    ┌──────────────┐  │
│  │  Bookie 1 (디스크)│    │  Bookie 2 (디스크)│    │ Bookie 3     │  │ (Stateful: 세그먼트 저장)
│  └─────────────────┘    └─────────────────┘    └──────────────┘  │
└──────────────────────────────────────────────────────────────────┘
```

### 🏷️ 1. 멀티 테넌시 토픽 계층 구조
Pulsar의 모든 토픽 URL은 체계적인 계층형 표준 구조를 따릅니다:
```text
{persistence}://{tenant}/{namespace}/{topic}
예: persistent://my-company/ecommerce/order-events
```
- **persistence**: `persistent`(BookKeeper 디스크 영구 저장) 또는 `non-persistent`(인메모리 휘발성 고속 전송).
- **tenant (테넌트)**: 기업, 부서 또는 조직 단위의 격리 공간 (보안 인증 및 리소스 할당).
- **namespace (네임스페이스)**: 설정 단위 (TTL, 보존 주기, 복제 정책, 암호화 설정).
- **topic (토픽)**: 실제 메시지가 전송되는 채널.

### 📊 Apache Kafka vs Apache Pulsar 비교
| 비교 항목 | Apache Kafka | Apache Pulsar |
| :--- | :--- | :--- |
| **아키텍처** | 컴퓨트-스토리지 일체형 (모놀리식 브로커) | 컴퓨트(Broker)와 스토리지(BookKeeper) 완벽 분리 |
| **스케일아웃 확장** | 브로커 추가 시 파티션 데이터 재할당(Rebalance) 고비용 | 브로커는 즉시 추가 가능, 데이터 이동 없음 |
| **메시징 모델** | 오직 순차 로그(Log) 기반 스트리밍 | **스트리밍(Kafka형) + 큐잉(RabbitMQ형)** 동시 지원 |
| **데이터 보관 비용** | 고가의 SSD 브로커 디스크에 장기 보관 | **Tiered Storage**: 오래된 데이터 AWS S3로 자동 이전 |
| **지연 전송** | 지원하지 않음 (별도 토픽/스케줄러 필요) | **네이티브 지원** (`deliverAfter`, `deliverAt`) |

---

## 3. 4대 구독 모드 (Subscription Types) 완벽 이해

Pulsar는 하나의 토픽에 대해 여러 애플리케이션이 각자의 비즈니스 요구에 맞추어 구독 방식을 선택할 수 있습니다.

```text
[4대 구독 모드 비교 다이어그램]
1. Exclusive   : [Topic] ──► [Consumer A] (단 1개만 허용, 절대 순서 보장)
2. Failover    : [Topic] ──► [Consumer A(Active)] ──[장애 시]──► [Consumer B(Standby)]
3. Shared      : [Topic] ──► [Consumer A] (라운드 로빈 작업 큐잉 분배)
                          ──► [Consumer B]
4. Key_Shared  : [Topic] ──► [Consumer A] (Key 1, Key 3 전담)
                          ──► [Consumer B] (Key 2, Key 4 전담)
```

| 구독 모드 | 동작 방식 | 주요 실무 활용처 |
| :--- | :--- | :--- |
| **Exclusive (단독)** | 하나의 큐에 **오직 1개의 컨슈머만 연결 허용**. 다른 컨슈머 접속 시 에러 발생 | 단일 파티션 엄격한 순서 보장 시스템 |
| **Failover (장애 조치)** | 여러 컨슈머가 대기하다가 주 컨슈머가 다운되면 **예비 컨슈머가 자동 승계** | 마스터-슬레이브 고가용성 파이프라인 |
| **Shared (공유 - 큐 모드)** | 메시지를 라운드 로빈 방식으로 여러 컨슈머에게 **작업 큐처럼 공평 분배** | RabbitMQ 같은 대규모 병렬 백엔드 작업 워커 |
| **Key_Shared (키 기반 공유)** | 메시지의 **동일 키(Partition Key)는 항상 동일한 컨슈머에게만 전달** | 유저별 순서는 보장하면서 전체 워커는 무한 수평 확장 |

---

## 4. [초보자 1단계] 헬로월드: 가장 단순한 메시지 송수신 (Python)

Pulsar 클라이언트를 생성하고 토픽에 메시지를 발행 및 수신하는 기본 예제입니다.

### 📤 생산자: `producer.py`
```python
import pulsar

# 1. Pulsar 브로커 클라이언트 연결 (기본 바이너리 포트: 6650)
client = pulsar.Client('pulsar://localhost:6650')

# 2. 생산자(Producer) 생성
producer = client.create_producer('persistent://public/default/hello-pulsar')

# 3. 메시지 발행 (문자열 바이트 전송)
message_content = "반갑습니다! Apache Pulsar 첫 이벤트입니다."
msg_id = producer.send(message_content.encode('utf-8'))

print(f" [V] 메시지 발행 성공! Message ID: {msg_id}")

# 4. 리소스 정리
producer.close()
client.close()
```

### 📥 소비자: `consumer.py`
```python
import pulsar

client = pulsar.Client('pulsar://localhost:6650')

# 소비자(Consumer) 생성 (구독 모드: Shared 모드)
consumer = client.subscribe(
    topic='persistent://public/default/hello-pulsar',
    subscription_name='my-shared-sub',
    consumer_type=pulsar.ConsumerType.Shared
)

print(" [*] 메시지 수신 대기 중... (종료: CTRL+C)")

while True:
    try:
        # 메시지 대기 및 수신
        msg = consumer.receive()
        print(f" [OK] 수신된 내용: {msg.data().decode('utf-8')} (ID: {msg.message_id()})")

        # 🚀 중요: 브로커에 정상 수신 확인(ACK) 통보
        consumer.acknowledge(msg)
    except Exception as e:
        print("수신 오류:", e)
        break

consumer.close()
client.close()
```

---

## 5. [초보자 2단계] 키 기반 메시징 & Key_Shared 병렬 확장

주문 번호나 유저 ID를 키(`partition_key`)로 설정하여, 사용자별 이벤트 순서를 철저히 지키면서도 수십 대의 서버가 병렬 처리하도록 만드는 패턴입니다.

```python
import pulsar

client = pulsar.Client('pulsar://localhost:6650')
producer = client.create_producer('persistent://public/default/orders-topic')

# 유저 ID를 partition_key로 부여하여 발행
orders = [
    {"user_id": "user_A", "order": "주문 생성"},
    {"user_id": "user_B", "order": "상품 결제"},
    {"user_id": "user_A", "order": "배송지 입력"}, # user_A는 위 주문 생성과 동일 컨슈머로 감
]

for item in orders:
    producer.send(
        item["order"].encode('utf-8'),
        partition_key=item["user_id"] # 🚀 키 지정
    )
    print(f" [발행 완료] 키: {item['user_id']} | 데이터: {item['order']}")

producer.close()
client.close()
```

---

## 6. [초보자 3단계] 지연 메시지 전송 (Delayed / Scheduled Messaging)

복잡한 외부 스케줄러나 Cron 없이, "지금부터 10분 뒤에 처리해줘"라는 작업을 브로커 수준에서 네이티브로 처리합니다.

```python
import pulsar
import time

client = pulsar.Client('pulsar://localhost:6650')
producer = client.create_producer('persistent://public/default/delayed-tasks')

# 🚀 10초 후에 소비자에게 배달되도록 설정 (deliver_after)
producer.send(
    b'Order #5524: 10초 미결제 자동 취소 작업',
    deliver_after=10 # 초 단위 지연 지정 (deliver_at은 타임스탬프)
)

print(" [V] 지연 메시지가 등록되었습니다. 10초 후에 컨슈머에게 나타납니다.")
producer.close()
client.close()
```

---

## 7. 계층화된 스토리지 (Tiered Storage) 자동 오프로드

브로커 로컬 SSD 용량이 차오르면 오래된 메시지 세그먼트를 **AWS S3, Google Cloud Storage, Azure Blob, MinIO** 등 저렴한 객체 스토리지로 무중단 자동 이전합니다.
- 소비자는 메시지가 S3에 있든 로컬 디스크에 있든 **동일한 오프셋 API로 투명하게 조회(Transparent Read)**할 수 있습니다.

```bash
# 네임스페이스에 10GB 초과 시 또는 2시간 초과 시 S3로 자동 오프로드 정책 설정
bin/pulsar-admin namespaces set-offload-threshold \
  --size-threshold 10G \
  public/default
```

---

## 8. 실무 백엔드 연동: Spring Boot (Spring for Apache Pulsar)

최신 Spring Boot 3.2+ 환경에서 공식 지원하는 Spring for Apache Pulsar 연동 표준입니다.

### 📄 `application.yml`
```yaml
spring:
  pulsar:
    client:
      service-url: pulsar://localhost:6650
    producer:
      topic-name: persistent://public/default/spring-topic
    consumer:
      subscription-name: spring-sub
      subscription-type: shared # exclusive, failover, shared, key_shared
```

### ☕ Spring 서비스 & 리스너 코드
```java
@Service
public class OrderEventService {

    @Autowired
    private PulsarTemplate<String> pulsarTemplate;

    // 1. 메시지 발행
    public void publishOrder(String orderId) {
        pulsarTemplate.send("persistent://public/default/spring-topic", orderId);
    }

    // 2. 메시지 수신 리스너
    @PulsarListener(
        topics = "persistent://public/default/spring-topic",
        subscriptionName = "order-processing-sub",
        subscriptionType = SubscriptionType.Shared
    )
    public void handleOrder(String orderId) {
        System.out.println("Spring Pulsar 수신 처리: " + orderId);
    }
}
```

---

## 9. Pulsar CLI 핵심 관리 명령어 치트시트 (`pulsar-admin`)

Pulsar 브로커 컨테이너 내부 또는 설치 디렉토리에서 실행하는 필수 관리 명령어입니다:

```bash
# 1. 클러스터 및 테넌트 관리
bin/pulsar-admin clusters list
bin/pulsar-admin tenants create my-tenant
bin/pulsar-admin tenants list

# 2. 네임스페이스 생성 및 정책 설정
bin/pulsar-admin namespaces create my-tenant/my-namespace
bin/pulsar-admin namespaces set-retention my-tenant/my-namespace --size 50G --time 7d

# 3. 토픽 관리 및 실시간 통계 조회
bin/pulsar-admin topics list my-tenant/my-namespace
bin/pulsar-admin topics stats persistent://my-tenant/my-namespace/my-topic

# 4. 토픽 파티션 생성 (대규모 병렬 처리용)
bin/pulsar-admin topics create-partitioned-topic persistent://my-tenant/my-namespace/logs --partitions 4

# 5. 서브스크립션 메시지 강제 오프셋 초기화 (되감기)
bin/pulsar-admin topics reset-cursor persistent://my-tenant/my-namespace/my-topic \
  --subscription my-sub --time 1h
```

---

## 10. 실무 주의사항 & 프로덕션 체크리스트

| 점검 항목 | 권장 사항 | 이유 |
| :--- | :--- | :--- |
| **구독 모드 적합성 검토** | 순서가 필요하면 `Exclusive` 또는 `Key_Shared`, 병렬 큐잉은 `Shared` 선택 | 잘못된 구독 모드 선택 시 메시지 처리 순서 뒤엉킴 발생 |
| **수동 ACK 누락 금지** | 메시지 수신 후 처리 성공 시 반드시 `consumer.acknowledge(msg)` 호출 | 미승인 메시지가 누적되면 메모리 사용량 및 백로그 급증 |
| **BookKeeper 디스크 모니터링** | Bookie 디스크 사용률이 85%를 넘지 않도록 관리 | 디스크 임계치 초과 시 브로커 전체가 읽기 전용으로 차단됨 |
| **Tiered Storage 활성화** | 1주일 이상 장기 보관이 필요한 로그/이벤트는 S3 오프로딩 적용 | 고비용 NVMe/SSD 클러스터 스토리지 비용을 80% 이상 절감 |
| **토픽 네이밍 표준화** | `persistent://{tenant}/{namespace}/{topic}` 체계를 엄격히 준수 | 멀티 테넌트 권한 제어 및 네임스페이스별 TTL/Quota 적용의 기본 |
💬
Apache Pulsar 치트시트

의견 및 질문

댓글 수정

댓글 삭제
