Kafkaクラスタアップグレード実践ガイド: ローリング更新と互換性の要点

Kafkaのアップグレードは、正しく計画すれば無停止で進められます。鍵になるのは互換性の理解と、段階的に進めるローリング更新の手順です。本稿では、試験対策（CCAAK）と運用現場の両方で役に立つ、公式ドキュメント準拠の考え方と手順をまとめます。

特に、inter.broker.protocol.version（IBPV）の固定、必要に応じたメッセージ形式の固定、コントローラやクライアントの順序、KRaftとZooKeeperでの差分、検証・ロールバックの勘所を、手順とチェックリストで具体化します。

互換性の前提を一枚で把握する

Kafkaの互換性は大きく、ワイヤプロトコル（ブローカー間・クライアント対ブローカー）、レコードのメッセージ形式、メタデータ機能レベル（KRaftの場合）の3層で考えます。ローリング更新では、まず既存の通信やレコード形式を壊さないように、IBPVやメッセージ形式を現行バージョンで固定してからバイナリを更新します。

クライアントは一般に、新しいブローカーに対しても古いAPIバージョンで会話できるため、ブローカーを先に上げるのが原則です。ZooKeeperモードではブローカーとコントローラの役割はブローカー側に内包されますが、KRaftモードではコントローラ群とブローカー群を別にローリングする順序性が加わります。

• ワイヤ互換性: IBPVでブローカー間のプロトコルを既存バージョンに固定してからアップグレード。
• メッセージ形式: 旧形式のままアップグレードし、全ブローカー更新後に切り替え。既存セグメントは再書き換えされない。
• クライアント互換性: 先にブローカーを上げ、クライアントは後追い。トランザクションや冪等プロデューサは旧ブローカーでは利用要件あり（0.11以降）。
• KRaftのメタデータ機能: KRaftでは機能レベルを最終化する手順が別途ある（例: kafka-featuresツール）。

ローリング更新の標準フロー（無停止を前提）

以下はZooKeeperモードの一般的な流れです。KRaftでも基本は同じですが、コントローラ群を先に、次いでブローカー群という順序性と、最終段の機能レベル最終化が追加されます。

大切なのは、最初に互換性を固定し、1台ずつ更新して健全性を確認し、全台が上がってから固定を解除（最新化）するという順序です。

• 事前: クラスタ健全性を確認（URP=0、オフライン分割なし、コントローラ安定）。必要に応じてIBPVとメッセージ形式を現行値に固定。
• 1台ずつ: 対象ブローカーの負荷とリーダーを可能な範囲で軽減→停止→バイナリ更新→起動→健全性確認。
• 全台完了後: IBPVおよびメッセージ形式を最新版へ更新。必要ならローリングで設定反映。
• KRaft: コントローラ群→ブローカー群の順で実施し、最後にメタデータ機能レベルを最終化。

ローリング更新の概念図（B1→B2→B3の順で1台ずつ）

実行ランブック例（ZooKeeperモード想定。KRaftは後述の注意を参照）

# 0) 事前確認（健全性）
$ kafka-topics.sh --bootstrap-server broker:9092 --describe --under-replicated-partitions
$ kafka-topics.sh --bootstrap-server broker:9092 --describe --unavailable-partitions
$ kafka-broker-api-versions.sh --bootstrap-server broker:9092 | head

# 1) 互換性の固定（server.properties を全ブローカーで揃える）
# 例: いまの運用バージョンが 2.8 の場合
inter.broker.protocol.version=2.8
log.message.format.version=2.8   # プロパティが存在する場合のみ。ない環境はスキップ

# 2) ブローカーを1台ずつ更新
# （オプション）停止前にリーダーを減らす
$ kafka-preferred-replica-election.sh --zookeeper zk:2181  # 利用可能な場合

# 対象ブローカーB1を停止→パッケージ更新→起動
$ sudo systemctl stop kafka
# パッケージ更新はディストリ/配布物に合わせて実施
$ sudo tar -xf kafka_2.13-3.6.0.tgz -C /opt/kafka --strip-components=1
$ sudo systemctl start kafka

# 健全性チェック（URP=0、オフライン分割なし、クライアントエラーなし）
$ kafka-topics.sh --bootstrap-server broker:9092 --describe --under-replicated-partitions

# B2, B3 …と繰り返し

# 3) 全台更新後に固定解除（最新版へ）
inter.broker.protocol.version=3.6  # 例
log.message.format.version=3.6     # プロパティが存在する場合のみ

# 4) 設定反映のための最終ローリング再起動
$ sudo systemctl restart kafka  # 各ブローカー順番に

