업그레이드 가이드

업그레이드 가이드 (Upgrade Guide)

이 가이드는 Pulsar 클러스터 전반의 업그레이드와 컴포넌트를 업그레이드하는 순서를 다뤄요. 브로커별 롤아웃 전략, 정상 종료, 로드 분산은 Rolling upgrade of brokers를 참고해요. 업그레이드 전에 전체를 읽고 계획을 세운 뒤 실행하는 것이 좋아요.

출처: 문서

본문

Kubernetes를 사용하고 있나요?

이 가이드는 서버를 가축보다 애완동물처럼 취급하던 시절에 작성됐어요. 개별적으로 이름을 붙이고, 세심히 돌보고, 한 번에 하나씩 업그레이드하는 방식이죠. 이런 수동·서버별 절차는 Kubernetes와 다른 현대적 오케스트레이션 배포의 실용적인 런북이 아니에요. 이 지침에 대한 업데이트가 예정돼 있어요.

짧은 서비스 중단이 허용 가능하다면 기본 Apache Pulsar Helm 차트가 클러스터 업그레이드의 간단한 방법을 제공해요. 중단 없는 서비스나 최대 중단 시간을 보장하지는 않아요. Upgrading Pulsar on Kubernetes부터 시작해요. 브로커 업그레이드 중 중단을 최소화해야 한다면 Rolling upgrade of brokers: Kubernetes deployments를 참고해요.

이 가이드는 Pulsar 클러스터 전반의 업그레이드와 컴포넌트를 업그레이드하는 순서를 다뤄요. 브로커별 롤아웃 전략, 정상 종료, 로드 분산은 Rolling upgrade of brokers를 참고해요.

업그레이드 지침 (Upgrade guidelines)

Apache Pulsar는 여러 컴포넌트, 메타데이터 스토어(Oxia 또는 ZooKeeper), 부키, 브로커로 구성돼요. 이 컴포넌트는 상태를 가지거나(stateful) 상태가 없거나(stateless) 해요. 특별한 요구 사항이 없다면 메타데이터 스토어를 업그레이드할 필요는 없어요. 업그레이드하는 동안 부키(상태 있음), 브로커, 프록시(상태 없음)에 주의를 기울여야 해요.

Pulsar 클러스터를 업그레이드하기 전에 다음 지침을 읽어요.

업그레이드 전에 모든 구성 파일을 백업해요.
가이드 전체를 읽고, 계획을 세우고, 그 계획을 실행해요. 업그레이드 계획을 세울 때 자신의 특정 요구 사항과 환경을 고려해야 해요.
컴포넌트의 업그레이드 순서에 주의해요. 일반적으로 메타데이터 스토어나 구성 스토어 클러스터를 업그레이드할 필요는 없어요. 부키를 먼저 업그레이드하고, 그다음 브로커, 프록시, 그리고 클라이언트를 업그레이드해요.
자동 복구(autorecovery)가 활성화되어 있다면 업그레이드 과정에서 자동 복구를 비활성화하고, 과정을 완료한 후 다시 활성화해야 해요.
각 릴리스의 릴리스 노트를 주의 깊게 읽어요. 릴리스 노트에는 업그레이드에 영향을 줄 수 있는 기능과 구성 변경이 포함돼 있어요.
클러스터의 해당 유형의 모든 노드를 업그레이드하기 전에 각 유형의 작은 부분집합 노드를 업그레이드해 새 버전을 카나리(canary) 테스트해요. 카나리 노드를 업그레이드하고 나서 잠시 실행해 올바르게 동작하는지 확인해요.
클러스터가 멀티-클러스터 복제 모드로 실행된다면 모든 데이터 센터를 업그레이드하기 전에 하나의 데이터 센터를 업그레이드해 새 버전을 검증해요.

note

현재 Apache Pulsar는 버전 간 호환 가능해요.

Kubernetes에서 브로커를 업데이트하려면 Kubernetes deployments를 확인해요.

업그레이드 순서 (Upgrade sequence)

Apache Pulsar 클러스터를 업그레이드하려면 다음 업그레이드 순서를 따라요.

