Kubernetes에 Pulsar 클러스터 배포하기

Kubernetes에 Pulsar 클러스터 배포하기

Pulsar 클러스터를 배포하기 전에 먼저 Kubernetes 리소스를 준비해야 해요. 준비가 끝나면 아래 단계를 따라 Pulsar Helm 차트로 클러스터를 배포할 수 있어요.

구성 옵션 선택 → 의존 차트 설치 → Helm 릴리스 준비 → Helm으로 배포 순으로 진행되고, 마지막에 클러스터 접근 방법과 트러블슈팅까지 살펴볼게요.

출처: 문서

본문

Pulsar 클러스터를 배포하기 전에 Kubernetes 리소스를 준비하고, 다음 단계로 진행해요.

1단계: 구성 옵션 선택 (Select configuration options)

Helm의 --set name=value 명령줄 옵션으로 Pulsar를 실행하는 방식을 지정해요. 각 섹션에서 helm install 명령과 함께 사용할 옵션을 모아두세요.

Kubernetes 네임스페이스 (Kubernetes namespace)

기본적으로 Pulsar Helm 차트는 pulsar라는 네임스페이스에 설치돼요.

namespace: pulsar

다른 Kubernetes 네임스페이스에 Pulsar Helm 차트를 설치하려면 helm install 명령에 이 옵션을 포함할 수 있어요.

--set namespace=<different-k8s-namespace>

기본적으로 Pulsar Helm 차트는 네임스페이스를 만들지 않아요.

namespaceCreate: false

Pulsar Helm 차트가 Kubernetes 네임스페이스를 자동으로 만들게 하려면 helm install 명령에 이 옵션을 포함할 수 있어요.

--set namespaceCreate=true

지속성 (Persistence)

기본적으로 Pulsar Helm 차트는 동적 프로비저너(dynamic provisioner)가 기본 Persistent Volume을 만들 것이라는 기대하에 Volume Claim을 생성해요.

volumes:
  persistence: true

알아두기: 프로덕션 Pulsar 인스턴스를 설치하기 전에 스토리지 설정을 계획해서 추가 스토리지 마이그레이션 작업을 피하세요. 초기 설치 후에는 스토리지 설정을 변경하려면 Kubernetes 객체를 수동으로 편집해야 하기 때문이에요.

Pulsar Helm 차트는 프로덕션용으로 설계돼요. 개발 환경(예: Minikube)에서 Pulsar Helm 차트를 사용하려면 helm install 명령에 이 옵션을 포함해 지속성을 비활성화할 수 있어요.

--set volumes.persistence=false

친화성 (Affinity)

기본적으로 같은 컴포넌트의 pod를 서로 다른 노드에서 실행하도록 안티-친화성(anti-affinity)이 활성화돼요.

affinity:
  anti_affinity: true

개발 환경(예: Minikube)에서 Pulsar Helm 차트를 사용하려면 helm install 명령에 이 옵션을 포함해 안티-친화성을 비활성화할 수 있어요.

--set affinity.anti_affinity=false

컴포넌트 (Components)

Pulsar Helm 차트는 프로덕션 사용을 위해 설계됐어요. Pulsar 핵심 컴포넌트와 모니터링 컴포넌트를 포함한 프로덕션 준비형 Pulsar 클러스터를 배포해요.

개별 컴포넌트를 켜고/끄면서 배포할 컴포넌트를 커스터마이즈할 수 있어요.

## Components
##
## Control what components of Apache Pulsar to deploy for the cluster
components:
  # zookeeper
  zookeeper: true
  # bookkeeper
  bookkeeper: true
  # bookkeeper - autorecovery
  autorecovery: true
  # broker
  broker: true
  # functions
  functions: true
  # proxy
  proxy: true
  # toolset
  toolset: true
  # pulsar manager
  pulsar_manager: true

메타데이터 저장소로 Oxia 사용하기

새 클러스터에서는 Oxia가 권장되는 메타데이터 저장소예요. Pulsar Helm 차트는 ZooKeeper 대신 Oxia를 배포할 수 있어요 — 값 파일에서 components.oxia: true와 components.zookeeper: false를 설정하세요. 그러면 차트가 브로커의 metadataStoreUrl과 BookKeeper의 metadataServiceUri를 자동으로 Oxia 클러스터를 가리키게 해요. Oxia 옵션(예: oxia.initialShardCount, oxia.replicationFactor)과 기능 제한 사항은 차트의 values.yaml을 참고해요.

