메타데이터 스토어 마이그레이션: ZooKeeper에서 Oxia로
메타데이터 스토어 마이그레이션: ZooKeeper에서 Oxia로 (Migrate metadata store from ZooKeeper to Oxia)
Pulsar는 다운타임 없이 메타데이터 스토어를 Apache ZooKeeper에서 Oxia로 실시간(live) 마이그레이션하는 것을 지원해요. 마이그레이션 중에도 데이터 플레인(게시와 소비)은 정상적으로 계속 동작해요. 마이그레이션 프레임워크는 Pulsar 5.0에서 PIP-454로 도입됐어요.
출처: 문서
본문
note
이 절차는 클러스터의 메타데이터 스토어(
metadataStoreUrl)를 마이그레이션해요. 별도의 구성 메타데이터 스토어(다른 앙상블을 가리키는configurationMetadataStoreUrl)를 마이그레이션하는 것은 범위 밖이며 별도로 처리해야 해요. 클러스터가 둘 모두에 단일 메타데이터 스토어를 사용한다면(standalone 및 단일 클러스터 배포의 기본), 이 절차가 모든 것을 다뤄요.
마이그레이션 동작 방식 (How the migration works)
마이그레이션은 쓰기-중지-및-복사(write-pause-and-copy) 방식을 사용해요. 높은 수준에서:
- 모든 브로커와 부키가 메타데이터 쓰기를 일시적으로 중지해요.
- 코디네이터가 모든 영속 메타데이터를 ZooKeeper에서 Oxia로 복사해요.
- 모든 브로커와 부키가 Oxia를 사용하도록 전환해요.
매 시점에 단일 진실 소스가 있으므로(이중 쓰기나 이중 읽기 없음) 메타데이터는 항상 일관된 상태예요.
마이그레이션 단계 (Migration phases)
| Phase | Reads from | Writes to | Data plane impact |
|---|---|---|---|
NOT_STARTED |
ZooKeeper | ZooKeeper | None |
PREPARATION |
ZooKeeper | Blocked | 게시/소비 동작. 토픽·구독 생성 차단, 로드 밸런싱 연산 지연됨 |
COPYING |
ZooKeeper | Blocked | PREPARATION과 동일 |
COMPLETED |
Oxia | Oxia | None |
FAILED |
ZooKeeper | ZooKeeper | None (ZooKeeper로 되돌림) |
PREPARATION과 COPYING 단계는 수백 MB 메타데이터가 있는 클러스터에서도 보통 30초 안에 완료돼요.
각 단계에서 일어나는 일 (What happens at each phase)
- PREPARATION — 코디네이터가 ZooKeeper에 마이그레이션 플래그를 기록해요. 각 브로커와 부키가 플래그를 감지하고, 대상 Oxia 클러스터에 연결해 Oxia에 자체 임시(ephemeral) 노드를 재생성하고, 참여자 등록을 제거해 준비 완료를 알려요. 코디네이터는 모든 참여자가 확인할 때까지 기다려요.
- COPYING — 코디네이터가 ZooKeeper의 모든 영속 메타데이터를 순회해 Oxia에 복사하면서 버전 ID와 수정 횟수를 보존해요. 임시 노드는 준비 단계에서 이미 재생성됐으므로 건너뛰어요.
- COMPLETED — 코디네이터가 완료 플래그를 기록해요. 모든 브로커와 부키가 읽기·쓰기를 Oxia로 전환하고, 캐시를 무효화하고, 정상 메타데이터 연산을 재개해요.
마이그레이션 중 오류가 발생하면 단계가 FAILED로 설정되고 모든 브로커와 부키가 자동으로 ZooKeeper 사용으로 되돌아가요. 수동 롤백은 필요 없어요.
전제 조건 (Prerequisites)
마이그레이션을 시작하기 전에:
- Oxia 클러스터를 설정해요. 모든 Pulsar 브로커와 부키에서 접근 가능하고, 대상 네임스페이스가 Oxia 클러스터에 존재하는지 확인해요. 배포 지침은 Oxia 문서를 참고해요.
- Pulsar 5.0 이상으로 업그레이드해요. 메타데이터 스토어에 연결하는 모든 컴포넌트(브로커, 부키, 자동-복구 데몬)는 마이그레이션을 지원하는 버전으로 실행해야 해요. 추가 브로커 구성은 필요 없어요 — 마이그레이션 래퍼(DualMetadataStore)는 ZooKeeper 기반 메타데이터 스토어에 대해 자동으로 활성화돼요.
- 부키를 Pulsar 메타데이터 드라이버로 실행해요. 부키는
conf/bookkeeper.conf에서metadata-store:스킴으로 구성된 경우에만 마이그레이션에 참여해요.
metadataServiceUri=metadata-store:zk:my-zk-1:2181/ledgers
일반 BookKeeper ZooKeeper 드라이버(zk+hierarchical://...)를 사용하는 부키는 참여하지 않으며, 마이그레이션을 시작하기 전에(롤링 재시작과 함께) 재구성해야 해요.
- Oxia 엔드포인트를 확인해요. 대상 URL은
oxia://스킴을 사용해야 해요.
oxia://<host>:<port>/<namespace>
예를 들어: oxia://oxia-1.example.com:6648/broker
tip
마이그레이션 관리 명령은 슈퍼유저 권한이 필요해요.
Step 1: 현재 상태 확인 (Check the current status)
진행 중인 마이그레이션이 없는지 확인해요.
bin/pulsar-admin metadata-migration status
예상 출력:
{
"phase" : "NOT_STARTED"
}
Step 2: 마이그레이션 시작 (Start the migration)
대상 Oxia URL을 지정해 마이그레이션을 트리거해요.
bin/pulsar-admin metadata-migration start --target oxia://oxia-1.example.com:6648/broker
이 명령은 마이그레이션을 시작한 직후 반환돼요. 실제 마이그레이션은 요청을 받은 브로커에서 비동기적으로 실행돼요.
Step 3: 진행 상황 모니터링 (Monitor progress)
COMPLETED를 보고할 때까지 마이그레이션 상태를 폴링해요.
bin/pulsar-admin metadata-migration status
단계가 PREPARATION, COPYING, 마지막으로 COMPLETED로 진행되는 것을 볼 수 있어요.
{
"phase" : "COMPLETED",
"targetUrl" : "oxia://oxia-1.example.com:6648/broker"
}
상태가 FAILED로 보이면 브로커 로그에서 오류 상세를 확인해요. 클러스터가 자동으로 ZooKeeper로 되돌아가므로 조사하고 재시도할 수 있어요.
Step 4: 브로커 구성 업데이트 (Update broker configuration)
마이그레이션이 완료된 후 브로커 구성이 Oxia를 직접 사용하도록 업데이트해요. conf/broker.conf에서:
metadataStoreUrl=oxia://oxia-1.example.com:6648/broker
configurationMetadataStoreUrl=oxia://oxia-1.example.com:6648/broker
그런 다음 모든 브로커의 롤링 재시작을 수행해요. 재시작 후 브로커는 마이그레이션 래퍼 없이 Oxia에 직접 연결해요.
Step 5: BookKeeper 구성 업데이트 (Update BookKeeper configuration)
BookKeeper 구성이 Oxia를 사용하도록 업데이트해요. conf/bookkeeper.conf에서:
metadataServiceUri=metadata-store:oxia://oxia-1.example.com:6648/bookkeeper
그런 다음 모든 부키의 롤링 재시작을 수행해요.
Step 6: ZooKeeper 해체 (Decommission ZooKeeper)
모든 브로커와 부키가 새 구성으로 재시작되고 정상 동작이 확인된 후에만 ZooKeeper 클러스터를 안전하게 해체할 수 있어요.
caution
모든 브로커와 부키가 새 구성으로 재시작될 때까지 ZooKeeper는 사용 가능한 상태로 유지되어야 해요. 여전히 이전 구성을 가진 컴포넌트는 시작 시 ZooKeeper에 연결해 마이그레이션 상태를 발견한 후 Oxia로 전환해요.
오류 처리 (Handling failures)
PREPARATION 또는 COPYING 중 마이그레이션 실패
마이그레이션 실패 시 단계가 자동으로 FAILED로 설정돼요. 모든 브로커와 부키가 즉시 ZooKeeper로 되돌아가요. 마이그레이션 중 쓰기가 중지되었고 ZooKeeper가 수정되지 않았으므로 데이터 손실은 없어요.
재시도하려면 그냥 start 명령을 다시 실행해요.
bin/pulsar-admin metadata-migration start --target oxia://oxia-1.example.com:6648/broker
마이그레이션 완료 후 브로커 재시작
마이그레이션 완료 후(구성이 업데이트되기 전에) 재시작되는 브로커나 부키는 시작 시 ZooKeeper에서 마이그레이션 상태를 읽고 모든 메타데이터 연산에 대해 Oxia에 연결해요.
마이그레이션 진행 중에 브로커나 부키를 재시작하지 않도록 해요 — 쓰기-중지 창은 보통 30초 미만이에요. 그 창 동안 컴포넌트가 재시작된다면, 마이그레이션이 COMPLETED를 보고한 후 다시 재시작해 새 메타데이터 스토어를 선택하도록 해요.
REST API
마이그레이션은 REST API를 통해서도 가능해요.
마이그레이션 시작:
curl -X POST "http://broker:8080/admin/v2/metadata/migration/start?target=oxia://oxia-1.example.com:6648/broker"
상태 확인:
curl "http://broker:8080/admin/v2/metadata/migration/status"
더 알아보기 (Learn more)
- Oxia 배포 지침은 Oxia 문서를 참고해요.
- 메타데이터 스토어 구성 방법은 Configure metadata store 문서를 참고해요.
- PIP-454에서 마이그레이션 프레임워크 설계를 확인할 수 있어요.