Kubernetes에서 standalone Pulsar 클러스터 실행하기
Kubernetes에서 standalone Pulsar 클러스터 실행하기
이 섹션은 Helm으로 Kubernetes에 Apache Pulsar를 설치하고 실행하는 전 과정을 빠르게 안내해요. Minikube 기반의 로컬 클러스터를 기준으로 동작하기 때문에, 처음 접하는 분도 그대로 따라 하면 됩니다.
프로덕션 용도로 Pulsar 클러스터를 배포하려면 Pulsar Helm 차트 구성·설치 문서를 읽어야 해요. 이 빠른 시작은 개발·테스트에만 적합한 기본 설정을 사용한다는 점을 꼭 기억해 두세요.
보안 안내: 이 빠른 시작 가이드는 개발과 테스트에만 적합한 기본 구성을 사용해요. 기본 Helm 차트 구성은 프로덕션 보안 요구 사항을 충족하지 못해요. 프로덕션 배포에서는 인증, 인가, TLS 암호화, 네트워크 정책을 포함한 보안 설정을 반드시 검토하고 커스터마이즈해야 해요.
출처: 문서
본문
사전 준비 (Prerequisites)
- Kubernetes 서버 1.25.0+ (최신 안정 버전 권장)
- k8s 서버 버전과 호환되는 kubectl 버전 (+/- 1 마이너 릴리스 버전)
- Helm 3.12+ (k8s 서버 버전과 호환되는 helm 버전 선택)
- Kubernetes 클러스터에 사용 가능한 RAM 최소 8GB
- 사용 가능한 영구 스토리지 최소 20GB
팁: 아래 단계 중 2단계와 3단계는 개발자용이고, 4단계와 5단계는 관리자용이에요.
0단계: Kubernetes 클러스터 준비 (Prepare a Kubernetes cluster)
Pulsar Helm 차트를 설치하기 전에 Kubernetes 클러스터를 만들어야 해요. 안내에 따라 Kubernetes 클러스터를 준비할 수 있어요.
이 빠른 시작 가이드에서는 Minikube를 사용해요. Kubernetes 클러스터를 준비하려면 다음 단계를 따라 해요.
- Minikube에서 Kubernetes 클러스터를 만들어요.
minikube start --memory=8192 --cpus=4
- kubectl이 Minikube를 사용하도록 설정해요.
kubectl config use-context minikube
- Minikube의 로컬 Kubernetes 클러스터에서 Kubernetes Dashboard를 사용하려면 아래 명령을 입력해요.
minikube dashboard
이 명령은 브라우저에서 웹페이지를 자동으로 엽니다.
1단계: Pulsar Helm 차트 설치 (Install Pulsar Helm chart)
- Pulsar charts 리포지토리를 추가해요.
helm repo add apachepulsar https://pulsar.apache.org/charts
helm repo update
- Pulsar Helm 차트 리포지토리를 클론해요.
git clone https://github.com/apache/pulsar-helm-chart
cd pulsar-helm-chart
prepare_helm_release.sh스크립트를 실행해 Apache Pulsar Helm 차트 설치에 필요한 시크릿을 만들어요.pulsar사용자 이름과pulsar비밀번호는 Grafana 대시보드와 Pulsar Manager에 로그인할 때 사용돼요.
알아두기: 스크립트를 실행할 때
-n으로 Pulsar Helm 차트가 설치될 Kubernetes 네임스페이스를,-k로 Pulsar Helm 릴리스 이름을,-c로 Kubernetes 네임스페이스 생성을 지정할 수 있어요. 스크립트에 대한 자세한 내용은./scripts/pulsar/prepare_helm_release.sh --help를 실행해요.
./scripts/pulsar/prepare_helm_release.sh \
-n pulsar \
-k pulsar-mini \
-c
- Pulsar Helm 차트를 사용해 Kubernetes에 Pulsar 클러스터를 설치해요.
아래 --set 오버라이드들은 모든 Pulsar 구성 요소를 이 문서 버전에 맞는 apachepulsar/pulsar:5.0.0-M2 이미지로 고정하고, ZooKeeper 대신 메타데이터 저장소로 Oxia를 사용하며 — 새 Pulsar 클러스터에 권장되는 옵션 — minikube 푸트프린트에 맞게 Oxia를 단일 복제본으로 축소해요. 이 값들은 명령줄 대신 값 파일에서 설정할 수도 있어요.
helm install \
--values examples/values-minikube.yaml \
--set defaultPulsarImageRepository=apachepulsar/pulsar \
--set defaultPulsarImageTag=5.0.0-M2 \
--set components.zookeeper=false \
--set components.oxia=true \
--set oxia.server.replicas=1 \
--set oxia.replicationFactor=1 \
--set oxia.initialShardCount=1 \
--namespace pulsar \
pulsar-mini apachepulsar/pulsar
팁:
values-minikube.yaml파일에 다음 줄들이 포함되어 있는지 확인해요.pulsar_manager: configData: ENV_SPRING_CONFIGURATION_FILE: "/pulsar-manager/pulsar-manager/application.properties" SPRING_CONFIGURATION_FILE: "/pulsar-manager/pulsar-manager/application.properties" PULSAR_MANAGER_OPTS: " -Dlog4j2.formatMsgNoLookups=true"
- 모든 pod의 상태를 확인해요.
kubectl get pods -n pulsar
모든 pod가 성공적으로 시작되면 STATUS가 Running 또는 Completed로 바뀐 걸 볼 수 있어요.
출력:
NAME READY STATUS RESTARTS AGE
pulsar-mini-bookie-0 1/1 Running 0 9m27s
pulsar-mini-bookie-init-5gphs 0/1 Completed 0 9m27s
pulsar-mini-broker-0 1/1 Running 0 9m27s
pulsar-mini-grafana-6b7bcc64c7-4tkxd 1/1 Running 0 9m27s
pulsar-mini-oxia-coordinator-7c9d8f5b6c-q4xtz 1/1 Running 0 9m27s
pulsar-mini-oxia-server-0 1/1 Running 0 9m27s
pulsar-mini-prometheus-5fcf5dd84c-w8mgz 1/1 Running 0 9m27s
pulsar-mini-proxy-0 1/1 Running 0 9m27s
pulsar-mini-pulsar-init-t7cqt 0/1 Completed 0 9m27s
pulsar-mini-pulsar-manager-9bcbb4d9f-htpcs 1/1 Running 0 9m27s
pulsar-mini-toolset-0 1/1 Running 0 9m27s
pulsar네임스페이스의 모든 서비스 상태를 확인해요.
kubectl get services -n pulsar
출력:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
pulsar-mini-bookie ClusterIP None <none> 3181/TCP,8000/TCP 11m
pulsar-mini-broker ClusterIP None <none> 8080/TCP,6650/TCP 11m
pulsar-mini-grafana LoadBalancer 10.106.141.246 <pending> 3000:31905/TCP 11m
pulsar-mini-oxia ClusterIP 10.103.0.51 <none> 6648/TCP,6649/TCP,8080/TCP 11m
pulsar-mini-oxia-coordinator ClusterIP 10.103.0.77 <none> 6649/TCP,8080/TCP 11m
pulsar-mini-oxia-svc ClusterIP None <none> 6648/TCP,6649/TCP,8080/TCP 11m
pulsar-mini-prometheus ClusterIP None <none> 9090/TCP 11m
pulsar-mini-proxy LoadBalancer 10.97.240.109 <pending> 80:32305/TCP,6650:31816/TCP 11m
pulsar-mini-pulsar-manager LoadBalancer 10.103.192.175 <pending> 9527:30190/TCP 11m
pulsar-mini-toolset ClusterIP None <none> <none> 11m
2단계: pulsar-admin으로 테넌트/네임스페이스/토픽 만들기 (Use pulsar-admin to create Pulsar tenants/namespaces/topics)
pulsar-admin은 Pulsar의 CLI(Command-Line Interface) 도구예요. 이 단계에서는 pulsar-admin을 사용해 테넌트, 네임스페이스, 토픽 같은 리소스를 만들 수 있어요.
- toolset 컨테이너로 들어가요.
kubectl exec -it -n pulsar pulsar-mini-toolset-0 -- /bin/bash
팁: 상태 확인을 하려면
bin/pulsar-admin brokers healthcheck명령을 사용할 수 있어요. 자세한 내용은 Pulsar admin 문서를 참고해요.
- toolset 컨테이너에서
apache라는 테넌트를 만들어요.
bin/pulsar-admin tenants create apache
그 다음 테넌트를 나열해 테넌트가 성공적으로 생성되었는지 확인해요.
bin/pulsar-admin tenants list
다음과 같은 출력이 보일 거예요. apache 테넌트가 성공적으로 생성되었어요.
"apache"
"public"
"pulsar"
- toolset 컨테이너에서
apache테넌트에pulsar라는 네임스페이스를 만들어요.
bin/pulsar-admin namespaces create apache/pulsar
그 다음 apache 테넌트의 네임스페이스를 나열해 네임스페이스가 성공적으로 생성되었는지 확인해요.
bin/pulsar-admin namespaces list apache
다음과 같은 출력이 보일 거예요. apache/pulsar 네임스페이스가 성공적으로 생성되었어요.
"apache/pulsar"
- toolset 컨테이너에서
apache/pulsar네임스페이스에 파티션이 4개인test-topic토픽을 만들어요.
bin/pulsar-admin topics create-partitioned-topic apache/pulsar/test-topic -p 4
- toolset 컨테이너에서
apache/pulsar네임스페이스의 모든 파티션 토픽을 나열해요.
bin/pulsar-admin topics list-partitioned-topics apache/pulsar
그 다음 apache/pulsar 네임스페이스의 모든 파티션 토픽을 볼 수 있어요.
"persistent://apache/pulsar/test-topic"
3단계: Pulsar 클라이언트로 메시지 생산·소비 (Use Pulsar client to produce and consume messages)
Pulsar 클라이언트를 사용해 메시지를 생산하고 소비하는 프로듀서와 컨슈머를 만들 수 있어요.
기본적으로 Pulsar Helm 차트는 Kubernetes LoadBalancer를 통해 Pulsar 클러스터를 노출해요. Minikube에서는 다음 명령으로 프록시 서비스를 확인할 수 있어요.
kubectl get services -n pulsar | grep pulsar-mini-proxy
다음과 같은 출력이 보일 거예요.
pulsar-mini-proxy LoadBalancer 10.97.240.109 <pending> 80:32305/TCP,6650:31816/TCP 28m
이 출력은 Pulsar 클러스터의 바이너리 포트와 HTTP 포트가 매핑된 노드 포트를 보여줘요. 80: 뒤의 포트는 HTTP 포트이고, 6650: 뒤의 포트는 바이너리 포트예요.
그 다음 다음 명령을 실행해 Minikube 서버의 IP 주소와 노출된 포트를 찾을 수 있어요.
minikube service pulsar-mini-proxy -n pulsar
출력:
|-----------|-------------------|-------------|-------------------------|
| NAMESPACE | NAME | TARGET PORT | URL |
|-----------|-------------------|-------------|-------------------------|
| pulsar | pulsar-mini-proxy | http/80 | http://172.17.0.4:32305 |
| | | pulsar/6650 | http://172.17.0.4:31816 |
|-----------|-------------------|-------------|-------------------------|
🏃 Starting tunnel for service pulsar-mini-proxy.
|-----------|-------------------|-------------|------------------------|
| NAMESPACE | NAME | TARGET PORT | URL |
|-----------|-------------------|-------------|------------------------|
| pulsar | pulsar-mini-proxy | | http://127.0.0.1:61853 |
| | | | http://127.0.0.1:61854 |
|-----------|-------------------|-------------|------------------------|
이 시점에서 Pulsar 클라이언트에 연결할 서비스 URL을 얻을 수 있어요. URL 예시는 다음과 같아요.
webServiceUrl=http://127.0.0.1:61853/
brokerServiceUrl=pulsar://127.0.0.1:61854/
그 다음 다음 단계를 진행해요.
- 다운로드 페이지에서 Apache Pulsar tarball을 다운로드해요.
- 다운로드한 파일에 따라 tarball의 압축을 풀어요.
tar -xf <file-name>.tar.gz
PULSAR_HOME을 노출해요.
(1) 압축을 푼 다운로드 파일의 디렉터리로 들어가요.
(2) PULSAR_HOME을 환경 변수로 노출해요.
export PULSAR_HOME=$(pwd)
- Pulsar 클라이언트를 구성해요.
${PULSAR_HOME}/conf/client.conf 파일에서 webServiceUrl과 brokerServiceUrl을 위 단계에서 얻은 서비스 URL로 바꿔요.
apache/pulsar/test-topic의 메시지를 소비할 구독을 만들어요.
bin/pulsar-client consume -s sub apache/pulsar/test-topic -n 0
- 새 터미널을 엽니다. 새 터미널에서 프로듀서를 만들고
test-topic토픽에 10개의 메시지를 보내요.
bin/pulsar-client produce apache/pulsar/test-topic -m "---------hello apache pulsar-------" -n 10
- 결과를 확인해요.
프로듀서 측:
출력:
메시지가 성공적으로 생산되었어요.
18:15:15.489 [main] INFO org.apache.pulsar.client.cli.PulsarClientTool - 10 messages successfully produced
컨슈머 측:
출력:
동시에 다음과 같이 메시지를 받을 수 있어요.
----- got message -----
---------hello apache pulsar-------
----- got message -----
---------hello apache pulsar-------
----- got message -----
---------hello apache pulsar-------
----- got message -----
---------hello apache pulsar-------
----- got message -----
---------hello apache pulsar-------
----- got message -----
---------hello apache pulsar-------
----- got message -----
---------hello apache pulsar-------
----- got message -----
---------hello apache pulsar-------
----- got message -----
---------hello apache pulsar-------
----- got message -----
---------hello apache pulsar-------
4단계: Pulsar Manager로 클러스터 관리 (Use Pulsar Manager to manage the cluster)
Pulsar Manager는 Pulsar를 관리하고 모니터링하는 웹 기반 GUI 관리 도구예요.
- 슈퍼유저 계정을 만들려면 pulsar-manager pod에 연결해 계정을 만들어요.
kubectl exec -it YOUR_PULSAR_MANAGER_POD_NAME -n pulsar -- /bin/bash
CSRF_TOKEN=$(curl http://localhost:7750/pulsar-manager/csrf-token)
curl \
-H "X-XSRF-TOKEN: $CSRF_TOKEN" \
-H "Cookie: XSRF-TOKEN=$CSRF_TOKEN;" \
-H 'Content-Type: application/json' \
-X PUT http://localhost:7750/pulsar-manager/users/superuser \
-d '{"name": "pulsar", "password": "pulsar", "description": "test", "email": "[email protected]"}'
- 기본적으로 Pulsar Manager는 별도의 LoadBalancer로 노출돼요. 다음 명령으로 Pulsar Manager UI를 열 수 있어요.
minikube service -n pulsar pulsar-mini-pulsar-manager
-
Pulsar Manager UI가 브라우저에 열려요.
pulsar사용자 이름과pulsar비밀번호로 Pulsar Manager에 로그인할 수 있어요. -
Pulsar Manager UI에서 환경(environment)을 만들 수 있어요.
- 왼쪽 위의 New Environment를 클릭해요.
- 팝업 창의 Environment Name 필드에
pulsar-mini를 입력해요. - 팝업 창의 Service URL 필드에
http://pulsar-mini-broker:8080을 입력해요. - 팝업 창의 Bookie URL 필드에
http://pulsar-mini-bookie:8080을 입력해요. - 팝업 창에서 Confirm을 클릭해요.
- 환경 생성에 성공하면 Pulsar Manager를 사용해 테넌트, 네임스페이스, 토픽을 만들 수 있어요.
5단계: Prometheus와 Grafana로 클러스터 모니터링 (Use Prometheus and Grafana to monitor cluster)
Grafana는 시계열 데이터를 대시보드로 시각화하는 데 사용할 수 있는 오픈소스 시각화 도구예요.
- 기본적으로 Grafana는 별도의 LoadBalancer로 노출돼요. 다음 명령으로 Grafana UI를 열 수 있어요.
minikube service pulsar-mini-grafana -n pulsar
-
Grafana UI가 브라우저에 열려요.
pulsar사용자 이름과pulsar비밀번호로 Grafana 대시보드에 로그인할 수 있어요. -
Pulsar 클러스터의 다양한 구성 요소에 대한 대시보드를 볼 수 있어요.
더 알아보기 (Learn more)
- 프로덕션용 Pulsar Helm 차트 구성은 Helm 구성 문서를 참고해요.
- Kubernetes 클러스터 준비 방법은 Helm 준비 문서를 살펴보세요.
- Pulsar 모니터링이 궁금하다면 모니터링 관련 문서를 확인해요.