모니터링 컴포넌트 (Monitoring Components)

Pulsar Helm 차트는 의존 Helm 차트인 kube-prometheus-stack을 사용해 모니터링 컴포넌트를 설치해요. 이 Helm 차트를 커스터마이즈해 설치할 모니터링 컴포넌트를 지정할 수 있어요. 이 컴포넌트들은 기본적으로 활성화돼요.

## Monitoring Components
##
## Control what components of the kube-prometheus-stack Helm chart to deploy for the cluster
kube-prometheus-stack:
  # Control deployment of this Helm chart entirely
  enabled: true
  # prometheus
  prometheus:
    enabled: true
  promtheus-node-exporter:
    enabled: true
  # grafana
  grafana:
    enabled: true

Docker 이미지 (Docker images)

Pulsar Helm 차트는 통제된 업그레이드를 가능하게 설계됐어요. 그래서 컴포넌트별로 독립적인 이미지 버전을 구성할 수 있어요. 개별 컴포넌트를 설정해 이미지를 커스터마이즈할 수 있어요.

## Images
##
## Control what images to use for each component
images:
  zookeeper:
    repository: apachepulsar/pulsar-all
    tag: latest
    pullPolicy: IfNotPresent
  bookie:
    repository: apachepulsar/pulsar-all
    tag: latest
    pullPolicy: IfNotPresent
  autorecovery:
    repository: apachepulsar/pulsar-all
    tag: latest
    pullPolicy: IfNotPresent
  broker:
    repository: apachepulsar/pulsar-all
    tag: latest
    pullPolicy: IfNotPresent
  proxy:
    repository: apachepulsar/pulsar-all
    tag: latest
    pullPolicy: IfNotPresent
  functions:
    repository: apachepulsar/pulsar-all
    tag: latest
  pulsar_manager:
    repository: apachepulsar/pulsar-manager
    tag: v0.3.0
    pullPolicy: IfNotPresent
    hasCommand: false

Pulsar Helm 차트는 의존 Pulsar 리소스의 생성과 연결을 조정하는 데 사용되는 초기화 컨테이너(init container)가 쓰는 이미지 버전도 지정할 수 있게 해줘요.

## Images
##
## Control what image to use for Pulsar init containers
pulsar_metadata:
  component: pulsar-init
  image:
    repository: apachepulsar/pulsar-all
    tag: latest
    pullPolicy: IfNotPresent

팁: 프라이빗 Docker 리포지토리나 풀스루(pull-thru) 캐시를 사용한다면, pulsar_metadata 컴포넌트를 포함한 모든 컴포넌트 정의에서 repository 구성 옵션을 그에 맞게 변경해야 해요.

TLS (TLS)

Pulsar Helm 차트는 컴포넌트 간 모든 트래픽을 보호하도록 TLS(Transport Layer Security)를 활성화하도록 구성할 수 있어요. TLS를 활성화하기 전에 필요한 컴포넌트용 TLS 인증서를 프로비저닝해야 해요.

cert-manager로 TLS 인증서 프로비저닝 (Provision TLS certificates using cert-manager)

cert-manager로 TLS 인증서를 프로비저닝하려면 Pulsar Helm 차트를 설치하기 전에 cert-manager를 설치해야 해요. cert-manager 설치에 성공하면 certs.internal_issuer.enabled를 true로 설정할 수 있어요. 그러면 Pulsar Helm 차트가 cert-manager를 사용해 구성된 컴포넌트용 자체 서명 TLS 인증서를 생성해요.

certs:
  internal_issuer:
    enabled: false
    component: internal-cert-issuer
    type: selfsigning

다음과 같이 필드를 구성해 생성된 TLS 인증서를 커스터마이즈할 수도 있어요.

tls:
  # common settings for generating certs
  common:
    # 90d
    duration: 2160h
    # 15d
    renewBefore: 360h
    organization:
      - pulsar
    keySize: 4096
    keyAlgorithm: rsa
    keyEncoding: pkcs8

TLS 활성화 (Enable TLS)

cert-manager를 설치한 후 tls.enabled를 true로 설정해 전체 클러스터의 TLS 암호화를 활성화할 수 있어요.

tls:
  enabled: false

개별 컴포넌트에 대해 TLS 암호화를 활성화할지 여부도 구성할 수 있어요.

