Contents
Apache Kafka の基本概念
Kafka は分散型ストリーミングプラットフォームで、リアルタイムに大量のイベントを永続化しつつ高速に配信できます。本セクションではハンズオンで必ず触れる ブローカー・トピック・パーティション・コンシューマーグループ の４要素について、概念と役割を簡潔に整理します。これらの理解があることで、以降の実装手順や障害対応が格段に楽になります。
ブローカー
ブローカーはメッセージを書き込むサーバーで、クラスタ内に複数配置することで冗長性とスケールアウトを実現します。各ブローカーは独自の ID を持ち、リーダー／フォロワーというレプリケーション構成でデータを保護します。
トピック
トピックは同種メッセージの論理的集合です。名前で一意に管理され、プロデューサが書き込み、コンシューマが読み取ります。ハンズオンでは demo-topic を作成して実際にデータを流します。
パーティション
トピックは 0 個以上のパーティションに分割されます。各パーティションは独立した順序付けられたログであり、並列処理とスループット向上の鍵となります。パーティション数を増やすほどコンシューマ側の水平拡張が可能です。
コンシューマーグループ
同一トピックに対して複数のコンシューマが協調して読み取る仕組みです。グループ内でパーティションが自動的に割り当てられ、同じメッセージが重複して処理されないようにします。
これら四要素は Kafka の全体像を把握する上での土台となります。次の章では実際にローカル環境を構築し、ハンズオンで操作できる状態に持っていきます。
ハンズオン環境の前提条件とインストール手順
本セクションではローカルマシン上で Kafka を動かすために必要なツールと推奨バージョンを整理し、OS 別のインストールコマンド例を示します。事前に環境を整えておくことで、ハンズオン開始時のトラブルを最小限に抑えることができます。
必要なソフトウェアと推奨バージョン
| ソフトウェア | 推奨バージョン（2024‑11 時点） |
|---|---|
| Docker Engine | 24.0 系以上 |
| Docker Compose (プラグイン形式) | 2.20 系以上 |
| OpenJDK | 17 以上（21 が最新の LTS） |
Kafka CLI (kafka-topics.sh 等) |
Confluent Platform 8.0 系（Kafka 3.7.x） |
バージョンは執筆時点の最新安定版です。インストール前に公式サイトで最新版を確認してください。
macOS のインストール例（Homebrew）
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# Docker Desktop (Compose 含む) brew install --cask docker # OpenJDK 17（または 21） brew install openjdk@17 sudo ln -sfn $(brew --prefix)/opt/openjdk@17/libexec/openjdk.jdk \ /Library/Java/JavaVirtualMachines/openjdk-17.jdk # Kafka CLI (Confluent Platform のバイナリ取得) curl -L https://packages.confluent.io/archive/8.0/confluent-community-8.0.0.tar.gz | tar xz export PATH=$PWD/confluent-8.0.0/bin:$PATH |
Ubuntu のインストール例（apt）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# Docker Engine と Compose Plugin sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg lsb-release curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \ sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gcr echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gcr] \ https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # OpenJDK 17 sudo apt-get install -y openjdk-17-jdk # Kafka CLI（Confluent Platform） curl -L https://packages.confluent.io/archive/8.0/confluent-community-8.0.0.tar.gz | tar xz export PATH=$PWD/confluent-8.0.0/bin:$PATH |
インストール後は
docker version、docker compose version、java -versionを実行してそれぞれのバージョンが期待通りであることを確認してください。
Docker Compose でローカル Kafka クラスター構築（KRaft モード対応）
Confluent が提供する公式イメージは KRaft (Kafka Raft) モード をデフォルトとしており、Zookeeper を使用しない構成が推奨されています。本セクションでは KRaft モードと従来の Zookeeper 併用モードの両方を示し、目的に合わせて選択できるようにします。
1. KRaft（Zookeeper 非依存）でシングルブローカー構築
以下の docker-compose.yml は Confluent Platform 8.0 系のイメージを使用し、KRaft モードだけで起動する最小構成です。設定項目は必要最低限に抑えているため、数秒でクラスターが利用可能になります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
version: "3.8" services: kafka: image: confluentinc/cp-kafka:8.0.0 container_name: kafka ports: - "9092:9092" environment: KAFKA_NODE_ID: 1 KAFKA_PROCESS_ROLES: broker,controller KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093 KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093 KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092 KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1 KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1 KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:9092"] interval: 10s timeout: 5s retries: 5 |
起動手順
|
1 2 3 |
docker compose up -d # バックグラウンドでサービス開始 docker compose ps # コンテナの状態確認 |
KRaft モードは将来的に Zookeeper 完全撤廃が予定されているため、長期的な学習・実装ではこちらを優先してください。
2. 従来通り Zookeeper を併用した構成（参考）
レガシー環境や既存システムとの互換性が必要な場合は、以下のように Zookeeper コンテナと連携させることも可能です。この記事では学習目的でのみ掲載しています。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
version: "3.8" services: zookeeper: image: confluentinc/cp-zookeeper:8.0.0 container_name: zookeeper ports: - "2181:2181" environment: ZOOKEEPER_CLIENT_PORT: 2181 kafka: image: confluentinc/cp-kafka:8.0.0 container_name: kafka depends_on: - zookeeper ports: - "9092:9092" environment: KAFKA_BROKER_ID: 1 KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181 KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092 KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1 |
将来的にはこの構成は非推奨になる可能性が高いため、学習後は必ず KRaft モードへの移行を検討してください。
正常起動の確認
-
ログチェック
bash
docker logs kafka | grep "started"
「Kafka start」や「Successfully started」 が出力されれば正常です。 -
ブローカー接続テスト
bash
nc -zv localhost 9092 && echo "Port open" -
KRaft のコントローラ状態確認（KRaft 使用時）
bash
docker exec kafka /usr/bin/kafka-metadata-shell.sh --bootstrap-server localhost:9092 --describe
トピック作成・メッセージ送受信・典型的エラー対処
CLI ツールだけで Kafka の基本操作が完結します。ここではトピックの作成、コンソールプロデューサ／コンシューマによるメッセージのやり取り、そしてハンズオン中に遭遇しやすいエラーとその対処法をまとめます。
トピック作成
以下コマンドはローカルブローカー（KRaft）に demo-topic を 3 パーティションで作成する例です。レプリケーション係数はシングルブローカー環境では 1 に設定してください。
|
1 2 3 4 5 6 7 |
kafka-topics.sh \ --bootstrap-server localhost:9092 \ --create \ --topic demo-topic \ --partitions 3 \ --replication-factor 1 |
コンソールプロデューサ
標準入力からメッセージを送信できます。Enter キーで改行ごとに１件がブローカーへ書き込まれます。
|
1 2 3 4 |
kafka-console-producer.sh \ --broker-list localhost:9092 \ --topic demo-topic |
Hello Kafkaと入力して Enter → メッセージ送信完了です。
コンソールコンシューマ（別タブで実行）
トピックの先頭から全メッセージをリアルタイムに取得します。
|
1 2 3 4 5 |
kafka-console-consumer.sh \ --bootstrap-server localhost:9092 \ --topic demo-topic \ --from-beginning |
典型的エラーと対処法
| エラー | 主な原因 | 推奨対策 |
|---|---|---|
Port already in use (Address already in use) |
同一ポートが他プロセスで占有中 | docker compose down 後、lsof -i :9092 で占有プロセスを特定し停止 |
| Out‑of‑Memory (OOM) キラー発動 | Docker に割り当てたメモリが不足 | Docker Desktop の設定でメモリ上限を 4 GB 以上 に増やす |
| Failed to connect to node | advertised.listeners が正しく設定されていない |
環境変数 KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092 を確認し、再起動 |
| Replication factor larger than number of brokers | レプリケーション係数がブローカー数を超えている | シングルブローカーでは --replication-factor 1 に固定 |
ハンズオン後のクリーンアップ
|
1 2 3 |
docker compose down --volumes # コンテナと永続ボリュームを削除 docker system prune -f # 未使用イメージ・ネットワークを整理 |
クリーンな状態に戻すことで、次回の実験や別プロジェクトへの切り替えがスムーズになります。
マネージドサービスへの拡張：Confluent Cloud と Amazon MSK
ローカル環境で基礎を習得したら、実運用に近いマネージド Kafka に挑戦しましょう。ここでは 2024 年時点で確認できる公式情報を元に、Confluent Cloud の無料トライアル と Amazon MSK の基本セットアップ手順を概観します。
Confluent Cloud（SaaS 型）
- 公式サイトでサインアップ → 無料クレジットが付与されます。
- クラスタ作成後、画面左側の 「Cluster」→「Details」 から Bootstrap servers と API Key / Secret を取得します。
- 認証情報は環境変数またはプロパティファイルに保存し、ローカル CLI と同様に操作できます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
export KAFKA_BOOTSTRAP_SERVERS="pkc-xxxxx.us-east-1.aws.confluent.cloud:9092" export KAFKA_SASL_USERNAME="<API_KEY>" export KAFKA_SASL_PASSWORD="<API_SECRET>" cat > client.properties <<EOF security.protocol=SASL_SSL sasl.mechanism=PLAIN sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="${KAFKA_SASL_USERNAME}" password="${KAFKA_SASL_PASSWORD}"; EOF kafka-topics.sh --bootstrap-server $KAFKA_BOOTSTRAP_SERVERS \ --command-config client.properties \ --create --topic cloud-demo --partitions 2 --replication-factor 3 |
注意：外部リンクは執筆時点の URL を使用していますが、将来的に変更される可能性があります。必ず公式ドキュメントで最新情報を確認してください。
Amazon Managed Streaming for Apache Kafka (MSK)
- AWS コンソールから Amazon MSK を選択し、ウィザードに従ってクラスタ作成。推奨設定は
kafka.t3.smallインスタンスタイプ、パーティション数 2、レプリケーション係数 3 です。 - 作成完了後、Bootstrap servers と IAM 認証情報 が表示されます。MSK は IAM ベースの認証がデフォルトなので、以下コマンドで一時的なトークンを取得します。
|
1 2 3 4 |
aws kafka get-bootstrap-brokers --cluster-arn <your-cluster-arn> \ --query 'BootstrapBrokerStringSaslIam' --output text # 例: b-1.mskcluster.xxxxxx.kafka.us-east-1.amazonaws.com:9098,b-2... |
- IAM 認証用プロパティファイルを作成し、CLI に渡します。
|
1 2 3 4 5 6 7 8 9 10 |
cat > iam-client.properties <<EOF security.protocol=SASL_SSL sasl.mechanism=AWS_MSK_IAM sasl.jaas.config=software.amazon.msk.auth.iam.IAMLoginModule required; EOF kafka-topics.sh --bootstrap-server <bootstrap-servers> \ --command-config iam-client.properties \ --create --topic msk-demo --partitions 2 --replication-factor 3 |
共通ベストプラクティス
| 項目 | 推奨設定 |
|---|---|
| 認証情報管理 | 環境変数または .properties に分離し、Git には絶対にコミットしない |
| ネットワーク | VPC エンドポイント（MSK）や Private Link（Confluent Cloud）を利用してレイテンシとセキュリティを最適化 |
| 監視・メトリクス | CloudWatch（MSK）／Confluent Metrics API を活用し、ブローカー・トピックのヘルスチェックを自動化 |
ローカルで習得した CLI 操作はクラウドでもほぼ同一なので、学習コストが低く、すぐに本番レベルのストリーミング基盤へ移行できます。
まとめ
- 基本概念：ブローカー・トピック・パーティション・コンシューマーグループを理解すると、Kafka の全体像が把握しやすくなります。
- 環境構築：Docker Compose と最新の Confluent Platform イメージ（KRaft モード推奨）で 3 分以内にローカルクラスターを起動できます。
- 操作手順：
kafka-topics.sh、kafka-console-producer/consumerを使えばトピック作成からメッセージ送受信まで CLI のみで完結します。 - エラー対策：ポート競合・メモリ不足・リスナー設定ミスなどのチェックリストを活用し、迅速に復旧できます。
- マネージド拡張：Confluent Cloud と Amazon MSK のセットアップ例を示したので、ローカルで学んだ知見をそのままクラウド環境へ適用可能です。
以上のステップを順に実践すれば、Kafka 初心者でも実務レベルのストリーミング処理を自信を持って扱えるようになります。ぜひローカルとクラウド両方でハンズオンを体験し、次のデータ駆動プロジェクトに活かしてください。