Apache Kafka クイックスタート - CLIとローカル例題を用いたKafka 4.2のインストール

Apache Kafka 4.2.0 が現在サポートされているリリースラインであり、Kafka 4.x は完全に ZooKeeper を不要とし、デフォルトで KRaft に構築されているため、モダンなクイックスタートには最適な基準となります。

このガイドは、コマンドラインを重視した実践的なクイックスタートです。Kafka のインストール、ローカルブローカーの起動、必須の Kafka CLI ツールの学習、そしてターミナルに貼り付けられる2つのエンドツーエンドの例で締めくくります。

Apache Kafka とは何か、そしてその用途

Apache Kafka はイベントストリーミングプラットフォームです。実用的な用語で言えば、イベントストリーミングとは、ソース（データベース、センサー、アプリ）からリアルタイムでイベントデータをキャプチャし、生成されたストリームを永続的に保存し、それらをリアルタイム（または後で）に処理またはルーティングすることを意味します。

Kafka は1つのプラットフォームに3つのコア機能をもたらします：イベントのストリームへのパブリッシュとサブスクライブ、必要に応じてストリームを永続的に保存し、ストリームが発生した時点または遡及的に処理することです。この組み合わせが、Kafka がリアルタイムデータパイプライン、統合、メッセージング、ストリーミング分析に使用される理由です。

Kafka がより広範なデータインフラストラクチャの中でどのような位置づけにあるかという文脈については、S3 互換のオブジェクトストレージ、PostgreSQL アーキテクチャ、Elasticsearch の最適化、AI 固有のデータレイヤーをカバーするAI システムのためのデータインフラストラクチャ：オブジェクトストレージ、データベース、検索＆AI データアーキテクチャ の柱を参照してください。

AWS で構築しており、マネージドな代替手段が必要な場合は、AWS Kinesis を用いたイベント駆動型マイクロサービスの構築 で、Kinesis Data Streams を用いたイベント駆動型マイクロサービスの実装について詳しく解説しています。

Kafka でのステートフルストリーム処理については、K8s と Kafka 上の Apache Flink: PyFlink、Go、運用、マネージド価格 を参照してください。

Kafka へのパブリッシュ前にデータベースに書き込むサービスの場合、トランザクショナルアウトボックスパターン は、データベースのコミットと Kafka の produce コールの間でイベントが決して失われないことを保証します。

運用上で、Kafka はサーバーとクライアントの分散システムであり、高性能な TCP プロトコルを介して通信します：ブローカーはデータを保存・提供し、クライアント（プロデューサーとコンシューマー）はイベントの書き込みと読み取りを行います。これらは大規模かつフォールトトレラントな環境で動作することが多いです。

CLI で繰り返し目にするいくつかの概念：

• トピックはイベントを整理します。トピックはマルチプロデューサーかつマルチサブスクライバーであり、レテンションが古いデータの破棄タイミングを制御するため、イベントは複数回読み取ることができます。
• パーティションはスケーラビリティのためにトピックをブローカー間で分割します。パーティションごとに順序が保証されます。
• レプリケーションファクターはフォールトトレランスを制御します。ドキュメントの例では、本番環境でレプリケーションファクター2または3を推奨しています（単一ノードの開発用クイックスタートでは通常1を使用します）。

Apache Kafka のインストール

Kafka 公式のクイックスタートでは、バイナリリリース（tarball）または公式 Docker イメージを使用します。どちらもローカル開発に有効です。

スキップすべきではない前提条件

Kafka 4.x はモダンな Java を必要とします：サーバーおよびツールにおいて、Java 17+ がローカル実行の基準であり、Kafka 4.0 は Java 8 のサポートを削除しました。

Kafka の学習のためにインストールする場合は、Java 17 または 21 などのサポートされている JDK を目指してください。Kafka の Java サポートページでは、Java 17、21、25 が完全にサポートされており、Java 11 はモジュールの一部（クライアントおよびストリーム）のみがサポートされていることがリストされています。

公式バイナリリリースからのインストール

Kafka 4.2.0 の公式クイックスタートは、バイナリディストリビューションのダウンロードと展開から始まります：