tls:
  # settings for generating certs for proxy
  proxy:
    enabled: false
    cert_name: tls-proxy
  # settings for generating certs for broker
  broker:
    enabled: false
    cert_name: tls-broker
  # settings for generating certs for bookies
  bookie:
    enabled: false
    cert_name: tls-bookie
  # settings for generating certs for zookeeper
  zookeeper:
    enabled: false
    cert_name: tls-zookeeper
  # settings for generating certs for recovery
  autorecovery:
    cert_name: tls-recovery
  # settings for generating certs for toolset
  toolset:
    cert_name: tls-toolset

인증 (Authentication)

기본적으로 인증은 비활성화되어 있어요. auth.authentication.enabled를 true로 설정해 인증을 활성화할 수 있어요. 현재 Pulsar Helm 차트는 JWT 인증 공급자만 지원해요. auth.authentication.provider를 jwt로 설정해 JWT 인증 공급자를 사용할 수 있어요.

# Enable or disable broker authentication and authorization.
auth:
  authentication:
    enabled: false
    provider: "jwt"
    jwt:
      # Enable JWT authentication
      # If the token is generated by a secret key, set the usingSecretKey as true.
      # If the token is generated by a private key, set the usingSecretKey as false.
      usingSecretKey: false
  superUsers:
    # broker to broker communication
    broker: "broker-admin"
    # proxy to broker communication
    proxy: "proxy-admin"
    # pulsar-admin client to broker/proxy communication
    client: "admin"

인증을 활성화하려면 prepare helm release를 실행해 auth.superUsers 필드에 지정된 세 슈퍼유저용 토큰 시크릿 키와 토큰을 생성할 수 있어요. 생성된 토큰 키와 슈퍼유저 토큰은 <pulsar-release-name>-token- 접두사가 붙은 Kubernetes 시크릿으로 업로드·저장돼요. 다음 명령으로 그 시크릿들을 찾을 수 있어요.

kubectl get secrets -n <k8s-namespace>

인가 (Authorization)

기본적으로 인가는 비활성화되어 있어요. 인가는 인증이 활성화된 경우에만 활성화할 수 있어요.

auth:
  authorization:
    enabled: false

인가를 활성화하려면 helm install 명령에 이 옵션을 포함할 수 있어요.

--set auth.authorization.enabled=true

CPU와 RAM 리소스 요구 사항 (CPU and RAM resource requirements)

기본적으로 Pulsar Helm 차트의 Pulsar 컴포넌트에 대한 리소스 요청(request)과 복제본 수는 소규모 프로덕션 배포에 적합해요. 비프로덕션 인스턴스를 배포한다면 기본값을 줄여 더 작은 클러스터에 맞출 수 있어요.

모든 구성 옵션을 모았다면, Pulsar Helm 차트를 설치하기 전에 의존 차트를 먼저 설치할 수 있어요.

2단계: 의존 차트 설치 (Install dependent charts)

스토리지 프로비저너 설치 (Install storage provisioner)

스토리지 프로비저너에 대한 자세한 내용은 Kubernetes 문서를 참고해요. Kubernetes 클러스터용 스토리지 클래스를 만들고, Helm 차트에 스토리지 클래스 이름을 구성해야 한다는 점에 주의해요.

영구 스토리지로 로컬 영구 볼륨을 사용하려면 로컬 스토리지 프로비저너를 설치해야 해요. 두 가지 옵션이 있어요.

• Local Path Provisioner
• Local Persistence Volume Static Provisioner

cert-manager 설치 (Install cert-manager)

Pulsar Helm 차트는 cert-manager를 사용해 TLS 인증서를 자동으로 프로비저닝·관리해요. 브로커나 프록시에 TLS 암호화를 활성화하려면 cert-manager를 미리 설치해야 해요.

cert-manager 설치 방법에 대한 자세한 내용은 공식 안내를 따르세요.

또는 cert-manager 릴리스를 cert-manager 네임스페이스에 설치하는 bash 스크립트 install-cert-manager.sh를 제공해요.

git clone https://github.com/apache/pulsar-helm-chart
cd pulsar-helm-chart
./scripts/cert-manager/install-cert-manager.sh

3단계: Helm 릴리스 준비 (Prepare Helm release)

모든 의존 차트를 설치하고 모든 구성 옵션을 모았다면, prepare_helm_release.sh를 실행해 Helm 릴리스를 준비할 수 있어요.