메타데이터 스토어 업그레이드 (선택). 아래 단계는 ZooKeeper 기반 메타데이터 스토어를 설명해요. Oxia를 사용한다면 Oxia 문서에서 동등한 절차를 따라요.
- 카나리 테스트: 하나 또는 작은 메타데이터 스토어 노드 집합에서 업그레이드 버전을 테스트해요.
- 롤링 업그레이드: 업그레이드 버전을 모든 메타데이터 스토어 노드에 한 번에 하나씩 점진적으로 롤아웃해요. 전체 롤링 업그레이드 과정 동안 대시보드를 모니터링해요.
부키 업그레이드.
- 카나리 테스트: 하나 또는 작은 부키 집합에서 업그레이드 버전을 테스트해요.
- 롤링 업그레이드:
  - a. 다음 명령으로 자동 복구를 비활성화해요.
```
bin/bookkeeper shell autorecovery -disable
```
  - b. 카나리 후 버전이 안전하다고 판단하면 업그레이드 버전을 클러스터의 모든 부키에 롤아웃해요.
  - c. 모든 부키를 업그레이드한 후 다음 명령으로 자동 복구를 다시 활성화해요.
```
bin/bookkeeper shell autorecovery -enable
```
브로커 업그레이드.
- 카나리 테스트: 하나 또는 작은 브로커 집합에서 업그레이드 버전을 테스트해요.
- 롤링 업그레이드: 카나리 후 버전이 안전하다고 판단하면 업그레이드 버전을 클러스터의 모든 브로커에 롤아웃해요. Rolling upgrade of brokers의 절차를 따라 각 브로커가 번들을 정상적으로 넘겨주고 브로커가 재시작되는 동안 로드 밸런서가 클러스터를 리밸런싱하지 않게 해요. Kubernetes의 경우 먼저 배포 전제 조건을 구성해요. 기본 StatefulSet RollingUpdate 전략은 Pulsar 재시작 검사를 강제하지 않아요.
프록시 업그레이드.
- 카나리 테스트: 하나 또는 작은 프록시 집합에서 업그레이드 버전을 테스트해요.
- 롤링 업그레이드: 카나리 후 버전이 안전하다고 판단하면 업그레이드 버전을 클러스터의 모든 프록시에 롤아웃해요.

ZooKeeper 업그레이드 (선택) (Upgrade ZooKeeper (optional))

ZooKeeper 서버를 업그레이드하는 동안 먼저 카나리 테스트를 한 다음 클러스터의 모든 ZooKeeper 서버를 업그레이드할 수 있어요.

카나리 테스트 (Canary test)

클러스터의 모든 ZooKeeper 서버를 업그레이드하기 전에 ZooKeeper 서버 중 하나에서 업그레이드 버전을 테스트할 수 있어요.

ZooKeeper 서버를 새 버전으로 업그레이드하려면 다음 단계를 완료해요.

ZooKeeper 서버를 중지해요.
바이너리와 구성 파일을 업그레이드해요.
새 바이너리 파일로 ZooKeeper 서버를 시작해요.
pulsar zookeeper-shell을 사용해 새로 업그레이드된 ZooKeeper 서버에 연결하고 몇 가지 명령을 실행해 예상대로 동작하는지 확인해요.
ZooKeeper 서버를 며칠 실행하며 관찰하고, ZooKeeper 클러스터가 잘 실행되는지 확인해요.

tip

카나리 테스트 중 문제가 발생하면 문제가 있는 ZooKeeper 노드를 종료하고, 바이너리와 구성을 되돌리고, 되돌린 바이너리로 ZooKeeper를 재시작할 수 있어요.

모든 ZooKeeper 서버 업그레이드 (Upgrade all ZooKeeper servers)

클러스터에서 ZooKeeper 하나를 업그레이드하는 카나리 테스트 후, 클러스터의 모든 ZooKeeper 서버를 업그레이드할 수 있어요.

카나리 테스트의 단계를 따라 모든 ZooKeeper 서버를 하나씩 업그레이드할 수 있어요.

부키 업그레이드 (Upgrade bookies)

부키를 업그레이드하는 동안 먼저 카나리 테스트를 한 다음 클러스터의 모든 부키를 업그레이드할 수 있어요. 자세한 내용은 Apache BookKeeper Upgrade guide를 읽을 수 있어요.

카나리 테스트 (Canary test)

클러스터의 모든 부키를 업그레이드하기 전에 하나 또는 작은 부키 집합에서 업그레이드 버전을 테스트할 수 있어요.

부키를 새 버전으로 업그레이드하려면 다음 단계를 완료해요.