tar -xzf kafka_2.13-4.2.0.tgz
cd kafka_2.13-4.2.0

上級者向けの注記：

• ファイル名の「2.13」は Scala のビルドラインを反映しています。Kafka 4.x バイナリでは、Scala 2.13 が主要なディストリビューションラインであり、Kafka 4.0 は Scala 2.12 のサポートを削除しました。
• サプライチェーンの整合性を重視する場合、ダウンロードページでは、Apache が公開した手順と KEYS を使用してダウンロードを検証できることが明確に文書化されています。

Docker でのインストール

Kafka は Docker Hub に公式 Docker イメージも提供しています。クイックスタートでは、以下のように Kafka 4.2.0 をプルして実行できることが示されています：

docker pull apache/kafka:4.2.0
docker run -p 9092:9092 apache/kafka:4.2.0

また、「ネイティブ」イメージライン（GraalVM ネイティブイメージベース）もあります。Kafka ドキュメントおよびこのイメージラインに関する Kafka 改善提案（KIP）では、これを実験的と記述しており、本番環境ではなくローカル開発およびテスト用に意図されています。

Windows ユーザー向けのプラットフォーム注記

Kafka ディストリビューションには Windows スクリプト（バッチファイル）が含まれています。Kafka ドキュメントでは歴史的に、Windows では Unix の bin/ .sh スクリプトの代わりに bin\windows\ と .bat スクリプトを使用すると記載しています。

KRaft でローカルに Kafka を起動

「Apache Kafka を実行するには ZooKeeper が必要ですか？」と疑問をお持ちの場合、モダンな答えはいいえです。Kafka 4.0 は、ZooKeeper を全く使用せずに動作するよう設計された最初のメジャーリリースであり、デフォルトでKRaft モードで実行され、ローカルおよび本番環境における運用オーバーヘッドを削減します。

展開された tarball から単一ノードのローカルブローカーを起動

Kafka 4.2 クイックスタートでは3つのコマンドを使用します：

1. クラスタ UUID を生成する
2. ログディレクトリをフォーマットする
3. サーバーを起動する

# Generate a Cluster UUID
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# Format Log Directories (standalone local format)
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

# Start the Kafka broker
bin/kafka-server-start.sh config/server.properties

KRaft で「フォーマット」ステップが重要な理由：Kafka の KRaft 運用ドキュメントでは、kafka-storage.sh random-uuid がクラスタIDを生成し、各サーバーで kafka-storage.sh format でフォーマットする必要があることを説明しています。その理由の1つとして、自動フォーマットがエラーを隠してしまう可能性があること、特にメタデータログ周りで問題が生じやすいことから、明示的なフォーマットが推奨されています。

このクイックスタートで実行しているもの

ローカル開発では、Kafka は簡略化された「統合」セットアップ（コントローラーとブローカーが一緒）で実行できます。Kafka の KRaft ドキュメントでは、統合サーバーは開発にはシンプルですが、重要なデプロイメント環境（コントローラーを分離し、独立してスケーリングしたい場合）には推奨されないと指摘しています。

「本番」クラスタでは、KRaft コントローラーとブローカーは別個の役割（process.roles）を持ち、コントローラーは通常3または5ノードのクォーラムとしてデプロイされます（可用性は多数派が生きていることに依存します）。

Kafka CLI の必須知識と主要なコマンドラインパラメータ

Kafka には bin/ 下に多くの CLI ツールが同梱されています。公式運用ドキュメントでは2つの有用な特性を強調しています：

• 共通ツールはディストリビューションの bin/ ディレクトリ下にあります。
• 各ツールは引数なしで実行すると、完全なコマンドライン使用方法を表示します。

また Kafka 4.x で重要なのは：AdminClient コマンドは --zookeeper を受け付けなくなりました。Kafka の互換性ドキュメントでは、Kafka 4.0 以降、クラスタと相互作用するには --bootstrap-server を使用する必要があると記載しています。

常に使用する Kafka 接続フラグ

ほとんどのツールはクラスタのエントリポイントが必要です：

