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 つの end-to-end 例で締めくくります。

distributed message processing infographic apache kafka

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

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

Kafka は 1 つのプラットフォームに 3 つの主要機能を統合しています：イベントストリームの 公開と購読（publish and subscribe）、必要に応じてストリームの永続的な 保存（store）、およびストリームの発生時または事後の 処理（process）。この組み合わせこそが、Kafka がリアルタイムデータパイプライン、統合、メッセージング、ストリーミング分析に使用される理由です。

Kafka が広範なデータインフラストラクチャにおける位置づけに関する背景情報については、S3 互換オブジェクトストレージ、PostgreSQL アーキテクチャ、Elasticsearch の最適化、AI ネイティブデータレイヤーをカバーする、AI システム向けデータインフラストラクチャ：オブジェクトストレージ、データベース、検索 & AI データアーキテクチャ の柱を参照してください。

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

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

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

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

  • トピック（Topics） はイベントを整理します。トピックはマルチプロデューサーかつマルチサブスクライバーであり、保持ポリシーが古いデータの破棄時期を制御するため、イベントは複数回読み取ることも可能です。
  • パーティション（Partitions） はスケーラビリティのためにトピックをブローカー間でシャードします。パーティションごとの順序は保証されます。
  • レプリケーションファクター（Replication factor） はフォルトトランスを制御します。ドキュメントの例では、本番環境でレプリケーションファクター 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 Improvement Proposal では、これを 実験的 であり、本番環境ではなくローカル開発とテストに意図されていると説明しています。

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. サーバーを起動
# クラスタ UUID を生成
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# ログディレクトリをフォーマット（スタンドアロンローカルフォーマット）
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

# Kafka ブローカーを起動
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 例

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

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

これは 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 の設定がどこにあるか（ワーカ設定とコネクタ設定）を学び、「取り込み、保存、エクスポート」ループを最小限に示すため、記憶の筋肉を鍛えるのに最適な例です。

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

「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 デモの実行とコンソールコンシューマーによる結果の検査を示しています）。