부키를 중지해요.
바이너리와 구성 파일을 업그레이드해요.
이 새 버전의 부키가 읽기 워크로드에 잘 동작하는지 확인하기 위해 ReadOnly 모드로 부키를 시작해요.
```
bin/pulsar bookie --readOnly
```
부키가 ReadOnly 모드에서 성공적으로 실행되면 부키를 중지하고 Write/Read 모드로 재시작해요.
```
bin/pulsar bookie
```
클러스터가 쓰기와 읽기 트래픽을 모두 서빙하는지 관찰하고 확인해요.

tip

카나리 테스트 중 문제가 발생하면 문제가 있는 부키 노드를 종료할 수 있어요. 클러스터의 다른 부키가 자동 복구로 이 문제 있는 부키 노드를 대체해요.

모든 부키 업그레이드 (Upgrade all bookies)

클러스터의 일부 부키를 업그레이드하는 카나리 테스트 후, 클러스터의 모든 부키를 업그레이드할 수 있어요.

업그레이드 전에 다운타임 및 롤링 업그레이드 시나리오를 포함해 전체 클러스터를 한 번에 업그레이드할지 결정해야 해요.

롤링 업그레이드 시나리오에서는 한 번에 하나의 부키를 업그레이드해요. 다운타임 업그레이드 시나리오에서는 전체 클러스터를 종료하고, 각 부키를 업그레이드하고, 클러스터를 시작해요.

두 시나리오에서 업그레이드하는 동안 각 부키의 절차는 동일해요.

부키를 중지해요.
소프트웨어(새 바이너리 또는 새 구성 파일)를 업그레이드해요.
부키를 시작해요.

tip

롤링 업그레이드 시나리오에서 큰 BookKeeper 클러스터를 업그레이드할 때 한 번에 하나씩 업그레이드하면 느려요. rack-aware 또는 region-aware 배치 정책을 구성했다면 부키를 랙별로 또는 지역별로 업그레이드할 수 있어 전체 업그레이드 과정을 빠르게 해요.

브로커와 프록시 업그레이드 (Upgrade brokers and proxies)

브로커와 프록시의 업그레이드 절차는 동일해요. 브로커와 프록시는 상태가 없으므로(stateless) 두 서비스 업그레이드는 쉬워요. 다만 브로커는 할당된 번들을 소유하며, 중지할 때 그것을 다른 브로커에 넘겨줘요. 어떻게 일어나는지, 얼마나 걸리는지, 로드 밸런서가 모든 재시작에 반응하지 않게 하는 방법은 Rolling upgrade of brokers에 설명돼 있어요.

note

브로커 업그레이드에는 카나리 업그레이드를 포함해 브로커용 롤링 업그레이드 절차를 따라요. Kubernetes에서 브로커를 업그레이드하기 전에 Kubernetes deployment prerequisites를 구성해요. 여기에는 API를 호출하는 preStop 훅으로 제어된 파드 삭제, 충분한 termination budget, 필요한 Service 레이아웃이 포함돼요. 이러한 공유 전제 조건은 제자리(in-place) 교체와 새 브로커 StatefulSet으로의 교체 모두에 적용돼요.

Apache Pulsar Helm 차트는 이 절차를 기본적으로 자동화하지 않아요. Pulsar 인지 롤아웃 자동화는 현재 없으며 기여를 환영해요. 완전한 자동화의 일부는 Kubernetes 오퍼레이터 로직이나 동등한 사용자 지정 컨트롤러가 필요해요. Apache Pulsar 프로젝트는 Pulsar용 Kubernetes 오퍼레이터를 제공하지 않아요. 필요한 오케스트레이션을 직접 배치해요. Helm 업그레이드만으로는 이 검사를 수행하지 않아요.

카나리 테스트 (Canary test)

클러스터의 모든 노드를 업그레이드하기 전에 하나 또는 작은 노드 집합에서 업그레이드 버전을 테스트할 수 있어요.

브로커(또는 프록시)를 새 버전으로 업그레이드하려면 다음 단계를 완료해요.