# 5) KRaftの場合の最終化（コントローラで実施。実際のオプションは環境のバージョンに合わせる）
$ kafka-features.sh --bootstrap-server controller:9093 --describe
$ kafka-features.sh --bootstrap-server controller:9093 --finalize-upgrade

主要設定と落とし穴

inter.broker.protocol.versionは、ブローカー間のワイヤプロトコルを既存バージョンに固定する設定です。これにより、新旧ブローカーが混在しても同じプロトコルで通信できるため、ローリング更新中の互換性が保たれます。固定は全ブローカーで揃えて適用し、全台の更新後に最新化します。

log.message.format.versionがある環境では、レコードのエンコード形式（マジックバイトやヘッダ構造など）を旧来の形式に固定できます。固定を外しても既存のログセグメントは書き換えられず、新規に書かれるレコードから新形式になります。よって切替時に大規模なIOが発生しないのが通常です。

• 固定の不整合: 一部ブローカーでIBPVが異なると、クラスタが不安定化する。必ず全台で揃える。
• 切替の順序: 固定→バイナリアップグレード→全台完了→固定解除（最新版）という順序を守る。
• クライアント順序: 基本はブローカー先行。新機能を使うクライアントは、サーバ側の最終化（IBPV/メッセージ形式/機能レベル）後に展開。
• トランザクション/冪等: 旧ブローカー混在中は機能差が出やすい。必要なら固定解除後に有効化を検討。
• KRaftの機能最終化: 最終化前は旧機能レベルに留まる。互換性維持のため、全台更新後に実施する。

設定確認のミニコマンド

# IBPV/メッセージ形式が想定どおりか（静的設定ファイルの例）
$ grep -E "^(inter.broker.protocol.version|log.message.format.version)" /etc/kafka/server.properties

# APIバージョンの対応（クライアント対ブローカー）
$ kafka-broker-api-versions.sh --bootstrap-server broker:9092 | sed -n '1,20p'

# クラスタ健全性（代表値）
$ kafka-metrics.sh  # メトリクス収集の仕組みに合わせて、以下のような指標を監視
# kafka.server:type=ReplicaManager,name=UnderReplicatedPartitions == 0
# kafka.controller:type=KafkaController,name=ActiveControllerCount == 1 (ZK)
# kafka.server:type=BrokerTopicMetrics,name=BytesInPerSec の平常性

検証とロールバック戦略

各ブローカー再起動後は、パーティションのレプリケーション完了、リーダーの安定、クライアントのタイムアウト増加がないことを確認します。ベンチマークではなく、業務トラフィックに近いスモークテストを流すのが実務的です。

異常が出たら、そのブローカーのみを旧バイナリに戻すロールバックを優先し、固定設定（IBPV/メッセージ形式）は変更しないのが安全です。全台の更新が進むまでは、固定を外さない限り後戻りしやすい構えを維持できます。

• 健全性ポイント: URP=0、OfflinePartitions=0、ISRの収束、クライアントのエラー率・レイテンシ平常。
• ログ確認: server.logにProtocolエラーやタイムアウトが連発していないか。
• ロールバック: 直近で更新した1台を旧版へ戻す→再検証。固定は触らない。

戦略比較とケース別指針

標準はローリング更新ですが、要件次第で停止更新や並行クラスター（いわゆるBlue/Green）を選ぶこともあります。監査対応や大規模バージョンスキップ時のリスク、インフラ費用を天秤にかけて選択します。

CCAAK視点では、ローリング更新の前提条件（IBPV固定、全台更新後の固定解除、クライアントは後追い）を確実に説明できることが重要です。

• トラフィック特性: 深夜でもピークがある系はBlue/Greenが有利。
• 規模・コスト: ブローカー台数が多いほどローリングが現実的。
• リスク許容度: 大幅スキップや設定大改修は並行検証の価値が高い。

試験対策まとめとチェックリスト

試験でよく問われるのは、固定→更新→解除の順序、クライアント更新順、メッセージ形式の扱い、KRaftの機能最終化の存在です。選択肢に「全台更新前にIBPVを上げる」「クライアントを先に更新」などの紛れ込みがあれば誤りです。

実務では、変更前後の観測点を明記し、1台ごとに合格基準を満たすまで次へ進まない運用が安定します。

• 固定は全台で揃える（IBPV、必要ならメッセージ形式）。
• 1台ずつ更新。各台でURP=0に戻るまで待つ。
• 全台完了後に固定解除（最新版化）。必要なら最終ローリング再起動。
• クライアントは最後に更新。新機能の有効化はサーバ側の最終化後。
• KRaftはコントローラ群→ブローカー群→機能最終化の順。

問題で確認

よくある質問