ローカル環境でApache Kafkaクラスター構築ガイド

ローカル環境でのApache Kafkaクラスター構築の目的とアプローチ

ローカル環境でApache Kafkaクラスターを構築する目的は、リアルタイムデータ処理のテストや学習用に安定した環境を提供することです。2026年現在では、ZooKeeper連携型とKRaftモード対応型の2つの主要なアプローチが存在します。両者には以下のような違いがあります。

本記事では、Docker Composeを用いて両方の構成方法を具体的に解説し、ローカル環境でのテスト開始が簡単になるようにします。

DockerとDocker Composeのインストール確認手順

ローカルでKafkaクラスターを構築するには、まずDockerとDocker Composeが正しく動作していることを確認しましょう。OSによってコマンドが異なるため、対応する手順を実施してください。

• macOSの場合:
  bash
docker --version
docker-compose --version
  出力例: Docker version 26.1.3, docker-compose version v2.25.0

• Linux（Ubuntuなど）の場合:
  bash
sudo systemctl status docker
docker-compose --version
  Dockerサービスが実行中であれば、active (running)と表示されます。

OSごとのDocker Composeバージョン依存性に注意。macOSはv2.25.0、Linuxではv2.17以降で動作確認済みです。

Docker Composeのバージョンは、v2.x以降でKafkaコンテナの起動に必要です。確認後、次節で具体的な構築手順に進みましょう。

ZooKeeper連携型Kafkaクラスター構築手順

ZooKeeperとKafkaを連携させる方法は、ローカル開発環境ではよく使われるアプローチです。以下にdocker-compose.ymlファイルの例とポート設定・環境変数の役割を解説します。

docker-compose.ymlファイル構成例

下記の内容をdocker-compose.ymlファイルとして保存してください。この構成は、ZooKeeperコンテナとKafkaコンテナをそれぞれ起動するものです。

ポート設定と環境変数の役割

• ポート設定:
• 2181はZooKeeperの通信用ポート。
• 9092はKafkaのプロトコル通信用ポート。
• 重要環境変数:
• KAFKA_ADVERTISED_HOST_NAME: 外部からアクセスする際のホスト名（例: localhost）を指定。
• KAFKA_ZOOKEEPER_CONNECT: ZooKeeperの接続先（例: zookeeper:2181）。

この構成で、docker-compose up -dと実行すれば、ローカルにZooKeeper連携型のKafkaクラスターが起動します。

KRaftモード対応型Kafkaクラスター構築手順

Apache Kafka 3.0以降では、KRaftモード（Kafka Raft Metadata Mode）という、ZooKeeperを不要とする新方式が導入されました。ここではその設定方法と注意点を解説します。

KRaftモード導入時の注意点

• ストレージディレクトリの永続化: 上記構成では./kraft-storageにデータを保存していますが、ローカル環境での再起動時にデータが残るよう、ボリュームマウントを必ず設定する必要があります。

• 初期化コマンド:
  bash
docker-compose run kafka bash -c "/opt/kafka/bin/kraft-tools.sh --bootstrap-server localhost:19092 --create-metadata-quorum"
  この手順で、KRaftモードのメタデータクォラムを初期化します（以前はlocalhost:19091が使用されていましたが、正しいポートは19092に修正しました）。

• ZooKeeperからKRaftへの移行: 現在運用中のクラスターからKRaftに移行する場合、完全なバックアップとテスト環境での確認が必須です。

クラスター構成確認と基本操作コマンド

クラスターの構築後は、動作しているかを確認し、必要に応じてトピックを作成します。

トピック作成・確認コマンド

Kafkaクラスターが正常に起動していることを確認するために、以下のようにkafka-topics.shを実行します。

このコマンドで、test-topicという名前のトピックが作成されます。確認は以下のようにします。

クラスターステータスチェック

KRaftモードの場合、以下のコマンドでステータスを確認できます。

このコマンドは、クラスター内のノードとその役割（ブローカー/コンテナ）を表示します。ポート接続の検証にはtelnet localhost 9092やnc -zv localhost 9092を使うのも有効です。

KRaftモード導入時の主要な制約とベストプラクティス

KRaftモードはZooKeeperを不要とするため、ローカル環境での構築が簡単ですが、いくつかの制約や注意点があります。

• データディレクトリの永続化: ローカルテストでも、ストレージボリュームをマウントしないとデータが失われるため、./kraft-storageなどのローカルパスに保存するようにしてください。
• ローカル環境でのデータ保持方法: 実験的な構築では、docker-compose down時にデータを削除しないよう、volumes:でマウントしたディレクトリを永続的に保つ必要があります。
• ZooKeeperからKRaftへの移行時の注意点: 既存のクラスターからKRaftモードに移行する際は、すべてのノードが同じバージョンを使用していることを確認し、データの整合性検証を必ず実施してください。

KRaftモードは将来的な推奨アプローチですが、ローカル環境での利用には慎重さが必要です。特に、クラスター構成の理解が深まれば、より安定した運用が可能になります。

ローカル環境構築時のよくあるミスと対処法

ローカル環境でKafkaを構築する際のよくあるエラーとその対処策を整理します。

これらのエラーは、構築手順を厳密に守らないと発生します。特にKRaftモードではストレージボリュームのマウントとポート設定の整合性に注意が必要です。