업그레이드

업그레이드 (Upgrading)

Kafka를 새 버전으로 올릴 때 알아야 할 절차와 버전별 주요 변경 사항을 정리한 문서예요. 특히 4.x부터 ZooKeeper 모드가 사라지고 KRaft 모드가 기본이 되면서, 업그레이드 절차와 메타데이터 버전 관리가 중요해졌어요.

출처: 문서

본문

4.3.1로 업그레이드하기

4.3.1의 주요 변경 사항

  • KIP-1035에서 도입된 오프셋 컬럼 패밀리와 관련해 RocksDB 컬럼 패밀리 핸들과 ColumnFamilyOptions가 해제되지 않아 발생한, Kafka Streams 네이티브 메모리 누수의 치명적 버그 수정을 포함해요 (KAFKA-20616, KAFKA-20688).
  • 재시작 시 OffsetOutOfRangeException을 일으킬 수 있는 Kafka Streams stale-offset 문제 수정을 포함해요 (KAFKA-20663).
  • 캐시된 리더가 클러스터를 떠났을 때 Admin 파티션 리더 API가 멈추는 문제 수정을 포함해요 (KAFKA-20673).
  • 파티션 리더십 변경 후에 가짜 그룹 코디네이터 오류가 기록되던 문제 수정을 포함해요 (KAFKA-20634, KAFKA-20635).

4.3.0로 업그레이드하기

3.3.x부터 4.2.0까지 어느 버전에서나 4.3.0으로 서버 업그레이드하기

참고: Apache Kafka 4.3은 KRaft 모드만 지원해요 — ZooKeeper 모드는 제거됐어요. 따라서 4.3.0(및 그 이상)으로의 브로커 업그레이드는 KRaft 모드를 요구하며, 소프트웨어·메타데이터 버전이 최소 3.3.x(KRaft 모드가 프로덕션 준비로 간주된 첫 버전)여야 해요. 3.3.x보다 오래된 KRaft 모드 클러스터라면 4.3.x로 올리기 전에 3.9.x로 업그레이드하는 걸 권장해요. ZooKeeper 모드 클러스터는 4.3.x로 업그레이드하기 전에 먼저 KRaft 모드로 마이그레이션해야 해요.

롤링 업그레이드 절차:

  • 브로커를 한 번에 하나씩 업그레이드해요: 브로커를 종료하고 코드를 갱신한 뒤 재시작해요. 이렇게 하면 브로커들이 최신 버전으로 실행되고, 클러스터의 동작·성능이 기대에 부합하는지 확인할 수 있어요.
  • 클러스터의 동작·성능이 검증되면 다음 명령으로 업그레이드를 마무리해요: bin/kafka-features.sh --bootstrap-server localhost:9092 upgrade --release-version 4.3
  • 이 버전은 메타데이터 변경이 있으므로 클러스터 메타데이터 다운그레이드를 지원하지 않아요. 각 MetadataVersion은 메타데이터 변경 여부를 나타내는 boolean 파라미터를 가져요(즉 IBP_4_3_IV0(30, "4.3", "IV0", true)는 이 버전에 메타데이터 변경이 있다는 뜻). 현재·목표 버전이 주어졌을 때, 그 사이 버전들에 메타데이터 변경이 없을 때만 다운그레이드가 가능해요.

