Apache Kafka クイックスタート - CLI とローカルサンプルを使用した Kafka 4.2 のインストール

Kafka 4.2 をインストールし、数分でイベントのストリーミング処理を開始します。

目次

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

このガイドは、実践的でコマンドラインを重視した Quickstart です。Kafka のインストール、ローカルブローカーの起動、基本的な Kafka CLI ツールの学習、そしてターミナルに貼り付けて実行できる 2 つの完全なエンドツーエンドの例で構成されています。

distributed message processing infographic apache kafka

Apache Kafka とは何か、そして何に使用されるか

Apache Kafka は イベントストリーミングプラットフォーム です。実務的な観点から言うと、イベントストリーミングとは、ソース（データベース、センサー、アプリケーションなど）からリアルタイムでイベントデータをキャプチャし、生成されたストリームを永続的に保存し、リアルタイム（または後から）に処理やルーティングを行うことを意味します。

Kafka は、1 つのプラットフォームに 3 つの中核機能を統合します。イベントのストリームへの パブリッシュとサブスクライブ、必要なだけストリームを 永続的に保存 する機能、ストリームが生成される際または遡って 処理 する機能です。この組み合わせこそが、Kafka がリアルタイムデータパイプライン、統合、メッセージング、ストリーミング分析に使用される理由です。

Kafka がより広範なデータインフラストラクチャのどこに位置するかに関する文脈については、S3 互換オブジェクトストレージ、PostgreSQL アーキテクチャ、Elasticsearch の最適化、AI ネイティブなデータレイヤーをカバーする データインフラストラクチャ for AI システム：オブジェクトストレージ、データベース、検索 & AI データアーキテクチャ pillar を参照してください。

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

運用面では、Kafka は高性能な TCP プロトコルを介して通信する サーバーとクライアント の分散システムです。ブローカーはデータを保存および提供し、クライアント（プロデューサーとコンシューマー）はイベントの書き込みと読み込みを行います。これらは通常、大規模かつフォールトトレラントに行われます。

CLI で繰り返し見かけるいくつかの概念があります：

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

Apache Kafka のインストール

Kafka の公式 Quickstart は、バイナリリリース（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 の公式 Quickstart は、バイナリ配布のダウンロードと展開から始まります：

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 イメージも提供しています。Quickstart では、以下のように Kafka 4.2.0 をプルして実行できることが示されています：

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

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

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 Quickstart は 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 つとして、自動フォーマットはエラー（特にメタデータログ周辺）を隠してしまう可能性があるため、明示的なフォーマットが推奨されます。

この Quickstart で実行されているもの

ローカル開発では、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 はコアライフサイクルのために使用されます：

  • トピックの作成、説明、リスト表示（Quickstart では --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

コンソールクライアントを使用したプロデュースとコンシューム

Quickstart では、コンソールプロデューサーとコンシューマーを使用して、検証とスモークテストに速く対応します：

  • 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 は、クライアントと他のブローカーにブローカーが広告するアドレスとして説明されており、バインドアドレスがクライアントが使用するべきアドレスと異なる場合に特に重要です。

今すぐ実行できる Quickstart 例

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

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

これは、Kafka 4.2 Quickstart の標準的な「作成、プロデュース、コンシューム」フローです。

ターミナル 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 の Quickstart では、ブローカーがイベントを永続的に保存し、イベントが複数回および複数のコンシューマーによって読み取られることができると説明しています。この永続性が、インストールまたはアップグレード後に最初に実行すべき Quickstart パターンである理由です。

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

Kafka Connect は、「すべてのカスタムプロデューサーとコンシューマーを作成せずに、データを Kafka へ入り、出しするにはどうすればよいか」という定期的な質問に答えます。Kafka Connect の概要では、コネクタを介して Kafka と他のシステムの間のスケーラブルで信頼性の高いストリーミングのためのツールとして説明されています。

Kafka 4.2 Quickstart には、ファイルソースとシンクコネクタを使用した最小限のローカル 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 設定がどこにあるか（ワーカー構成 plus コネクタ構成）を教えてくれるだけでなく、最小限の「取り込み、保存、エクスポート」ループを示すため、素晴らしい筋肉記憶の構築になります。

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

ほとんどの「Kafka Quickstart が起動しない」問題は、いくつかの根本原因に分類されます。

ブローカーが起動しない

公式要件から始めます：

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

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

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 外（または別のマシン）にある場合、正しいリスナー広告が必要になる可能性があります。ブローカー設定ドキュメントでは、advertised.listeners は、クライアントが接続すべきアドレスがバインドアドレス（listeners）と異なる場合に使用されると説明されています。

Quickstart の後に行くべき場所

この投稿の例を完了した場合、最も一般的な最初の検索に対する答えをすでに得ています：

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

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

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