브로커(또는 프록시)를 중지해요. 브로커는 pulsar-admin --admin-url <broker-admin-url> brokers shutdown 또는 SIGTERM으로 중지하고 프로세스가 종료될 때까지 기다려요. 먼저 번들을 해제해요(What happens when a broker stops 참고). 명령이 의도한 브로커에 도달하도록 개별 브로커의 admin URL을 사용해요.
바이너리와 구성 파일을 업그레이드해요.
브로커(또는 프록시)를 시작해요.
브로커의 경우 다음 것으로 진행하기 전에 개별 admin URL에서 등록, 상태, 접근성, 로드 보고를 확인해요. Restart one broker at a time의 모든 검사를 따라요.

tip

카나리 테스트 중 문제가 발생하면 문제가 있는 브로커(또는 프록시) 노드를 종료할 수 있어요. 이전 버전으로 되돌리고 브로커(또는 프록시)를 재시작해요.

모든 브로커 또는 프록시 업그레이드 (Upgrade all brokers or proxies)

클러스터의 일부 브로커 또는 프록시를 업그레이드하는 카나리 테스트 후, 클러스터의 모든 브로커 또는 프록시를 업그레이드할 수 있어요.

브로커 롤링 업그레이드의 경우, 자동 리밸런싱을 일시 중지하는 것부터 마지막 브로커 재시작 후 복구를 확인하는 것까지 업그레이드 전체에 걸쳐 브로커용 롤링 업그레이드 절차를 따라요.

업그레이드 전에 다운타임 및 롤링 업그레이드 시나리오를 포함해 전체 클러스터를 한 번에 업그레이드할지 결정해야 해요.

롤링 업그레이드 시나리오에서는 클러스터 크기가 작으면 한 번에 하나의 브로커나 프록시를 업그레이드할 수 있어요. 클러스터가 크면 브로커나 프록시를 배치로 업그레이드할 수 있어요. 브로커나 프록시 배치를 업그레이드할 때 남은 브로커와 프록시가 업그레이드 중 트래픽을 처리할 충분한 용량이 있는지 확인해요. 브로커 롤링을 시작하기 전에 자동 로드 셰딩과 번들 분할을 일시 중지하고, 마지막 브로커가 상태가 좋고 로드를 보고하면 이전 설정을 복원해요.

다운타임 업그레이드 시나리오에서는 전체 클러스터를 종료하고, 각 브로커나 프록시를 업그레이드하고, 클러스터를 시작해요.

각 브로커나 프록시에 대해 다음 단계를 수행해요. 롤링 브로커 업그레이드 동안에는 브로커용 롤링 업그레이드 절차의 일부로 적용하고, 현재 리더를 마지막에 재시작하고, 다음 브로커를 중지하기 전에 등록·상태·접근성·로드 보고 검사를 완료해요. 현재 리더는 pulsar-admin brokers leader-broker(GET /admin/v2/brokers/leaderBroker)로 조회해요. 배치 결정을 내리는 로드 매니저에게 교체 브로커의 로드 정보와 수신 브로커의 증가된 워크로드를 반영한 업데이트된 보고서가 도달했는지 확인한 후 계속해요. Kubernetes에서는 OnDelete가 있는 제자리 교체 또는 새 StatefulSet으로의 교체 중 하나를 선택해요. 아래 중지/시작 단계는 제자리 교체를 설명해요. 새 풀(new-pool) 대안은 각 새 브로커를 시작하고 오래된 것을 은퇴시키기 전에 워크로드를 전송해요. 둘 다 동일한 상태·로드 보고 검사가 필요해요.

브로커(또는 프록시)를 중지하고 프로세스가 종료될 때까지 기다려요.
소프트웨어(새 바이너리 또는 새 구성 파일)를 업그레이드해요.
브로커(또는 프록시)를 시작하고, 브로커의 경우 다음 것을 중지하기 전에 재시작 검사를 완료해요.

tip

브로커의 상태를 확인하려면 개별 admin URL을 다음 명령 또는 API와 함께 사용해요. 공유 Service나 프록시가 상태 검사를 다른 브로커로 보낼 수 있어요.

Admin CLI

pulsar-admin --admin-url <broker-admin-url> brokers healthcheck

REST API: 이 엔드포인트로 GET 요청을 보내요. GET /admin/v2/brokers/health

더 알아보기 (Learn more)

브로커별 롤링 업그레이드 전략은 Rolling upgrade of brokers 문서를 참고해요.
Kubernetes에서 Pulsar 업그레이드는 Upgrading Pulsar on Kubernetes 문서를 참고해요.
부키 업그레이드 상세는 Apache BookKeeper Upgrade guide를 참고해요.