Docker Compose로 로컬에서 Pulsar 클러스터 실행하기

Docker Compose로 로컬에서 Pulsar를 실행하는 방법을 단계별로 안내해요. 준비된 compose.yml 템플릿을 사용하면 클러스터를 빠르게 띄울 수 있고, Docker 볼륨을 이용해 데이터를 지속적으로 보존할 수 있어요.

이 예시의 클러스터는 메타데이터 저장소로 Oxia를 사용해요. 새 Pulsar 클러스터의 권장 옵션이죠. Oxia standalone은 단일 기본 네임스페이스를 제공하며, 여기서는 Pulsar와 BookKeeper가 모두 이 네임스페이스를 사용해요.

출처: 문서

본문

사전 준비 (Prerequisites)

Docker (20.10+ 권장)
Docker Compose (2.0+ 권장)
클러스터용 RAM 최소 8GB
여유 디스크 공간 최소 10GB

1단계: compose.yml 템플릿 구성 (Configure the compose.yml template)

Pulsar 클러스터를 빠르게 띄우려면 아래 템플릿을 사용해, environment 섹션의 구성을 수정하거나 추가해 compose.yml 파일을 만들면 돼요.

이 클러스터는 메타데이터 저장소로 Oxia를 사용해요 — 새 Pulsar 클러스터에 권장되는 옵션이에요. Oxia standalone은 단일 기본 네임스페이스를 제공하며, 여기서는 Pulsar와 BookKeeper가 모두 이 네임스페이스를 사용해요. 프로덕션 클러스터는 별도의 Oxia 네임스페이스를 사용해요 (메타데이터 저장소 구성 문서 참고).

version: '3'
networks:
  pulsar:
    driver: bridge
services:
  # Start Oxia (metadata store)
  oxia:
    image: oxia/oxia:latest
    container_name: oxia
    restart: on-failure
    networks:
      - pulsar
    volumes:
      - oxia-data:/data
    command:
      - oxia
      - standalone
    healthcheck:
      test: ["CMD", "oxia", "health", "--port=6648"]
      interval: 10s
      timeout: 5s
      retries: 30

  # Init cluster metadata
  pulsar-init:
    container_name: pulsar-init
    hostname: pulsar-init
    image: apachepulsar/pulsar:5.0.0-M2
    networks:
      - pulsar
    command:
      - bash
      - -c
      - |
        bin/pulsar initialize-cluster-metadata \
        --cluster cluster-a \
        --metadata-store oxia://oxia:6648/default \
        --configuration-store oxia://oxia:6648/default \
        --web-service-url http://broker:8080 \
        --broker-service-url pulsar://broker:6650
    depends_on:
      oxia:
        condition: service_healthy

  # Start bookie
  bookie:
    image: apachepulsar/pulsar:5.0.0-M2
    container_name: bookie
    restart: on-failure
    networks:
      - pulsar
    environment:
      - clusterName=cluster-a
      - metadataServiceUri=metadata-store:oxia://oxia:6648/default
      - advertisedAddress=bookie
      - BOOKIE_MEM=-Xms512m -Xmx512m -XX:MaxDirectMemorySize=256m
    depends_on:
      oxia:
        condition: service_healthy
      pulsar-init:
        condition: service_completed_successfully
    volumes:
      - bookie-data:/pulsar/data/bookkeeper
    command: bash -c "bin/apply-config-from-env.py conf/bookkeeper.conf && exec bin/pulsar bookie"

  # Start broker
  broker:
    image: apachepulsar/pulsar:5.0.0-M2
    container_name: broker
    hostname: broker
    restart: on-failure
    networks:
      - pulsar
    environment:
      - metadataStoreUrl=oxia://oxia:6648/default
      - clusterName=cluster-a
      - managedLedgerDefaultEnsembleSize=1
      - managedLedgerDefaultWriteQuorum=1
      - managedLedgerDefaultAckQuorum=1
      - advertisedAddress=broker
      - advertisedListeners=external:pulsar://127.0.0.1:6650
      - PULSAR_MEM=-Xms512m -Xmx512m -XX:MaxDirectMemorySize=256m
    depends_on:
      oxia:
        condition: service_healthy
      bookie:
        condition: service_started
    ports:
      - "6650:6650"
      - "8080:8080"
    command: bash -c "bin/apply-config-from-env.py conf/broker.conf && exec bin/pulsar broker"

volumes:
  oxia-data:
  bookie-data:

2단계: Pulsar 클러스터 만들기 (Create a Pulsar cluster)

compose.yml 파일로 Pulsar 클러스터를 만들려면 다음 명령을 실행해요.

docker compose up -d

알아두기: 이 클러스터는 메타데이터와 메시지 데이터를 명명된 Docker 볼륨(oxia-data와 bookie-data)에 보존하므로, docker compose down과 docker compose up을 해도 데이터가 유지돼요. 데이터를 완전히 지우고 처음부터 다시 시작하려면 docker compose down -v를 실행해요.

3단계: Pulsar 클러스터 제거 (Destroy the Pulsar cluster)

모든 컨테이너와 함께 Pulsar 클러스터를 제거하려면 다음 명령을 실행해요. -v 플래그는 명명된 볼륨(클러스터 데이터)과 컨테이너가 연결된 네트워크도 함께 제거해요.

docker compose down -v

더 알아보기 (Learn more)

Docker로 단일 Pulsar를 실행하는 방법은 Docker 시작 문서를 참고해요.
메타데이터 저장소 구성이 궁금하다면 메타데이터 저장소 문서를 살펴보세요.
클러스터 메타데이터 초기화가 궁금하다면 클러스터 관리 문서를 확인해요.