git clone https://github.com/apache/pulsar-helm-chart
cd pulsar-helm-chart
./scripts/pulsar/prepare_helm_release.sh -n <k8s-namespace> -k <helm-release-name>

prepare_helm_release는 다음 리소스를 생성해요.

• Pulsar 릴리스를 설치할 Kubernetes 네임스페이스.
• 세 슈퍼유저(broker-admin, proxy-admin, admin)용 JWT 시크릿 키와 토큰. 기본적으로 비대칭 공개/개인 키 쌍을 생성해요. --symmetric을 지정하면 대칭 시크릿 키를 생성하도록 선택할 수 있어요.
  • broker-admin 역할은 브로커 간 통신에 사용돼요.
  • proxy-admin 역할은 프록시가 브로커와 통신하는 데 사용돼요.
  • admin 역할은 admin 도구에서 사용돼요.

4단계: Helm으로 Pulsar 클러스터 배포 (Deploy Pulsar cluster using Helm)

위 단계를 모두 마쳤으면 Helm 릴리스를 설치할 수 있어요.

이 예시에서 Helm 릴리스 이름은 pulsar예요.

helm repo add apachepulsar https://pulsar.apache.org/charts
helm repo update
helm install pulsar apache/pulsar \
    --timeout 10m \
    --set [your configuration options]

특정 버전의 Pulsar Helm 차트를 설치하고 싶다면 --version <installation version> 옵션을 사용할 수도 있어요.

팁: Pulsar 클러스터가 배포되면 설치된 리소스 목록이 출력돼요. 이 작업은 5-10분 정도 걸릴 수 있어요.

배포 상태를 확인하려면 helm status pulsar 명령을 실행해요. 다른 터미널에서 명령을 실행하면 배포가 진행되는 동안에도 확인할 수 있어요.

Pulsar 클러스터 접근 (Access Pulsar cluster)

기본값은 다음 리소스에 대해 ClusterIP를 만들며, 이를 사용해 클러스터와 상호작용할 수 있어요.

• 프록시 (Proxy) — IP 주소를 사용해 설치된 Pulsar 클러스터에 메시지를 생산·소비할 수 있어요.
• Pulsar Manager — http://<pulsar-manager-ip>:9527에서 Pulsar Manager UI에 접근할 수 있어요.
• Grafana 대시보드 — http://<grafana-dashboard-ip>:3000에서 Grafana 대시보드에 접근할 수 있어요.

이 컴포넌트들의 IP 주소를 찾으려면 다음 명령을 실행해요.

kubectl get service -n <k8s-namespace>

프록시와 Pulsar Manager를 ClusterIP 대신 NodePort로 구성할 수 있어요.

proxy:
  service:
    type: NodePort
pulsar_manager:
  service:
    type: NodePort

트러블슈팅 (Troubleshoot)

저희는 이 차트들을 최대한 매끄럽게 만들기 위해 최선을 다했지만, 때로는 통제 밖의 문제가 발생하기도 해요. 일반적인 문제 해결을 위한 팁과 요령을 모았어요. 이슈를 제기하기 전에 먼저 확인하고, Pull Request를 만들어 해결책을 추가하는 것도 자유롭게 해 주세요.

제거 (Uninstall)

Pulsar Helm 차트를 제거하려면 다음 명령을 실행해요.

helm uninstall <pulsar-release-name>

연속성(continuity)을 위해 이 차트들의 일부 Kubernetes 객체는 helm uninstall 명령으로 제거할 수 없어요. 재배포에 영향을 주므로 이 항목들을 신중하게(의식적으로) 제거하는 것이 좋아요.

• 상태 저장 데이터용 PVC — 이 항목을 제거해요.
• ZooKeeper — 이것이 메타데이터예요.
• BookKeeper — 이것이 데이터예요.
• Prometheus — 안전하게 제거할 수 있는 메트릭 데이터예요.
• 시크릿 — 시크릿이 준비된 릴리스 스크립트로 생성된 것이라면 시크릿 키와 토큰을 담고 있어요. 필요에 따라 cleanup 릴리스 스크립트를 사용해 이 시크릿과 토큰을 제거할 수 있어요.

더 알아보기 (Learn more)

• 배포 전에 필요한 준비 사항은 Helm 준비 문서를 참고해요.
• Pulsar Helm 차트 개요는 Helm 개요 문서를 살펴보세요.
• Pulsar Helm 릴리스를 업그레이드하는 방법은 Helm 업그레이드 문서를 확인해요.