버전 표기와 레거시

버전 표기 읽는 법

Apache 아카이브의 4.3.1 디렉터리에는 배포 파일이 하나만 올라와 있습니다. kafka_2.13-4.3.1.tgz입니다. 이 한 줄에 버전 번호가 두 개 들어 있어서 오해가 끊이지 않습니다.

kafka_2.13-4.3.1.tgz
      ────  ─────
      Scala  Kafka
      2.13   4.3.1

무엇을 내려받아야 하는가

버전별 주요 변경 타임라인 (2.0 → 4.3)

Kafka 2.x / 3.x를 아직 쓰는 조직을 위한 안내

ZooKeeper 앙상블 구성

ZooKeeper는 과반수 기반 합의를 쓰므로 앙상블 크기를 홀수로 두는 것이 관례였습니다. 3대면 1대 장애, 5대면 2대 장애를 견딥니다. 운영 관점의 핵심은 Kafka 브로커와 ZooKeeper 노드를 같은 머신에 두지 않는 것과 ZooKeeper의 트랜잭션 로그를 별도 디스크에 두는 것이었습니다 — ZooKeeper는 쓰기마다 fsync를 하므로 디스크 지연에 매우 민감했습니다.

이 "두 개의 분산 시스템을 함께 운영해야 한다"는 부담이 KIP-500(ZooKeeper 제거)의 출발점이었습니다. Kafka를 운영하려면 Kafka와 ZooKeeper 양쪽의 튜닝·모니터링·보안·업그레이드를 모두 알아야 했습니다.

ZooKeeper에 저장되던 것들

--zookeeper CLI의 시대

2.x 자료를 보면 아래와 같은 명령이 흔히 나옵니다. 이 명령들은 현행 Kafka에서 동작하지 않습니다. 관리 도구의 --zookeeper 플래그는 KIP-555로 deprecated되고 Kafka 3.0에서 제거되었습니다(KIP-604).

bin/kafka-topics.sh --zookeeper localhost:2181 \
  --create --topic orders --partitions 6 --replication-factor 3

bin/kafka-topics.sh --zookeeper localhost:2181 --list

bin/kafka-configs.sh --zookeeper localhost:2181 \
  --entity-type topics --entity-name orders --describe

bin/kafka-acls.sh \
  --authorizer-properties zookeeper.connect=localhost:2181 --list

bin/kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic orders --partitions 6 --replication-factor 3

bin/kafka-topics.sh --bootstrap-server localhost:9092 --list

bin/kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders --describe

bin/kafka-acls.sh --bootstrap-server localhost:9092 --list

4.0에서는 남아 있던 ZooKeeper 흔적까지 정리되었습니다 — kafka-acls의 --authorizer·--authorizer-properties·--zk-tls-config-file 옵션이 제거되고 --bootstrap-server 또는 --bootstrap-controller를 쓰게 되었으며, kafka.admin.ZkSecurityMigrator 도구도 제거되었습니다. 또한 KRaft 모드용 설정 파일이 별도의 config/kraft 디렉터리에 있던 관행도 끝나 모든 설정 파일이 config 디렉터리로 통합되었습니다.

ZooKeeper 시대의 흔한 장애

어떤 장애가 잦았는지는 Kafka가 그 시절 어떤 메트릭을 노출했는지를 보면 드러납니다. 아래 메트릭들은 모두 4.x에서 제거되었지만, 그 이름이 곧 당시의 걱정거리 목록입니다.

업그레이드 경로 — 2.x → 3.9 → 4.x

왜 3.9를 경유해야 하는가

4.3 업그레이드 문서의 서술을 정리하면 이유가 세 겹입니다.

1. 4.x는 KRaft만 지원합니다. 문서는 "ZooKeeper 모드 클러스터는 4.3.x로 업그레이드하기 전에 반드시 KRaft로 마이그레이션되어야 한다"고 명시합니다. 그리고 ZooKeeper → KRaft 마이그레이션 기능이 있는 마지막 버전이 3.9입니다. 4.0 이후에는 마이그레이션 경로 자체가 없습니다.
2. 4.x 브로커 업그레이드는 소프트웨어·메타데이터 버전이 최소 3.3.x여야 합니다. 문서는 이를 "KRaft 모드가 production ready로 판정된 첫 버전"이라는 이유로 설명합니다. 3.3.x보다 오래된 KRaft 클러스터에는 3.9.x로 먼저 올리는 것을 권장합니다.
3. 클라이언트는 4.0 이전에 2.1 이상이어야 합니다. 4.0에서 오래된 프로토콜 API 버전이 제거되었기 때문입니다(KIP-896). Connect와 Kafka Streams도 내부적으로 클라이언트를 쓰므로 함께 해당됩니다.

단계별 절차

# 1. 브로커를 하나씩: 정지 → 코드 교체 → 재시작
#    전부 끝나면 클러스터 동작과 성능이 기대와 맞는지 검증합니다.

# 2. 검증이 끝나면 업그레이드를 확정합니다 (되돌릴 수 없습니다)
bin/kafka-features.sh --bootstrap-server localhost:9092 \
  upgrade --release-version 4.3