4.3.0의 주요 변경 사항

  • kafka-configs.sh --alter --delete-config는 더 이상 대상 리소스에 지정된 구성 키가 존재할 것을 요구하지 않아요. 이전에는 존재하지 않는 구성 키 삭제를 시도하면 InvalidConfigurationException이 났어요. 이제 키가 없으면 삭제가 no-op이며, --bootstrap-controller로 오프라인 브로커의 구성을 관리할 수 있게 됐어요. 자세한 내용은 KAFKA-20506 참고.
  • 동적 쿼럼 컨트롤러의 구성을 동적으로 변경하는 것을 지원해요. 이전에는 브로커와 정적 쿼럼 컨트롤러만 지원했어요. 자세한 내용은 KAFKA-18928 참고.
  • 새 구성 2개가 도입됐어요: group.coordinator.cached.buffer.max.bytes와 share.coordinator.cached.buffer.max.bytes. 각각의 코디네이터가 재사용을 위해 보존하는 최대 버퍼 크기를 설정할 수 있게 해줘요. 자세한 내용은 KIP-1196 참고.
  • 새 구성 remote.log.metadata.topic.min.isr이 기본값 2로 도입됐어요. 필요하면 kafka-configs.sh로 기존 __remote_log_metadata 토픽의 min.insync.replicas를 보정할 수 있어요. 자세한 내용은 KIP-1235 참고.
  • 새 구성 접두사 remote.log.metadata.admin.이 도입됐어요. TopicBasedRemoteLogMetadataManager가 사용하는 admin 클라이언트를 독립적으로 구성할 수 있게 해줘요. 자세한 내용은 KIP-1208 참고.
  • kafka-streams-scala 라이브러리는 Kafka 4.3부터 비권장이며 Kafka 5.0에서 제거될 예정이에요. 자세한 내용은 마이그레이션 가이드 참고.
  • Kafka Streams는 이제 새 dsl.store.format 구성으로 DSL 연산자용 옵트인 헤더 인식 상태 저장소를 지원해요. 이 구성은 DEFAULT 또는 HEADERS를 받아요. Store-supplier API는 DslStoreFormat enum(값: PLAIN, TIMESTAMPED, HEADERS)을 사용하며, DslStoreFormat.DEFAULT는 존재하지 않아요. 이는 KIP-1271에서 도입된 헤더 인식 상태 저장소 구현을 기반으로 해요. 자세한 내용과 현재 DSL 결과-헤더 제한은 KIP-1285 참고.
  • 로그 디렉토리 코든(cordoning) 지원: 자세한 내용은 KIP-1066 참고.
  • group.coordinator.rebalance.protocols 구성은 비권장이며 Kafka 5.0에서 제거될 예정이에요. Kafka 5.0에서는 모든 프로토콜이 항상 활성화되고 kafka-features.sh를 통한 기능 버전(group.version, streams.version, share.version)으로만 제어돼요. 자세한 내용은 KIP-1237 참고.
  • 새 그룹 구성이 도입됐어요: share.delivery.count.limit, share.partition.max.record.locks, share.renew.acknowledge.enable, 그리고 최소·최대 값을 지정하는 동등한 브로커 구성도요. 또한 그룹 구성의 검증이 개선됐어요. 자세한 내용은 KIP-1240 참고.
  • 정규식 구독 갱신에 사용되는 그룹 코디네이터의 스레드 풀 크기를 제어하는 새 구성 group.coordinator.background.threads가 추가됐어요. 이전에는 스레드 풀이 단일 스레드뿐이었어요. 이제 기본적으로 두 스레드이며 크기를 설정할 수 있어요. 자세한 내용은 KIP-1263 참고.
  • 새 구성 group.consumer.assignment.interval.ms, group.share.assignment.interval.ms, group.streams.assignment.interval.ms가 추가돼 consumer·share·streams 그룹의 할당 업데이트 간격을 설정하고, 최소·최대 값과 그룹 구성을 위한 브로커 구성도 함께 추가됐어요. 기본값은 1초 간격이고, 이전에는 실질적으로 0이었어요. 자세한 내용은 KIP-1263 참고.
  • 새 동적 브로커 구성 follower.fetch.last.tiered.offset.enable(기본값 false)이 추가됐어요. 티어드 스토리지가 있는 클러스터에서 활성화하면, 로컬 데이터가 없는 새로 추가된 팔로워 복제본이 리더의 가장 이른 대기 업로드 오프셋으로 바로 건너뛰어 원격 저장소에 이미 저장된 데이터를 다시 가져오지 않아요. 큰 티어드 스토리지 토픽의 부트스트랩 시간을 크게 줄여줘요. 자세한 내용은 KIP-1023 참고.
  • ListOffsets API가 버전 11로 확장되어 EARLIEST_PENDING_UPLOAD_TIMESTAMP(-6) 타임스탬프 유형을 지원해요. 클라이언트가 아직 티어드 스토리지에 업로드되지 않은 리더의 가장 이른 오프셋을 조회할 수 있게 해줘요. 자세한 내용은 KIP-1023 참고.

