feat: 공식 문서 근거자료, 브랜치 기능 문서 작성
This commit is contained in:
DongHyeonka
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: official-doc / KIP-429 — Kafka Consumer Incremental Cooperative Rebalance Protocol
|
||||
source_type: official-doc
|
||||
url: https://cwiki.apache.org/confluence/display/KAFKA/KIP-429%3A+Kafka+Consumer+Incremental+Rebalance+Protocol
|
||||
archive_url:
|
||||
related_branches: [feature-kafka-consumer-inbox-contract]
|
||||
related_projects: [ca-skeleton]
|
||||
tags: [official-doc, ca-skeleton, messaging, kafka]
|
||||
created: 2026-07-28
|
||||
---
|
||||
|
||||
# KIP-429 — Kafka Consumer Incremental Cooperative Rebalance Protocol
|
||||
|
||||
> Layer: `raw/` — 외부 자료(공식 문서)의 **원문 발췌·출처 기록**.
|
||||
> 문서 종류: Apache Kafka 공식 Kafka Improvement Proposal (KIP), Apache Software Foundation Confluence wiki (cwiki.apache.org) 호스팅.
|
||||
|
||||
## URL Fetch 기록
|
||||
|
||||
- 최초 시도 URL(요청됨): `https://cwiki.apache.org/confluence/display/KAFKA/KIP-429%3A+Kafka+Consumer+Incremental+Rebalance+Protocol` — WebFetch 도구는 HTTP 200을 반환했으나, 그 출력은 소형 모델이 재구성한 **paraphrase 요약**(예: "KIP-429 introduces an incremental cooperative rebalancing protocol...")이었고 원문 바이트와 일치하지 않아 Self-Grep 검증 대상으로 사용할 수 없었다.
|
||||
- 대체 조치: 동일 URL을 `curl` 로 직접 fetch(HTTP 200, 127,631 bytes)한 뒤, HTML 태그를 제거하는 결정론적 변환 스크립트로 순수 텍스트를 추출해 `/tmp/.../scratchpad/source-fetch-kip429.txt` (50,212 chars, 481 lines)에 저장. 이 파일을 Self-Grep 검증의 단일 기준으로 사용했다.
|
||||
- 인코딩 이슈 재시도는 불필요했다 — 원 URL(`%3A` 인코딩 그대로)이 curl 직접 fetch에서 정상 동작함.
|
||||
|
||||
## Parent / 활용 branch
|
||||
|
||||
| Branch | 이 자료가 정당화하는 결정 |
|
||||
|---|---|
|
||||
| [[raw/branch-notes/feature-kafka-consumer-inbox-contract]] | ca-skeleton consumer 가 파티션 할당 전략으로 incremental cooperative rebalance(`cooperative-sticky`)를 채택할지의 근거 — eager 프로토콜은 rebalance 마다 소유한 모든 파티션을 revoke 하지만 cooperative 는 소유 파티션을 유지해 피해 범위를 줄이며, 그 결과 `onPartitionsRevoked` 가 호출되지 않을 수도 있어 revoke 시점 커밋(manual ack / inbox 트랜잭션 경계) 로직을 유일한 체크포인트로 설계하면 안 된다는 근거 |
|
||||
|
||||
## 출처
|
||||
|
||||
- 원본 URL: https://cwiki.apache.org/confluence/display/KAFKA/KIP-429%3A+Kafka+Consumer+Incremental+Rebalance+Protocol
|
||||
- 아카이브 URL: (미제공)
|
||||
- 저자 / 조직: Boyang Chen (작성, Confluence 표기), A. Sophie Blee-Goldman (최종 수정, 2021-05-11) — Apache Kafka 프로젝트, Apache Software Foundation
|
||||
- 발행일: Confluence 표기에 최초 생성일은 없음 — "Created by Boyang Chen, last updated by A. Sophie Blee-Goldman on May 11, 2021" 만 명시
|
||||
- 마지막 확인일: 2026-07-28
|
||||
|
||||
## 왜 저장했는지
|
||||
|
||||
`feature-kafka-consumer-inbox-contract` 브랜치가 파티션 할당 전략(eager vs cooperative-sticky)을 결정하고 `ConsumerRebalanceListener` 콜백(특히 revoke 시점 커밋 로직) 설계를 재검토하기 위해서는, "cooperative 프로토콜에서 `onPartitionsRevoked` 가 호출되지 않을 수 있다"는 사실이 공식 문서로 뒷받침되어야 한다. 이 KIP 은 그 사실을 규정하는 원 사양 문서다.
|
||||
|
||||
## 핵심 인용
|
||||
|
||||
> [§Status, line 44] "Current state :" [...] "Accepted (2.4.0)" (원문은 콜론 뒤 non-breaking space + 일반 space 조합이라 정확한 원본 공백 문자와 자간을 그대로 재현하지 않고 elide 표기로 분리 인용함 — 두 fragment 모두 grep 검증됨)
|
||||
|
||||
> [§Public Interfaces — `ConsumerPartitionAssignor.RebalanceProtocol` javadoc, line 312] "The {@link RebalanceProtocol#EAGER} rebalance protocol requires a consumer to always revoke all its owned" [...] (line 313) "partitions before participating in a rebalance event. It therefore allows a complete reshuffling of the assignment."
|
||||
|
||||
> [§Public Interfaces — 동 javadoc, line 315] "{@link RebalanceProtocol#COOPERATIVE} rebalance protocol allows a consumer to retain its currently owned" [...] (line 316) "partitions before participating in a rebalance event. The assignor should not reassign any owned partitions"
|
||||
|
||||
> [§ConsumerRebalanceListener and ConsumerPartitionAssignor Semantics, line 210] "Listener#onPartitionsLost : if the member has missed a rebalance and fallen out of the group, this new callback will be invoked on the set of all owned partitions (unless empty). The member will then rejoin the group."
|
||||
|
||||
> [§ConsumerRebalanceListener and ConsumerPartitionAssignor Semantics, line 224] "it is possible for #onPartitionsRevoked to never be invoked at all during a rebalance, and should not be relied on to signal that a rebalance has started."
|
||||
|
||||
## Claims Extracted
|
||||
|
||||
| Claim ID | Claim | Evidence quote | Strength | Applies to | Does not prove |
|
||||
|---|---|---|---|---|---|
|
||||
| KIP429-C1 | KIP-429 는 Apache Kafka 프로젝트가 공식 채택(Accepted)한 제안이며 Kafka 2.4.0 에 반영되었다 | [§Status, line 44] "Current state :" [...] "Accepted (2.4.0)" | `official-vendor-doc` | Kafka client 2.4.0 이상에서 incremental cooperative rebalance protocol 이 공식 기능으로 존재한다는 것 | ca-skeleton 이 실제로 Kafka client 2.4.0 이상 버전을 사용한다는 것(별도 의존성 버전 확인 필요), Spring Kafka wrapper 가 이 기능을 그대로 노출한다는 것 |
|
||||
| KIP429-C2 | EAGER rebalance protocol 은 consumer 가 rebalance event 에 참여하기 전 소유한 모든 파티션을 항상 revoke 하도록 요구하며, 그 결과 할당의 완전한 재구성(complete reshuffling)을 허용한다 | [§Public Interfaces, line 312-313] "The {@link RebalanceProtocol#EAGER} rebalance protocol requires a consumer to always revoke all its owned" [...] "partitions before participating in a rebalance event. It therefore allows a complete reshuffling of the assignment." | `official-vendor-doc` | Kafka consumer 의 (변경 전) 기본/전통적 rebalance protocol 동작(RangeAssignor·RoundRobinAssignor 등 EAGER 전용 assignor 사용 시) | EAGER 프로토콜이 ca-skeleton 환경에서 실측 downtime 을 유발한다는 것 — 이는 로컬/dev 측정으로 별도 검증 필요 |
|
||||
| KIP429-C3 | COOPERATIVE rebalance protocol 은 consumer 가 rebalance event 참여 전 현재 소유한 파티션을 유지하도록 허용하며, assignor 는 소유 파티션을 즉시 재할당하지 않고 다음 rebalance 에서 revoke 가 필요함을 표시만 한다 | [§Public Interfaces, line 315-316] "{@link RebalanceProtocol#COOPERATIVE} rebalance protocol allows a consumer to retain its currently owned" [...] "partitions before participating in a rebalance event. The assignor should not reassign any owned partitions" | `official-vendor-doc` | `cooperative-sticky` assignor(Kafka 2.4+)를 사용하는 plain consumer | 모든 커스텀 assignor 가 cooperative 를 지원한다는 것 — 문서는 오히려 기존 StickyAssignor 는 Cooperative 를 지원하도록 만들어지지 않았다고 별도 서술한다(§메모 참조, 이 Claim 의 인용 범위 밖) |
|
||||
| KIP429-C4 | cooperative protocol 에서 `onPartitionsLost` 콜백은 멤버가 rebalance 를 놓치고 그룹에서 이탈했을 때 소유하고 있던 모든 파티션 집합(비어있지 않은 경우)에 대해 호출되며, 이후 멤버는 그룹에 재가입한다 | [§ConsumerRebalanceListener and ConsumerPartitionAssignor Semantics, line 210] "Listener#onPartitionsLost : if the member has missed a rebalance and fallen out of the group, this new callback will be invoked on the set of all owned partitions (unless empty). The member will then rejoin the group." | `official-vendor-doc` | cooperative rebalance listener 구현 시 "멤버십 손실"(그룹 이탈) 경로의 파티션 정리 로직 설계 | `onPartitionsLost` 이후 `InboxStorePort` 의 커밋/롤백을 어떤 방식으로 처리해야 하는지 — 그 메커니즘 자체는 이 KIP 가 아니라 본 branch 의 별도 설계 결정 |
|
||||
| KIP429-C5 | cooperative protocol 에서 `onPartitionsRevoked` 콜백은 rebalance 도중 전혀 호출되지 않을 수 있으며, rebalance 가 시작되었음을 알리는 신호로 신뢰해서는 안 된다 | [§ConsumerRebalanceListener and ConsumerPartitionAssignor Semantics, line 224] "it is possible for #onPartitionsRevoked to never be invoked at all during a rebalance, and should not be relied on to signal that a rebalance has started." | `official-vendor-doc` | revoke 시점 커밋/flush 로직을 rebalance 감지의 유일한 체크포인트로 설계하면 안 된다는 근거 — manual ack·inbox 커밋 시점을 `onPartitionsRevoked` 호출에만 의존하도록 설계해서는 안 됨 | `onPartitionsAssigned` 이 이 상황에서 ca-skeleton 의 안전한 대체 체크포인트로 항상 충분하다는 것 — 원문은 "always be called"만 말할 뿐, ca-skeleton `InboxStorePort` 트랜잭션 경계 설계 자체는 이 KIP 로 증명되지 않고 별도 구현·검증 필요 |
|
||||
|
||||
## Usage Boundaries
|
||||
|
||||
- 이 자료가 직접 증명하는 것:
|
||||
- `KIP429-C1`: KIP-429 가 공식 채택되어 Kafka 2.4.0 에 반영된 사실
|
||||
- `KIP429-C2`: EAGER protocol 의 "항상 전체 revoke 후 재참여" 정의
|
||||
- `KIP429-C3`: COOPERATIVE protocol 의 "소유 파티션 유지, 필요한 것만 다음 rebalance 에서 revoke" 정의
|
||||
- `KIP429-C4`: `onPartitionsLost` 가 그룹 이탈(멤버십 손실) 시에만 호출된다는 것
|
||||
- `KIP429-C5`: `onPartitionsRevoked` 가 cooperative protocol 에서 호출되지 않을 수 있다는 것 — rebalance 시작 신호로 신뢰 불가
|
||||
- 이 자료가 증명하지 않는 것:
|
||||
- ca-skeleton 이 실제로 `cooperative-sticky` assignor 를 설정했다는 것(구현 사실) — 이 문서는 프로토콜 사양일 뿐 프로젝트 구현 증거가 아님
|
||||
- Spring Kafka 의 `ConcurrentKafkaListenerContainerFactory`/`ContainerProperties` 가 이 콜백 시맨틱을 그대로 노출하는지 — Spring Kafka 자체의 공식 문서로 별도 확인 필요
|
||||
- `InboxStorePort` 트랜잭션 커밋을 어느 콜백(assigned/lost/revoked)에 바인딩해야 하는지의 **구현 방법** — 이 KIP 은 원칙(revoked 가 신뢰 불가능한 신호)만 규정하며 ca-skeleton 의 구체적 커밋 바인딩은 branch 의 별도 설계 결정
|
||||
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
||||
- ca-skeleton 이 사용하는 Kafka client 실제 버전이 2.4.0 이상인지(빌드 의존성 확인)
|
||||
- Spring Kafka `ConsumerRebalanceListener` 래퍼가 `onPartitionsLost` 를 KIP-429 원문 시맨틱 그대로 전달하는지(Spring Kafka 공식 문서 별도 인용 필요)
|
||||
|
||||
## 메모
|
||||
|
||||
- 확인됨(grep 검증, line 360, 이번 5개 인용에는 미포함): "The existing StickyAssignor was not made to support Cooperative to ensure users follow the smooth upgrade path outlined below..." — 기존 `StickyAssignor` 는 cooperative 미지원. ca-skeleton 이 `cooperative-sticky` 가 아닌 다른 sticky 계열 assignor 를 검토할 경우 이 문장을 별도 Claim 으로 승격해 인용할 것.
|
||||
- 업그레이드 경로(2회 rolling bounce) 관련 문장도 line 369 부근에서 grep 확인됨 — ca-skeleton 은 신규 프로젝트라 rolling upgrade 시나리오 자체가 branch 결정 범위 밖일 가능성이 높음(운영 중인 기존 컨슈머 그룹의 무중단 업그레이드가 아니라면). 필요 시 별도 Claim 화.
|
||||
- WebFetch 도구의 출력이 verbatim 이 아니라 paraphrase 라는 것을 이번에 직접 확인함 — 향후 동일 유형 작업에서는 curl 직접 fetch + 결정론적 HTML→text 변환을 기본 경로로 삼는 것이 안전하다.
|
||||
|
||||
## 관련
|
||||
|
||||
- 같은 branch 의 다른 official-doc: [[raw/official-docs/kafka-message-delivery-semantics-design.md]] — delivery semantics(at-least-once/exactly-once) 정의, 인접 관심사
|
||||
- 이 자료를 인용한 wiki 요약: (생성 시 링크)
|
||||
Reference in New Issue
Block a user