# 3. 현재 feature 레벨 확인
bin/kafka-features.sh --bootstrap-server localhost:9092 describe

# (참고) 4.x 에서는 inter.broker.protocol.version 이 아니라
#        metadata.version 을 feature 로 관리합니다.

레거시 → 현행 대응표

옛 자료나 사내 위키에서 아래 왼쪽 항목을 만나면 오른쪽으로 옮겨 읽으세요.

버전 병기 항목 — 트랙별 값

본문에서 .note--version으로 병기하는 항목들을 한 표에 모았습니다. 기억에 의존해 3.x 기준으로 답하면 틀리는 항목들입니다.

확인 문제

버전 표기와 타임라인을 확인하는 문항입니다. 실무 이관에서 자주 걸리는 지점이자, 시험에서도 버전 차이를 직접 묻는 문항이 나옵니다.

이어서 볼 곳

• 3장 · KRaft와 클러스터 메타데이터 현행 아키텍처. 컨트롤러 쿼럼, 노드 롤, 부트스트랩 절차. CCAAK 중심
• 11장 · 운영 기초 보안·모니터링·성능 튜닝, 파티션 재할당, Share Groups. CCAAK 중심
• CLI 치트시트 목적별 명령 표. 모든 명령이 --bootstrap-server 기준입니다. 빠른참조
• 설정 치트시트 6개 영역 설정 표와 처리량·지연·내구성 프리셋 3종. 빠른참조
• 예제 1 · 로컬 KRaft 클러스터 ZooKeeper 없는 3노드 클러스터를 직접 띄워 봅니다. 실무 예제
• 1장 · Kafka 개요 4.x가 이전과 다른 점 요약과 조용히 바뀐 기본값들. 기본개념

공식 문서 출처

타임라인의 각 항목은 아래에서 확인했습니다. 4.x 항목은 Apache Kafka 4.3 업그레이드 문서에 직접 기재된 내용이고, 3.x 이하는 공식 릴리스 발표와 KIP으로 교차 확인했습니다.

• Upgrading Apache Kafka — 4.0 · 4.1 · 4.2 · 4.3의 notable changes 전문, 4.3 업그레이드 요건(KRaft 필수·최소 3.3.x·3.9.x 경유 권장·ZooKeeper 사전 마이그레이션), 메타데이터 다운그레이드 가능 여부, 클라이언트 2.1+ 요건, linger.ms 0→5, Scala 2.12 제거, Java 요구사항 변경, 4.1.0 Streams 메모리 누수 권고
• Differences Between KRaft mode and ZooKeeper mode — 제거된 ZooKeeper 관련 설정·메트릭 전체 목록, inter.broker.protocol.version → metadata.version, advertised.listeners의 동적 변경 불가, 동적 로그 레벨 변경 명령, KRaft의 KafkaPrincipalSerde 요구
• Downloads — kafka_2.13-4.3.1.tgz 단일 바이너리 배포, 소스 배포판 이름
• Java Version — Java 17·21·25 완전 지원, Java 11은 일부 모듈
• Security Overview — SASL 메커니즘별 도입 버전 (OAUTHBEARER는 2.0)
• Connect Exactly-once support — sink 0.11.0 / source 3.3.0
• Connect Administration — 2.3.0부터 증분 협력적 리밸런스가 기본, connect.protocol=eager로 복귀
• Connect Plugin Discovery — 3.6부터 plugin.discovery 설정 가능, 기본 hybrid_warn
• Streams Processing Guarantees — 2.6의 exactly-once v2(KIP-447), 3.0에서 1세대 deprecated
• Release Announcements — 각 버전의 발표 시기
• Apache Kafka 4.0.0 Release Announcement — ZooKeeper 제거, KIP-848 GA, Queues 초기 작업
• Apache Kafka 3.9.0 Release Announcement — ZooKeeper 모드를 지원하는 마지막 릴리스, 동적 KRaft 쿼럼(KIP-853), Tiered Storage production-ready
• Apache Kafka 3.6.0 Release Announcement — Tiered Storage early access (KIP-405)
• KIP-500 — Replace ZooKeeper with a Self-Managed Metadata Quorum — 2.8 early access의 근거와 ZooKeeper 제거 동기
• KIP-833 — Mark KRaft as Production Ready — 3.3에서 KRaft production-ready, 3.5를 bridge release로 지정
• KIP-679 — Producer will enable the strongest delivery guarantee by default — 3.0의 acks=all·enable.idempotence=true
• KIP-726 — Change the default assignor — partition.assignment.strategy 기본값 변경
• KIP-429 — Kafka Consumer Incremental Rebalance Protocol — 2.4의 CooperativeStickyAssignor
• KIP-604 — Remove ZooKeeper Flags from the Administrative Tools — --zookeeper가 3.0에서 제거
• KIP-932 — Queues for Kafka — Share Groups 설계
• KIP-405 — Kafka Tiered Storage
• Apache Kafka Release Archive — 각 버전의 배포 파일 목록과 파일명 규칙 확인