4.2.1로 업그레이드하기

4.2.1의 주요 변경 사항

  • KIP-932 Share Group 경로의 치명적 교착(deadlock) 수정을 포함해요 (KAFKA-20505).
  • 트랜잭션 프로듀서를 사용하는 클러스터에서 UnsupportedVersionException을 일으킬 수 있는 롤링 업그레이드 문제 수정을 포함해요 (KAFKA-20322).
  • Streams Rebalance Protocol의 오프라인 마이그레이션 코드의 치명적 브로커 측 버그 수정을 포함해요 (KAFKA-20254). 4.2.1부터 classic에서 streams 그룹으로의 마이그레이션이 안전해요.

4.2.0로 업그레이드하기

3.3.x부터 4.1.x까지 어느 버전에서나 4.2.0으로 서버 업그레이드하기

참고: Apache Kafka 4.2은 KRaft 모드만 지원해요 — ZooKeeper 모드는 제거됐어요. 브로커 업그레이드는 KRaft 모드를 요구하며 소프트웨어·메타데이터 버전이 최소 3.3.x여야 해요. 3.3.x보다 오래된 KRaft 클러스터는 3.9.x로 먼저 업그레이드하는 걸 권장해요. ZooKeeper 모드 클러스터는 먼저 KRaft 모드로 마이그레이션해야 해요.

롤링 업그레이드 절차는 4.3.0과 동일해요(브로커별로 종료→갱신→재시작, 검증 후 bin/kafka-features.sh --bootstrap-server localhost:9092 upgrade --release-version 4.2). 단, 이 버전은 메타데이터 변경이 없으므로 클러스터 메타데이터 다운그레이드를 지원해요 (IBP_4_2_IV1(29, "4.2", "IV1", false)는 메타데이터 변경이 없다는 뜻).

  • 3개 미만의 브로커로 이뤄진 클러스터에서 share group을 쓰려면, share group 사용 전에 브로커 구성 share.coordinator.state.topic.replication.factor와 share.coordinator.state.topic.min.isr을 1로 설정해야 해요. 이는 share group이 처음 사용할 때 자동 생성되는 __share_group_state라는 새 내부 토픽을 쓰기 때문이에요. 다른 내부 토픽과 마찬가지로 기본 구성은 복제본 3개를 사용하고 최소 3개 브로커를 요구해요.

