업그레이드 원칙 — 롤링 업그레이드와 메타데이터 버전
Apache Kafka Official Documentation — Getting Started (v4.3) — Apache Software Foundation Section 5: Upgrading — 'Upgrading to X.Y.Z' 반복 패턴 및 'Note' 전제조건 (pp.16-33)
이 모듈을 다 읽으면
- 브로커 롤링 업그레이드의 3단계 절차를 설명할 수 있다.
- MetadataVersion의 '메타데이터 변경 여부' 플래그가 다운그레이드 가능 여부를 어떻게 결정하는지 설명할 수 있다.
- KRaft 모드로의 전환이 4.x 업그레이드의 전제조건이 되는 이유를 설명할 수 있다.
Kafka 4.x의 모든 마이너/패치 버전 업그레이드 절은 '브로커를 하나씩 순차 재시작 → kafka-features.sh로 확정(finalize) → 메타데이터 변경 여부에 따라 다운그레이드 가능 여부 결정'이라는 동일한 3단계 패턴을 반복한다. 또한 4.x 브로커 업그레이드는 클러스터가 이미 KRaft 모드(3.3.x 이상)로 동작 중이어야 한다는 전제조건을 공통으로 갖는다.
롤링 업그레이드 3단계
4.0 이후 모든 마이너/패치 버전의 'Upgrading to X.Y.Z' 절은 동일한 3단계 절차를 반복한다.
1) 브로커를 한 번에 하나씩 종료 → 바이너리/설정 교체 → 재시작한다. 모든 브로커를 순차적으로 교체하면서 각 단계마다 클러스터의 동작과 성능이 기대치를 충족하는지 확인한다. 2) 전체 브로커 교체가 끝나고 동작이 검증되면, `bin/kafka-features.sh --bootstrap-server <host:port> upgrade --release-version <X.Y>` 명령으로 업그레이드를 '확정(finalize)'한다. 이 시점 전까지는 새 기능/프로토콜이 클러스터 전체에 활성화되지 않는다. 3) 확정 이후 메타데이터 다운그레이드가 가능한지는 버전 간 MetadataVersion에 달려 있다.
핵심 포인트
- 브로커는 한 번에 하나씩 순차적으로 재시작하는 롤링 방식으로 업그레이드한다.
- 새 기능/프로토콜은 kafka-features.sh upgrade --release-version 으로 클러스터 전체에 확정(finalize)해야 실제로 활성화된다.
- 확정 전까지는 검증 단계이고, 확정 후 다운그레이드 가능 여부는 메타데이터 변경 여부에 달려 있다.
MetadataVersion과 다운그레이드 가능 여부
매 릴리스마다 MetadataVersion에는 '이 버전에 메타데이터 스키마 변경이 있는가'를 나타내는 boolean 플래그가 붙는다. 예를 들어 4.3용 IBP_4_3_IV0(30, "4.3", "IV0", true)는 메타데이터 변경이 있음(true)을 뜻하고, 4.2용 IBP_4_2_IV1(29, "4.2", "IV1", false)는 변경이 없음(false)을 뜻한다.
현재 버전과 목표 버전 사이의 모든 MetadataVersion에 메타데이터 변경이 하나도 없어야만 다운그레이드가 가능하다. 즉 4.3.0처럼 메타데이터 변경이 있는 버전으로 확정한 뒤에는 4.2 이하로 되돌릴 수 없지만, 4.2.0처럼 메타데이터 변경이 없는 버전이라면 다운그레이드가 허용된다. 업그레이드를 확정하기 전에 반드시 변경사항을 확인해야 하는 이유다.
핵심 포인트
- MetadataVersion마다 메타데이터 스키마 변경 여부(boolean)가 기록되어 있다.
- 현재~목표 버전 사이에 메타데이터 변경이 하나라도 있으면 다운그레이드가 불가능하다.
- 예: 4.3.0(IBP_4_3_IV0, true)은 다운그레이드 불가, 4.2.0(IBP_4_2_IV1, false)은 다운그레이드 가능.
KRaft 마이그레이션이 업그레이드의 전제조건
Kafka 4.0부터는 ZooKeeper 모드가 완전히 제거되어 KRaft 모드만 지원한다. 따라서 4.x로 브로커를 업그레이드하려면 클러스터가 이미 KRaft 모드로 동작 중이어야 하고, 소프트웨어·메타데이터 버전이 최소 3.3.x(=KRaft가 프로덕션 레디로 선언된 첫 버전) 이상이어야 한다. 3.3.x보다 오래된 KRaft 클러스터는 먼저 3.9.x로 올린 뒤 4.x로 가는 것이 권장되며, 여전히 ZooKeeper 모드로 운영 중인 클러스터는 4.x로 직접 갈 수 없고 반드시 'ZooKeeper to KRaft Migration' 절차를 먼저 거쳐야 한다.
또한 4.0.0 릴리스 노트는 오래된 프로토콜 API 버전이 제거되었다는 점도 명시한다 — 브로커를 4.0으로 올리기 전 Java 클라이언트(Connect·Kafka Streams 포함)가 2.1 이상인지, 반대로 클라이언트를 4.0으로 올리기 전 브로커가 2.1 이상인지 상호 확인해야 한다.
핵심 포인트
- Kafka 4.0부터 ZooKeeper 모드가 완전히 제거되어 KRaft 모드만 지원한다.
- 4.x 브로커 업그레이드의 전제조건: 이미 KRaft 모드 + 소프트웨어/메타데이터 버전 3.3.x 이상.
- ZooKeeper 모드 클러스터는 먼저 KRaft로 마이그레이션해야 4.x로 업그레이드할 수 있다.
- 브로커와 Java 클라이언트(Connect, Streams 포함) 모두 2.1 이상이어야 상호 업그레이드가 안전하다(오래된 프로토콜 API 제거 때문).