• --bootstrap-server host:port
  トピック操作、コンシューマーグループ、およびほとんどのブローカー向けコマンドにこれを使用します。Kafka 4.x では ZooKeeper ベースの管理ワークフローの正規の代替手段です。

KRaft は一部のツールにおいてブローカーエンドポイントとコントローラーエンドポイントを区別します。例えば、kafka-features.sh やメタデータツールの一部はコントローラーエンドポイントを使用できますが、多くの管理操作はブローカーエンドポイントを使用します。KRaft 運用ページでは両方のスタイルが例で示されています。

kafka-topics.sh によるトピック管理

コアライフサイクルには kafka-topics.sh を使用します：

• トピックの作成、説明、一覧表示（クイックスタートでは --create、--describe、--topic が示されています）。
• パーティションとレプリケーションファクターを介してスケーラビリティと耐久性を指定します。運用ガイドでは --partitions と --replication-factor を示し、それらがスケーラビリティとフォールトトレランスにどのように影響するかを説明しています。
• 作成時に --config key=value でトピック固有のオーバーライドを追加します（トピック設定ドキュメントには具体的な例が示されています）。

「本番を意識した」作成コマンドの例は以下の通りです（この形状は公式運用ドキュメントで使用されています）：

bin/kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic my_topic_name \
  --partitions 20 --replication-factor 3 \
  --config x=y

コンソールクライアントによるプロデュースとコンシューム

クイックスタートでは、検証とスモークテストに高速であるため、コンソールプロデューサーとコンシューマーを使用します：

• kafka-console-producer.sh --topic ... --bootstrap-server ...
• kafka-console-consumer.sh --topic ... --from-beginning --bootstrap-server ...

Kafka 4.2 には CLI の一貫性改善も含まれています。アップグレードノートでは：

• kafka-console-producer は --max-partition-memory-bytes を非推奨とし、代わりに --batch-size を推奨しています。
• kafka-console-consumer は --property（フォーマッタープロパティ）を非推奨とし、代わりに --formatter-property を使用します。
• kafka-console-producer は --property（メッセージリーダープロパティ）を非推奨とし、代わりに --reader-property を使用します。

内部ランブックを維持している場合、Kafka 5.0 が非推奨フラグを削除する前に、これらの注記を更新しておく価値があります。

kafka-consumer-groups.sh によるコンシューマーラグの検査

実システムでは、「私のコンシューマーは追いついているか」は日常的な質問です。運用ガイドでは以下を実演しています：

• グループ一覧：--list
• オフセットとラグを含むグループの説明：--describe --group ...
• メンバーと割り当ての説明：--members と --verbose
• グループの削除：--delete
• オフセットの安全なリセット：--reset-offsets

例：

bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group

ローカルDockerおよびリモートクライアント向けの1つの設定注意事項

コンテナ内で Kafka を実行したり、ロードバランサーの背後に配置したりする場合、リスナーを正しく設定する必要がある場面が訪れます。Kafka のブローカー設定ドキュメントでは、バインドアドレスがクライアントが使用するべきアドレスと異なる場合、特にブローカーがクライアントや他のブローカーに宣伝するアドレスとして advertised.listeners を説明しています。

今すぐ実行できるクイックスタート例

以下の例は意図的に CLI ベースであり、アプリケーションコードを書く前にローカル Kafka セットアップを検証できます。

例：トピックを実行し、エンドツーエンドでメッセージをストリームする

これは Kafka 4.2 クイックスタートからの典型的な「作成、プロデュース、コンシューム」フローです。

ターミナルAを開き、トピックを作成します：

bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092

次に説明を表示します（オプションですが、パーティションとレプリケーションファクターを学ぶ際に役立ちます）：

bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092

ターミナルBを開き、プロデューサーを起動します：

bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092

数行入力し（各行がイベントになります）、プロデューサーを実行したままにします：

This is my first event
This is my second event

ターミナルCを開き、最初からコンシューマーを起動します：

bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092

同じ行が表示されるはずです。

なぜこれにより「動作する」以上の検証ができるのか：Kafka のクイックスタートでは、ブローカーがイベントを永続的に保存し、イベントが複数回、複数のコンシューマーによって読み取られることを説明しています。この耐久性が、インストールまたはアップグレード後に最初にこのクイックスタートパターンを実行すべき理由です。