4.2.0의 주요 변경 사항

  • kafka-console-producer의 --max-partition-memory-bytes 옵션은 비권장이며 Kafka 5.0에서 제거될 예정이에요. --batch-size를 사용해 주세요.
  • Queues for Kafka (KIP-932) 가 Apache Kafka 4.2에서 프로덕션 준비가 됐어요. 이 기능은 consumer group의 대안으로 share group이라는 새 종류의 그룹을 도입해요. share group의 컨슈머는 각 파티션을 한 컨슈머에게만 할당하지 않고 토픽의 레코드를 협력적으로 소비해요. share group은 레코드별 승인(acknowledgement)과 전달 시도 횟수 계산도 도입해요. 레코드를 순서 스트림의 일부가 아니라 한 번에 하나씩 처리하는 경우에 share group을 사용해요.
  • Streams Rebalance Protocol (KIP-1071) 이 핵심 기능 세트에 대해 프로덕션 준비가 됐어요. Kafka Streams 애플리케이션을 위해 설계된 이 브로커 주도 리밸런싱 시스템은 더 빠르고 안정적인 리밸런스와 더 나은 관찰성을 제공해요. 지원 기능·사용법·마이그레이션은 Streams 개발자 가이드를 참고해요. 오프라인 마이그레이션 코드의 치명적 브로커 측 버그(KAFKA-20254) 때문에 4.2.0에서는 classic에서 streams 그룹으로의 마이그레이션을 권장하지 않아요. 새로 만든 streams 그룹은 영향이 없어요. 수정은 4.2.1에서 제공돼요.
  • org.apache.kafka.common.header.internals.RecordHeader 클래스가 읽기 스레드 안전하게 갱신됐어요 (KIP-1205). 즉 ConsumerRecord의 headers 안의 각 Header 객체를 이제 여러 스레드에서 동시에 안전하게 읽을 수 있어요.
  • org.apache.kafka.disallowed.login.modules 구성이 비권장됐어요. org.apache.kafka.allowed.login.modules를 사용해 주세요.
  • remote.log.manager.thread.pool.size 구성이 비권장됐어요. remote.log.manager.follower.thread.pool.size를 사용해 주세요.
  • KafkaPrincipalBuilder가 이제 KafkaPrincipalSerde를 확장해요. 커스텀 KafkaPrincipalBuilder에 KafkaPrincipalSerde 구현을 강제해요 (KIP-1157).
  • org.apache.kafka.streams.KafkaStreams#removeStreamThread의 동작이 바뀌었어요. 이제 removeStreamThread가 끝나도 컨슈머가 즉시 제거되지 않고, StreamThread가 run 함수를 완료한 후 그룹에서 쫓겨나요.
  • kafka_mx4jenable 시스템 속성으로 활성화되는 MX4J 라이브러리 지원이 비권장됐고 Kafka 5.0에서 제거될 예정이에요.
  • ProducerConfig의 PARTITIONER_ADPATIVE_PARTITIONING_ENABLE_CONFIG가 비권장되어 Kafka 5.0에서 제거될 예정이에요. PARTITIONER_ADAPTIVE_PARTITIONING_ENABLE_CONFIG를 사용해 주세요.
  • ConsumerPerformance 커맨드라인 도구에 --include 옵션이 추가됐어요. --topic의 대안으로, 소비할 토픽 목록을 지정하는 정규식을 전달할 수 있어 여러 토픽이나 동적으로 일치하는 토픽 집합에 걸친 컨슈머 성능 테스트에 유용해요.
  • 커맨드라인 도구의 인자 이름 일관성이 개선됐어요 (KIP-1147). 비권장 옵션은 Kafka 5.0에서 제거될 예정이에요.
    • kafka-producer-perf-test.sh: --bootstrap-server, --reporting-interval 옵션 추가.
    • kafka-console-consumer.sh/kafka-console-share-consumer.sh: 포매터 속성을 지정하는 --property가 --formatter-property로 비권장.
    • kafka-console-producer.sh: message reader에 key=value 속성을 지정하는 --property가 --reader-property로 비권장.
    • kafka-consumer-perf-test.sh/kafka-share-consumer-perf-test.sh: --messages가 --num-records로 비권장(성능 테스트 도구 통일).
    • 모든 커맨드라인 도구의 --command-property, --command-config 옵션 통일(kafka-console-consumer/producer/share-consumer.sh, kafka-producer-perf-test.sh, kafka-cluster.sh, kafka-leader-election.sh 등).
  • num.replica.fetchers 구성의 하한이 1이 됐어요.
  • LIST 타입 구성의 검증 규칙과 기본값이 개선됐어요 (KIP-1161). LIST 타입 구성은 더 엄격한 검증을 강제해요: 대부분의 LIST 구성에서 null 값이 더 이상 허용되지 않고, 중복 항목도 대부분 허용되지 않으며(중복이 명시적으로 지원되는 경우 제외, 허용되지 않으면 경고 로그와 함께 무시), 특정 구성의 경우 빈 목록이 시스템 오작동을 일으켜 더 이상 허용되지 않아요. 여러 구성이 쉼표로 구분된 값으로 쓰임을 반영해 STRING→LIST로 재분류됐고, 기본값도 조정됐어요. cleanup.policy는 빈 값을 지원해 무한 보존을 뜻해요. 이는 retention.ms=-1과 retention.bytes=-1을 설정한 것과 동등해요. cleanup.policy가 비어 있고 remote.storage.enable이 true면 로컬 로그 세그먼트는 log.local.retention.bytes와 log.local.retention.ms 값에 따라 정리되고, false면 로컬 세그먼트가 자동 삭제되지 않지만 deleteRecords API 호출로 명시적으로 삭제할 수 있어요(로그 시작 오프셋이 앞당겨지고 해당 로그 세그먼트가 제거돼요).
  • controller.quorum.auto.join.enable이 QuorumConfig에 추가되어 KRaft 컨트롤러가 클러스터의 voter 집합에 자동으로 조인하게 하고, 기본값은 false예요. true로 설정하면 제거된 컨트롤러가 자동으로 다시 조인하는 걸 피하기 위해 voter 집합에서 제거하기 전에 컨트롤러를 종료해야 해요 (KIP-853).
  • AppInfo 지표의 다음 지표 이름이 비권장되며 Kafka 5.0에서 제거될 예정이에요: [name=start-time-ms, group=app-info, ...], [name=commit-id, group=app-info, ...], [name=version, group=app-info, ...]. 추가로 이 지표들의 태그에 client-id가 추가돼요. 자세한 내용은 KIP-1120 참고.
  • 지표 org.apache.kafka.server:type=AssignmentsManager.QueuedReplicaToDirAssignments, org.apache.kafka.storage.internals.log:type=RemoteStorageThreadPool.RemoteLogReaderTaskQueueSize, ...RemoteLogReaderAvgIdlePercent가 비권장되고 Kafka 5.0에서 제거될 예정이에요. 대체 지표(같은 정보를 보고): kafka.server:type=AssignmentsManager.QueuedReplicaToDirAssignments, kafka.log.remote:type=RemoteStorageThreadPool.RemoteLogReaderTaskQueueSize, ...RemoteLogReaderAvgIdlePercent. 자세한 내용은 KIP-1100 참고.
  • ControllerEventManager와 MetadataLoader 그룹에 새 지표 AvgIdleRatio가 추가됐어요. 각 이벤트 큐 스레드의 평균 유휴 비율을 측정하며, 값은 0.0(항상 바쁨)~1.0(항상 유휴) 범위예요.
  • org.apache.kafka.streams.KafkaStreams$CloseOptions와 관련 메서드(KafkaStreams#close(CloseOptions) 등)가 비권장됐어요. 대신 org.apache.kafka.streams.CloseOptions와 KafkaStreams#close(CloseOptions)를 사용해요 (KIP-1153).
  • ConnectorClientConfigOverridePolicy의 새 구현 AllowlistConnectorClientConfigOverridePolicy가 추가됐어요. connector.client.config.override.allowlist로 커넥터가 재정의할 수 있는 구성을 지정할 수 있어요. Kafka 5.0.0부터 기본 정책이 될 예정이고, PrincipalConnectorClientConfigOverridePolicy는 비권장되어 5.0.0에서 제거될 예정이에요 (KIP-1188).
  • Kafka Streams punctuation의 시작 시간을 지정할 수 있게 됐어요(등록 시의 비결정적 시간에 의존하지 않음). KIP-1146 참고.
  • FeatureCommand에 선택적 --node-id 플래그가 추가됐어요. 설명할 노드를 지정해요. 제공하지 않으면 임의의 노드가 사용돼요.

4.1.2로 업그레이드하기

4.1.2의 주요 변경 사항

  • 레코드가 잘못된 토픽에 배치될 수 있는 희귀한 Kafka 프로듀서 버그 수정을 포함해요 (KAFKA-19012).

4.1.1로 업그레이드하기

4.1.1의 주요 변경 사항

  • range 스캔과 특정 DSL 연산자(session windows, sliding windows, stream-stream joins, foreign-key joins) 사용자에게 영향을 주던 메모리 누수 문제를 해결한 치명적 Kafka Streams 버그 수정을 포함해요 (KAFKA-19748).
  • 잠재적 데이터 손실과 관련된 치명적 Kafka Streams 버그 수정을 포함해요 (KAFKA-19479).

4.1.0로 업그레이드하기

참고: Kafka Streams 4.1.0은 range 스캔·특정 DSL 연산자 사용자에게 영향을 주는 치명적 메모리 누수 버그(KAFKA-19748)가 있어요. Kafka Streams 사용자는 수정이 포함된 4.1.1로 바로 업그레이드하는 걸 고려해야 해요.

3.3.x부터 4.0.x까지 어느 버전에서나 4.1.0으로 서버 업그레이드하기

4.1.x의 롤링 업그레이드 절차는 4.0 업그레이드와 동일해요. 자세한 단계는 "4.0.x로 서버 업그레이드" 섹션을 참고해요.

4.1.0의 주요 변경 사항

  • Apache Kafka 4.1은 Queues for Kafka (KIP-932) 의 프리뷰를 제공해요. share group이라는 새 종류의 그룹(consumer group의 대안)을 도입해요. share group을 활성화하려면 kafka-features.sh 도구로 share.version=1로 업그레이드해요. 자세한 내용은 릴리스 노트 참고.
  • 로깅 관련: LogCleaner의 로거 클래스 이름이 kafka.log.LogCleaner에서 org.apache.kafka.storage.internals.log.LogCleaner로 갱신되고, 로테이션된 state-change.log 파일 이름이 stage-change.log.[date]에서 state-change.log.[date]로 수정됐어요 (log4j2.yaml).
  • 브로커: log.cleaner.enable 구성이 비권장됐어요. KIP-966 파트 1인 Eligible Leader Replicas(ELR)가 새 클러스터에서 기본으로 활성화되고, 활성화 후에 이전에 설정된 브로커 레벨 min.insync.replicas 값은 제거되니 필요하면 클러스터 레벨로 설정해요.
  • 프로듀서: flush 메서드가 잠재적 교착을 감지해 콜백 내부 사용을 금지해요.
  • 커맨드: ConfigCommand의 force 옵션이 제거됐어요(0.10.1.0부터 비동작 상태였음).
  • Admin: Admin의 listConsumerGroups()와 listConsumerGroups(ListConsumerGroupsOptions)가 비권장되고 다음 메이저 버전에서 제거될 예정이에요. Admin.listGroups(ListGroupsOptions.forConsumerGroups())를 사용해요.
  • Kafka Streams: Streams rebalance protocol의 Early Access. KIP-848에 이어 KIP-1071이 Kafka Streams 애플리케이션에 브로커 측 작업 할당을 추가해요. 이 기능은 Early Access이며 기본적으로 비활성화되어 있고 프로덕션용이 아니에요.

4.0.1로 업그레이드하기

4.0.1로 클라이언트 업그레이드하기

롤링 업그레이드: 클라이언트를 한 번에 하나씩 종료→갱신→재시작해요. 클라이언트(Streams·Connect 포함)는 4.0으로 업그레이드하기 전에 버전 2.1 이상이어야 해요. 많은 비권장 API가 Kafka 4.0에서 제거됐어요. 호환성은 호환성 행렬 또는 KIP-1124 참고.

3.3.x부터 3.9.x까지 어느 버전에서나 4.0.1로 서버 업그레이드하기

참고: Apache Kafka 4.0은 KRaft 모드만 지원해요 — ZooKeeper 모드는 제거됐어요. 브로커 업그레이드는 KRaft 모드를 요구하며 소프트웨어·메타데이터 버전이 최소 3.3.x여야 해요. 3.3.x보다 오래된 KRaft 클러스터는 3.9.x로 먼저 업그레이드하세요. ZooKeeper 모드 클러스터는 먼저 KRaft로 마이그레이션해야 해요.

롤링 업그레이드 절차는 4.3.0과 동일해요(브로커별 종료→갱신→재시작, 검증 후 bin/kafka-features.sh ... upgrade --release-version 4.0). 단 이 버전은 메타데이터 변경이 있으므로 다운그레이드는 지원되지 않아요.

4.0.1의 주요 변경 사항

  • 로테이션된 state-change.log 파일 이름이 stage-change.log.[date]에서 state-change.log.[date]로 수정됐어요 (KAFKA-19576).
  • Kafka Streams에 KStreams#transformValues()(4.0.0에서 제거)에서 KStreams#processValues()로 업그레이드하는 치명적 수정이 포함돼요. 마이그레이션 가이드 참고.

4.0.0의 주요 변경 사항

  • 오래된 프로토콜 API 버전이 제거됐어요. Java 클라이언트(내부적으로 클라이언트를 쓰는 Connect·Streams 포함)를 4.0으로 올리기 전에 브로커가 버전 2.1 이상인지, 브로커를 4.0으로 올리기 전에 Java 클라이언트가 2.1 이상인지 확인해야 해요. Apache Kafka가 아닌 클라이언트에도 주의가 필요해요 (KIP-896).
  • Apache Kafka 4.0은 KRaft 모드만 지원해요 — ZooKeeper 모드 제거.
  • 새 그룹 코디네이터 구현이 도입됐어요. 기능적으로는 같은 API를 모두 구현해요. 합리적인 기본값이 있고, group.coordinator 접두사의 구성으로 튜닝할 수 있어요.
  • 차세대 Consumer Rebalance Protocol (KIP-848) 이 Apache Kafka 4.0에서 GA(Generally Available)가 됐어요. 업그레이드를 마무리하면 서버에서 자동으로 활성화돼요. 새 프로토콜을 consumer group이 사용하면 클러스터는 3.4.1 이상으로만 다운그레이드할 수 있어요.
  • Transactions Server-Side Defense (KIP-890) 이 4.0에 강화된 트랜잭션 프로토콜을 가져와요. 업그레이드를 마무리하면 새 프로토콜이 활성화돼요. 4.0 프로듀서 클라이언트를 쓰면 매 트랜잭션마다 producer epoch가 증가해, 각 트랜잭션이 의도한 메시지를 포함하고 다음 트랜잭션의 일부로 중복이 쓰이지 않게 보장해요.
  • Eligible Leader Replicas (KIP-966 Part 1) 이 복제 프로토콜을 강화해요. KRaft 컨트롤러가 ISR에 포함되지 않았지만 데이터 손실 없이 리더로 선출돼도 안전한 데이터 파티션 복제본을 추적해요. 그런 복제본은 파티션 메타데이터에 Eligible Leader Replicas(ELR)로 저장돼요.
  • 시스템 속성 org.apache.kafka.sasl.oauthbearer.allowed.urls이 추가돼 SASL OAUTHBEARER 토큰·jwks 엔드포인트로 허용 URL을 설정할 수 있어요. 기본값은 빈 목록이며 필요하면 명시적으로 설정해야 해요.
  • 많은 비권장 클래스·메서드·구성·도구가 제거됐어요:
    • 공통: metrics.jmx.blacklist/metrics.jmx.whitelist는 metrics.jmx.exclude/metrics.jmx.include로 대체, auto.include.jmx.reporter 제거(metric.reporters가 기본으로 JmxReporter), bufferpool-wait-time-total/io-waittime-total/iotime-total 지표는 -ns-total 버전으로 대체, DescribeLogDirsResponse.LogDirInfo/ReplicaInfo 클래스는 DescribeLogDirsResult.descriptions() 등으로 대체.
    • 브로커: delegation.token.master.key는 delegation.token.secret.key로, offsets.commit.required.acks 제거, log.message.timestamp.difference.max.ms는 log.message.timestamp.before.max.ms/log.message.timestamp.after.max.ms로 대체, remote.log.manager.copier/expiration.thread.pool.size 기본값이 -1에서 10으로, remote.log.manager.thread.pool.size 기본값이 10에서 2로, segment.bytes 최소값이 14바이트에서 1MB로 변경 (KIP-1030).
    • MirrorMaker: 원본 MirrorMaker(MM1)와 관련 클래스 제거(MM2 사용), use.incremental.alter.configs, add.source.alias.to.metrics 제거, config.properties.blacklist→config.properties.exclude, topics.blacklist→topics.exclude, groups.blacklist→groups.exclude.
    • 도구: kafka.common.MessageReader는 RecordReader 인터페이스로, kafka.tools.DefaultMessageFormatter 등은 org.apache.kafka.tools.consumer.*로, --whitelist는 --include로, kafka-acls의 --authorizer 등 제거.
    • Connect: ReplaceField의 whitelist/blacklist는 include/exclude로, SinkTask.onPartitionsRevoked/Assigned(Collection)·SourceTask.commitRecord(SourceRecord) 메서드 제거.
    • 컨슈머: poll(long)은 poll(Duration)으로(파티션 할당 대기 동작 다름), committed(TopicPartition)은 committed(Set<TopicPartition>)으로, MockConsumer.setException은 setPollException으로.
    • 프로듀서: enable.idempotence가 max.in.flight.requests.per.connection이 5를 넘을 때 더 이상 자동 폴백하지 않아요. sendOffsetsToTransaction(Map, String) 메서드 제거. linger.ms 기본값이 0에서 5로 변경.
    • Admin 클라이언트: alterConfigs는 incrementalAlterConfigs로, ConsumerGroupState는 GroupState로, describeConsumerGroups는 그룹을 찾지 못하면 DEAD 대신 GroupIdNotFoundException 던짐, DeleteTopicsResult.values()→topicNameValues(), TopicListing 생성자·ListConsumerGroupOffsetsOptions 메서드 변경.
    • Kafka Streams: 3.6 이전에서 비권장된 모든 공개 API 제거(JoinWindows.of(), JoinWindows#grace() 제외). KStreams#transformValues()→KStreams#processValues() 마이그레이션 가이드 참고.
  • 기타 변경: 클라이언트·Streams의 최소 Java 버전이 Java 8→Java 11로, 브로커·Connect·도구는 Java 17 요구 (KIP-750, KIP-1013). Java 23 지원 추가. Scala 2.12 지원 제거 (KIP-751). 로깅 프레임워크가 Log4j→Log4j2로 마이그레이션 (log4j-transform-cli 도구로 기존 Log4j 설정 변환 가능). KafkaLog4jAppender 제거(Log4j2 appender 사용). kafka-topics의 --delete-config 비권장. RLMM에 nextSegmentWithTxnIndex API 추가 (KIP-1058). ReplicationPolicy의 내부 토픽 식별 기준 갱신 (KIP-1074). Kafka Streams의 KIP-714 지원 (KIP-1076). num.recovery.threads.per.data.dir 기본값 1→2. message.timestamp.after.max.ms 기본값 Long.Max→1시간 (KIP-1030). KIP-890의 TransactionAbortableException 도입 — 트랜잭션 프로듀서에서 TimeoutException·TransactionAbortableException 둘 다 트랜잭션 중단(abort) 트리거로 처리해야 exactly-once 의미를 보존해요. state-change.log 파일 이름 오타 수정(KAFKA-19576, 4.0.1에서 수정).

3.9.0 및 이전 버전으로 업그레이드하기

3.9 문서의 "이전 버전에서 업그레이드하기(Upgrading From Previous Versions)" 섹션을 참고해요.

더 알아보기 (Learn more)

  • 4.x 업그레이드는 KRaft 모드 전제가 핵심이에요 — ZooKeeper 모드 클러스터는 먼저 KRaft로 마이그레이션해야 해요.
  • 롤링 업그레이드 후 kafka-features.sh upgrade --release-version <버전>으로 메타데이터 버전을 확정해야 해요.
  • 각 버전별 "Notable changes"는 비권장·제거 항목이 많으니, 업그레이드 전에 반드시 훑어보는 걸 권장해요.