例：ファイルからトピックへ、そしてファイルへというシンプルな Kafka Connect パイプラインを実行する

Kafka Connect は、「すべてのためにカスタムプロデューサーとコンシューマーを書かずに、データを Kafka 内外に移動するにはどうすればよいのか」という再発する質問に答えます。Kafka Connect の概要では、コネクタを介して Kafka と他のシステム間のスケーラブルで信頼性の高いストリーミングツールと記述しています。

Kafka 4.2 クイックスタートには、ファイルソースとシンクコネクタを使用した最小限のローカル Connect デモが含まれています。

Kafka ディレクトリから、まずワーカープラグインパスを提供されたファイルコネクタJARを含むように設定します：

echo "plugin.path=libs/connect-file-4.2.0.jar" >> config/connect-standalone.properties

小さな入力ファイルを作成します：

echo -e "foo\nbar" > test.txt

ソースとシンクコネクタ設定の両方でスタンドアロンモードで Connect ワーカーを起動します：

bin/connect-standalone.sh \
  config/connect-standalone.properties \
  config/connect-file-source.properties \
  config/connect-file-sink.properties

何が起こるべきか（そしてそれがなぜ有用か）：

• ソースコネクタは test.txt から行を読み取り、トピック connect-test にプロデュースします。
• シンクコネクタは connect-test から読み取り、test.sink.txt に書き込みます。

シンクファイルを確認します：

more test.sink.txt

以下が表示されるはずです：

foo
bar

トピックを直接確認することもできます：

bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connect-test --from-beginning

この2番目の例は、Connect 設定がどこにあるか（ワーカー設定プラスコネクタ設定）を教えてくれるだけでなく、最小限の「取り込み、保存、エクスポート」ループを示すため、素晴らしい筋肉記憶の構築になります。

トラブルシューティングと次のステップ

「Kafka クイックスタートが起動しない」問題のほとんどは、限られた根本原因に分類されます。

ブローカーが起動しない

公式要件から始めます：

• Kafka 4.2 クイックスタートは明確にJava 17+ を必要とします。古い JDK を使用している場合は、まずそれを修正してください。
• KRaft モードでは、ストレージのフォーマットは必須の明示的なステップです。kafka-storage.sh format をスキップすると、起動失敗やメタデータエラーが発生する可能性があります。

実験してクリーンな状態に戻したい場合、Kafka クイックスタートではデモで使用されるローカルデータディレクトリを削除する方法を示しています：

rm -rf /tmp/kafka-logs /tmp/kraft-combined-logs

ブローカーは動作しているが CLI コマンドが失敗する

Kafka 4.x では、--bootstrap-server（--zookeeper ではない）を使用していることを確認してください。Kafka の互換性ドキュメントでは、Kafka 4.0 から AdminClient コマンドから --zookeeper が削除されたことを明確に指摘しています。

Docker ネットワークの驚き

Kafka が Docker 内にあり、クライアントツールが Docker 外（または別のマシン）にある場合、正しいリスナー宣伝が必要になることがあります。ブローカー設定ドキュメントでは、クライアントが接続すべきアドレスがバインドアドレス（listeners）と異なる場合に advertised.listeners が使用されると説明しています。

クイックスタート後の進み方

この記事の例を完了した場合、最も一般的な最初の検索への答えは既に得ています：

• Kafka の用途（エンドツーエンドのイベントストリーミング）
• ローカルに Kafka をインストールする方法（tarball または Docker）
• なぜ ZooKeeper がなくなり、4.x で KRaft がデフォルトなのか
• 日常に重要な CLI ツール（トピック、プロデューサー、コンシューマー、グループ）

ここから、最も価値のある次のステップは通常以下の通りです：

• トピック、パーティション、レプリケーションのより深いメンタルモデルのために Kafka の「Introduction」を読む。
• 最初の処理アプリケーションを望む場合、Kafka Streams クイックスタートを探索する（Streams クイックスタートでは WordCount デモの実行と、コンソールコンシューマーによる結果の検査を示しています）。