RHEL での AMQ Streams の使用


Red Hat AMQ 2020.Q4

AMQ Streams 1.6 on Red Hat Enterprise Linux 向け

概要

本ガイドでは、Red Hat AMQ Streams をインストール、設定、および管理して、大規模なメッセージングネットワークを構築する方法を説明します。

第1章 AMQ Streams の概要

Red Hat AMQ Streams は、Apache ZooKeeper および Apache Kafka プロジェクトをベースとした、スケーラビリティーが高く、分散され、高パフォーマンスのデータストリーミングプラットフォームです。

主なコンポーネントは以下で構成されます。

Kafka Broker

生成クライアントから消費側のクライアントにレコードを配信するメッセージングブローカー。

Apache ZooKeeper は Kafka のコア依存関係で、高信頼性の分散調整のためのクラスター調整サービスを提供します。

Kafka Streams API
ストリームプロセッサー アプリケーションを作成するための API。
プロデューサーおよびコンシューマー API
Kafka ブローカーとの間でメッセージを生成および消費するための Java ベースの API。
Kafka Bridge
AMQ Streams Kafka Bridge では、HTTP ベースのクライアントと Kafka クラスターとの対話を可能にする RESTful インターフェイスが提供されます。
Kafka Connect
Connector プラグインを使用して、Kafka ブローカーと他のシステム間でデータをストリーミングするツールキット。
Kafka MirrorMaker
データセンター内またはデータセンター全体の 2 つの Kafka クラスター間でデータをレプリケートします。
Kafka Exporter
監視用に Kafka メトリクスデータの抽出に使用されるエクスポーター。

Kafka ブローカーのクラスターは、これらのすべてのコンポーネントを接続するハブです。ブローカーは、設定データの保存やクラスターの調整に Apache ZooKeeper を使用します。Apache Kafka の実行前に、Apache ZooKeeper クラスターを用意する必要があります。

図1.1 AMQ Streams のアーキテクチャー

AMQ Streams のアーキテクチャー

1.1. Kafka の機能

Kafka の基盤のデータストリーム処理機能とコンポーネントアーキテクチャーによって以下が提供されます。

  • スループットが非常に高く、レイテンシーが低い状態でデータを共有するマイクロサービスおよびその他のアプリケーション
  • メッセージの順序の保証
  • アプリケーションの状態を再構築するためにデータストレージからメッセージを巻き戻し/再生
  • キーバリューログの使用時に古いレコードを削除するメッセージ圧縮
  • クラスター設定での水平スケーラビリティー
  • 耐障害性を制御するデータのレプリケーション
  • 即時アクセス用の大量データの保持

1.2. Kafka のユースケース

Kafka の機能は、以下に適しています。

  • イベント駆動型のアーキテクチャー
  • アプリケーションの状態に加えられた変更をイベントのログとしてキャプチャーするイベントソーシング
  • メッセージのブローカー
  • Web サイトアクティビティーの追跡
  • メトリクスによる運用上のモニタリング
  • ログの収集および集計
  • 分散システムのコミットログ
  • アプリケーションがリアルタイムでデータに対応できるようにするストリーム処理

1.3. サポートされる構成

AMQ Streams をサポートされる構成で実行するには、以下の JVM バージョンの 1 つと、サポートされるオペレーティングシステムの 1 つで実行する必要があります。

表1.1 サポートされる Java 仮想マシンの一覧
Java 仮想マシンバージョン

OpenJDK

1.8、11

OracleJDK

1.8

IBM JDK

1.8

表1.2 サポートされるオペレーティングシステムの一覧
オペレーティングシステムアーキテクチャーバージョン

Red Hat Enterprise Linux

x86_64

7.x、8.x

1.4. 本書の表記慣例

置き換え可能なテキスト

本書では、置き換え可能なテキストは、monospace フォントのイタリック体、大文字、およびハイフンで記載されています。

たとえば、以下のコードでは、BOOTSTRAP-ADDRESS および TOPIC-NAME を実際のアドレスおよびトピック名に置き換えます。

bin/kafka-console-consumer.sh --bootstrap-server BOOTSTRAP-ADDRESS --topic TOPIC-NAME --from-beginning

第2章 はじめに

2.1. AMQ Streams のディストリビューション

AMQ Streams は単一の ZIP ファイルとして配布されます。この ZIP ファイルには AMQ Streams コンポーネントが含まれます。

2.2. AMQ Streams アーカイブのダウンロード

AMQ Streams のアーカイブディストリビューションは、Red Hat の Web サイトからダウンロードできます。以下の手順に従うと、ディストリビューションのコピーをダウンロードできます。

手順

2.3. AMQ Streams のインストール

以下の手順に従って、Red Hat Enterprise Linux に最新バージョンの AMQ Streams をインストールします。

既存のクラスターを AMQ Streams 1.6 にアップグレードする手順は、「 AMQ Streams および Kafka のアップグレード 」を参照してください。

前提条件

手順

  1. 新しい kafka ユーザーおよびグループを追加します。

    sudo groupadd kafka
    sudo useradd -g kafka kafka
    sudo passwd kafka
  2. /opt/kafka ディレクトリーの作成

    sudo mkdir /opt/kafka
  3. 一時ディレクトリーを作成し、AMQ Streams ZIP ファイルの内容を展開します。

    mkdir /tmp/kafka
    unzip amq-streams_y.y-x.x.x.zip -d /tmp/kafka
  4. 展開した内容を /opt/kafka ディレクトリーに移動して、一時ディレクトリーを削除します。

    sudo mv /tmp/kafka/kafka_y.y-x.x.x/* /opt/kafka/
    rm -r /tmp/kafka
  5. /opt/kafka ディレクトリーの所有権を kafka ユーザーに変更します。

    sudo chown -R kafka:kafka /opt/kafka
  6. ZooKeeper データを格納する /var/lib/zookeeper ディレクトリーを作成し、その所有権を kafka ユーザーに設定します。

    sudo mkdir /var/lib/zookeeper
    sudo chown -R kafka:kafka /var/lib/zookeeper
  7. Kafka データを格納する /var/lib/kafka ディレクトリーを作成し、その所有権を kafka ユーザーに設定します。

    sudo mkdir /var/lib/kafka
    sudo chown -R kafka:kafka /var/lib/kafka

2.4. データストレージに関する留意事項

効率的なデータストレージインフラストラクチャーは、AMQ Streams のパフォーマンスを最適化するために不可欠です。

AMQ Streams ではブロックストレージが必要で、Amazon Elastic Block Store (EBS) などのクラウドベースのブロックストレージソリューションとうまく機能します。ファイルストレージの使用は推奨されていません。

可能な場合はローカルストレージを選択します。ローカルストレージが利用できない場合は、ファイバーチャネルや iSCSI などのプロトコルがアクセスする SAN (Storage Area Network) を使用できます。

2.4.1. Apache Kafka および ZooKeeper ストレージのサポート

Apache Kafka と ZooKeeper には別々のディスクを使用します。

Kafka は、複数のディスクまたはボリュームのデータストレージ設定である JBOD(Just a Bunch of Disks)ストレージをサポートします。JBOD は、Kafka ブローカーのデータストレージを増やします。また、パフォーマンスを向上することもできます。

ソリッドステートドライブ (SSD) は必須ではありませんが、複数のトピックに対してデータが非同期的に送受信される大規模なクラスターで Kafka のパフォーマンスを向上させることができます。SSD は、高速で低レイテンシーのデータアクセスが必要な ZooKeeper で特に有効です。

注記

Kafka と ZooKeeper の両方にデータレプリケーションが組み込まれているため、複製されたストレージのプロビジョニングは必要ありません。

2.4.2. ファイルシステム

XFS ファイルシステムを使用するようにストレージシステムを設定することが推奨されます。AMQ Streams は ext4 ファイルシステムとも互換性がありますが、最適な結果を得るには追加の設定が必要になることがあります。

関連情報

2.5. 単一ノードの AMQ Streams クラスターの実行

この手順では、単一の Apache ZooKeeper ノードと単一の Apache Kafka ノード (両方とも同じホストで実行されている) で構成される基本的な AMQ Streams クラスターを実行する方法を説明します。デフォルトの設定ファイルは ZooKeeper および Kafka に使用されます。

警告

単一ノードの AMQ Streams クラスターは、信頼性および高可用性を提供しないため、開発目的にのみ適しています。

前提条件

  • AMQ Streams がホストにインストールされている。

クラスターの実行

  1. ZooKeeper 設定ファイル /opt/kafka/config/zookeeper.properties を編集します。dataDir オプションを /var/lib/zookeeper/ に設定します。

    dataDir=/var/lib/zookeeper/
  2. Kafka 設定ファイル /opt/kafka/config/server.properties を編集します。log.dirs オプションを /var/lib/kafka/ に設定します。

    log.dirs=/var/lib/kafka/
  3. kafka ユーザーに切り替えます。

    su - kafka
  4. ZooKeeper を起動します。

    /opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties
  5. ZooKeeper が実行されていることを確認します。

    jcmd | grep zookeeper

    以下を返します。

    number org.apache.zookeeper.server.quorum.QuorumPeerMain /opt/kafka/config/zookeeper.properties
  6. Kafka を起動します。

    /opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties
  7. Kafka が稼働していることを確認します。

    jcmd | grep kafka

    以下を返します。

    number kafka.Kafka /opt/kafka/config/server.properties

関連情報

2.6. クラスターの使用

この手順では、Kafka コンソールプロデューサーおよびコンシューマークライアントを起動し、それらを使用して複数のメッセージを送受信する方法を説明します。

新しいトピックは、ステップ 1 で自動的に作成されます。トピックの自動作成 は、auto.create.topics.enable 設定プロパティーを使用して制御されます (デフォルトでは true に設定されます)。または、クラスターを使用する前にトピックを設定および作成することもできます。詳細は、「トピック」 を参照してください。

手順

  1. Kafka コンソールプロデューサーを起動し、メッセージを新しいトピックに送信するように設定します。

    /opt/kafka/bin/kafka-console-producer.sh --broker-list <bootstrap-address> --topic <topic-name>

    以下に例を示します。

    /opt/kafka/bin/kafka-console-producer.sh --broker-list localhost:9092 --topic my-topic
  2. コンソールに複数のメッセージを入力します。Enter を押して、各メッセージを新しいトピックに送信します。

    >message 1
    >message 2
    >message 3
    >message 4

    Kafka が新しいトピックを自動的に作成すると、トピックが存在しないという警告が表示される可能性があります。

    WARN Error while fetching metadata with correlation id 39 :
    {4-3-16-topic1=LEADER_NOT_AVAILABLE} (org.apache.kafka.clients.NetworkClient)

    この警告は、さらにメッセージを送信すると再度表示されなくなります。

  3. 新しいターミナルウィンドウで、Kafka コンソールコンシューマーを起動し、新しいトピックの最初からメッセージを読み取るように設定します。

    /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server <bootstrap-address> --topic <topic-name> --from-beginning

    以下に例を示します。

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

    受信メッセージがコンシューマーコンソールに表示されます。

  4. プロデューサーコンソールに切り替え、追加のメッセージを送信します。それらがコンシューマーコンソールに表示されていることを確認します。
  5. Ctrl+C を押して Kafka コンソールプロデューサーを停止し、コンシューマーを停止します。

2.7. AMQ Streams サービスの停止

スクリプトを実行して、Kafka および ZooKeeper サービスを停止できます。Kafka および ZooKeeper サービスへのすべての接続が終了します。

前提条件

  • AMQ Streams がホストにインストールされている。
  • ZooKeeper および Kafka が稼働している。

手順

  1. Kafka ブローカーを停止します。

    su - kafka
    /opt/kafka/bin/kafka-server-stop.sh
  2. Kafka ブローカーが停止していることを確認します。

    jcmd | grep kafka
  3. ZooKeeper を停止します。

    su - kafka
    /opt/kafka/bin/zookeeper-server-stop.sh

2.8. AMQ Streams の設定

前提条件

  • AMQ Streams がホストにダウンロードされ、インストールされている。

手順

  1. テキストエディターで ZooKeeper および Kafka ブローカー設定ファイルを開きます。設定ファイルは以下にあります。

    ZooKeeper
    /opt/kafka/config/zookeeper.properties
    Kafka
    /opt/kafka/config/server.properties
  2. 設定オプションを編集します。設定ファイルは Java プロパティー形式です。すべての設定オプションは、以下の形式で別々の行に指定する必要があります。

    <option> = <value>

    # または ! で始まる行はコメントとして処理され、AMQ Streams コンポーネントによって無視されます。

    # This is a comment

    改行/キャリッジリターンの直前で \ を使用して、値を複数の行に分割することができます。

    sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
        username="bob" \
        password="bobs-password";
  3. 変更を保存します。
  4. ZooKeeper または Kafka ブローカーを再起動します。
  5. クラスターのすべてのノードでこの手順を繰り返します。

第3章 ZooKeeper の設定

Kafka は ZooKeeper を使用して設定データを保存し、クラスターの連携を行います。レプリケートされた ZooKeeper インスタンスのクラスターを実行することが強く推奨されます。

3.1. 基本設定

最も重要な ZooKeeper 設定オプションは次のとおりです。

tickTime
Zoo Keeper の基本時間単位 (ミリ秒)。ハートビートとセッションのタイムアウトに使用されます。たとえば、最小セッションタイムアウトは 2 ティックになります。
dataDir
ZooKeeper がトランザクションログとインメモリーデータベースのスナップショットを保存するディレクトリー。これは、インストール時に作成された /var/lib/zookeeper/ ディレクトリーに設定する必要があります。
clientPort
クライアントが接続できるポート番号。デフォルトは 2181 です。

config/zookeeper.properties という名前の ZooKeeper 設定ファイルのサンプルは、AMQ Streams のインストールディレクトリーに置かれます。ZooKeeper でレイテンシーを最小限に抑えるために、別のディスクデバイスに dataDir ディレクトリーを配置することが推奨されます。

ZooKeeper 設定ファイルは /opt/kafka/config/zookeeper.properties に置く必要があります。設定ファイルの基本的な例は以下で確認できます。設定ファイルは kafka ユーザーが読み取りできる必要があります。

tickTime=2000
dataDir=/var/lib/zookeeper/
clientPort=2181

3.2. ZooKeeper クラスター設定

信頼できる ZooKeeper サービスでは、ZooKeeper をクラスターにデプロイする必要があります。そのため、実稼働のユースケースでは、レプリケートされた ZooKeeper インスタンスのクラスターを実行する必要があります。ZooKeeper クラスターは ensembles とも呼ばれます。

ZooKeeper クラスターは通常、奇数のノードで構成されます。ZooKeeper では、クラスター内のほとんどのノードが稼働している必要があります。以下に例を示します。

  • 3 つのノードで構成されるクラスターでは、少なくとも 2 つのノードが稼働している必要があります。これは、1 つのノードが停止していることを許容できることを意味します。
  • 5 つのノードで構成されるクラスターでは、最低でも 3 つのノードが利用可能である必要があります。これは、2 つのノードが停止していることを許容できることを意味します。
  • 7 つのノードで構成されるクラスターでは、最低でも 4 つのノードが利用可能である必要があります。これは、3 つのノードが停止していることを許容できることを意味します。

ZooKeeper クラスターにより多くのノードがあると、クラスター全体の回復性と信頼性が向上します。

ZooKeeper は、偶数のノードを持つクラスターで実行できます。ただし、追加のノードは、クラスターの回復性は向上しません。4 つのノードで構成されるクラスターでは、少なくとも 3 つのノードが利用可能で、1 つのノードがダウンしているノードのみを許容する必要があります。そのため、3 つのノードのみを持つクラスターと全く同じ回復性があります。

理想的には、異なる ZooKeeper ノードを異なるデータセンターまたはネットワークセグメントに置く必要があります。ZooKeeper ノードの数を増やすと、クラスターの同期に費やされたワークロードが増えます。ほとんどの Kafka のユースケースでは、3、5、または 7 つのノードで構成される ZooKeeper クラスターでは十分です。

警告

3 つのノードで構成される ZooKeeper クラスターは、利用できないノードを 1 つだけ許容できます。つまり、クラスターノードがクラッシュし、別のノードでメンテナンスを実施している場合、ZooKeeper クラスターが利用できなくなります。

レプリケートされた ZooKeeper 設定は、スタンドアロン設定でサポートされるすべての設定オプションをサポートします。クラスタリング設定にさらにオプションが追加されます。

initLimit
フォロワーがクラスターリーダーに接続して同期できるようにする時間。時間はティック数として指定されます (詳細は timeTick オプション を参照してください)。
syncLimit
フォロワーがリーダーの背後にあることのできる時間。時間はティック数として指定されます (詳細は timeTick オプション を参照してください)。
reconfigEnabled
動的再設定 を有効または無効にします。サーバーを ZooKeeper クラスターに追加または削除するには、有効にする必要があります。
standaloneEnabled
ZooKeeper が 1 つのサーバーでのみ実行されるスタンドアロンモードを有効または無効にします。

上記のオプションの他に、すべての設定ファイルに ZooKeeper クラスターのメンバーである必要があるサーバーの一覧が含まれている必要があります。サーバーレコードは server.id=hostname:port1:port2 の形式で指定する必要があります。ここで、

id
ZooKeeper クラスターノードの ID。
hostname
ノードが接続をリッスンするホスト名または IP アドレス。
port1
クラスター内通信に使用されるポート番号。
port2
リーダーエレクションに使用されるポート番号。

以下は、3 つのノードで構成される ZooKeeper クラスターの設定ファイルの例になります。

timeTick=2000
dataDir=/var/lib/zookeeper/
initLimit=5
syncLimit=2
reconfigEnabled=true
standaloneEnabled=false

server.1=172.17.0.1:2888:3888:participant;172.17.0.1:2181
server.2=172.17.0.2:2888:3888:participant;172.17.0.2:2181
server.3=172.17.0.3:2888:3888:participant;172.17.0.3:2181
注記

ZooKeeper 3.5.7 では、使用する前に、許可リストに 4 文字のコマンド を追加する必要があります。詳細は、Zoo Keeper のドキュメント を参照してください。

myid ファイル

ZooKeeper クラスターの各ノードには、一意の ID を割り当てる必要があります。各ノードの IDmyid ファイルで設定し、/var/lib/zookeeper/ のように dataDir フォルダーに保存する必要があります。myid ファイルには、テキストとして ID が記述された単一行のみが含まれている必要があります。ID には、1 から 255 までの任意の整数を指定することができます。このファイルは、各クラスターノードに手動で作成する必要があります。このファイルを使用すると、各 ZooKeeper インスタンスは設定ファイルの対応する server. 行の設定を使用して、そのリスナーを設定します。また、他の server. 行すべてを使用して、他のクラスターメンバーを特定します。

上記の例では、3 つのノードがあるので、各ノードは値がそれぞれ 12、および 3 の異なる myid を持ちます。

3.3. マルチノードの ZooKeeper クラスターの実行

この手順では、ZooKeeper をマルチノードクラスターとして設定し、実行する方法を説明します。

注記

ZooKeeper 3.5.7 では、使用する前に、許可リストに 4 文字のコマンド を追加する必要があります。詳細は、Zoo Keeper のドキュメント を参照してください。

前提条件

  • AMQ Streams が、ZooKeeper クラスターノードとして使用されるすべてのホストにインストールされている。

クラスターの実行

  1. /var/lib/zookeeper/myid ファイルを作成します。最初の ZooKeeper ノードに ID 1 を、2 番目の ZooKeeper ノードに 2 を、それぞれ入力します。

    su - kafka
    echo "<NodeID>" > /var/lib/zookeeper/myid

    以下に例を示します。

    su - kafka
    echo "1" > /var/lib/zookeeper/myid
  2. ZooKeeper 設定ファイル /opt/kafka/config/zookeeper.properties を編集します。

    • dataDir オプションを /var/lib/zookeeper/ に設定します。
    • initLimit および syncLimit オプションを設定します。
    • reconfigEnabled および standaloneEnabled オプションを設定します。
    • すべての ZooKeeper ノードの一覧を追加します。この一覧には、現在のノードも含まれている必要があります。

      5 つのメンバーを持つ ZooKeeper クラスターのノードの設定例

      timeTick=2000
      dataDir=/var/lib/zookeeper/
      initLimit=5
      syncLimit=2
      reconfigEnabled=true
      standaloneEnabled=false
      
      server.1=172.17.0.1:2888:3888:participant;172.17.0.1:2181
      server.2=172.17.0.2:2888:3888:participant;172.17.0.2:2181
      server.3=172.17.0.3:2888:3888:participant;172.17.0.3:2181
      server.4=172.17.0.4:2888:3888:participant;172.17.0.4:2181
      server.5=172.17.0.5:2888:3888:participant;172.17.0.5:2181

  3. デフォルトの設定ファイルで ZooKeeper を起動します。

    su - kafka
    /opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties
  4. ZooKeeper が稼働していることを確認します。

    jcmd | grep zookeeper
  5. クラスターのすべてのノードでこの手順を繰り返します。
  6. クラスターのすべてのノードが稼働したら、ncat ユーティリティーを使用して stat コマンドを各ノードに送信して、すべてのノードがクラスターのメンバーであることを確認します。

    ncat stat を使用してノードのステータスを確認します。

    echo stat | ncat localhost 2181

    この出力に、ノードが leader または follower のいずれかである情報が表示されるはずです。

    ncat コマンドの出力例

    ZooKeeper version: 3.4.13-2d71af4dbe22557fda74f9a9b4309b15a7487f03, built on 06/29/2018 00:39 GMT
    Clients:
     /0:0:0:0:0:0:0:1:59726[0](queued=0,recved=1,sent=0)
    
    Latency min/avg/max: 0/0/0
    Received: 2
    Sent: 1
    Connections: 1
    Outstanding: 0
    Zxid: 0x200000000
    Mode: follower
    Node count: 4

関連情報

3.4. 認証

デフォルトでは、ZooKeeper はどのような認証も使用せず、匿名の接続を許可します。ただし、Simple Authentication and Security Layer(SASL)を使用した認証の設定に使用できる Java Authentication and Authorization Service (JAAS) をサポートします。ZooKeeper は、ローカルに保存されたクレデンシャルと DIGEST-MD5 SASL メカニズムを使用した認証をサポートします。

3.4.1. SASL を使用した認証

JAAS は個別の設定ファイルを使用して設定されます。JAAS 設定ファイルを ZooKeeper 設定と同じディレクトリー (/opt/kafka/config/) に置くことが推奨されます。推奨されるファイル名は zookeeper-jaas.conf です。複数のノードで ZooKeeper クラスターを使用する場合は、JAAS 設定ファイルをすべてのクラスターノードで作成する必要があります。

JAAS はコンテキストを使用して設定されます。サーバーとクライアントなどの個別の部分は、常に別の コンテキスト で設定されます。コンテキストは 設定 オプションで、以下の形式となっています。

ContextName {
       param1
       param2;
};

SASL 認証は、サーバー間通信 (Zoo Keeper インスタンス間の通信) とクライアント間通信 (Kafka と Zoo Keeper 間の通信) に対して別々に構成されます。サーバー間の認証は、複数のノードを持つ ZooKeeper クラスターにのみ関連します。

サーバー間の認証

サーバー間の認証では、JAAS 設定ファイルには 2 つの部分が含まれます。

  • サーバー設定
  • クライアント設定

DIGEST-MD5 SASL メカニズムを使用する場合、認証サーバーの設定に QuorumServer コンテキストが使用されます。暗号化されていない形式で、接続できるすべてのユーザー名とパスワードが含まれている必要があります。2 つ目のコンテキスト QuorumLearner は、ZooKeeper に組み込まれるクライアント用に設定する必要があります。また、暗号化されていない形式のパスワードも含まれます。DIGEST-MD5 メカニズムの JAAS 設定ファイルの例は、以下を参照してください。

QuorumServer {
       org.apache.zookeeper.server.auth.DigestLoginModule required
       user_zookeeper="123456";
};

QuorumLearner {
       org.apache.zookeeper.server.auth.DigestLoginModule required
       username="zookeeper"
       password="123456";
};

JAAS 設定ファイルの他に、以下のオプションを指定して、通常の ZooKeeper 設定ファイルでサーバー間の認証を有効にする必要があります。

quorum.auth.enableSasl=true
quorum.auth.learnerRequireSasl=true
quorum.auth.serverRequireSasl=true
quorum.auth.learner.loginContext=QuorumLearner
quorum.auth.server.loginContext=QuorumServer
quorum.cnxn.threads.size=20

KAFKA_OPTS 環境変数を使用して、JAAS 設定ファイルを Java プロパティーとして ZooKeeper サーバーに渡します。

su - kafka
export KAFKA_OPTS="-Djava.security.auth.login.config=/opt/kafka/config/zookeeper-jaas.conf"; /opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties

サーバー間の認証の詳細は、ZooKeeper Wiki を参照してください。

クライアント/サーバー間の認証

クライアント/サーバー間の認証は、サーバー間の認証と同じ JAAS ファイルで設定されます。ただし、サーバー間の認証とは異なり、サーバー設定のみが含まれます。設定のクライアント部分は、クライアントで実行する必要があります。認証を使用して ZooKeeper に接続するように Kafka ブローカーを設定する方法は、Kafka インストール セクションを参照してください。

JAAS 設定ファイルにサーバーコンテキストを追加して、クライアント/サーバー間の認証を設定します。DIGEST-MD5 メカニズムの場合は、すべてのユーザー名とパスワードを設定します。

Server {
    org.apache.zookeeper.server.auth.DigestLoginModule required
    user_super="123456"
    user_kafka="123456"
    user_someoneelse="123456";
};

JAAS コンテキストの設定後、以下の行を追加して ZooKeeper 設定ファイルでクライアント/サーバー間の認証を有効にします。

requireClientAuthScheme=sasl
authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
authProvider.2=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
authProvider.3=org.apache.zookeeper.server.auth.SASLAuthenticationProvider

ZooKeeper クラスターの一部であるすべてのサーバーに authProvider.<ID> プロパティーを追加する必要があります。

KAFKA_OPTS 環境変数を使用して、JAAS 設定ファイルを Java プロパティーとして ZooKeeper サーバーに渡します。

su - kafka
export KAFKA_OPTS="-Djava.security.auth.login.config=/opt/kafka/config/zookeeper-jaas.conf"; /opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties

Kafka ブローカーでの ZooKeeper 認証の設定に関する詳細は、「ZooKeeper の認証」 を参照してください。

3.4.2. DIGEST-MD5 を使用したサーバー間の認証の有効化

この手順では、ZooKeeper クラスターのノード間で SASL DIGEST-MD5 メカニズムを使用した認証を有効にする方法を説明します。

前提条件

  • AMQ Streams がホストにインストールされている。
  • ZooKeeper クラスターが複数のノードで 設定 されている。

SASL DIGEST-MD5 認証の有効化

  1. すべての ZooKeeper ノードで、/opt/kafka/config/zookeeper-jaas.conf JAAS 設定ファイルを作成または編集し、以下のコンテキストを追加します。

    QuorumServer {
           org.apache.zookeeper.server.auth.DigestLoginModule required
           user_<Username>="<Password>";
    };
    
    QuorumLearner {
           org.apache.zookeeper.server.auth.DigestLoginModule required
           username="<Username>"
           password="<Password>";
    };

    ユーザー名とパスワードは両方の JAAS コンテキストで同一である必要があります。以下に例を示します。

    QuorumServer {
           org.apache.zookeeper.server.auth.DigestLoginModule required
           user_zookeeper="123456";
    };
    
    QuorumLearner {
           org.apache.zookeeper.server.auth.DigestLoginModule required
           username="zookeeper"
           password="123456";
    };
  2. すべての ZooKeeper ノードで、/opt/kafka/config/zookeeper.properties ZooKeeper 設定ファイルを編集し、以下のオプションを設定します。

    quorum.auth.enableSasl=true
    quorum.auth.learnerRequireSasl=true
    quorum.auth.serverRequireSasl=true
    quorum.auth.learner.loginContext=QuorumLearner
    quorum.auth.server.loginContext=QuorumServer
    quorum.cnxn.threads.size=20
  3. すべての ZooKeeper ノードを 1 つずつ再起動します。JAAS 設定を ZooKeeper に渡すには、KAFKA_OPTS 環境変数を使用します。

    su - kafka
    export KAFKA_OPTS="-Djava.security.auth.login.config=/opt/kafka/config/zookeeper-jaas.conf"; /opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties

関連情報

3.4.3. DIGEST-MD5 を使用したクライアント/サーバー間の認証の有効化

この手順では、ZooKeeper クライアントと ZooKeeper との間で SASL DIGEST-MD5 メカニズムを使用した認証を有効にする方法を説明します。

前提条件

SASL DIGEST-MD5 認証の有効化

  1. すべての ZooKeeper ノードで、/opt/kafka/config/zookeeper-jaas.conf JAAS 設定ファイルを作成または編集し、以下のコンテキストを追加します。

    Server {
        org.apache.zookeeper.server.auth.DigestLoginModule required
        user_super="<SuperUserPassword>"
        user<Username1>_="<Password1>" user<USername2>_="<Password2>";
    };

    super は自動的に管理者特権を持たせます。このファイルには複数のユーザーを含めることができますが、Kafka ブローカーが必要とする追加ユーザーは 1 つだけです。Kafka ユーザーに推奨される名前は kafka です。

    以下の例は、クライアント/サーバー間の認証の Server コンテキストを示しています。

    Server {
        org.apache.zookeeper.server.auth.DigestLoginModule required
        user_super="123456"
        user_kafka="123456";
    };
  2. すべての ZooKeeper ノードで、/opt/kafka/config/zookeeper.properties ZooKeeper 設定ファイルを編集し、以下のオプションを設定します。

    requireClientAuthScheme=sasl
    authProvider.<IdOfBroker1>=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
    authProvider.<IdOfBroker2>=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
    authProvider.<IdOfBroker3>=org.apache.zookeeper.server.auth.SASLAuthenticationProvider

    authProvider.<ID> プロパティーは、ZooKeeper クラスターの一部であるすべてのノードに追加する必要があります。3 ノードの ZooKeeper クラスターの設定例は以下のようになります。

    requireClientAuthScheme=sasl
    authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
    authProvider.2=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
    authProvider.3=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
  3. すべての ZooKeeper ノードを 1 つずつ再起動します。JAAS 設定を ZooKeeper に渡すには、KAFKA_OPTS 環境変数を使用します。

    su - kafka
    export KAFKA_OPTS="-Djava.security.auth.login.config=/opt/kafka/config/zookeeper-jaas.conf"; /opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties

関連情報

3.5. 承認

ZooKeeper はアクセス制御リスト(ACL)をサポートし、内部に保存されているデータを保護します。Kafka ブローカーは、他の ZooKeeper ユーザーが変更できないように、作成するすべての ZooKeeper レコードに ACL 権限を自動的に設定できます。

Kafka ブローカーで ZooKeeper ACL を有効にする方法は、「ZooKeeper の承認」 を参照してください。

3.6. TLS

ZooKeeper は、暗号化または認証用に TLS をサポートします。

3.7. その他の設定オプション

ユースケースに基づいて、以下の追加の ZooKeeper 設定オプションを設定できます。

maxClientCnxns
ZooKeeper クラスターの単一のメンバーへの同時クライアント接続の最大数。
autopurge.snapRetainCount
保持される ZooKeeper のインメモリーデータベースのスナップショットの数。デフォルト値は 3 です。
autopurge.purgeInterval
スナップショットをパージするための時間間隔 (時間単位)。デフォルト値は 0 で、このオプションは無効になります。

利用可能なすべての設定オプションは、ZooKeeper のドキュメント を参照してください。

3.8. ロギング

ZooKeeper は、ロギングインフラストラクチャーとして log4j を使用しています。ロギング設定は、デフォルトでは /opt/kafka/config/ ディレクトリーまたはクラスパスのいずれかに配置される log4j.properties 設定ファイルから読み取られます。設定ファイルの場所と名前は、Java プロパティー log4j.configuration を使用して変更できます。これは、KAFKA_LOG4J_OPTS 環境変数を使用して ZooKeeper に渡すことができます。

su - kafka
export KAFKA_LOG4J_OPTS="-Dlog4j.configuration=file:/my/path/to/log4j.properties"; /opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties

Log4j の設定に関する詳細は、Log4j のドキュメント を参照してください。

第4章 Kafka の設定

Kafka はプロパティーファイルを使用して静的設定を保存します。推奨される設定ファイルの場所は /opt/kafka/config/server.properties です。設定ファイルは kafka ユーザーが読み取りできる必要があります。

AMQ Streams には、製品のさまざまな基本的な機能と高度な機能を強調する設定ファイルのサンプルが含まれています。AMQ Streams インストールディレクトリーの config/server.properties を参照してください。

本章では、最も重要な設定オプションについて説明します。サポートされる Kafka ブローカー設定オプションの完全リストは、「付録A ブローカー設定パラメーター」を参照してください。

4.1. ZooKeeper

Kafka ブローカーは、構成の一部を保存し、クラスターを調整するために (たとえば、どのノードがどのパーティションのリーダーであるかを決定するために) Zoo Keeper を必要とします。ZooKeeper クラスターの接続の詳細は、設定ファイルに保存されます。zookeeper.connect フィールドには、zookeeper クラスターのメンバーのホスト名およびポートのコンマ区切りリストが含まれます。

以下に例を示します。

zookeeper.connect=zoo1.my-domain.com:2181,zoo2.my-domain.com:2181,zoo3.my-domain.com:2181

Kafka はこれらのアドレスを使用して ZooKeeper クラスターに接続します。この設定により、すべての Kafka znodes が ZooKeeper データベースのルートに直接作成されます。そのため、このような ZooKeeper クラスターは単一の Kafka クラスターにのみ使用できます。単一の Zoo Keeper クラスターを使用するように複数の Kafka クラスターを構成するには、Kafka 構成ファイルの Zoo Keeper 接続文字列の最後にベース (プレフィックス) パスを指定します。

zookeeper.connect=zoo1.my-domain.com:2181,zoo2.my-domain.com:2181,zoo3.my-domain.com:2181/my-cluster-1

4.2. 「リスナー」

Kafka ブローカーは、複数のリスナーを使用するように設定できます。各リスナーは、異なるポートまたはネットワークインターフェースでリッスンするのに使用でき、異なる設定を指定できます。リスナーは、設定ファイルの listeners プロパティーで設定されます。listeners プロパティーには、< listenerName > :// <hostname > :_<port>_ として設定された各リスナーのリストが含まれます。ホスト名の値が空の場合、Kafka は java.net.InetAddress.getCanonicalHostName() をホスト名として使用します。以下の例は、複数のリスナーの設定方法を示しています。

listeners=INT1://:9092,INT2://:9093,REPLICATION://:9094

Kafka クライアントが Kafka クラスターに接続する場合、まず ブートストラップサーバー に接続します。ブートストラップサーバー はクラスターノードの 1 つです。クライアントに対し、クラスターの一部である他のすべてのブローカーのリストが提供され、クライアントはそれらを個別に接続します。デフォルトでは、ブートストラップサーバー は、listeners フィールドに基づいてノードの一覧をクライアントに提供します。

アドバタイズされたリスナー

listeners プロパティーで指定されたものとは異なるアドレスのセットをクライアントに付与することができます。これは、プロキシーなどの追加のネットワークインフラストラクチャーがクライアントとブローカー間にある場合、または IP アドレスの代わりに外部 DNS 名を使用する必要がある場合に役立ちます。ここで、ブローカーは advertised.listeners 設定プロパティーでリスナーのアドバタイズされたアドレスを定義できます。このプロパティーは listeners プロパティーと同じ形式です。以下の例は、アドバタイズされたリスナーの設定方法を示しています。

listeners=INT1://:9092,INT2://:9093
advertised.listeners=INT1://my-broker-1.my-domain.com:1234,INT2://my-broker-1.my-domain.com:1234:9093
注記

リスナーの名前は、listeners プロパティーのリスナー名と一致する必要があります。

inter-broker リスナー

クラスターが複製されたトピックがある場合、これらのトピックでメッセージを複製するために、このようなトピックに対応するブローカーは相互に通信する必要があります。複数のリスナーが設定されている場合、設定フィールド inter.broker.listener.name を使用してブローカー間のレプリケーションに使用するリスナーの名前を指定します。以下に例を示します。

inter.broker.listener.name=REPLICATION

4.3. ログのコミット

Apache Kafka は、プロデューサーから受信するすべてのレコードをコミットログに保存します。コミットログには、Kafka が配信する必要がある実際のデータ (レコードの形式) が含まれます。これらは、ブローカーの動作を記録するアプリケーションログファイルではありません。

ログディレクトリー

log.dirs プロパティーファイルを使用してログディレクトリーを設定し、1 つまたは複数のログディレクトリーにコミットログを保存できます。これは、インストール時に作成された /var/lib/kafka ディレクトリーに設定する必要があります。

log.dirs=/var/lib/kafka

パフォーマンス上の理由から、log.dir を複数のディレクトリーに設定し、それぞれを別の物理デバイスに配置して、ディスク I/O のパフォーマンスを向上できます。以下に例を示します。

log.dirs=/var/lib/kafka1,/var/lib/kafka2,/var/lib/kafka3

4.4. ブローカー ID

ブローカー ID は、クラスター内の各ブローカーの一意の ID です。ブローカー ID として 0 以上の整数を割り当てることができます。ブローカー ID は、再起動またはクラッシュ後にブローカーを識別するために使用されます。そのため、ID が安定し、時間の経過とともに変更されないようにすることが重要です。ブローカー ID はブローカーのプロパティーファイルで設定されます。

broker.id=1

4.5. マルチノードの Kafka クラスターの実行

この手順では、Kafka をマルチノードクラスターとして設定および実行する方法を説明します。

前提条件

クラスターの実行

AMQ Streams クラスターの各 Kafka ブローカーに対して以下を行います。

  1. 以下のように、Kafka 設定ファイル /opt/kafka/config/server.properties を編集します。

    • 最初のブローカーの broker.id フィールドを 0 に、2 番目のブローカーを 1 に、それぞれ設定します。
    • zookeeper.connect オプションで ZooKeeper への接続の詳細を設定します。
    • Kafka リスナーを設定します。
    • logs.dir のディレクトリーに、コミットログが保存されるディレクトリーを設定します。

      以下は、Kafka ブローカーの設定例です。

      broker.id=0
      zookeeper.connect=zoo1.my-domain.com:2181,zoo2.my-domain.com:2181,zoo3.my-domain.com:2181
      listeners=REPLICATION://:9091,PLAINTEXT://:9092
      inter.broker.listener.name=REPLICATION
      log.dirs=/var/lib/kafka

      各 Kafka ブローカーが同じハードウェアで実行されている通常のインストールでは、broker.id 設定プロパティーのみがブローカー設定ごとに異なります。

  2. デフォルトの設定ファイルで Kafka ブローカーを起動します。

    su - kafka
    /opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties
  3. Kafka ブローカーが稼働していることを確認します。

    jcmd | grep Kafka

ブローカーの検証

クラスターのすべてのノードが稼働したら、ncat ユーティリティーを使用して dump コマンドを ZooKeeper ノードのいずれかに送信して、すべてのノードが Kafka クラスターのメンバーであることを確認します。このコマンドは、ZooKeeper に登録されているすべての Kafka ブローカーを出力します。

  1. ncat stat を使用してノードのステータスを確認します。

    echo dump | ncat zoo1.my-domain.com 2181

    出力には、設定および起動したすべての Kafka ブローカーが含まれるはずです。

    3 つのノードで構成される Kafka クラスターの ncat コマンドの出力例

    SessionTracker dump:
    org.apache.zookeeper.server.quorum.LearnerSessionTracker@28848ab9
    ephemeral nodes dump:
    Sessions with Ephemerals (3):
    0x20000015dd00000:
            /brokers/ids/1
    0x10000015dc70000:
            /controller
            /brokers/ids/0
    0x10000015dc70001:
            /brokers/ids/2

関連情報

4.6. ZooKeeper の認証

デフォルトでは、ZooKeeper と Kafka 間の接続は認証されません。ただし、Kafka および ZooKeeper は、SASL (Simple Authentication and Security Layer) を使用して認証を設定するのに使用できる Java Authentication and Authorization Service (JAAS) をサポートします。ZooKeeper は、ローカルに保存されたクレデンシャルと DIGEST-MD5 SASL メカニズムを使用した認証をサポートします。

4.6.1. JAAS 設定

ZooKeeper 接続の SASL 認証は JAAS 設定ファイルで設定する必要があります。デフォルトでは、Kafka は ZooKeeper への接続用に Client という名前の JAAS コンテキストを使用します。Clientコンテキストは /opt/kafka/config/jass.conf ファイルで設定する必要があります。以下の例のように、コンテキストでは PLAIN SASL 認証を有効にする必要があります。

Client {
    org.apache.kafka.common.security.plain.PlainLoginModule required
    username="kafka"
    password="123456";
};

4.6.2. ZooKeeper 認証の有効化

この手順では、ZooKeeper に接続する際に SASL DIGEST-MD5 メカニズムを使用した認証を有効にする方法を説明します。

前提条件

  • ZooKeeper でクライアント/サーバー間の認証が 有効である

SASL DIGEST-MD5 認証の有効化

  1. すべての Kafka ブローカーノードで、/opt/kafka/config/jaas.conf JAAS 設定ファイルを作成または編集し、以下のコンテキストを追加します。

    Client {
        org.apache.kafka.common.security.plain.PlainLoginModule required
        username="<Username>"
        password="<Password>";
    };

    ユーザー名とパスワードは ZooKeeper で設定されているものと同じである必要があります。

    Client コンテキストの例を以下に示します。

    Client {
        org.apache.kafka.common.security.plain.PlainLoginModule required
        username="kafka"
        password="123456";
    };
  2. すべての Kafka ブローカーノードを 1 つずつ再起動します。JAAS 設定を Kafka ブローカーに渡すには、KAFKA_OPTS 環境変数を使用します。

    su - kafka
    export KAFKA_OPTS="-Djava.security.auth.login.config=/opt/kafka/config/jaas.conf"; /opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties

関連情報

  • ZooKeeper でのクライアント/サーバー間の認証の設定に関する詳細は、「認証」 を参照してください。

4.7. 承認

Kafka ブローカーの承認は、オーソライザープラグインを使用して実装されます。

本セクションでは、Kafka で提供される AclAuthorizer プラグインを使用する方法を説明します。

または、独自の承認プラグインを使用できます。たとえば、OAuth 2.0 トークンベースの認証 を使用している場合、OAuth 2.0 承認 を使用できます。

4.7.1. シンプルな ACL オーソライザー

AclAuthorizer を含む authorizer プラグインは authorizer.class.name プロパティーを使用して有効にします。

authorizer.class.name=kafka.security.auth.SimpleAclAuthorizer

選択したオーソライザーには完全修飾名が必要です。AclAuthorizer の場合、完全修飾名は kafka.security.auth.SimpleAclAuthorizer です。

4.7.1.1. ACL ルール

AclAuthorizer は ACL ルールを使用して Kafka ブローカーへのアクセスを管理します。

ACL ルールは以下の形式で定義されます。

プリンシパル P は、ホスト H から Kafka リソース R で操作 O を許可または拒否されます。

たとえば、以下のようにルールを設定できます。

John は、ホスト 127.0.0.1 からトピック コメント表示 できます。

ホストは、John が接続しているマシンの IP アドレスです。

ほとんどの場合、ユーザーはプロデューサーまたはコンシューマーアプリケーションです。

Consumer01 は、ホスト 127.0.0.1 からコンシューマーグループ アカウント書き込み できます。

ACL ルールが存在しない場合

特定のリソースに ACL ルールが存在しない場合は、すべてのアクションが拒否されます。この動作は、Kafka 設定ファイル /opt/kafka/config/server.propertiesallow.everyone.if.no.acl.found プロパティーを true に設定すると変更できます。

4.7.1.2. プリンシパル

プリンシパル はユーザーのアイデンティティーを表します。ID の形式は、クライアントが Kafka に接続するために使用される認証メカニズムによって異なります。

  • User:ANONYMOUS: 認証なしで接続する場合。
  • User:<username>: PLAIN や SCRAM などの単純な認証メカニズムを使用して接続する場合。

    例: User:admin または User:user1

  • User:<DistinguishedName>: TLS クライアント認証を使用して接続する場合。

    例: User:CN=user1,O=MyCompany,L=Prague,C=CZ

  • User:<Kerberos username>: Kerberos を使用して接続する場合。

DistinguishedName はクライアント証明書からの識別名です。

Kerberos ユーザー名 は、Kerberos プリンシパルの主要部分で、Kerberos を使用して接続する場合のデフォルトで使用されます。sasl.kerberos.principal.to.local.rules プロパティーを使用して、Kerberos プリンシパルから Kafka プリンシパルを構築する方法を設定できます。

4.7.1.3. ユーザーの認証

承認を使用するには、認証を有効にし、クライアントにより使用される必要があります。そうでないと、すべての接続のプリンシパルは User:ANONYMOUS になります。

認証方法の詳細は、「暗号化および認証」 を参照してください。

4.7.1.4. スーパーユーザー

スーパーユーザーは、ACL ルールに関係なくすべてのアクションを実行できます。

スーパーユーザーは、super.users プロパティーを使用して Kafka 設定ファイルで定義されます。

以下に例を示します。

super.users=User:admin,User:operator
4.7.1.5. レプリカブローカーの認証

承認を有効にすると、これはすべてのリスナーおよびすべての接続に適用されます。これには、ブローカー間のデータのレプリケーションに使用される inter-broker の接続が含まれます。そのため、承認を有効にする場合は、inter-broker 接続に認証を使用し、ブローカーが使用するユーザーに十分な権限を付与してください。たとえば、ブローカー間の認証で kafka-broker ユーザーが使用される場合、スーパーユーザー設定にはユーザー名 super.users=User:kafka-broker が含まれている必要があります。

4.7.1.6. サポートされるリソース

Kafka ACL は、以下のタイプのリソースに適用できます。

  • トピック
  • コンシューマーグループ
  • クラスター
  • TransactionId
  • DelegationToken
4.7.1.7. サポートされる操作

AclAuthorizer はリソースでの操作を承認します。

以下の表で X の付いたフィールドは、各リソースでサポートされる操作を表します。

表4.1 リソースでサポートされる操作
 トピックコンシューマーグループCluster

Read

X

X

 

Write

X

  

Create

  

X

削除

X

  

Alter

X

  

Describe

X

X

X

ClusterAction

  

X

すべて

X

X

X

4.7.1.8. ACL 管理オプション

ACL ルールは、Kafka ディストリビューションパッケージの一部として提供される bin/kafka-acls.sh ユーティリティーを使用して管理されます。

kafka-acls.sh パラメーターオプションを使用して、ACL ルールを追加、一覧表示、および削除したり、その他の機能を実行したりします。

パラメーターには、--add など、二重ハイフンの標記が必要です。

オプションタイプ説明デフォルト

add

アクション

ACL ルールを追加します。

 

remove

アクション

ACL ルールを削除します。

 

list

アクション

ACL ルールを一覧表示します。

 

authorizer

アクション

オーソライザーの完全修飾クラス名。

kafka.security.auth.SimpleAclAuthorizer

authorizer-properties

設定

初期化のためにオーソライザーに渡されるキー/値のペア。

AclAuthorizer では、サンプル値は zookeeper.connect=zoo1.my-domain.com:2181 です。

 

bootstrap-server

リソース

Kafka クラスターに接続するためのホスト/ポートのペア。

このオプションまたは authorizer オプションを使用します (両方ではなく)。

command-config

リソース

管理クライアントに渡す設定プロパティーファイル。これは bootstrap-server パラメーターと共に使用されます。

 

cluster

リソース

クラスターを ACL リソースとして指定します。

 

topic

リソース

トピック名を ACL リソースとして指定します。

ワイルドカードとして使用されるアスタリスク (*) は、すべてのトピック に解釈されます。

1 つのコマンドに複数の --topic オプションを指定できます。

 

group

リソース

コンシューマーグループ名を ACL リソースとして指定します。

1 つのコマンドに複数の --group オプションを指定できます。

 

transactional-id

リソース

トランザクション ID を ACL リソースとして指定します。

トランザクション配信は、プロデューサーによって複数のパーティションに送信されたすべてのメッセージが正常に配信されるか、いずれも配信されない必要があることを意味します。

ワイルドカードとして使用されるアスタリスク (*) は、すべての ID に解釈されます。

 

delegation-token

リソース

委任トークンを ACL リソースとして指定します。

ワイルドカードとして使用されるアスタリスク (*) は、すべてのトークン に解釈されます。

 

resource-pattern-type

設定

add パラメーターのリソースパターンのタイプ、または list または remove パラメーターのリソースパターンのフィルター値を指定します。

literal または prefixed をリソース名のリソースパターンタイプとして使用します。

any または match を、リソースパターンのフィルター値または特定のパターンタイプフィルターとして使用します。

literal

allow-principal

プリンシパル

allow ACL ルールに追加されるプリンシパル。

1 つのコマンドに複数の --allow-principal オプションを指定できます。

 

deny-principal

プリンシパル

拒否 ACL ルールに追加されるプリンシパル。

1 つのコマンドに複数の --deny-principal オプションを指定できます。

 

principal

プリンシパル

プリンシパルの ACL の一覧を返すために list パラメーターと共に使用されるプリンシパル名。

1 つのコマンドに複数の --principal オプションを指定できます。

 

allow-host

Host

--allow-principal に記載されているプリンシパルへのアクセスを許可する IP アドレス。

ホスト名または CIDR 範囲はサポートされていません。

--allow-principal が指定されている場合、デフォルトは * で「すべてのホスト」を意味します。

deny-host

Host

--deny-principal に記載されているプリンシパルへのアクセスを拒否する IP アドレス。

ホスト名または CIDR 範囲はサポートされていません。

--deny-principal が指定されている場合、デフォルトは * で「すべてのホスト」を意味します。

operation

操作

操作を許可または拒否します。

1 つのコマンドに複数の --operation オプションを指定できます。

すべて

producer

ショートカット

メッセージプロデューサーが必要とするすべての操作を許可または拒否するためのショートカット (トピックでは WRITE と DESCRIBE、クラスターでは CREATE)。

 

consumer

ショートカット

メッセージコンシューマーが必要とするすべての操作を許可または拒否するためのショートカット (トピックについては READ と DESCRIBE、コンシューマーグループについては READ)。

 

idempotent

ショートカット

--producer パラメーターとの併用時に冪等性を有効にするショートカット。これにより、メッセージがパーティションに 1 度だけ配信されるようになります。

プロデューサーが特定のトランザクション ID に基づいてメッセージを送信することを許可されている場合、Idepmotence は自動的に有効になります。

 

force

ショートカット

すべてのクエリーを受け入れ、プロンプトは表示されないショートカット。

 

4.7.2. 承認の有効化

この手順では、Kafka ブローカーでの承認用に AclAuthorizer プラグインを有効にする方法を説明します。

前提条件

手順

  1. AclAuthorizer を使用するように、Kafka 設定ファイル /opt/kafka/config/server.properties を編集します。

    authorizer.class.name=kafka.security.auth.SimpleAclAuthorizer
  2. Kafka ブローカーを (再) 起動します。

関連情報

4.7.3. ACL ルールの追加

AclAuthorizer は、ユーザーが実行できる/できない操作を記述するルールのセットを定義するアクセス制御リスト (ACL) を使用します。

この手順では、Kafka ブローカーで AclAuthorizer プラグインを使用する場合に、ACL ルールを追加する方法を説明します。

ルールは kafka-acls.sh ユーティリティーを使用して追加され、ZooKeeper に保存されます。

前提条件

手順

  1. --add オプションを指定して kafka-acls.sh を実行します。

    例:

    • MyConsumerGroup コンシューマーグループを使用して、user1 および user2myTopic からの読み取りを許可します。

      bin/kafka-acls.sh --authorizer-properties zookeeper.connect=zoo1.my-domain.com:2181 --add --operation Read --topic myTopic --allow-principal User:user1 --allow-principal User:user2
      
      bin/kafka-acls.sh --authorizer-properties zookeeper.connect=zoo1.my-domain.com:2181 --add --operation Describe --topic myTopic --allow-principal User:user1 --allow-principal User:user2
      
      bin/kafka-acls.sh --authorizer-properties zookeeper.connect=zoo1.my-domain.com:2181 --add --operation Read --operation Describe --group MyConsumerGroup --allow-principal User:user1 --allow-principal User:user2
    • user1 が IP アドレスホスト 127.0.0.1 から myTopic を読むためのアクセスを拒否します。

      bin/kafka-acls.sh --authorizer-properties zookeeper.connect=zoo1.my-domain.com:2181 --add --operation Describe --operation Read --topic myTopic --group MyConsumerGroup --deny-principal User:user1 --deny-host 127.0.0.1
    • MyConsumerGroupmyTopic のコンシューマーとして user1 を追加します。

      bin/kafka-acls.sh --authorizer-properties zookeeper.connect=zoo1.my-domain.com:2181 --add --consumer --topic myTopic --group MyConsumerGroup --allow-principal User:user1

関連情報

4.7.4. ACL ルールの一覧表示

この手順では、Kafka ブローカーで AclAuthorizer プラグインを使用する場合に、既存の ACL ルールを一覧表示する方法を説明します。

ルールは、kafka-acls.sh ユーティリティーを使用してリストされます。

前提条件

手順

  • --list オプションを指定して kafka-acls.sh を実行します。

    以下に例を示します。

    $ bin/kafka-acls.sh --authorizer-properties zookeeper.connect=zoo1.my-domain.com:2181 --list --topic myTopic
    
    Current ACLs for resource `Topic:myTopic`:
    
    User:user1 has Allow permission for operations: Read from hosts: *
    User:user2 has Allow permission for operations: Read from hosts: *
    User:user2 has Deny permission for operations: Read from hosts: 127.0.0.1
    User:user1 has Allow permission for operations: Describe from hosts: *
    User:user2 has Allow permission for operations: Describe from hosts: *
    User:user2 has Deny permission for operations: Describe from hosts: 127.0.0.1

関連情報

4.7.5. ACL ルールの削除

この手順では、Kafka ブローカーで AclAuthorizer プラグインを使用する場合に、ACL ルールを削除する方法を説明します。

ルールは kafka-acls.sh ユーティリティーを使用して削除されます。

前提条件

手順

  • --remove オプションを指定して kafka-acls.sh を実行します。

    例:

  • MyConsumerGroup コンシューマーグループを使用して、user1 および user2myTopic からの読み取りを許可する ACL を削除します。

    bin/kafka-acls.sh --authorizer-properties zookeeper.connect=zoo1.my-domain.com:2181 --remove --operation Read --topic myTopic --allow-principal User:user1 --allow-principal User:user2
    
    bin/kafka-acls.sh --authorizer-properties zookeeper.connect=zoo1.my-domain.com:2181 --remove --operation Describe --topic myTopic --allow-principal User:user1 --allow-principal User:user2
    
    bin/kafka-acls.sh --authorizer-properties zookeeper.connect=zoo1.my-domain.com:2181 --remove --operation Read --operation Describe --group MyConsumerGroup --allow-principal User:user1 --allow-principal User:user2
  • MyConsumerGroupmyTopic のコンシューマーとして user1 を追加する ACL を削除します。

    bin/kafka-acls.sh --authorizer-properties zookeeper.connect=zoo1.my-domain.com:2181 --remove --consumer --topic myTopic --group MyConsumerGroup --allow-principal User:user1
  • user1 が IP アドレスホスト 127.0.0.1 から myTopic を読むためのアクセスを拒否する ACL を削除します。

    bin/kafka-acls.sh --authorizer-properties zookeeper.connect=zoo1.my-domain.com:2181 --remove --operation Describe --operation Read --topic myTopic --group MyConsumerGroup --deny-principal User:user1 --deny-host 127.0.0.1

関連情報

4.8. ZooKeeper の承認

Kafka と Zoo Keeper の間で認証が有効になっている場合、Zoo Keeper アクセス制御リスト (ACL) ルールを使用して、Zoo Keeper に格納されている Kafka のメタデータへのアクセスを自動的に制御できます。

4.8.1. ACL 設定

ZooKeeper ACL ルールの適用は、config/server.properties Kafka 設定ファイルの zookeeper.set.acl プロパティーによって制御されます。

プロパティーはデフォルトで無効になっていて、true に設定することにより有効になります。

zookeeper.set.acl=true

ACL ルールが有効になっている場合、ZooKeeper で znode が作成されると、作成した Kafka ユーザーのみが変更または削除できます。その他のすべてのユーザーには読み取り専用アクセスがあります。

Kafka は、新しく作成された ZooKeeper znodes に対してのみ ACL ルールを設定します。ACL がクラスターの最初の起動後にのみ有効である場合、zookeeper-security-migration.sh ツールは既存のすべての znodes に ACL を設定できます。

ZooKeeper のデータの機密性

ZooKeeper に保存されるデータには以下が含まれます。

  • トピック名およびその設定
  • SASL SCRAM 認証が使用される場合のソルトおよびハッシュ化されたユーザークレデンシャル

しかし、ZooKeeper は Kafka を使用して送受信されたレコードを保存しません。ZooKeeper に保存されるデータは機密ではないと想定されます。

データが機密として考慮される場合 (たとえば、トピック名にカスタマー ID が含まれるなど)、保護に使用できる唯一のオプションは、ネットワークレベルで ZooKeeper を分離し、Kafka ブローカーにのみアクセスを許可することです。

4.8.2. 新しい Kafka クラスターでの ZooKeeper ACL の有効化

この手順では、新しい Kafka クラスターの Kafka 設定で ZooKeeper ACL を有効にする方法を説明します。この手順は、Kafka クラスターの最初の起動前にのみ使用してください。すでに実行中のクラスターで ZooKeeper ACL を有効にする場合は、「既存の Kafka クラスターでの ZooKeeper ACL の有効化」 を参照してください。

前提条件

手順

  1. すべてのクラスターノードの /opt/kafka/config/server.properties Kafka 設定ファイルを編集し、zookeeper.set.acl フィールドを true に設定します。

    zookeeper.set.acl=true
  2. Kafka ブローカーを起動します。

4.8.3. 既存の Kafka クラスターでの ZooKeeper ACL の有効化

この手順では、稼働している Kafka クラスターの Kafka 設定で ZooKeeper ACL を有効にする方法を説明します。zookeeper-security-migration.sh ツールを使用して、既存のすべての znodes に ZooKeeper の ACL を設定します。zookeeper-security-migration.sh は AMQ Streams の一部として利用でき、bin ディレクトリーにあります。

前提条件

ZooKeeper ACL の有効化

  1. すべてのクラスターノードの /opt/kafka/config/server.properties Kafka 設定ファイルを編集し、zookeeper.set.acl フィールドを true に設定します。

    zookeeper.set.acl=true
  2. すべての Kafka ブローカーを 1 つずつ再起動します。
  3. zookeeper-security-migration.sh ツールを使用して、既存のすべての znodes ノードに ACL を設定します。

    su - kafka
    cd /opt/kafka
    KAFKA_OPTS="-Djava.security.auth.login.config=./config/jaas.conf"; ./bin/zookeeper-security-migration.sh --zookeeper.acl=secure --zookeeper.connect=<ZooKeeperURL>
    exit

    以下に例を示します。

    su - kafka
    cd /opt/kafka
    KAFKA_OPTS="-Djava.security.auth.login.config=./config/jaas.conf"; ./bin/zookeeper-security-migration.sh --zookeeper.acl=secure --zookeeper.connect=zoo1.my-domain.com:2181
    exit

4.9. 暗号化と認証

AMQ Streams は、リスナー設定の一部として設定される暗号化および認証をサポートします。

4.9.1. リスナーの設定

Kafka ブローカーの暗号化および認証は、リスナーごとに設定されます。Kafka リスナーの設定に関する詳細は、「「リスナー」」 を参照してください。

Kafka ブローカーの各リスナーは、独自のセキュリティープロトコルで設定されます。設定プロパティー listener.security.protocol.map は、どのリスナーがどのセキュリティープロトコルを使用するかを定義します。各リスナー名がセキュリティープロトコルにマッピングされます。サポートされるセキュリティープロトコルは次のとおりです。

PLAINTEXT
暗号化または認証を使用しないリスナー。
SSL
TLS 暗号化を使用し、オプションで TLS クライアント証明書を使用した認証を使用するリスナー。
SASL_PLAINTEXT
暗号化なし、SASL ベースの認証を使用するリスナー。
SASL_SSL
TLS ベースの暗号化および SASL ベースの認証を使用するリスナー。

以下の listeners 設定の場合、

listeners=INT1://:9092,INT2://:9093,REPLICATION://:9094

listener.security.protocol.map は以下のようになります。

listener.security.protocol.map=INT1:SASL_PLAINTEXT,INT2:SASL_SSL,REPLICATION:SSL

これにより、リスナー INT1 は暗号化されていない接続および SASL 認証を使用し、リスナー INT2 は暗号化された接続および SASL 認証を使用し、REPLICATION インターフェイスは TLS による暗号化 (TLS クライアント認証が使用される可能性があり) を使用するように設定されます。同じセキュリティープロトコルを複数回使用できます。以下は、有効な設定の例です。

listener.security.protocol.map=INT1:SSL,INT2:SSL,REPLICATION:SSL

このような設定は、すべてのインターフェイスに TLS 暗号化および TLS 認証を使用します。以下の章では、TLS および SASL の設定方法について詳しく説明します。

4.9.2. TLS 暗号化

Kafka は、Kafka クライアントとの通信を暗号化するために TLS をサポートします。

TLS による暗号化およびサーバー認証を使用するには、秘密鍵と公開鍵が含まれるキーストアを提供する必要があります。これは通常、Java Keystore (JKS) 形式のファイルを使用して行われます。このファイルのパスは、ssl.keystore.location プロパティーに設定されます。ssl.keystore.password プロパティーを使用して、キーストアを保護するパスワードを設定する必要があります。以下に例を示します。

ssl.keystore.location=/path/to/keystore/server-1.jks
ssl.keystore.password=123456

秘密鍵を保護するために、追加のパスワードが使用されることがあります。このようなパスワードは、ssl.key.password プロパティーを使用して設定できます。

Kafka は、認証局によって署名された鍵と自己署名の鍵を使用できます。認証局が署名する鍵を使用することが、常に推奨される方法です。クライアントが接続している Kafka ブローカーのアイデンティティーを検証できるようにするには、証明書に Common Name (CN) または Subject Alternative Names (SAN) としてアドバタイズされたホスト名が常に含まれる必要があります。

異なるリスナーに異なる SSL 設定を使用できます。ssl. で始まるすべてのオプションの前に listener.name.<NameOfTheListener>. を付けることができます。この場合、リスナーの名前は常に小文字である必要があります。これにより、その特定のリスナーのデフォルトの SSL 設定が上書きされます。以下の例は、異なるリスナーに異なる SSL 設定を使用する方法を示しています。

listeners=INT1://:9092,INT2://:9093,REPLICATION://:9094
listener.security.protocol.map=INT1:SSL,INT2:SSL,REPLICATION:SSL

# Default configuration - will be used for listeners INT1 and INT2
ssl.keystore.location=/path/to/keystore/server-1.jks
ssl.keystore.password=123456

# Different configuration for listener REPLICATION
listener.name.replication.ssl.keystore.location=/path/to/keystore/server-1.jks
listener.name.replication.ssl.keystore.password=123456

その他の TLS 設定オプション

上記のメインの TLS 設定オプションの他に、Kafka は TLS 設定を調整するための多くのオプションをサポートします。たとえば、TLS/ SSL プロトコルまたは暗号スイートを有効または無効にするには、次のコマンドを実行します。

ssl.cipher.suites
有効な暗号スイートの一覧。各暗号スイートは、TLS 接続に使用される認証、暗号化、MAC、および鍵交換アルゴリズムの組み合わせです。デフォルトでは、利用可能なすべての暗号スイートが有効になっています。
ssl.enabled.protocols
有効な TLS / SSL プロトコルのリスト。デフォルトは TLSv1.2,TLSv1.1,TLSv1 です。

サポートされる Kafka ブローカー設定オプションの完全リストは、「付録A ブローカー設定パラメーター」を参照してください。

4.9.3. TLS 暗号化の有効化

この手順では、Kafka ブローカーで暗号化を有効にする方法を説明します。

前提条件

手順

  1. クラスター内のすべての Kafka ブローカーの TLS 証明書を生成します。証明書には、Common Name または Subject Alternative Name にアドバタイズされたアドレスおよびブートストラップアドレスが必要です。
  2. 以下のように、すべてのクラスターノードの /opt/kafka/config/server.properties Kafka 設定ファイルを編集します。

    • listener.security.protocol.map フィールドを変更して、TLS 暗号化を使用するリスナーに SSL プロトコルを指定します。
    • ssl.keystore.location オプションを、ブローカー証明書を持つ JKS キーストアへのパスに設定します。
    • ssl.keystore.password オプションを、キーストアの保護に使用したパスワードに設定します。

      以下に例を示します。

      listeners=UNENCRYPTED://:9092,ENCRYPTED://:9093,REPLICATION://:9094
      listener.security.protocol.map=UNENCRYPTED:PLAINTEXT,ENCRYPTED:SSL,REPLICATION:PLAINTEXT
      ssl.keystore.location=/path/to/keystore/server-1.jks
      ssl.keystore.password=123456
  3. Kafka ブローカーを (再) 起動します。

関連情報

4.9.4. 認証

認証には、以下を使用できます。

4.9.4.1. TLS クライアント認証

TLS クライアント認証は、TLS 暗号化を使用している接続でのみ使用できます。TLS クライアント認証を使用するには、公開鍵のあるトラストストアをブローカーに提供できます。これらのキーは、ブローカーに接続するクライアントを認証するために使用できます。トラストストアは Java Keystore (JKS) 形式で提供され、認証局の公開鍵が含まれている必要があります。トラストストアに含まれる認証局のいずれかによって署名された公開鍵および秘密鍵を持つクライアントはすべて認証されます。トラストストアの場所は、フィールド ssl.truststore.location を使用して設定されます。トラストストアがパスワードで保護される場合、ssl.truststore.password プロパティーでパスワードを設定する必要があります。以下に例を示します。

ssl.truststore.location=/path/to/keystore/server-1.jks
ssl.truststore.password=123456

トラストストアが設定したら、ssl.client.auth プロパティーを使用して TLS クライアント認証を有効にする必要があります。このプロパティーは、3 つの異なる値のいずれかに設定できます。

none
TLS クライアント認証はオフになっています。(デフォルト値)
requested
TLS クライアント認証は任意です。クライアントは TLS クライアント証明書を使用した認証を要求されますが、選択することはできません。
required
クライアントは TLS クライアント証明書を使用して認証する必要があります。

クライアントが TLS クライアント認証を使用して認証する場合、認証されたプリンシパル名は認証済みクライアント証明書からの識別名になります。たとえば、CN=someuser という識別名の証明書を持つユーザーは、プリンシパル CN=someuser,OU=Unknown,O=Unknown,L=Unknown,ST=Unknown,C=Unknown で認証されます。TLS クライアント認証が使用されておらず、SASL が無効な場合、プリンシパル名は ANONYMOUS になります。

4.9.4.2. SASL 認証

SASL 認証は、Java Authentication and Authorization Service (JAAS) を使用して設定されます。JAAS は、Kafka と ZooKeeper 間の接続の認証にも使用されます。JAAS は独自の設定ファイルを使用します。このファイルに推奨される場所は /opt/kafka/config/jaas.conf です。ファイルは kafka ユーザーが読み取りできる必要があります。Kafka を実行中の場合、このファイルの場所は Java システムプロパティー java.security.auth.login.config を使用して指定されます。このプロパティーは、ブローカーノードの起動時に Kafka に渡す必要があります。

KAFKA_OPTS="-Djava.security.auth.login.config=/path/to/my/jaas.config"; bin/kafka-server-start.sh

SASL 認証は、暗号化されていないプレーンの接続と TLS 接続の両方を介してサポートされます。SASL はリスナーごとに個別に有効にできます。これを有効にするには、listener.security.protocol.map のセキュリティープロトコルを SASL_PLAINTEXT または SASL_SSL のいずれかにする必要があります。

Kafka の SASL 認証は、いくつかの異なるメカニズムをサポートします。

PLAIN
ユーザー名とパスワードに基づいて認証を実装します。ユーザー名とパスワードは Kafka 設定にローカルに保存されます。
SCRAM-SHA-256 および SCRAM-SHA-512
Salted Challenge Response Authentication Mechanism (SCRAM) を使用して認証を実装します。SCRAM 認証情報は、ZooKeeper に一元的に保存されます。SCRAM は、ZooKeeper クラスターノードがプライベートネットワークで分離された状態で実行されている場合に使用できます。
GSSAPI
Kerberos サーバーに対して認証を実装します。
警告

PLAIN メカニズムは、ネットワークを通じてユーザー名とパスワードを暗号化されていない形式で送信します。そのため、TLS による暗号化と組み合わせる場合にのみ使用してください。

SASL メカニズムは JAAS 設定ファイルを使用して設定されます。Kafka は KafkaServer という名前の JAAS コンテキストを使用します。JAAS で設定された後、Kafka 設定で SASL メカニズムを有効にする必要があります。これは、sasl.enabled.mechanisms プロパティーを使用して実行されます。このプロパティーには、有効なメカニズムのコンマ区切りリストが含まれます。

sasl.enabled.mechanisms=PLAIN,SCRAM-SHA-256,SCRAM-SHA-512

inter-broker 通信に使用されるリスナーが SASL を使用している場合、sasl.mechanism.inter.broker.protocol プロパティーを使用して使用する SASL メカニズムを指定する必要があります。以下に例を示します。

sasl.mechanism.inter.broker.protocol=PLAIN

inter-broker 通信に使用されるユーザー名およびパスワードは、フィールド username および password を使用して KafkaServer JAAS コンテキストで指定する必要があります。

SASL プレーン

PLAIN メカニズムを使用するには、接続が許可されるユーザー名およびパスワードは JAAS コンテキストに直接指定されます。以下の例は、SASL PLAIN 認証に設定されたコンテキストを示しています。この例では、3 つの異なるユーザーを設定します。

  • admin
  • user1
  • user2
KafkaServer {
    org.apache.kafka.common.security.plain.PlainLoginModule required
    user_admin="123456"
    user_user1="123456"
    user_user2="123456";
};

ユーザーデータベースを持つ JAAS 設定ファイルは、すべての Kafka ブローカーで同期して維持する必要があります。

SASL PLAIN が inter-broker の認証にも使用される場合、username および password プロパティーを JAAS コンテキストに含める必要があります。

KafkaServer {
    org.apache.kafka.common.security.plain.PlainLoginModule required
    username="admin"
    password="123456"
    user_admin="123456"
    user_user1="123456"
    user_user2="123456";
};

SASL SCRAM

Kafka の SCRAM 認証は、SCRAM-SHA-256 および SCRAM-SHA-512 の 2 つのメカニズムで構成されます。これらのメカニズムは、使用されるハッシュアルゴリズム (SHA-256 とより強力な SHA-512) のみが異なります。SCRAM 認証を有効にするには、JAAS 設定ファイルに以下の設定を含める必要があります。

KafkaServer {
    org.apache.kafka.common.security.scram.ScramLoginModule required;
};

Kafka 設定ファイルで SASL 認証を有効にすると、両方の SCRAM メカニズムが一覧表示されます。ただし、それらの 1 つのみを inter-broker 通信に選択できます。以下に例を示します。

sasl.enabled.mechanisms=SCRAM-SHA-256,SCRAM-SHA-512
sasl.mechanism.inter.broker.protocol=SCRAM-SHA-512

SCRAM メカニズムのユーザークレデンシャルは ZooKeeper に保存されます。kafka-configs.sh ツールを使用してそれらを管理できます。たとえば、以下のコマンドを実行して、パスワード 123456 で user1 を追加します。

bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'SCRAM-SHA-256=[password=123456],SCRAM-SHA-512=[password=123456]' --entity-type users --entity-name user1

ユーザー認証情報を削除するには、以下を使用します。

bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --delete-config 'SCRAM-SHA-512' --entity-type users --entity-name user1

SASL GSSAPI

Kerberos を使用した認証に使用される SASL メカニズムは GSSAPI と呼ばれます。Kerberos SASL 認証を設定するには、以下の設定を JAAS 設定ファイルに追加する必要があります。

KafkaServer {
    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true
    storeKey=true
    keyTab="/etc/security/keytabs/kafka_server.keytab"
    principal="kafka/kafka1.hostname.com@EXAMPLE.COM";
};

Kerberos プリンシパルのドメイン名は常に大文字にする必要があります。

JAAS 設定の他に、Kerberos サービス名を Kafka 設定の sasl.kerberos.service.name プロパティーで指定する必要があります。

sasl.enabled.mechanisms=GSSAPI
sasl.mechanism.inter.broker.protocol=GSSAPI
sasl.kerberos.service.name=kafka

複数の SASL メカニズム

Kafka は複数の SASL メカニズムを同時に使用できます。異なる JAAS 設定はすべて同じコンテキストに追加できます。

KafkaServer {
    org.apache.kafka.common.security.plain.PlainLoginModule required
    user_admin="123456"
    user_user1="123456"
    user_user2="123456";

    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true
    storeKey=true
    keyTab="/etc/security/keytabs/kafka_server.keytab"
    principal="kafka/kafka1.hostname.com@EXAMPLE.COM";

    org.apache.kafka.common.security.scram.ScramLoginModule required;
};

複数のメカニズムを有効にすると、クライアントは使用するメカニズムを選択できます。

4.9.5. TLS クライアント認証の有効化

この手順では、Kafka ブローカーで TLS クライアント認証を有効にする方法を説明します。

前提条件

手順

  1. ユーザー証明書に署名するために使用される認証局の公開鍵が含まれる JKS トラストストアを準備します。
  2. 以下のように、すべてのクラスターノードの /opt/kafka/config/server.properties Kafka 設定ファイルを編集します。

    • ssl.truststore.location オプションを、ユーザー証明書の認証局が含まれる JKS トラストストアへのパスに設定します。
    • ssl.truststore.password オプションを、トラストストアの保護に使用したパスワードに設定します。
    • ssl.client.auth オプションを required に設定します。

      以下に例を示します。

      ssl.truststore.location=/path/to/truststore.jks
      ssl.truststore.password=123456
      ssl.client.auth=required
  3. Kafka ブローカーを (再) 起動します。

関連情報

4.9.6. SASL PLAIN 認証の有効化

この手順では、Kafka ブローカーで SASL PLAIN 認証を有効にする方法を説明します。

前提条件

手順

  1. /opt/kafka/config/jaas.conf JAAS 設定ファイルを編集するか、作成します。このファイルには、すべてのユーザーとそのパスワードが含まれている必要があります。このファイルがすべての Kafka ブローカーで同じであることを確認します。

    以下に例を示します。

    KafkaServer {
        org.apache.kafka.common.security.plain.PlainLoginModule required
        user_admin="123456"
        user_user1="123456"
        user_user2="123456";
    };
  2. 以下のように、すべてのクラスターノードの /opt/kafka/config/server.properties Kafka 設定ファイルを編集します。

    • listener.security.protocol.map フィールドを変更して、SASL PLAIN 認証を使用するリスナーの SASL_PLAINTEXT または SASL_SSL プロトコルを指定します。
    • sasl.enabled.mechanisms オプションを PLAIN に設定します。

      以下に例を示します。

      listeners=INSECURE://:9092,AUTHENTICATED://:9093,REPLICATION://:9094
      listener.security.protocol.map=INSECURE:PLAINTEXT,AUTHENTICATED:SASL_PLAINTEXT,REPLICATION:PLAINTEXT
      sasl.enabled.mechanisms=PLAIN
  3. KAFKA_OPTS 環境変数を使用して Kafka ブローカーを (再) 起動し、JAAS 構成を Kafka ブローカーに渡します。

    su - kafka
    export KAFKA_OPTS="-Djava.security.auth.login.config=/opt/kafka/config/jaas.conf"; /opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties

関連情報

4.9.7. SASL SCRAM 認証の有効化

この手順では、Kafka ブローカーで SASL SCRAM 認証を有効にする方法を説明します。

前提条件

手順

  1. /opt/kafka/config/jaas.conf JAAS 設定ファイルを編集するか、作成します。KafkaServer コンテキストの ScramLoginModule を有効にします。このファイルがすべての Kafka ブローカーで同じであることを確認します。

    以下に例を示します。

    KafkaServer {
        org.apache.kafka.common.security.scram.ScramLoginModule required;
    };
  2. 以下のように、すべてのクラスターノードの /opt/kafka/config/server.properties Kafka 設定ファイルを編集します。

    • listener.security.protocol.map フィールドを変更して、SASL SCRAM 認証を使用するリスナーの SASL_PLAINTEXT または SASL_SSL プロトコルを指定します。
    • sasl.enabled.mechanisms オプションを SCRAM-SHA-256 または SCRAM-SHA-512 に設定します。

      以下に例を示します。

      listeners=INSECURE://:9092,AUTHENTICATED://:9093,REPLICATION://:9094
      listener.security.protocol.map=INSECURE:PLAINTEXT,AUTHENTICATED:SASL_PLAINTEXT,REPLICATION:PLAINTEXT
      sasl.enabled.mechanisms=SCRAM-SHA-512
  3. KAFKA_OPTS 環境変数を使用して Kafka ブローカーを (再) 起動し、JAAS 構成を Kafka ブローカーに渡します。

    su - kafka
    export KAFKA_OPTS="-Djava.security.auth.login.config=/opt/kafka/config/jaas.conf"; /opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties

関連情報

4.9.8. SASL SCRAM ユーザーの追加

この手順では、SASL SCRAM を使用した認証に新しいユーザーを追加する方法を説明します。

前提条件

手順

  • kafka-configs.sh ツールを使用して、新しい SASL SCRAM ユーザーを追加します。

    bin/kafka-configs.sh --bootstrap-server <BrokerAddress> --alter --add-config 'SCRAM-SHA-512=[password=<Password>]' --entity-type users --entity-name <Username>

    以下に例を示します。

    bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'SCRAM-SHA-512=[password=123456]' --entity-type users --entity-name user1

関連情報

4.9.9. SASL SCRAM ユーザーの削除

この手順では、SASL SCRAM 認証を使用する場合にユーザーを削除する方法を説明します。

前提条件

手順

  • kafka-configs.sh ツールを使用して SASL SCRAM ユーザーを削除します。

    bin/kafka-configs.sh --bootstrap-server <BrokerAddress> --alter --delete-config 'SCRAM-SHA-512' --entity-type users --entity-name <Username>

    以下に例を示します。

    bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --delete-config 'SCRAM-SHA-512' --entity-type users --entity-name user1

関連情報

4.10. 「OAuth 2.0 トークンベース認証の使用」

AMQ Streams は、SASL OAUTHBEARER メカニズムを使用して OAuth 2.0 認証の使用をサポートします。

OAuth 2.0 は、アプリケーション間で標準的なトークンベースの認証および承認を有効にし、中央の承認サーバーを使用してリソースに制限されたアクセスを付与するトークンを発行します。

OAuth 2.0 認証を設定した後に OAuth 2.0 承認 を設定できます。OAuth 2.0 認証は、使用する承認サーバーに関係なく ACL ベースの Kafka 承認 と併用することもできます。OAuth 2.0 のトークンベースの認証を使用すると、アプリケーションクライアントはアカウントのクレデンシャルを公開せずにアプリケーションサーバー (リソースサーバー と呼ばれる) のリソースにアクセスできます。

アプリケーションクライアントは、アクセストークンを認証の手段として渡します。アプリケーションサーバーはこれを使用して、付与するアクセス権限のレベルを決定することもできます。承認サーバーは、アクセスの付与とアクセスに関する問い合わせを処理します。

AMQ Streams のコンテキストでは以下が行われます。

  • Kafka ブローカーは OAuth 2.0 リソースサーバーとして動作します。
  • Kafka クライアントは OAuth 2.0 アプリケーションクライアントとして動作します。

Kafka クライアントは Kafka ブローカーに対して認証を行います。ブローカーおよびクライアントは、必要に応じて OAuth 2.0 承認サーバーと通信し、アクセストークンを取得または検証します。

AMQ Streams のデプロイメントでは、OAuth 2.0 インテグレーションは以下を提供します。

  • Kafka ブローカーのサーバー側の OAuth 2.0 サポート。
  • Kafka MirrorMaker、Kafka Connect、および Kafka Bridge のクライアント側 OAuth 2.0 サポート。

その他のリソース

4.10.1. OAuth 2.0 認証メカニズム

Kafka SASL OAUTHBEARER メカニズムは、Kafka ブローカーで認証されたセッションを確立するために使用されます。

Kafka クライアントは、形式がアクセストークンであるクレデンシャルの交換に SASL OAUTHBEARER メカニズムを使用して Kafka ブローカーでセッションを開始します。

Kafka ブローカーおよびクライアントは、OAuth 2.0 を使用するように設定する必要があります。

4.10.1.1. プロパティーまたは変数を使用した OAuth 2.0 の設定

OAuth 2.0 設定は、Java Authentication and Authorization Service (JAAS) プロパティーまたは環境変数を使用して設定できます。

  • JAASのプロパティーは、server.properties 設定ファイルで設定され、listener.name.LISTENER-NAME.oauthbearer.sasl.jaas.config プロパティーのキーと値のペアとして渡されます。
  • 環境変数を使用する場合は、server.properties ファイルに listener.name.LISTENER-NAME.oauthbearer.sasl.jaas.config プロパティーが必要ですが、他の JAAS プロパティーを省略することができます。

    大文字の環境変数の命名規則または大文字の環境変数の命名規則を使用できます。

Kafka OAuth 2.0 ライブラリーは、oauth. で始まるプロパティーを使用して認証を設定し、strimzi で始まるプロパティーを使用して OAuth 2.0 承認を設定 します。

4.10.2. 「OAuth 2.0 Kafka ブローカーの設定」

OAuth 2.0 の Kafka ブローカー設定には、以下が関係します。

  • 承認サーバーでの OAuth 2.0 クライアントの作成
  • Kafka クラスターでの OAuth 2.0 認証の構成
注記

承認サーバーに関連する Kafka ブローカーおよび Kafka クライアントはどちらも OAuth 2.0 クライアントと見なされます。

4.10.2.1. 承認サーバーの OAuth 2.0 クライアント設定

セッションの開始中に受信されたトークンを検証するように Kafka ブローカーを設定するには、承認サーバーで OAuth 2.0 クライアント 定義を作成し、以下のクライアントクレデンシャルを有効にして 機密 として設定することが推奨されます。

  • kafka-broker のクライアント ID (例)
  • 認証メカニズムとしてのクライアント ID およびシークレット
注記

承認サーバーのパブリックでないイントロスペクションエンドポイントを使用する場合のみ、クライアント ID およびシークレットを使用する必要があります。高速のローカル JWT トークンの検証と同様に、パブリック承認サーバーのエンドポイントを使用する場合は、通常クレデンシャルは必要ありません。

4.10.2.2. Kafka クラスターでの OAuth 2.0 認証設定

Kafka クラスターで OAuth 2.0 認証を使用するには、Kafka server.properties ファイルで Kafka クラスターのリスナー設定を有効にします。最小設定が必要です。また、TLS が inter-broker 通信に使用される TLS リスナーを設定することもできます。

以下を使用して、承認サーバーによるトークンの検証用にブローカーを設定できます。

  • JWKS エンドポイントと署名済み JWT 形式のアクセストークンの組み合わせ
  • イントロスペクション エンドポイント

ここで示される最低限の設定は、グローバル リスナー設定を適用します。つまり、ブローカー間の通信はアプリケーションクライアントと同じリスナーを通過します。

特定のリスナーの OAuth 2.0 設定を有効にするには、以下のリスナー設定の例に記載されている sasl.enabled.mechanisms の代わりに listener.name.LISTENER-NAME.sasl.enabled.mechanisms を指定します。LISTENER-NAME はリスナーの名前です(大文字小文字の区別なし)。以下の例では、リスナーに CLIENT という名前を付け、プロパティー名は listener.name.client.sasl.enabled.mechanisms になります。

JWKS エンドポイントを使用した OAuth 2.0 認証の最小リスナー設定

sasl.enabled.mechanisms=OAUTHBEARER 1
listeners=CLIENT://0.0.0.0:9092 2
listener.security.protocol.map=CLIENT:SASL_PLAINTEXT 3
listener.name.client.sasl.enabled.mechanisms=OAUTHBEARER 4
sasl.mechanism.inter.broker.protocol=OAUTHBEARER 5
inter.broker.listener.name=CLIENT 6
listener.name.client.oauthbearer.sasl.server.callback.handler.class=io.strimzi.kafka.oauth.server.JaasServerOauthValidatorCallbackHandler 7
listener.name.client.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \ 8
  oauth.valid.issuer.uri="https://AUTH-SERVER-ADDRESS" \ 9
  oauth.jwks.endpoint.uri="https://AUTH-SERVER-ADDRESS/jwks" \ 10
  oauth.username.claim="preferred_username"  \ 11
  oauth.client.id="kafka-broker" \ 12
  oauth.client.secret="kafka-secret" \ 13
  oauth.token.endpoint.uri="https://AUTH-SERVER-ADDRESS/token" ; 14
listener.name.client.oauthbearer.sasl.login.callback.handler.class=io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler 15
listener.name.client.oauthbearer.connections.max.reauth.ms=3600000 16

1
SASL でのクレデンシャル交換の SASL メカニズムとして OAUTHBEARER を有効にします。
2
接続するクライアントアプリケーションのリスナーを設定します。システム hostname はアドバタイズされたホスト名として使用されます。これは、再接続するためにクライアントが解決する必要があります。この例では、リスナーの名前は CLIENT です。
3
リスナーのチャネルプロトコルを指定します。SASL_SSL は TLS 用です。暗号化されていない接続 (TLS なし) には SASL_PLAINTEXT が使用されますが、TCP 接続層での盗聴のリスクがあります。
4
CLIENT リスナーの SASL として OAUTHBEARER を指定します。クライアント名(CLIENT)は通常、listeners プロパティーでは大文字で、listeners.name プロパティー( listener.name.client)では小文字で、listener.name .クライアント .*プロパティーの一部として小文字で指定します。
5
ブローカー間の通信に OAUTHBEARERSASL として指定します。
6
inter-broker 通信のリスナーを指定します。仕様は、有効な設定のために必要です。
7
クライアントリスナーで OAuth 2.0 認証を設定します。
8
クライアントおよび inter-broker 通信の認証設定を設定します。oauth.client.idoauth.client.secret、および auth.token.endpoint.uri プロパティーは inter-broker 設定に関連するものです。
9
有効な発行者 URI。この発行者が発行するアクセストークンのみが受け入れられます。例: https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME
10
JWKS エンドポイント URL。例: https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME/protocol/openid-connect/certs
11
トークンの実際のユーザー名が含まれるトークン要求 (またはキー)。ユーザー名は、ユーザーの識別に使用される principal です。値は、使用される認証フローと承認サーバーによって異なります。
12
すべてのブローカーで同じ Kafka ブローカーのクライアント ID。これは、kafka-broker として承認サーバーに登録されたクライアントです
13
すべてのブローカーで同じ Kafka ブローカーのシークレット。
14
承認サーバーへの OAuth 2.0 トークンエンドポイント URL。実稼働環境では、常に HTTPS を使用してください 例: https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME/protocol/openid-connect/token
15
inter-broker 通信の OAuth2.0 認証を有効にします (これにのみ必要です)。
16
(任意設定)トークンの有効期限が切れるとセッションの有効期限を強制し、Kafka の再認証メカニズム も有効にします。指定された値がアクセストークンの有効期限が切れるまでの残り時間未満の場合、クライアントは実際にトークンの有効期限が切れる前に再認証する必要があります。デフォルトでは、アクセストークンの期限が切れてもセッションは期限切れにならず、クライアントは再認証を試行しません。

OAuth 2.0 認証の TLS リスナー設定

sasl.enabled.mechanisms=
listeners=REPLICATION://kafka:9091,CLIENT://kafka:9092 1
listener.security.protocol.map=REPLICATION:SSL,CLIENT:SASL_PLAINTEXT 2
listener.name.client.sasl.enabled.mechanisms=OAUTHBEARER
inter.broker.listener.name=REPLICATION
listener.name.replication.ssl.keystore.password=KEYSTORE-PASSWORD 3
listener.name.replication.ssl.truststore.password=TRUSTSTORE-PASSWORD
listener.name.replication.ssl.keystore.type=JKS
listener.name.replication.ssl.truststore.type=JKS
listener.name.replication.ssl.endpoint.identification.algorithm=HTTPS 4
listener.name.replication.ssl.secure.random.implementation=SHA1PRNG 5
listener.name.replication.ssl.keystore.location=PATH-TO-KEYSTORE 6
listener.name.replication.ssl.truststore.location=PATH-TO-TRUSTSTORE 7
listener.name.replication.ssl.client.auth=required 8
listener.name.client.oauthbearer.sasl.server.callback.handler.class=io.strimzi.kafka.oauth.server.JaasServerOauthValidatorCallbackHandler
listener.name.client.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
  oauth.valid.issuer.uri="https://AUTH-SERVER-ADDRESS" \
  oauth.jwks.endpoint.uri="https://AUTH-SERVER-ADDRESS/jwks" \
  oauth.username.claim="preferred_username" ; 9

1
inter-broker 通信とクライアントアプリケーションには、個別の設定が必要です。
2
REPLICATION リスナーが TLS を使用し、CLIENT リスナーが暗号化されていないチャネルで SASL を使用するように設定します。実稼働環境では、クライアントは暗号化されたチャンネル (SASL_SSL) を使用できます。
3
ssl. プロパティーは TLS 設定を定義します。
4
乱数ジェネレーターの実装。設定されていない場合は、Java プラットフォーム SDK デフォルトが使用されます。
5
ホスト名の検証。空の文字列に設定すると、ホスト名の検証はオフになります。設定されていない場合、デフォルト値は HTTPS で、サーバー証明書のホスト名の検証を強制します。
6
リスナーのキーストアへのパス。
7
リスナーのトラストストアへのパス。
8
(inter-broker 接続に使用される) TLS 接続の確立時に REPLICATION リスナーのクライアントがクライアント証明書で認証する必要があることを指定します。
9
OAuth 2.0 の CLIENT リスナーを設定します。承認サーバーとの接続はセキュアな HTTPS 接続を使用する必要があります。
4.10.2.3. 高速なローカル JWT トークン検証の設定

高速なローカル JWT トークンの検証では、JWTトークンの署名がローカルでチェックされます。

ローカルチェックでは、トークンに対して以下が確認されます。

  • アクセストークンに Bearer の (typ) 要求値が含まれ、トークンがタイプに準拠することを確認します。
  • 有効であるか (期限切れでない) を確認します。
  • トークンに validIssuerURI と一致する発行元があることを確認します。

承認サーバーによって発行されなかったすべてのトークンが拒否されるよう、リスナーの設定時に 有効な発行者 URI を指定します。

高速のローカル JWT トークン検証の実行中に、承認サーバーの通信は必要はありません。OAuth 2.0 承認サーバーによって公開される JWK エンドポイント URI を指定して、高速のローカル JWT トークン検証をアクティベートします。エンドポイントには、署名済み JWT トークンの検証に使用される公開鍵が含まれます。これらは、Kafka クライアントによってクレデンシャルとして送信されます。

注記

承認サーバーとの通信はすべて HTTPS を使用して実行する必要があります。

TLS リスナーでは、証明書 トラストストア を設定し、トラストストアファイルをポイントできます。

高速なローカル JWT トークン検証のプロパティーの例

listener.name.client.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
  oauth.valid.issuer.uri="https://AUTH-SERVER-ADDRESS" \ 1
  oauth.jwks.endpoint.uri="https://AUTH-SERVER-ADDRESS/jwks" \ 2
  oauth.jwks.refresh.seconds="300" \ 3
  oauth.jwks.refresh.min.pause.seconds="1" \ 4
  oauth.jwks.expiry.seconds="360" \ 5
  oauth.username.claim="preferred_username" \ 6
  oauth.ssl.truststore.location="PATH-TO-TRUSTSTORE-P12-FILE" \ 7
  oauth.ssl.truststore.password="TRUSTSTORE-PASSWORD" \ 8
  oauth.ssl.truststore.type="PKCS12" ; 9

1
有効な発行者 URI。この発行者が発行するアクセストークンのみが受け入れられます。例: https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME
2
JWKS エンドポイント URL。例: https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME/protocol/openid-connect/certs
3
エンドポイントの更新間隔 (デフォルトは 300)。
4
JWKS 公開鍵の更新が連続して試行される間隔の最小一時停止時間 (秒単位)。不明な署名キーが検出されると、JWKS キーの更新は、最後に更新を試みてから少なくとも指定された期間は一時停止し、通常の定期スケジュール以外でスケジュールされます。キーの更新は指数バックオフ (指数バックオフ) のルールに従い、oauth.jwks.refresh.seconds に到達するまで、一時停止を増やして失敗した更新を再試行します。デフォルト値は 1 です。
5
JWK 証明書が期限切れになる前に有効とみなされる期間。デフォルトは 360 秒です。デフォルトよりも長い時間を指定する場合は、無効になった証明書へのアクセスが許可されるリスクを考慮してください。
6
トークンの実際のユーザー名が含まれるトークン要求 (またはキー)。ユーザー名は、ユーザーの識別に使用される principal です。値は、使用される認証フローと承認サーバーによって異なります。
7
TLS 設定で使用されるトラストストアの場所。
8
トラストストアにアクセスするためのパスワード。
9
PKCS #12 形式のトラストストアタイプ。
4.10.2.4. OAuth 2.0 イントロスペクションエンドポイントの設定

OAuth 2.0 のイントロスペクションエンドポイントを使用したトークンの検証では、受信したアクセストークンは不透明として対処されます。Kafka ブローカーは、アクセストークンをイントロスペクションエンドポイントに送信します。このエンドポイントは、検証に必要なトークン情報を応答として返します。ここで重要なのは、特定のアクセストークンが有効である場合は最新情報を返すことで、トークンの有効期限に関する情報も返します。

OAuth 2.0 イントロスペクションベースの検証を構成するには、高速ローカル JWT トークン検証用に指定された JWK エンドポイント URI ではなく、イントロスペクションエンドポイント URI を指定します。通常、イントロスペクションエンドポイントは保護されているため、承認サーバーに応じて client ID および client secret を指定する必要があります。

イントロスペクションエンドポイントのプロパティー例

listener.name.client.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
  oauth.introspection.endpoint.uri="https://AUTH-SERVER-ADDRESS/introspection" \ 1
  oauth.client.id="kafka-broker" \ 2
  oauth.client.secret="kafka-broker-secret" \ 3
  oauth.ssl.truststore.location="PATH-TO-TRUSTSTORE-P12-FILE" \ 4
  oauth.ssl.truststore.password="TRUSTSTORE-PASSWORD" \ 5
  oauth.ssl.truststore.type="PKCS12" \ 6
  oauth.username.claim="preferred_username" ; 7

1
OAuth 2.0 イントロスペクションエンドポイント URI。例: https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME/protocol/openid-connect/token/introspect
2
Kafka ブローカーのクライアント ID。
3
Kafka ブローカーのシークレット。
4
TLS 設定で使用されるトラストストアの場所。
5
トラストストアにアクセスするためのパスワード。
6
PKCS #12 形式のトラストストアタイプ。
7
トークンの実際のユーザー名が含まれるトークン要求 (またはキー)。ユーザー名は、ユーザーの識別に使用される principal です。oauth.username.claim の値は、使用される承認サーバーによって異なります。

4.10.3. Kafka ブローカーの再認証の設定

AMQ Streams の OAuth 2.0 認証に使用される Kafka SASL OAUTHBEARER メカニズムは、再認証 メカニズムと呼ばれる Kafka 機能をサポートします。

リスナー設定で再認証メカニズムが有効になっている場合、アクセストークンの期限が切れるとブローカーの認証されたセッションが期限切れになります。その後、クライアントは接続を切断せずに新しい有効なアクセストークンをブローカーに送信し、既存のセッションを再認証する必要があります。

トークンの検証に成功すると、既存の接続を使用して新しいクライアントセッションが開始されます。クライアントが再認証に失敗した場合、さらにメッセージを送受信しようとすると、ブローカーは接続を閉じます。ブローカーで再認証メカニズムが有効になっていると、Kafka クライアントライブラリー 2.2 以降を使用する Java クライアントが自動的に再認証されます。

Kafka server.properties ファイルで Kafka ブローカーのセッションの再認証を有効にします。OAUTHBEARER を SASL メカニズムとして有効にした TLS リスナーに connections.max.reauth.ms プロパティーを設定します。

リスナーごとにセッションの再認証を指定できます。以下に例を示します。

listener.name.client.oauthbearer.connections.max.reauth.ms=3600000

セッションの再認証は、高速のローカル JWT とイントロスペクションエンドポイントの両タイプのトークン検証でサポートされます。設定例については、「Kafka ブローカーの OAuth 2.0 サポートの設定」 を参照してください。

Kafka バージョン 2.2 に追加された再認証メカニズムの詳細は、「KIP-368」を参照してください。

4.10.4. OAuth 2.0 Kafka クライアントの設定

Kafka クライアントは以下のいずれかで設定されます。

  • 承認サーバーから有効なアクセストークンを取得するために必要な認証情報(クライアント ID およびシークレット)
  • 承認サーバーから提供されたツールを使用して取得された、有効期限の長い有効なアクセストークンまたは更新トークン。

クレデンシャルは Kafka ブローカーに送信されることはありません。アクセストークンは、Kafka ブローカーに送信される唯一の情報です。クライアントによるアクセストークンの取得後、承認サーバーと通信する必要はありません。

クライアント ID とシークレットを使用した認証が最も簡単です。有効期間の長いアクセストークンまたは更新トークンを使用すると、承認サーバーツールに追加の依存関係があるため、より複雑になります。

注記

有効期間が長いアクセストークンを使用している場合は、承認サーバーでクライアントを設定し、トークンの最大有効期間を長くする必要があります。

Kafka クライアントが直接アクセストークンで設定されていない場合、クライアントは承認サーバーと通信して Kafka セッションの開始中にアクセストークンのクレデンシャルを交換します。Kafka クライアントは以下のいずれかを交換します。

  • クライアント ID およびシークレット
  • クライアント ID、更新トークン、および (任意の) シークレット

4.10.5. OAuth 2.0 のクライアント認証フロー

ここでは、Kafka セッションの開始時における Kafka クライアント、Kafka ブローカー、および承認ブローカー間の通信フローを説明および可視化します。フローは、クライアントとサーバーの設定によって異なります。

Kafka クライアントがアクセストークンをクレデンシャルとして Kafka ブローカーに送信する場合、トークンを検証する必要があります。

使用する承認サーバーや利用可能な設定オプションによっては、以下の使用が適している場合があります。

  • 承認サーバーと通信しない、JWT の署名確認およびローカルトークンのイントロスペクションをベースとした高速なローカルトークン検証。
  • 承認サーバーによって提供される OAuth 2.0 のイントロスペクションエンドポイント。

高速のローカルトークン検証を使用するには、トークンでの署名検証に使用される公開証明書のある JWKS エンドポイントを提供する承認サーバーが必要になります。

この他に、承認サーバーで OAuth 2.0 のイントロスペクションエンドポイントを使用することもできます。新しい Kafka ブローカー接続が確立されるたびに、ブローカーはクライアントから受け取ったアクセストークンを承認サーバーに渡し、応答を確認してトークンが有効であるかどうかを確認します。

Kafka クライアントのクレデンシャルは以下に対して設定することもできます。

  • 以前に生成された有効期間の長いアクセストークンを使用した直接ローカルアクセス。
  • 新しいアクセストークンの発行についての承認サーバーとの通信。
注記

承認サーバーは不透明なアクセストークンの使用のみを許可する可能性があり、この場合はローカルトークンの検証は不可能です。

4.10.5.1. クライアント認証フローの例

Kafka クライアントおよびブローカーが以下に設定されている場合の、Kafka セッション認証中のコミュニケーションフローを確認できます。

クライアントがクライアント ID とシークレットを使用し、ブローカーが検証を承認サーバーに委任する場合

Client using client ID and secret with broker delegating validation to authorization server

  1. Kafka クライアントは承認サーバーからアクセストークンを要求します。これにはクライアント ID とシークレットを使用し、任意で更新トークンも使用します。
  2. 承認サーバーによって新しいアクセストークンが生成されます。
  3. Kafka クライアントは SASL OAUTHBEARER メカニズムを使用してアクセストークンを渡し、Kafka ブローカーの認証を行います。
  4. Kafka ブローカーは、独自のクライアント ID およびシークレットを使用して、承認サーバーでトークンイントロスペクションエンドポイントを呼び出し、アクセストークンを検証します。
  5. トークンが有効な場合は、Kafka クライアントセッションが確立されます。

クライアントではクライアント ID およびシークレットが使用され、ブローカーによって高速のローカルトークン検証が実行される場合

Client using client ID and secret with broker performing fast local token validation

  1. Kafka クライアントは、トークンエンドポイントから承認サーバーの認証を行います。これにはクライアント ID とシークレットが使用され、任意で更新トークンも使用されます。
  2. 承認サーバーによって新しいアクセストークンが生成されます。
  3. Kafka クライアントは SASL OAUTHBEARER メカニズムを使用してアクセストークンを渡し、Kafka ブローカーの認証を行います。
  4. Kafka ブローカーは、JWT トークン署名チェックおよびローカルトークンイントロスペクションを使用して、ローカルでアクセストークンを検証します。

クライアントでは有効期限の長いアクセストークンが使用され、ブローカーによって検証が承認サーバーに委譲される場合

Client using long-lived access token with broker delegating validation to authorization server

  1. Kafka クライアントは、SASL OAUTHBEARER メカニズムを使用して有効期限の長いアクセストークンを渡し、Kafka ブローカーの認証を行います。
  2. Kafka ブローカーは、独自のクライアント ID およびシークレットを使用して、承認サーバーでトークンイントロスペクションエンドポイントを呼び出し、アクセストークンを検証します。
  3. トークンが有効な場合は、Kafka クライアントセッションが確立されます。

クライアントでは有効期限の長いアクセストークンが使用され、ブローカーによって高速のローカル検証が実行される場合

Client using long-lived access token with broker performing fast local validation

  1. Kafka クライアントは、SASL OAUTHBEARER メカニズムを使用して有効期限の長いアクセストークンを渡し、Kafka ブローカーの認証を行います。
  2. Kafka ブローカーは、JWT トークン署名チェックおよびローカルトークンイントロスペクションを使用して、ローカルでアクセストークンを検証します。
警告

トークンが取り消された場合に承認サーバーとのチェックが行われないため、高速のローカル JWT トークン署名の検証は有効期限の短いトークンにのみ適しています。トークンの有効期限はトークンに書き込まれますが、失効はいつでも発生する可能性があるため、承認サーバーと通信せずに対応することはできません。発行されたトークンはすべて期限切れになるまで有効とみなされます。

4.10.6. OAuth 2.0 認証の設定

OAuth 2.0 は、Kafka クライアントと AMQ Streams コンポーネントとの対話に使用されます。

AMQ Streams に OAuth 2.0 を使用するには、以下を行う必要があります。

4.10.6.1. OAuth 2.0 承認サーバーとしての Red Hat Single Sign-On の設定

この手順では、Red Hat Single Sign-On を承認サーバーとしてデプロイし、AMQ Streams と統合するための設定方法を説明します。

承認サーバーは、一元的な認証および承認の他、ユーザー、クライアント、およびパーミッションの一元管理を実現します。Red Hat Single Sign-On にはレルムの概念があります。レルム はユーザー、クライアント、パーミッション、およびその他の設定の個別のセットを表します。デフォルトの マスターレルム を使用できますが、新しいレルムを作成することもできます。各レルムは独自の OAuth 2.0 エンドポイントを公開します。そのため、アプリケーションクライアントとアプリケーションサーバーはすべて同じレルムを使用する必要があります。

AMQ Streams で OAuth 2.0 を使用するには、認証レルムを作成および管理できるように承認サーバーのデプロイメントが必要です。

注記

Red Hat Single Sign-On がすでにデプロイされている場合は、デプロイメントの手順を省略して、現在のデプロイメントを使用できます。

作業を開始する前に

Red Hat Single Sign-On を使用するための知識が必要です。

インストールおよび管理の手順は、以下を参照してください。

前提条件

  • AMQ Streams および Kafka が稼働している。

Red Hat Single Sign-On デプロイメントの場合:

手順

  1. Red Hat Single Sign-On をインストールします。

    ZIP ファイルから、または RPM を使用してインストールできます。

  2. Red Hat Single Sign-On の Admin Console にログインし、AMQ Streams の OAuth 2.0 ポリシーを作成します。

    ログインの詳細は、Red Hat Single Sign-On のデプロイ時に提供されます。

  3. レルムを作成し、有効にします。

    既存のマスターレルムを使用できます。

  4. 必要に応じて、レルムのセッションおよびトークンのタイムアウトを調整します。
  5. kafka-broker というクライアントを作成します。
  6. Settings タブで以下を設定します。

    • Access TypeConfidential に設定します。
    • Standard Flow EnabledOFF に設定し、このクライアントからの Web ログインを無効にします。
    • Service Accounts EnabledON に設定し、このクライアントが独自の名前で認証できるようにします。
  7. 続行する前に Save クリックします。
  8. Credentials タブにある、AMQ Streams の Kafka クラスター設定で使用するシークレットを書き留めておきます。
  9. Kafka ブローカーに接続するすべてのアプリケーションクライアントに対して、このクライアント作成手順を繰り返し行います。

    新しいクライアントごとに定義を作成します。

    設定では、名前をクライアント ID として使用します。

次のステップ

承認サーバーのデプロイおよび設定後に、Kafka ブローカーが OAuth 2.0 を使用するように設定 します。

4.10.6.2. Kafka ブローカーの OAuth 2.0 サポートの設定

この手順では、ブローカーリスナーが承認サーバーを使用して OAuth 2.0 認証を使用するように、Kafka ブローカーを設定する方法について説明します。

TLS リスナーを設定して、暗号化されたインターフェイスで OAuth 2.0 を使用することが推奨されます。プレーンリスナーは推奨されません。

選択した承認サーバーをサポートするプロパティーと、実装している承認のタイプを使用して、Kafka ブローカーを設定します。

作業を開始する前の注意事項

Kafka ブローカーリスナーの設定および認証に関する詳細は、以下を参照してください。

リスナー設定で使用されるプロパティーの説明は、以下を参照してください。

前提条件

  • AMQ Streams および Kafka が稼働している。
  • OAuth 2.0 の承認サーバーがデプロイされている。

手順

  1. server.properties ファイルで Kafka ブローカーリスナー設定を設定します。

    以下に例を示します。

    sasl.enabled.mechanisms=OAUTHBEARER
    listeners=CLIENT://0.0.0.0:9092
    listener.security.protocol.map=CLIENT:SASL_PLAINTEXT
    listener.name.client.sasl.enabled.mechanisms=OAUTHBEARER
    sasl.mechanism.inter.broker.protocol=OAUTHBEARER
    inter.broker.listener.name=CLIENT
    listener.name.client.oauthbearer.sasl.server.callback.handler.class=io.strimzi.kafka.oauth.server.JaasServerOauthValidatorCallbackHandler
    listener.name.client.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required ;
    listener.name.client.oauthbearer.sasl.login.callback.handler.class=io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler
  2. listener.name.client.oauthbearer.sasl.jaas.config の一部としてブローカーの接続設定を行います。

    この例では、接続設定オプションを示しています。

    例 1: JWKS エンドポイント設定を使用したローカルトークンの検証

    listener.name.client.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
      oauth.valid.issuer.uri="https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME" \
      oauth.jwks.endpoint.uri="https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME/protocol/openid-connect/certs" \
      oauth.jwks.refresh.seconds="300" \
      oauth.jwks.refresh.min.pause.seconds="1" \
      oauth.jwks.expiry.seconds="360" \
      oauth.username.claim="preferred_username" \
      oauth.ssl.truststore.location="PATH-TO-TRUSTSTORE-P12-FILE" \
      oauth.ssl.truststore.password="TRUSTSTORE-PASSWORD" \
      oauth.ssl.truststore.type="PKCS12" ;
    listener.name.client.oauthbearer.connections.max.reauth.ms=3600000

    例 2: OAuth 2.0 イントロスペクションエンドポイントを使用した承認サーバーへのトークン検証の委譲

    listener.name.client.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
      oauth.introspection.endpoint.uri="https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME/protocol/openid-connect/introspection" \
      # ...

  3. 必要な場合は、承認サーバーへのアクセスを設定します。

    この手順は通常、サービスメッシュ などの技術がコンテナーの外部でセキュアなチャネルを設定するために使用される場合を除き、実稼働環境で必要になります。

    1. セキュアな承認サーバーに接続するためのカスタムトラストストアを指定します。承認サーバーへのアクセスには SSL が常に必要になります。

      プロパティーを設定してトラストストアを設定します。

      以下に例を示します。

      listener.name.client.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
        # ...
        oauth.client.id="kafka-broker" \
        oauth.client.secret="kafka-broker-secret" \
        oauth.ssl.truststore.location="PATH-TO-TRUSTSTORE-P12-FILE" \
        oauth.ssl.truststore.password="TRUSTSTORE-PASSWORD" \
        oauth.ssl.truststore.type="PKCS12" ;
    2. 証明書のホスト名がアクセス URL ホスト名と一致しない場合は、証明書のホスト名の検証をオフにできます。

      oauth.ssl.endpoint.identification.algorithm=""

      このチェックは、承認サーバーへのクライアント接続が認証されるようにします。実稼働以外の環境で検証をオフにすることもできます。

  4. 選択した認証フローに応じて、追加のプロパティーを設定します。

    listener.name.client.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
      # ...
      oauth.token.endpoint.uri="https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME/protocol/openid-connect/token" \ 1
      oauth.valid.issuer.uri="https://https://AUTH-SERVER-ADDRESS/auth/REALM-NAME" \ 2
      oauth.client.id="kafka-broker" \ 3
      oauth.client.secret="kafka-broker-secret" \ 4
    
      oauth.refresh.token="REFRESH-TOKEN-FOR-KAFKA-BROKERS" \ 5
      oauth.access.token="ACCESS-TOKEN-FOR-KAFKA-BROKERS" ; 6
    1
    承認サーバーへの OAuth 2.0 トークンエンドポイント URL。実稼働環境では、常に HTTPS を使用してください KeycloakRBACAuthorizer を使用する場合、または inter-broker 通信に OAuth 2.0 が有効なリスナーが使用されている場合に必要です。
    2
    有効な発行者 URI。この発行者が発行するアクセストークンのみが受け入れられます。(常に必要です)
    3
    すべてのブローカーで同一の、Kafka ブローカーの設定されたクライアント ID。これは、kafka-broker として承認サーバーに登録されたクライアントです。イントロスペクションエンドポイントがトークンの検証に使用される場合、または KeycloakRBACAuthorizer が使用される場合に必要です。
    4
    すべてのブローカーで同じ Kafka ブローカーに設定されたシークレット。ブローカーが認証サーバーに対して認証する必要がある場合は、クライアントシークレット、アクセストークン、または更新トークンのいずれかを指定する必要があります。
    5
    (オプション) Kafka ブローカー用の長期間有効な更新トークン。
    6
    (オプション) Kafka ブローカー用の長期間有効なアクセストークン。
  5. OAuth 2.0 認証の適用方法、および使用されている認証サーバーのタイプに応じて、構成設定を追加します。

    listener.name.client.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
      # ...
      oauth.check.issuer=false \ 1
      oauth.fallback.username.claim="CLIENT-ID" \ 2
      oauth.fallback.username.prefix="CLIENT-ACCOUNT" \ 3
      oauth.valid.token.type="bearer" \ 4
      oauth.userinfo.endpoint.uri="https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME/protocol/openid-connect/userinfo" ; 5
    1
    承認サーバーが iss クレームを提供しない場合は、発行者チェックを行うことができません。このような場合、oauth.check.issuerfalse に設定し、oauth.valid.issuer.uri を指定しないようにします。デフォルトは true です。
    2
    承認サーバーは、通常ユーザーとクライアントの両方を識別する単一の属性を提供しない場合があります。クライアントが独自の名前で認証される場合、サーバーによって クライアント ID が提供されることがあります。更新トークンまたはアクセストークンを取得するために、ユーザー名およびパスワードを使用してユーザーが認証される場合、サーバーによってクライアント ID の他に ユーザー名 が提供されることがあります。プライマリーユーザー ID 属性が使用できない場合は、このフォールバックオプションで、使用するユーザー名クレーム (属性) を指定します。
    3
    oauth.fallback.username.claim が適用される場合、ユーザー名クレームの値とフォールバックユーザー名クレームの値が競合しないようにする必要もあることがあります。producer というクライアントが存在し、producer という通常ユーザーも存在する場合について考えてみましょう。この 2 つを区別するには、このプロパティーを使用してクライアントのユーザー ID に接頭辞を追加します。
    4
    (oauth.introspection.endpoint.uri を使用する場合のみ該当): 使用している認証サーバーによっては、イントロスペクションエンドポイントによって トークンタイプ 属性が返されるかどうかは分からず、異なる値が含まれることがあります。イントロスペクションエンドポイントからの応答に含まれなければならない有効なトークンタイプ値を指定できます。
    5
    (oauth.introspection.endpoint.uri を使用する場合のみ該当): イントロスペクションエンドポイントの応答に識別可能な情報が含まれないように、承認サーバーが設定または実装されることがあります。ユーザー ID を取得するには、userinfo エンドポイントの URI をフォールバックとして設定します。oauth.fallback.username.claimoauth.fallback.username.claim、および oauth.fallback.username.prefix 設定が userinfo エンドポイントの応答に適用されます。
4.10.6.3. OAuth 2.0 を使用するための Kafka Java クライアントの設定

この手順では、Kafka ブローカーとの対話に OAuth 2.0 を使用するように Kafka プロデューサーおよびコンシューマー API を設定する方法を説明します。

クライアントコールバックプラグインを pom.xml ファイルに追加し、システムプロパティーを設定します。

前提条件

  • AMQ Streams および Kafka が稼働している。
  • OAuth 2.0 承認サーバーがデプロイされ、Kafka ブローカーへの OAuth のアクセスが設定されている。
  • Kafka ブローカーが OAuth 2.0 に対して設定されている。

手順

  1. OAuth 2.0 サポートのあるクライアントライブラリーを Kafka クライアントの pom.xml ファイルに追加します。

    <dependency>
     <groupId>io.strimzi</groupId>
     <artifactId>kafka-oauth-client</artifactId>
     <version>0.6.1.redhat-00003</version>
    </dependency>
  2. コールバックのシステムプロパティーを設定します。

    以下はその例です。

    System.setProperty(ClientConfig.OAUTH_TOKEN_ENDPOINT_URI, “https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME/protocol/openid-connect/token”); 1
    System.setProperty(ClientConfig.OAUTH_CLIENT_ID, "CLIENT-NAME"); 2
    System.setProperty(ClientConfig.OAUTH_CLIENT_SECRET, "CLIENT_SECRET"); 3
    System.setProperty(ClientConfig.OAUTH_SCOPE, "SCOPE-VALUE") 4
    1
    承認サーバーのトークンエンドポイントの URI です。
    2
    クライアント ID。承認サーバーで client を作成するときに使用される名前です。
    3
    承認サーバーで client を作成するときに作成されるクライアントシークレット。
    4
    (オプション): トークンエンドポイントからトークンを要求するための scope。認証サーバーでは、クライアントによるスコープの指定が必要になることがあります。
  3. Kafka クライアント設定の TLS で暗号化された接続で SASL OAUTHBEARER メカニズムを有効にします。

    以下は例になります。

    props.put("sasl.jaas.config", "org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required;");
    props.put("security.protocol", "SASL_SSL"); 1
    props.put("sasl.mechanism", "OAUTHBEARER");
    props.put("sasl.login.callback.handler.class", "io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler");
    1
    この例では、TLS 接続で SASL_SSL を使用します。暗号化されていない接続では SASL_PLAINTEXT を使用します。
  4. Kafka クライアントが Kafka ブローカーにアクセスできることを確認します。

4.11. OAuth 2.0 トークンベース承認の使用

トークンベースの認証に OAuth 2.0 と Red Hat Single Sign-On を使用している場合、Red Hat Single Sign-On を使用して承認ルールを設定し、Kafka ブローカーへのクライアントのアクセスを制限することもできます。認証はユーザーのアイデンティティーを確立します。承認は、そのユーザーのアクセスレベルを決定します。

AMQ Streams は、Red Hat Single Sign-On の 認証サービス による OAuth 2.0 トークンベースの承認をサポートします。これにより、セキュリティーポリシーとパーミッションの一元的な管理が可能になります。

Red Hat Single Sign-On で定義されたセキュリティーポリシーおよびパーミッションは、Kafka ブローカーのリソースへのアクセスを付与するために使用されます。ユーザーとクライアントは、Kafka ブローカーで特定のアクションを実行するためのアクセスを許可するポリシーに対して照合されます。

Kafka では、デフォルトですべてのユーザーがブローカーに完全アクセスできます。また、アクセス制御リスト(ACL)を基にして承認を設定するために AclAuthorizer プラグインが提供されます。

ZooKeeper には、ユーザー名 を基にしてリソースへのアクセスを付与または拒否する ACL ルールが保存されます。ただし、Red Hat Single Sign-On を使用した OAuth 2.0 トークンベースの承認では、より柔軟にアクセス制御を Kafka ブローカーに実装できます。さらに、Kafka ブローカーで OAuth 2.0 の承認および ACL が使用されるように設定することができます。

4.11.1. OAuth 2.0 の承認メカニズム

AMQ Streams の OAuth 2.0 での承認では、Red Hat Single Sign-On サーバーの Authorization Services REST エンドポイントを使用して、Red Hat Single Sign-On を使用するトークンベースの認証が拡張されます。これは、定義されたセキュリティーポリシーを特定のユーザーに適用し、そのユーザーの異なるリソースに付与されたパーミッションの一覧を提供します。ポリシーはロールとグループを使用して、パーミッションをユーザーと照合します。OAuth 2.0 の承認では、Red Hat Single Sign-On の Authorization Services から受信した、ユーザーに付与された権限のリストを基にして、権限がローカルで強制されます。

4.11.1.1. Kafka ブローカーのカスタムオーソライザー

AMQ Streams では、Red Hat Single Sign-On の オーソライザー (KeycloakRBACAuthorizer) が提供されます。Red Hat Single Sign-On によって提供される Authorization Services で Red Hat Single Sign-On REST エンドポイントを使用できるようにするには、Kafka ブローカーでカスタムオーソライザーを設定します。

オーソライザーは必要に応じて付与された権限のリストを承認サーバーから取得し、ローカルで Kafka ブローカーに承認を強制するため、クライアントの要求ごとに迅速な承認決定が行われます。

4.11.2. OAuth 2.0 承認サポートの設定

この手順では、Red Hat Single Sign-On の Authorization Services を使用して、OAuth 2.0 承認を使用するように Kafka ブローカーを設定する方法を説明します。

作業を開始する前に

特定のユーザーに必要なアクセス、または制限するアクセスについて検討してください。Red Hat Single Sign-On では、Red Hat Single Sign-On の グループロールクライアント、および ユーザー の組み合わせを使用して、アクセスを設定できます。

通常、グループは組織の部門または地理的な場所を基にしてユーザーを照合するために使用されます。また、ロールは職務を基にしてユーザーを照合するために使用されます。

Red Hat Single Sign-On を使用すると、ユーザーおよびグループを LDAP で保存できますが、クライアントおよびロールは LDAP で保存できません。ユーザーデータへのアクセスとストレージを考慮して、承認ポリシーの設定方法を選択する必要がある場合があります。

注記

スーパーユーザー は、Kafka ブローカーに実装された承認にかかわらず、常に制限なく Kafka ブローカーにアクセスできます。

前提条件

  • AMQ Streams は、トークンベースの認証 に Red Hat Single Sign-On と OAuth 2.0 を使用するように設定されている必要がある。承認を設定するときに、同じ Red Hat Single Sign-On サーバーエンドポイントを使用する必要があります。
  • Red Hat Single Sign-On のドキュメント の説明にあるように、Red Hat Single Sign-On の Authorization Services のポリシーおよびパーミッションを管理する方法を理解している必要がある。

手順

  1. Red Hat Single Sign-On の Admin Console にアクセスするか、Red Hat Single Sign-On の Admin CLI を使用して、OAuth 2.0 認証の設定時に作成した Kafka ブローカークライアントの Authorization Services を有効にします。
  2. 承認サービスを使用して、クライアントのリソース、承認スコープ、ポリシー、およびパーミッションを定義します。
  3. ロールとグループをユーザーとクライアントに割り当てて、パーミッションをユーザーとクライアントにバインドします。
  4. Red Hat Single Sign-On 承認を使用するように Kafka ブローカーを設定します。

    以下を Kafka server.properties 設定ファイルに追加し、Kafka にオーソライザーをインストールします。

    authorizer.class.name=io.strimzi.kafka.oauth.server.authorizer.KeycloakRBACAuthorizer
    principal.builder.class=io.strimzi.kafka.oauth.server.authorizer.JwtKafkaPrincipalBuilder
  5. Kafka ブローカーの設定を追加して、承認サーバーおよび Authorization Services にアクセスします。

    ここでは、server.properties への追加プロパティーとして追加される設定例を示しますが、大文字で始める、または大文字の命名規則を使用して、環境変数として定義することもできます。

    strimzi.authorization.token.endpoint.uri="https://AUTH-SERVER-ADDRESS/auth/realms/REALM-NAME/protocol/openid-connect/token" 1
    strimzi.authorization.client.id="kafka" 2
    1
    Red Hat Single Sign-On への OAuth 2.0 トークンエンドポイントの URL。実稼働環境では、常に HTTPS を使用してください
    2
    承認サービスが有効になっている Red Hat Single Sign-On の OAuth 2.0 クライアント定義のクライアント ID。通常、kafka が ID として使用されます。
  6. (オプション) 特定の Kafka クラスターの構成を追加します。

    以下に例を示します。

    strimzi.authorization.kafka.cluster.name="kafka-cluster" 1
    1
    特定の Kafka クラスターの名前。名前はパーミッションをターゲットにするために使用され、同じ Red Hat シングルサインオンレルム内で複数のクラスターを管理できるようにします。デフォルト値は kafka-cluster です。
  7. (オプション) 単純許可に委任します。

    以下に例を示します。

    strimzi.authorization.delegate.to.kafka.acl="false" 1
    1
    Red Hat Single Sign-On Authorization Services ポリシーでアクセスが拒否された場合、Kafka AclAuthorizer に権限を委任します。デフォルトは false です。
  8. (オプション) TLS 接続の構成を許可サーバーに追加します。

    以下に例を示します。

    strimzi.authorization.ssl.truststore.location=<path-to-truststore> 1
    strimzi.authorization.ssl.truststore.password=<my-truststore-password> 2
    strimzi.authorization.ssl.truststore.type=JKS 3
    strimzi.authorization.ssl.secure.random.implementation=SHA1PRNG 4
    strimzi.authorization.ssl.endpoint.identification.algorithm=HTTPS 5
    1
    証明書が含まれるトラストストアへのパス。
    2
    トラストストアのパスワード。
    3
    トラストストアのタイプ。設定されていない場合は、デフォルトの Java キーストアタイプが使用されます。
    4
    乱数ジェネレーターの実装。設定されていない場合は、Java プラットフォーム SDK デフォルトが使用されます。
    5
    ホスト名の検証。空の文字列に設定すると、ホスト名の検証はオフになります。設定されていない場合、デフォルト値は HTTPS で、サーバー証明書のホスト名の検証を強制します。
  9. (オプション) 許可サーバーからの許可の更新を構成します。付与更新ジョブは、アクティブなトークンを列挙し、それぞれに最新の付与を要求することで機能します。

    以下に例を示します。

    strimzi.authorization.grants.refresh.period.seconds="120" 1
    strimzi.authorization.grants.refresh.pool.size="10" 2
    1
    許可サーバーからの許可のリストが更新される頻度を指定します (デフォルトでは 1 分に 1 回)。デバッグの目的で付与の更新をオフにするには、"0" に設定します。
    2
    付与更新ジョブで使用されるスレッドプールのサイズ (並列度) を指定します。デフォルト値は "5" です。
  10. クライアントまたは特定のロールを持つユーザーとして Kafka ブローカーにアクセスして、設定したパーミッションを検証し、必要なアクセス権限があり、付与されるべきでないアクセス権限がないことを確認します。

4.12. OPA ポリシーベースの承認の使用

Open Policy Agent (OPA) は、オープンソースのポリシーエンジンです。OPA と AMQ Streams を統合して、Kafka ブローカーでのクライアント操作を許可するポリシーベースの承認メカニズムとして機能します。

クライアントからリクエストが実行されると、OPA は Kafka アクセスに定義されたポリシーに対してリクエストを評価し、リクエストを許可または拒否します。

注記

Red Hat は OPA サーバーをサポートしません。

4.12.1. OPA ポリシーの定義

OPA と AMQ Streams を統合する前に、粒度の細かいアクセス制御を提供するポリシーの定義方法を検討してください。

Kafka クラスター、コンシューマーグループ、およびトピックのアクセス制御を定義できます。たとえば、プロデューサークライアントから特定のブローカートピックへの書き込みアクセスを許可する承認ポリシーを定義できます。

このポリシーでは、以下の項目を指定することができます。

  • プロデューサークライアントに関連付けられた ユーザープリンシパル および ホストアドレス
  • クライアントに許可される 操作
  • ポリシーが適用される リソースタイプ (topic) および リソース名

許可と拒否の決定がポリシーに書き込まれ、提供された要求とクライアント識別データに基づいて応答が提供されます。

この例では、プロデューサークライアントはトピックへの書き込みが許可されるポリシーを満たす必要があります。

4.12.2. OPA への接続

Kafka が OPA ポリシーエンジンにアクセスしてアクセス制御ポリシーをクエリーできるようにするには、Kafka server.properties ファイルでカスタム OPA オーソライザープラグイン (kafka-authorizer-opa-VERSION.jar) を設定します。

クライアントがリクエストを行うと、OPA ポリシーエンジンは、指定された URL アドレスと REST エンドポイントを使用してプラグインによってクエリーされます。これは、定義されたポリシーの名前でなければなりません。

プラグインは、ポリシーに対してチェックされる JSON 形式で、クライアント要求の詳細 (ユーザープリンシパル、操作、およびリソース) を提供します。詳細には、クライアントの一意のアイデンティティーが含まれます。たとえば、TLS 認証が使用される場合にクライアント証明書からの識別名を取ります。

OPA はデータを使用して、リクエストを許可または拒否するためにプラグインに true または false のいずれかの応答を提供します。

4.12.3. OPA 承認サポートの設定

この手順では、OPA 承認を使用するように Kafka ブローカーを設定する方法を説明します。

作業を開始する前に

特定のユーザーに必要なアクセス、または制限するアクセスについて検討してください。ユーザー リソースと Kafka リソース の組み合わせを使用して、OPA ポリシーを定義できます。

OPA を設定して、LDAP データソースからユーザー情報を読み込むことができます。

注記

スーパーユーザー は、Kafka ブローカーに実装された承認にかかわらず、常に制限なく Kafka ブローカーにアクセスできます。

前提条件

手順

  1. Kafka ブローカーで操作を実行するため、クライアントリクエストの承認に必要な OPA ポリシーを記述します。

    「OPA ポリシーの定義」 を参照してください。

    これで、Kafka ブローカーが OPA を使用するように設定します。

  2. Kafka の OPA オーソライザープラグイン をインストールします。

    「OPA への接続」 を参照してください。

    プラグインファイルが Kafka クラスパスに含まれていることを確認してください。

  3. 以下を Kafka server.properties 設定ファイルに追加し、OPA プラグインを有効にします。

    authorizer.class.name: com.bisnode.kafka.authorization.OpaAuthorizer
  4. Kafka ブローカーの server.properties にさらに設定を追加して、OPA ポリシーエンジンおよびポリシーにアクセスします。

    以下に例を示します。

    opa.authorizer.url=https://OPA-ADDRESS/allow 1
    opa.authorizer.allow.on.error=false 2
    opa.authorizer.cache.initial.capacity=50000 3
    opa.authorizer.cache.maximum.size=50000 4
    opa.authorizer.cache.expire.after.seconds=600000 5
    super.users=User:alice;User:bob 6
    1
    (必須) オーソライザープラグインがクエリーするポリシーの OAuth 2.0 トークンエンドポイント URL。この例では、ポリシーは allow という名前です。
    2
    オーソライザープラグインが OPA ポリシーエンジンとの接続に失敗した場合に、クライアントがデフォルトで許可または拒否されるかどうかを指定するフラグ。
    3
    ローカルキャッシュの初期容量 (バイト単位)。すべてのリクエストについてプラグインに OPA ポリシーエンジンをクエリーする必要がないように、キャッシュが使用されます。
    4
    ローカルキャッシュの最大容量 (バイト単位)。
    5
    OPA ポリシーエンジンからのリロードによってローカルキャッシュが更新される時間 (ミリ秒単位)。
    6
    スーパーユーザーとして扱われるユーザープリンシパルのリスト。これにより、Open Policy Agent ポリシーをクエリーしなくても常に許可されます。

    認証および承認オプションの詳細は、Open Policy Agent の Web サイト を参照してください。

  5. 正しい承認を持つクライアントと持たないクライアントを使用して、Kafka ブローカーにアクセスして、設定したパーミッションを検証します。

4.13. ロギング

Kafka ブローカーは Log4j をロギングインフラストラクチャーとして使用します。デフォルトでは、ロギング設定は /opt/kafka/config/ ディレクトリーまたはクラスパスのいずれかに配置される log4j.properties 設定ファイルから読み取られます。設定ファイルの場所と名前は、Java プロパティー log4j.configuration を使用して変更できます。これは、KAFKA_LOG4J_OPTS 環境変数を使用して Kafka に渡すことができます。

su - kafka
export KAFKA_LOG4J_OPTS="-Dlog4j.configuration=file:/my/path/to/log4j.config"; /opt/kafka/bin/kafka-server-start.sh /opt/kafka/config/server.properties

Log4j の設定に関する詳細は、Log4j のマニュアル を参照してください。

4.13.1. Kafka ブローカーロガーのロギングレベルの動的な変更

Kafka ブローカーロギングは、複数の 各ブローカーのブローカーロガー によって提供されます。ブローカーを再起動することなく、ブローカーロガーのロギングレベルを動的に変更できます。ログで返される詳細度レベルを上げると (たとえば、INFO から DEBUG に変更)、Kafka クラスターでパフォーマンスの問題を調査するのに役立ちます。

ブローカーロガーは、デフォルトのロギングレベルに動的にリセットすることもできます。

手順

  1. kafka ユーザーに切り替えます。

    su - kafka
  2. kafka-configs.sh ツールを使用して、ブローカーのブローカーロガーの一覧を表示します。

    /opt/kafka/bin/kafka-configs.sh --bootstrap-server BOOTSTRAP-ADDRESS --describe --entity-type broker-loggers --entity-name BROKER-ID

    たとえば、ブローカー 0 の場合:

    /opt/kafka/bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type broker-loggers --entity-name 0

    これにより、TRACEDEBUGINFOWARNERROR、または FATAL の各ロガーのロギングレベルが返されます。以下に例を示します。

    #...
    kafka.controller.ControllerChannelManager=INFO sensitive=false synonyms={}
    kafka.log.TimeIndex=INFO sensitive=false synonyms={}
  3. 1 つ以上のブローカーロガーのロギングレベルを変更します。--alter および --add-config オプションを使用して、各ロガーとそのレベルを二重引用符のコンマ区切りリストとして指定します。

    /opt/kafka/bin/kafka-configs.sh --bootstrap-server BOOTSTRAP-ADDRESS --alter --add-config "LOGGER-ONE=NEW-LEVEL,LOGGER-TWO=NEW-LEVEL" --entity-type broker-loggers --entity-name BROKER-ID

    たとえば、ブローカー 0 の場合:

    /opt/kafka/bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config "kafka.controller.ControllerChannelManager=WARN,kafka.log.TimeIndex=WARN" --entity-type broker-loggers --entity-name 0

    成功すると、以下が返されます。

    Completed updating config for broker: 0.
ブローカーロガーのリセット

kafka-configs.sh ツールを使用して、1 つ以上のブローカーロガーをデフォルトのロギングレベルにリセットできます。--alter および --delete-config オプションを使用して、各ブローカーロガーを二重引用符のコンマ区切りリストとして指定します。

/opt/kafka/bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --delete-config "LOGGER-ONE,LOGGER-TWO" --entity-type broker-loggers --entity-name BROKER-ID

関連情報

第5章 トピック

Kafka のメッセージは、常にトピックとの間で送受信されます。本章では、Kafka トピックを設定および管理する方法を説明します。

5.1. パーティションおよびレプリカ

Kafka のメッセージは、常にトピックとの間で送受信されます。トピックは、常に 1 つ以上のパーティションに分割されます。パーティションはシャードとして機能します。つまり、プロデューサーによって送信されたすべてのメッセージは常に単一のパーティションにのみ書き込まれます。メッセージの異なるパーティションへのシャーディングにより、トピックを簡単に水平的にスケーリングできます。

各パーティションには 1 つ以上のレプリカを含めることができ、レプリカはクラスター内の異なるブローカーに保存されます。トピックの作成時に、レプリケーション係数 を使用してレプリカ数を設定できます。レプリケーション係数 は、クラスター内で保持するコピーの数を定義します。指定したパーティションのレプリカの 1 つがリーダーとして選択されます。リーダーレプリカは、プロデューサーが新しいメッセージを送信し、コンシューマーがメッセージを消費するために使用されます。他のレプリカはフォロワーレプリカです。フォロワーはリーダーを複製します。

リーダーが失敗すると、フォロワーの 1 つが新しいリーダーに自動的になります。各サーバーは、一部のパーティションのリーダーおよび他のパーティションのフォロワーとして機能し、クラスター内で負荷が均等に分散されます。

注記

レプリケーション係数は、リーダーとフォロワーを含むレプリカ数を決定します。たとえば、レプリケーション係数を 3 に設定すると、1 つのリーダーと 2 つのフォロワーレプリカが設定されます。

5.2. メッセージの保持

メッセージの保持ポリシーは、Kafka ブローカーにメッセージを保存する期間を定義します。これは、時間、パーティションサイズ、またはその両方に基づいて定義できます。

たとえば、メッセージの保存に関して以下のように定義できます。

  • 7 日間。
  • 解析に 1 GB のメッセージが含まれるまで。制限に達すると、最も古いメッセージが削除されます。
  • 7 日間、または 1 GB の制限に達するまで。最初に制限が使用されます。
警告

Kafka ブローカーはメッセージをログセグメントに保存します。保持ポリシーを超えたメッセージは、新規ログセグメントが作成された場合にのみ削除されます。新しいログセグメントは、以前のログセグメントが設定されたログセグメントサイズを超えると作成されます。さらに、ユーザーは定期的に新しいセグメントの作成を要求できます。

さらに、Kafka ブローカーはコンパクト化ポリシーをサポートします。

圧縮ポリシーのあるトピックでは、ブローカーは常に各キーの最後のメッセージのみを保持します。同じキーを持つ古いメッセージは、パーティションから削除されます。圧縮は定期的に実行されるため、同じキーを持つ新しいメッセージがパーティションに送信されてもすぐには実行されません。代わりに、古いメッセージが削除されるまで時間がかかる場合があります。

メッセージの保持設定オプションの詳細は、「トピックの設定」 を参照してください。

5.3. トピックの自動作成

プロデューサーまたはコンシューマーが存在しないトピックとの間でメッセージを送受信しようとすると、Kafka はデフォルトでそのトピックを自動的に作成します。この動作は、デフォルトで true に設定された auto.create.topics.enable 設定プロパティーによって制御されます。

これを無効にするには、Kafka ブローカー設定ファイルで auto.create.topics.enablefalse に設定します。

auto.create.topics.enable=false

5.4. トピックの削除

Kafka では、トピックの削除を無効にすることができます。これは、デフォルトで true (つまり、トピックの削除が可能) に設定されている delete.topic.enable プロパティーで設定されます。このプロパティーを false に設定すると、トピックの削除はできず、トピックの削除試行はすべて成功を返しますが、トピックは削除されません。

delete.topic.enable=false

5.5. トピックの設定

自動作成されたトピックは、ブローカーのプロパティーファイルで指定できるデフォルトのトピック設定を使用します。ただし、トピックを手動で作成する場合は、作成時に設定を指定できます。トピックの作成後に、トピックの設定を変更することもできます。手動で作成したトピックの主なトピック設定オプションは次のとおりです。

cleanup.policy
delete または compact に保持ポリシーを設定します。delete ポリシーは古いレコードを削除します。compact ポリシーはログの圧縮を有効にします。デフォルト値は delete です。ログコンパクションの詳細は、Kafka の Web サイト を参照してください。
compression.type
保存されたメッセージに使用される圧縮を指定します。有効な値は、gzipsnappylz4uncompressed (圧縮なし)、および producer (プロデューサーによって使用される圧縮コーデックを保持) です。デフォルト値は producer です。
max.message.bytes
Kafka ブローカーによって許可されるメッセージのバッチの最大サイズ (バイト単位)。デフォルト値は 1000012 です。
min.insync.replicas
書き込みが成功したとみなされるために同期する必要があるレプリカの最小数。デフォルト値は 1 です。
retention.ms
ログセグメントが保持される最大ミリ秒数。この値より古いログセグメントは削除されます。デフォルト値は 604800000 (7 日) です。
retention.bytes
パーティションが保持する最大バイト数。パーティションサイズがこの制限を超えると、一番古いログセグメントが削除されます。-1 の値は無制限を意味します。デフォルト値は -1 です。
segment.bytes
単一のコミットログセグメントファイルの最大ファイルサイズ (バイト単位)。セグメントがそのサイズに達すると、新しいセグメントが起動します。デフォルト値は 1073741824 バイト (1 ギガバイト) です。

サポートされるすべてのトピック設定オプションの一覧は、「付録B トピック設定パラメーター」を参照してください。

自動作成されたトピックのデフォルトは、同様のオプションを使用して Kafka ブローカー設定に指定できます。

log.cleanup.policy
上記の cleanup.policy を参照してください。
compression.type
上記の compression.type を参照してください。
message.max.bytes
上記の max.message.bytes を参照してください。
min.insync.replicas
上記の min.insync.replicas を参照してください。
log.retention.ms
上記の retention.ms を参照してください。
log.retention.bytes
上記の retention.bytes を参照してください。
log.segment.bytes
上記の segment.bytes を参照してください。
default.replication.factor
自動的に作成されるトピックのデフォルトレプリケーション係数。デフォルト値は 1 です。
num.partitions
自動作成されるトピックのデフォルトパーティション数。デフォルト値は 1 です。

サポートされるすべての Kafka ブローカー設定オプションの一覧は、「付録A ブローカー設定パラメーター」を参照してください。

5.6. 内部トピック

内部トピックは、Kafka ブローカーおよびクライアントによって内部で作成され、使用されます。Kafka には複数の内部トピックがあります。これらはコンシューマーオフセット (__consumer_offsets) またはトランザクションの状態 (__transaction_state) を格納するために使用されます。これらのトピックは、プレフィックス offsets.topic. および transaction.state.log. で始まる専用の Kafka ブローカー設定オプションを使用して設定できます。最も重要な設定オプションは以下のとおりです。

offsets.topic.replication.factor
__consumer_offsets トピックのレプリカの数です。デフォルト値は 3 です。
offsets.topic.num.partitions
__consumer_offsets トピックのパーティションの数です。デフォルト値は 50 です。
transaction.state.log.replication.factor
__transaction_state のトピックのレプリカ数デフォルト値は 3 です。
transaction.state.log.num.partitions
__transaction_state のトピックのパーティション数デフォルト値は 50 です。
transaction.state.log.min.isr
__transaction_state トピックへの書き込みが正常であると考えられるために、確認される必要のあるレプリカの最小数。この最小値が満たされない場合、プロデューサーは例外で失敗します。デフォルト値は 2 です。

5.7. トピックの作成

kafka-topics.sh ツールを使用してトピックを管理できます。kafka-topics.sh は AMQ Streams ディストリビューションの一部で、bin ディレクトリーにあります。

前提条件

  • AMQ Streams クラスターがインストールされ、実行されている。

トピックの作成

  1. kafka-topics.sh ユーティリティーを使用し以下の項目を指定して、トピックを作成します。

    • --bootstrap-server における Kafka ブローカーのホストおよびポート。
    • --create オプション: 作成される新しいトピック。
    • --topic オプション: トピック名。
    • --partitions オプション: パーティション数。
    • --replication-factor オプション: トピックレプリケーション係数。

      また、--config オプションを使用して、デフォルトのトピック設定オプションの一部を上書きすることもできます。このオプションは複数回使用して、異なるオプションを上書きできます。

      bin/kafka-topics.sh --bootstrap-server <BrokerAddress> --create --topic <TopicName> --partitions <NumberOfPartitions> --replication-factor <ReplicationFactor> --config <Option1>=<Value1> --config <Option2>=<Value2>

      mytopic というトピックを作成するコマンドの例

      bin/kafka-topics.sh --bootstrap-server localhost:9092 --create --topic mytopic --partitions 50 --replication-factor 3 --config cleanup.policy=compact --config min.insync.replicas=2

  2. kafka-topics.sh を使用して、トピックが存在することを確認します。

    bin/kafka-topics.sh --bootstrap-server <BrokerAddress> --describe --topic <TopicName>

    mytopic というトピックを記述するコマンドの例

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

関連情報

5.8. トピックの一覧表示および説明

kafka-topics.sh ツールは、トピックの一覧表示および説明に使用できます。kafka-topics.sh は AMQ Streams ディストリビューションの一部で、bin ディレクトリーにあります。

前提条件

  • AMQ Streams クラスターがインストールされ、実行されている。
  • トピック mytopic が存在する。

トピックの記述

  1. kafka-topics.sh ユーティリティーを使用し以下の項目を指定して、トピックを説明します。

    • --bootstrap-server における Kafka ブローカーのホストおよびポート。
    • --describe オプション: トピックを記述することを指定するために使用します。
    • --topic オプション: このオプションでトピック名を指定する必要があります。
    • --topic オプションを省略すると、利用可能なすべてのトピックを記述します。

      bin/kafka-topics.sh --bootstrap-server <BrokerAddress> --describe --topic <TopicName>

      mytopic というトピックを記述するコマンドの例

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

      describe コマンドは、このトピックに属するすべてのパーティションおよびレプリカを一覧表示します。また、すべてのトピック設定オプションも表示されます。

関連情報

5.9. トピック設定の変更

kafka-configs.sh ツールを使用して、トピック設定を変更することができます。kafka-configs.sh は AMQ Streams ディストリビューションの一部で、bin ディレクトリーにあります。

前提条件

  • AMQ Streams クラスターがインストールされ、実行されている。
  • トピック mytopic が存在する。

トピック設定の変更

  1. kafka-configs.sh ツールを使用して、現在の設定を取得します。

    • --bootstrap-server オプションで Kafka ブローカーのホストおよびポートを指定します。
    • --entity-typetopic として、--entity-name をトピックの名前に設定します。
    • --describe オプション: 現在の設定を取得するために使用します。

      bin/kafka-configs.sh --bootstrap-server <BrokerAddress> --entity-type topics --entity-name <TopicName> --describe

      mytopic という名前のトピックの設定を取得するコマンドの例

      bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type topics --entity-name mytopic --describe

  2. kafka-configs.sh ツールを使用して、現在の設定を変更します。

    • --bootstrap-server オプションで Kafka ブローカーのホストおよびポートを指定します。
    • --entity-typetopic として、--entity-name をトピックの名前に設定します。
    • --alter オプション: 現在の設定を変更するのに使用します。
    • --add-config オプション: 追加または変更するオプションを指定します。

      bin/kafka-configs.sh --bootstrap-server <BrokerAddress> --entity-type topics --entity-name <TopicName> --alter --add-config <Option>=<Value>

      mytopic という名前のトピックの設定を変更するコマンドの例

      bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type topics --entity-name mytopic --alter --add-config min.insync.replicas=1

  3. kafka-configs.sh ツールを使用して、既存の設定オプションを削除します。

    • --bootstrap-server オプションで Kafka ブローカーのホストおよびポートを指定します。
    • --entity-typetopic として、--entity-name をトピックの名前に設定します。
    • --delete-config オプション: 既存の設定オプションを削除するのに使用します。
    • --remove-config オプション: 削除するオプションを指定します。

      bin/kafka-configs.sh --bootstrap-server <BrokerAddress> --entity-type topics --entity-name <TopicName> --alter --delete-config <Option>

      mytopic という名前のトピックの設定を変更するコマンドの例

      bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type topics --entity-name mytopic --alter --delete-config min.insync.replicas

関連情報

5.10. トピックの削除

kafka-topics.sh ツールを使用してトピックを管理できます。kafka-topics.sh は AMQ Streams ディストリビューションの一部で、bin ディレクトリーにあります。

前提条件

  • AMQ Streams クラスターがインストールされ、実行されている。
  • トピック mytopic が存在する。

トピックの削除

  1. kafka-topics.sh ユーティリティーを使用してトピックを削除します。

    • --bootstrap-server における Kafka ブローカーのホストおよびポート。
    • --delete オプション: 既存のトピックを削除することを指定するのに使用します。
    • --topic オプション: このオプションでトピック名を指定する必要があります。

      bin/kafka-topics.sh --bootstrap-server <BrokerAddress> --delete --topic <TopicName>

      mytopic というトピックを作成するコマンドの例

      bin/kafka-topics.sh --bootstrap-server localhost:9092 --delete --topic mytopic

  2. kafka-topics.sh を使用して、トピックが削除されたことを確認します。

    bin/kafka-topics.sh --bootstrap-server <BrokerAddress> --list

    すべてのトピックを一覧表示するコマンドの例

    bin/kafka-topics.sh --bootstrap-server localhost:9092 --list

関連情報

第6章 クライアント設定のチューニング

設定プロパティーを使用して、Kafka プロデューサーおよびコンシューマーのパフォーマンスを最適化します。

最小セットの設定プロパティーが必要ですが、プロパティーを追加または調整して、プロデューサーとコンシューマーが Kafka と対話する方法を変更できます。たとえば、プロデューサーの場合は、クライアントがリアルタイムでデータに応答できるように、メッセージのレイテンシーおよびスループットをチューニングできます。また、設定を変更して、より強力にメッセージの持続性を保証することもできます。

クライアントメトリックを分析して初期設定を行う場所を判断することから始め、必要な設定になるまで段階的に変更を加え、さらに比較を行うことができます。

6.1. Kafka プロデューサー設定のチューニング

特定のユースケースに合わせて調整されたオプションのプロパティーとともに、基本的なプロデューサー設定を使用します。

設定を調整してスループットを最大化すると、レイテンシーが増加する可能性があり、その逆も同様です。必要なバランスを取得するために、プロデューサー設定を実験して調整する必要があります。

6.1.1. 基本のプロデューサー設定

接続およびシリアライザープロパティーはすべてのプロデューサーに必要です。通常、追跡用のクライアント ID を追加し、プロデューサーで圧縮してリクエストのバッチサイズを減らすことが推奨されます。

基本的なプロデューサー設定は、以下のようになります。

  • パーティション内のメッセージの順序は保証されません。
  • ブローカーに到達するメッセージの完了通知は持続性を保証しません。
# ...
bootstrap.servers=localhost:9092 1
key.serializer=org.apache.kafka.common.serialization.StringSerializer 2
value.serializer=org.apache.kafka.common.serialization.StringSerializer 3
client.id=my-client 4
compression.type=gzip 5
# ...
1
(必須) Kafka ブローカーの host:port ブートストラップサーバーアドレスを使用して Kafka クラスターに接続するようプロデューサーを指示します。プロデューサーはアドレスを使用して、クラスター内のすべてのブローカーを検出し、接続します。サーバーがダウンした場合に備えて、コンマ区切りリストを使用して 2 つまたは 3 つのアドレスを指定しますが、クラスター内のすべてのブローカーのリストを提供する必要はありません。
2
(必須) メッセージがブローカーに送信される前に、各メッセージの鍵をバイトに変換するシリアライザー。
3
(必須) メッセージがブローカーに送信される前に、各メッセージの値をバイトに変換するシリアライザー。
4
(オプション) クライアントの論理名。リクエストのソースを特定するためにログおよびメトリクスで使用されます。
5
(オプション) メッセージを圧縮するコーデック。これは、送信され、圧縮された形式で格納された後、コンシューマーへの到達時に圧縮解除される可能性があります。圧縮はスループットを改善し、ストレージの負荷を減らすのに役立ちますが、圧縮や圧縮解除のコストが異常に高い低レイテンシーのアプリケーションには不適切である場合があります。

6.1.2. データの持続性

メッセージ配信の完了通知を使用して、データの持続性を適用し、メッセージが失われる可能性を最小限に抑えることができます。

# ...
acks=all 1
# ...
1
acks=all を指定すると、パーティションリーダーは、メッセージリクエストが正常に受信されたことを確認する前に、一定数のフォロワーにメッセージを複製するように強制します。追加のチェックにより、acks=all はプロデューサーがメッセージを送信して確認応答を受信する間のレイテンシーを長くします。

完了通知がプロデューサーに送信される前にメッセージをログに追加する必要のあるブローカーの数は、トピックの min.insync.replicas 設定によって決定されます。最初に、トピックレプリケーション係数を 3 にし、他のブローカーの In-Sync レプリカを 2 にするのが一般的です。この設定では、単一のブローカーが利用できない場合でもプロデューサーは影響を受けません。2 番目のブローカーが利用できなくなると、プロデューサーは完了通知を受信せず、それ以上のメッセージを生成できなくなります。

acks=all をサポートするトピック設定

# ...
min.insync.replicas=2 1
# ...

1
Sync レプリカでは 2 を使用します。デフォルトは 1 です。
注記

システムに障害が発生すると、バッファーの未送信データが失われる可能性があります。

6.1.3. 順序付き配信

メッセージは 1 度だけ配信されるため、べき等プロデューサーは重複を回避します。障害発生時でも配信の順序が維持されるように、ID とシーケンス番号がメッセージに割り当てられます。データの一貫性を保つために acks=all を使用している場合は、順序付けられた配信に冪等性を有効にすることが妥当です。

べき等を使った順序付き配信

# ...
enable.idempotence=true 1
max.in.flight.requests.per.connection=5 2
acks=all 3
retries=2147483647 4
# ...

1
べき等プロデューサーを有効にするには true に設定します。
2
べき等配信では、インフライトリクエストの数が 1 を越えることがありますがメッセージの順序は維持されます。デフォルトのインフライトリクエストの数は 5 です。
3
acksall に設定します。
4
失敗したメッセージリクエストを再送信する試行回数を設定します。

パフォーマンスコストが原因で acks=all と idempotency を使用していない場合には、インフライト (承認されていない) リクエストの数を 1 に設定して、順序を保持します。そうしないと、Message-A が失敗し、Message-B がブローカーに書き込まれた後にのみ成功する可能性があります。

べき等を使用しない順序付け配信

# ...
enable.idempotence=false 1
max.in.flight.requests.per.connection=1 2
retries=2147483647
# ...

1
false に設定すると、べき等プロデューサーを無効にします。
2
インフライトリクエストの数のみを 1 に設定します。

6.1.4. 信頼性の保証

べき等は、1 つのパーティションへの書き込みを 1 回だけ行う場合に便利です。トランザクションをべき等と使用すると、複数のパーティション全体で 1 度だけ書き込みを行うことができます。

トランザクションは、同じトランザクション ID を使用するメッセージが 1 度作成され、すべて がそれぞれのログに書き込まれるか、何も 書き込まれないかのどちらかになることを保証します。

# ...
enable.idempotence=true
max.in.flight.requests.per.connection=5
acks=all
retries=2147483647
transactional.id=UNIQUE-ID 1
transaction.timeout.ms=900000 2
# ...
1
一意のトランザクション ID を指定します。
2
タイムアウトエラーが返されるまでのトランザクションの最大許容時間 (ミリ秒単位) を設定します。デフォルトは 900000 または 15 分です。

トランザクション保証を維持するには、transactional.id の選択が重要です。トランザクション ID は、一意なトピックパーティションセットに使用する必要があります。たとえば、トピックパーティション名からトランザクション ID への外部マッピングを使用したり、競合を回避する関数を使用してトピックパーティション名からトランザクション IDを算出したりすると、これを実現できます。

6.1.5. スループットおよびレイテンシーの最適化

通常、システムの要件は、指定のレイテンシー内であるメッセージの割合に対して、特定のスループットのターゲットを達成することです。たとえば、95 % のメッセージが 2 秒以内に完了確認される、1 秒あたり 500,000 個のメッセージをターゲットとします。

プロデューサーのメッセージングセマンティック (メッセージの順序付けと持続性) は、アプリケーションの要件によって定義される可能性があります。たとえば、アプリケーションが提供する重要なプロパティーや保証を壊さずに acks=0 または acks=1 を使用するオプションはありません。

ブローカーの再起動は、パーセンタイルの高いの統計に大きく影響します。たとえば、長期間では、99% のレイテンシーはブローカーの再起動に関する動作によるものです。これは、ベンチマークを設計したり、本番環境のパフォーマンスで得られた数字を使ってベンチマークを行い、そのパフォーマンスの数字を比較したりする場合に検討する価値があります。

目的に応じて、Kafka はスループットとレイテンシーのプロデューサーパフォーマンスを調整するために多くの設定パラメーターと設定方法を提供します。

メッセージのバッチ処理 (linger.ms および batch.size)
メッセージのバッチ処理では、同じブローカー宛のメッセージをより多く送信するために、メッセージの送信を遅らせ、単一の生成リクエストでバッチ処理できるようにします。バッチ処理では、スループットを増やすためにレイテンシーを長くして妥協します。時間ベースのバッチ処理は linger.ms を使用して設定され、サイズベースのバッチ処理は batch.size を使用して設定されます。
圧縮 (compression.type)
メッセージ圧縮処理により、プロデューサー (メッセージの圧縮に費やされた CPU 時間) のレイテンシーが追加されますが、リクエスト (および場合によってはディスクの書き込み) を小さくするため、スループットが増加します。圧縮に価値があるかどうか、および使用に最適な圧縮は、送信されるメッセージによって異なります。圧縮は KafkaProducer.send() を呼び出すスレッドで発生するため、アプリケーションでこのメソッドのレイテンシーが重要となる場合は、より多くのスレッドの使用を検討する必要があります。
パイプライン処理 (max.in.flight.requests.per.connection)
パイプライン処理は、以前のリクエストへの応答を受け取る前により多くのリクエストを送信します。通常、パイプライン処理を増やすと、バッチ処理の悪化などの別の問題がスループットに悪影響を与え始めるしきい値まではスループットが増加します。

レイテンシーの短縮

アプリケーションが KafkaProducer.send() を呼び出す場合、メッセージは以下のようになります。

  • インターセプターによる処理
  • シリアライズ
  • パーティションへの割り当て
  • 圧縮処理
  • パーティションごとのキュー内のメッセージのバッチに追加

ここで、send() メソッドが返されます。そのため、send() がブロックされる時間は、以下によって決定されます。

  • インターセプター、シリアライザー、およびパーティションヤーで費やされた時間
  • 使用される圧縮アルゴリズム
  • 圧縮に使用するバッファーの待機に費やされた時間

バッチは、以下のいずれかが行われるまでキューに残ります。

  • バッチが満杯になる (batch.sizeによる)
  • linger.ms によって導入された遅延が経過する
  • 送信者は他のパーティションのメッセージバッチを同じブローカーに送信しようとし、このバッチの追加も可能である
  • プロデューサーがフラッシュまたは閉じられている

バッチ処理とバッファーの設定を参照して、レイテンシーをブロックする send() の影響を軽減します。

# ...
linger.ms=100 1
batch.size=16384 2
buffer.memory=33554432 3
# ...
1
linger プロパティーは、より大きなメッセージのバッチが蓄積され、リクエストで送信されるように、ミリ秒単位の遅延を追加します。デフォルトは 0'. です。
2
batch.size の最大値をバイト単位で指定した場合、最大値に達したとき、またはメッセージが linger.ms を超えてキューに入っていたとき (いずれか早いほう) にリクエストが送信されます。遅延を追加すると、メッセージをバッチサイズまで累積できます。
3
バッファーサイズは、少なくともバッチサイズと同じ大きさである必要があり、バッファー、圧縮、およびインフライトリクエストに対応できる必要があります。

スループットの増加

メッセージの配信および送信リクエストの完了までの最大待機時間を調整して、メッセージリクエストのスループットを向上します。

また、カスタムパーティションを作成してデフォルトを置き換えることで、メッセージを指定のパーティションに転送することもできます。

# ...
delivery.timeout.ms=120000 1
partitioner.class=my-custom-partitioner 2

# ...
1
送信リクエストの完了まで待機する最大時間 (ミリ秒単位)。この値を MAX_LONG に設定すると、Kafka に無限の再試行を委任できます。デフォルトは 120000 または 2 分です。
2
カスタムパーティショナーのクラス名を指定します。

6.2. Kafka コンシューマー設定の調整

特定のユースケースに合わせて調整されたオプションのプロパティーとともに、基本的なコンシューマー設定を使用します。

コンシューマーを調整する場合、最も重要なことは、取得するデータ量に効率的に対処できるようにすることです。プロデューサーのチューニングと同様に、コンシューマーが想定どおりに動作するまで、段階的に変更を加える必要があります。

6.2.1. 基本的なコンシューマー設定

接続およびデシリアライザープロパティーはすべてのコンシューマーに必要です。通常、追跡用にクライアント ID を追加することが推奨されます。

コンシューマー設定では、後続の設定に関係なく、以下を行います。

  • メッセージをスキップまたは再読み取りするようオフセットを変更しない限り、コンシューマーはメッセージを指定のオフセットから取得し、順番に消費します。
  • オフセットはクラスターの別のブローカーに送信される可能性があるため、オフセットを Kafka にコミットした場合でも、ブローカーはコンシューマーが応答を処理したかどうかを認識しません。
# ...
bootstrap.servers=localhost:9092 1
key.deserializer=org.apache.kafka.common.serialization.StringDeserializer  2
value.deserializer=org.apache.kafka.common.serialization.StringDeserializer  3
client.id=my-client 4
group.id=my-group-id 5
# ...
1
(必須) Kafka ブローカーの host:port ブートストラップサーバーアドレスを使用して、コンシューマーが Kafka クラスターに接続するよう指示しますコンシューマーはアドレスを使用して、クラスター内のすべてのブローカーを検出し、接続します。サーバーがダウンした場合に備えて、コンマ区切りリストを使用して 2 つまたは 3 つのアドレスを指定しますが、クラスター内のすべてのブローカーのリストを提供する必要はありません。ロードバランサーサービスを使用して Kafka クラスターを公開する場合、可用性はロードバランサーによって処理されるため、サービスのアドレスのみが必要になります。
2
(必須) Kafka ブローカーから取得されたバイトをメッセージキーに変換するデシリアライザー。
3
(必須) Kafka ブローカーから取得されたバイトをメッセージ値に変換するデシリアライザー。
4
(オプション) クライアントの論理名。リクエストのソースを特定するためにログおよびメトリクスで使用されます。ID は、時間クォータの処理に基づいてコンシューマーにスロットリングを適用するために使用することもできます。
5
(条件) コンシューマーがコンシューマーグループに参加するには、グループ ID が 必要 です。

コンシューマーグループは通常、特定のトピックから複数のプロデューサーで生成される大規模なデータストリームを共有するために使用されます。コンシューマーは group.id でグループ化され、メッセージをメンバー全体に分散できます。

6.2.2. コンシューマーグループを使用したデータ消費のスケーリング

コンシューマーグループは、特定のトピックから 1 つまたは複数のプロデューサーによって生成される、典型的な大量のデータストリームを共有します。group.id プロパティーが同じコンシューマーは同じグループにあります。グループ内のコンシューマーの 1 つがリーダーを選択し、パーティションをグループのコンシューマーにどのように割り当てるかを決定します。各パーティションは 1 つのコンシューマーにのみ割り当てることができます。

コンシューマーの数がパーティション数だけない場合には、同じ group.id を持つコンシューマーインスタンスを追加して、データ消費をスケーリングできます。コンシューマーをグループに追加して、パーティションの数より多くしても、スループットは改善されませんが、コンシューマーが機能しなくなったときに予備のコンシューマーを使用できます。より少ないコンシューマーでスループットの目標を達成できれば、リソースを節約できます。

同じコンシューマーグループのコンシューマーは、オフセットコミットとハートビートを同じブローカーに送信します。グループのコンシューマーの数が多いほど、ブローカーのリクエスト負荷が高くなります。

# ...
group.id=my-group-id 1
# ...
1
グループ ID を使用してコンシューマーグループにコンシューマーを追加します。

6.2.3. メッセージの順序の保証

Kafka ブローカーは、トピック、パーティション、およびオフセット位置のリストからメッセージを送信するようブローカーに要求するコンシューマーからフェッチリクエストを受け取ります。

コンシューマーは、ブローカーにコミットされたのと同じ順序でメッセージを単一のパーティションで監視します。つまり、Kafka は単一パーティションのメッセージ のみ 順序付けを保証します。逆に、コンシューマーが複数のパーティションからメッセージを消費している場合、コンシューマーによって監視される異なるパーティションのメッセージの順序は、必ずしも送信順序を反映しません。

1 つのトピックからメッセージを厳格に順序付ける場合は、コンシューマーごとに 1 つのパーティションを使用します。

6.2.4. スループットおよびレイテンシーの最適化

クライアントアプリケーションが KafkaConsumer.poll() を呼び出すときに返されるメッセージの数を制御します。

fetch.max.wait.ms および fetch.min.bytes プロパティーを使用して、Kafka ブローカーからコンシューマーによって取得される最小データ量を増やします。時間ベースのバッチ処理は fetch.max.wait.ms を使用して設定され、サイズベースのバッチ処理は fetch.min.bytes を使用して設定されます。

コンシューマーまたはブローカーの CPU 使用率が高い場合、コンシューマーからのリクエストが多すぎる可能性があります。fetch.max.wait.ms プロパティーおよび fetch.min.bytes プロパティーを調整して、より大きなバッチで要求とメッセージが配信されるようにすることができます。より高い値に調整することでスループットが改善されますが、レイテンシーのコストが発生します。生成されるデータ量が少ない場合、より高い値に調整することもできます。

たとえば、fetch.max.wait.ms を 500ms に設定し、fetch.min.bytes を 16384 バイトに設定した場合、Kafka がコンシューマーからフェッチリクエストを受信すると、いずれかのしきい値に最初に到達した時点で応答されます。

逆に、fetch.max.wait.ms プロパティーおよび fetch.min.bytes プロパティーを調整して、エンドツーエンドのレイテンシーを改善できます。

# ...
fetch.max.wait.ms=500 1
fetch.min.bytes=16384 2
# ...
1
ブローカーがフェッチリクエストを完了するまで待機する最大時間 (ミリ秒単位)。デフォルトは 500 ミリ秒です。
2
最小バッチサイズ (バイト単位) が使用された場合、最低限到達時にリクエストが送信されます。または、メッセージが fetch.max.wait.ms よりも長くキューに入れられると、リクエストが送信されます。遅延を追加すると、メッセージをバッチサイズまで累積できます。

フェッチリクエストサイズの増加によるレイテンシーの短縮

fetch.max.bytes プロパティーおよび max.partition.fetch.bytes プロパティーを使用して、Kafka ブローカーからコンシューマーによって取得されるデータの最大量を増やします。

fetch.max.bytes プロパティーは、一度にブローカーから取得されるデータ量の上限をバイト単位で設定します。

max.partition.fetch.bytes は、各パーティションで返されるデータ量の上限をバイト単位で設定します。これは、max.message.bytes のブローカーまたはトピック設定に設定されたバイト数よりも大きくする必要があります。

クライアントが消費できるメモリーの最大量は、以下のように概算されます。

NUMBER-OF-BROKERS * fetch.max.bytes and NUMBER-OF-PARTITIONS * max.partition.fetch.bytes

メモリー使用量がこれに対応できる場合は、これら 2 つのプロパティーの値を増やすことができます。各リクエストでより多くのデータを許可すると、フェッチリクエストが少なくなるため、レイテンシーが向上されます。

# ...
fetch.max.bytes=52428800 1
max.partition.fetch.bytes=1048576 2
# ...
1
フェッチリクエストに対して返されるデータの最大量 (バイト単位)。
2
各パーティションに対して返されるデータの最大量 (バイト単位)。

6.2.5. オフセットをコミットする際のデータ損失または重複の回避

Kafka の 自動コミットメカニズム により、コンシューマーはメッセージのオフセットを自動的にコミットできます。有効にすると、コンシューマーはブローカーをポーリングして受信したオフセットを 5000ms 間隔でコミットします。

自動コミットのメカニズムは便利ですが、データ損失と重複のリスクが発生します。コンシューマーが多くのメッセージを取得および変換し、自動コミットの実行時にコンシューマーバッファーに処理されたメッセージがある状態でシステムがクラッシュすると、そのデータは失われます。メッセージの処理後、自動コミットの実行前にシステムがクラッシュした場合、リバランス後に別のコンシューマーインスタンスでデータが複製されます。

ブローカーへの次のポーリングの前またはコンシューマーが閉じられる前に、すべてのメッセージが処理された場合は、自動コミットによるデータの損失を回避できます。

データの損失や重複の可能性を最小限に抑えるには、enable.auto.commitfalse に設定し、クライアントアプリケーションを開発して、オフセットのコミットをより詳細に制御できるようにします。または、auto.commit.interval.ms を使用してコミットの間隔を減らすことができます。

# ...
enable.auto.commit=false 1
# ...
1
自動コミットを false に設定すると、オフセットのコミットの制御が強化されます。

enable.auto.commitfalse に設定すると、すべての 処理が実行され、メッセージが消費された後にオフセットをコミットできます。たとえば、Kafka commitSync および commitAsync コミット API を呼び出すようにアプリケーションを設定できます。

commitSync API は、ポーリングから返されるメッセージバッチのオフセットをコミットします。バッチのメッセージすべての処理が完了したら API を呼び出します。commitSync API を使用する場合、アプリケーションはバッチの最後のオフセットがコミットされるまで新しいメッセージをポーリングしません。これがスループットに悪影響する場合は、コミットする頻度が低いか、commitAsync API を使用できます。commitAsync API はブローカーがコミットリクエストに応答するまで待機しませんが、リバランス時にさらに重複が発生するリスクがあります。一般的な方法として、両方のコミット API をアプリケーションで組み合わせ、コンシューマーをシャットダウンまたはリバランスの直前に commitSync API を使用し、最終コミットが正常に実行されるようにします。

6.2.5.1. トランザクションメッセージの制御

プロデューサー側でトランザクション ID を使用し、べき等性 (enable.idempotence=true) を有効にすることを検討してください。これにより、1 回限りの配信を保証します。コンシューマー側で、isolation.level プロパティーを使用して、コンシューマーによってトランザクションメッセージが読み取られる方法を制御できます。

isolation.level プロパティーには、有効な 2 つの値があります。

  • read_committed
  • read_uncommitted (デフォルト)

read_committed を使用して、コミットされたトランザクションメッセージのみがコンシューマーによって読み取られるようにします。ただし、これによりトランザクションの結果を記録するトランザクションマーカー (committed または aborted) がブローカーによって書き込まれるまで、コンシューマーはメッセージを返すことができないため、エンドツーエンドのレイテンシーが長くなります。

# ...
enable.auto.commit=false
isolation.level=read_committed 1
# ...
1
コミットされたメッセージのみがコンシューマーによって読み取られるように、read_committed に設定します。

6.2.6. データ損失を回避するための障害からの復旧

session.timeout.ms および heartbeat.interval.ms プロパティーを使用して、コンシューマーグループ内のコンシューマー障害をチェックし、復旧するのにかかった時間を設定します。

session.timeout.ms プロパティーは、コンシューマーグループ内のコンシューマーがブローカーとのコンタクトを絶った場合に、非アクティブとみなされ、グループ内のアクティブなコンシューマー間で リバランス が発生するまでの最大時間をミリ秒単位で指定します。グループのリバランス時に、パーティションはグループのメンバーに再割り当てされます。

heartbeat.interval.ms プロパティーは、コンシューマーがアクティブで接続されていることを示す、コンシューマーグループコーディネーターへの ハートビート チェックの間隔をミリ秒単位で指定します。通常、ハートビートの間隔はセッションタイムアウトの間隔の 3 分の 2 にする必要があります。

session.timeout.ms プロパティーを低く設定すると、失敗したコンシューマーが先に検出され、リバランスがより迅速に実行されます。ただし、タイムアウトの値を低くしすぎて、ブローカーがハートビートを時間内に受信できず、不必要なリバランスがトリガーされることがないように気を付けてください。

ハートビートの間隔が短くなると、誤ってリバランスを行う可能性が低くなりますが、ハートビートを頻繁に行うとブローカーリソースのオーバーヘッドが増えます。

6.2.7. オフセットポリシーの管理

auto.offset.reset プロパティーを使用して、オフセットがコミットされていない場合にコンシューマーの動作を制御するか、コミットされたオフセットが有効でなくなったりします。

コンシューマーアプリケーションを初めてデプロイし、既存のトピックからメッセージを読み取る場合について考えてみましょう。これは group.id が初めて使用されるため、__consumer_offsets トピックには、このアプリケーションのオフセット情報は含まれません。新しいアプリケーションは、ログの始めからすべての既存メッセージの処理を開始するか、新しいメッセージのみ処理を開始できます。デフォルトのリセット値は、パーティションの最後に開始する latest で、一部のメッセージは見逃されることを意味します。データの損失は避けたいが、処理量を増やしたい場合は、auto.offset.resetearliest に設定して、パーティションの先頭から開始します。

また、ブローカーに設定されたオフセットの保持期間 (offsets.retention.minutes) が終了したときにメッセージが失われるのを防ぐために、earliest オプションの使用も検討してください。コンシューマーグループまたはスタンドアロンコンシューマーが非アクティブで、保持期間中にオフセットをコミットしない場合、以前にコミットされたオフセットは __consumer_offsets から削除されます。

# ...
heartbeat.interval.ms=3000 1
session.timeout.ms=10000 2
auto.offset.reset=earliest 3
# ...
1
予想されるリバランスに応じて、ハートビートの間隔を短くして調整します。
2
タイムアウトの期限が切れる前に Kafka ブローカーによってハートビートが受信されなかった場合、コンシューマーはコンシューマーグループから削除され、リバランスが開始されます。ブローカー設定に group.min.session.timeout.msgroup.max.session.timeout.ms がある場合、セッションタイムアウト値はその範囲内である必要があります。
3
パーティションの最初に戻り、オフセットがコミットされなかった場合にデータの損失を回避するために、earliest 値に設定します。

1 つのフェッチリクエストで返されるデータ量が大きい場合、コンシューマーが処理する前にタイムアウトが発生することがあります。この場合、max.partition.fetch.bytes を減らしたり、session.timeout.ms を増やすこともできます。

6.2.8. リバランスの影響の最小限化

グループのアクティブなコンシューマー間で行うパーティションのリバランスは、以下にかかる時間です。

  • コンシューマーによるオフセットのコミット
  • 作成される新しいコンシューマーグループ
  • グループリーダーによるグループメンバーへのパーティションの割り当て
  • 割り当てを受け取り、取得を開始するグループのコンシューマー

明らかに、このプロセスは特にコンシューマーグループクラスターのローリング再起動時に繰り返し発生するサービスのダウンタイムを増やします。

このような場合、静的メンバーシップ の概念を使用してリバランスの数を減らすことができます。リバランスによって、コンシューマーグループメンバー全体でトピックパーティションが割り当てられます。静的メンバーシップは永続性を使用し、セッションタイムアウト後の再起動時にコンシューマーインスタンスが認識されるようにします。

コンシューマーグループコーディネーターは、group.instance.id プロパティーを使用して指定される一意の ID を使用して新しいコンシューマーインスタンスを特定できます。再起動時には、コンシューマーには新しいメンバー ID が割り当てられますが、静的メンバーとして、同じインスタンス ID を使用し、同じトピックパーティションの割り当てが行われます。

コンシューマーアプリケーションが少なくとも max.poll.interval.ms ミリ秒毎にポーリングへの呼び出しを行わない場合、コンシューマーが失敗したと見なされ、リバランスが発生します。アプリケーションがポーリングから返されたすべてのレコードを時間内に処理できない場合は、max.poll.interval.ms プロパティーを使用してコンシューマーから新しいメッセージのポーリングの間隔をミリ秒単位で指定して、リバランスを回避することができます。または、max.poll.records プロパティーを使用して、コンシューマーバッファーから返されるレコードの数の上限を設定できます。これにより、アプリケーションは max.poll.interval.ms の制限内のより少ないレコードを処理できます。

# ...
group.instance.id=UNIQUE-ID 1
max.poll.interval.ms=300000 2
max.poll.records=500 3
# ...
1
一意のインスタンス ID により、新しいコンシューマーインスタンスに同じトピックパーティションが割り当てられます。
2
コンシューマーがメッセージの処理を継続していることを確認する間隔を設定します。
3
コンシューマーから返される処理済のレコードの数を設定します。

第7章 クラスターのスケーリング

7.1. Kafka クラスターのスケーリング

7.1.1. ブローカーのクラスターへの追加

トピックのスループットを向上させる主な方法は、そのトピックのパーティション数を増やすことです。これは、パーティションによってクラスター内のブローカー間でそのトピックの負荷が共有できるためです。ブローカーがすべて何らかのリソース (通常は I/O) によって制約されている場合、より多くのパーティションを使用してもスループットは向上しません。代わりに、クラスターにブローカーを追加する必要があります。

追加のブローカーをクラスターに追加する場合、AMQ Streams ではパーティションは自動的に割り当てられません。既存のブローカーから新しいブローカーに移動するパーティションを決定する必要があります。

すべてのブローカー間でパーティションが再分散されたら、各ブローカーのリソース使用率が低下するはずです。

7.1.2. クラスターからのブローカーの削除

クラスターからブローカーを削除する前に、そのブローカーにパーティションが割り当てられていないことを確認します。使用を停止するブローカーの各パーティションに対応する残りのブローカーを決定する必要があります。ブローカーに割り当てられたパーティションがない場合は、ブローカーを停止することができます。

7.2. パーティションの再割り当て

kafka-reassign-partitions.sh は、パーティションを別のブローカーに再割り当てする際に使用します。

これには、以下の 3 つのモードがあります。

--generate
トピックとブローカーのセットを取得し、再割り当て JSON ファイル を生成します。これにより、トピックのパーティションがブローカーに割り当てられます。再割り当て JSON ファイル を生成する簡単な方法です。ただし、トピック全体で機能するため、その使用が常に適切であるとは限りません。
--execute
再割り当て JSON ファイル を取得し、クラスターのパーティションおよびブローカーに適用します。パーティションを取得するブローカーは、パーティションリーダーのフォロワーになります。特定のパーティションでは、新規ブローカーが ISR に参加できたら、古いブローカーはフォロワーではなくなり、そのレプリカが削除されます。
--verify
--verify は、-- execute ステップと同じ 再割り当て JSON ファイル を使用して、ファイル内のすべてのパーティションが目的のブローカーに移動されたかどうかを確認します。再割り当てが完了すると、有効な スロットル も削除されます。スロットルを削除しないと、再割り当てが完了した後もクラスターは影響を受け続けます。

クラスターでは、1 度に 1 つの再割当てのみを実行でき、実行中の再割り当てをキャンセルすることはできません。再割り当てをキャンセルする必要がある場合は、割り当てが完了するのを待ってから別の再割り当てを実行し、最初の再割り当ての結果を元に戻します。kafka-reassign-partitions.sh によって、元に戻すための再割り当て JSON が出力の一部として生成されます。大規模な再割り当ては、進行中の再割り当てを停止する必要がある場合に備えて、複数の小さな再割り当てに分割するようにしてください。

7.2.1. 再割り当て JSON ファイル

再割り当て JSON ファイル には特定の構造があります。

{
  "version": 1,
  "partitions": [
    <PartitionObjects>
  ]
}

ここで <PartitionObjects> は、以下のようなコンマ区切りのオブジェクトリストになります。

{
  "topic": <TopicName>,
  "partition": <Partition>,
  "replicas": [ <AssignedBrokerIds> ],
  "log_dirs": [<LogDirs>]
}

"log_dirs" プロパティーはオプションで、パーティションを特定のログディレクトリーに移動するために使用されます。

以下は、トピック topic-a およびパーティション 4 をブローカー 24 および 7 に割り当て、トピック topic-b およびパーティション 2 をブローカー 15、および 7 に割り当てる、再割り当て JSON ファイルの例になります。

{
  "version": 1,
  "partitions": [
    {
      "topic": "topic-a",
      "partition": 4,
      "replicas": [2,4,7]
    },
    {
      "topic": "topic-b",
      "partition": 2,
      "replicas": [1,5,7]
    }
  ]
}

JSON に含まれていないパーティションは変更されません。

7.2.2. 再割り当て JSON ファイルの生成

指定のトピックのセットのすべてのパーティションを、指定のブローカーのセットに割り当てる最も簡単な方法は、kafka-reassign-partitions.sh --generate コマンドを使用して再割り当て JSON ファイルを生成することです。

bin/kafka-reassign-partitions.sh --zookeeper <ZooKeeper> --topics-to-move-json-file <TopicsFile> --broker-list <BrokerList> --generate

<TopicsFile> は、移動するトピックをリストする JSON ファイルです。これには、以下の構造があります。

{
  "version": 1,
  "topics": [
    <TopicObjects>
  ]
}

ここで <TopicObjects> は、以下のようなコンマ区切りのオブジェクトリストになります。

{
  "topic": <TopicName>
}

たとえば、topic-a および topic-b のすべてのパーティションをブローカー 4 および 7 に移動する場合は、以下を実行します。

bin/kafka-reassign-partitions.sh --zookeeper localhost:2181 --topics-to-move-json-file topics-to-be-moved.json --broker-list 4,7 --generate

topics-to-be-moved.json のコンテンツがあります。

{
  "version": 1,
  "topics": [
    { "topic": "topic-a"},
    { "topic": "topic-b"}
  ]
}

7.2.3. 手動による再割り当て JSON ファイルの作成

特定のパーティションを移動したい場合は、再割り当て JSON ファイルを手動で作成できます。

7.3. 再割り当てスロットル

パーティションの再割り当てには、多くのデータをブローカー間で移動させる必要があるため、処理が遅くなる可能性があります。クライアントへの悪影響を防ぐため、再割り当てに スロットル を使用できます。スロットルを使用すると、再割り当てに時間がかかる可能性があります。スロットルが低すぎると、新たに割り当てられたブローカーは公開されるレコードに遅れずに対応することはできず、再割り当ては永久に完了しません。スロットルが高すぎると、クライアントに影響します。たとえば、プロデューサーの場合は、承認待ちが通常のレイテンシーよりも大きくなる可能性があります。コンシューマーの場合は、ポーリング間のレイテンシーが大きいことが原因でスループットが低下する可能性があります。

7.4. Kafka クラスターのスケールアップ

この手順では、Kafka クラスターでブローカーの数を増やす方法を説明します。

前提条件

  • 既存の Kafka クラスター。
  • AMQ ブローカーが インストールされている 新しいマシン。
  • 拡大されたクラスターで、パーティションをブローカーに再割り当てする方法を示す 再割り当て JSON ファイル

手順

  1. クラスター内の他のブローカーと同じ設定を使用して新しいブローカーの設定ファイルを作成します。ただし、broker.id には他のブローカで使用されていない番号を指定してください。
  2. 前のステップで作成した設定ファイルをkafka-server-start.sh スクリプトの引数に渡して、新しい Kafka ブローカーを起動します。

    su - kafka
    /opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties
  3. Kafka ブローカーが稼働していることを確認します。

    jcmd | grep Kafka
  4. 新しいブローカーごとに上記の手順を繰り返します。
  5. kafka-reassign-partitions.sh コマンドラインツールを使用して、パーティションの再割り当てを実行します。

    kafka-reassign-partitions.sh --zookeeper <ZooKeeperHostAndPort> --reassignment-json-file <ReassignmentJsonFile> --execute

    レプリケーションをスロットルで調整する場合、--throttle と inter-broker のスロットル率 (バイト/秒単位) を渡すこともできます。以下に例を示します。

    kafka-reassign-partitions.sh --zookeeper zookeeper1:2181 --reassignment-json-file reassignment.json --throttle 5000000 --execute

    このコマンドは、2 つの再割り当て JSON オブジェクトを出力します。最初の JSON オブジェクトには、移動されたパーティションの現在の割り当てが記録されます。後で再割り当てを元に戻す必要がある場合に備えて、これをファイルに保存する必要があります。2 つ目の JSON オブジェクトは、再割り当て JSON ファイルに渡したターゲットの再割り当てです。

  6. 再割り当ての最中にスロットルを変更する必要がある場合は、同じコマンドラインに別のスロットル率を指定して実行します。以下に例を示します。

    kafka-reassign-partitions.sh --zookeeper zookeeper1:2181 --reassignment-json-file reassignment.json --throttle 10000000 --execute
  7. kafka-reassign-partitions.sh コマンドラインツールを使用して、再割り当てが完了したかどうかを定期的に確認します。これは先ほどの手順と同じコマンドですが、--execute オプションの代わりに --verify オプションを使用します。

    kafka-reassign-partitions.sh --zookeeper <ZooKeeperHostAndPort> --reassignment-json-file <ReassignmentJsonFile> --verify

    以下に例を示します。

    kafka-reassign-partitions.sh --zookeeper zookeeper1:2181 --reassignment-json-file reassignment.json --verify
  8. --verify コマンドによって、移動した各パーティションが正常に完了したことが報告されると、再割り当ては終了します。この最終的な --verify によって、結果的に再割り当てスロットルも削除されます。割り当てを元のブローカーに戻すために JSON ファイルを保存した場合は、ここでそのファイルを削除できます。

7.5. Kafka クラスターのスケールダウン

関連情報

この手順では、Kafka クラスターでブローカーの数を減らす方法を説明します。

前提条件

  • 既存の Kafka クラスター。
  • ブローカーが削除された後にクラスターのブローカーにパーティションを再割り当てする方法が記述されている 再割り当て JSON ファイル

手順

  1. kafka-reassign-partitions.sh コマンドラインツールを使用して、パーティションの再割り当てを実行します。

    kafka-reassign-partitions.sh --zookeeper <ZooKeeperHostAndPort> --reassignment-json-file <ReassignmentJsonFile> --execute

    レプリケーションをスロットルで調整する場合、--throttle と inter-broker のスロットル率 (バイト/秒単位) を渡すこともできます。以下に例を示します。

    kafka-reassign-partitions.sh --zookeeper zookeeper1:2181 --reassignment-json-file reassignment.json --throttle 5000000 --execute

    このコマンドは、2 つの再割り当て JSON オブジェクトを出力します。最初の JSON オブジェクトには、移動されたパーティションの現在の割り当てが記録されます。後で再割り当てを元に戻す必要がある場合に備えて、これをファイルに保存する必要があります。2 つ目の JSON オブジェクトは、再割り当て JSON ファイルに渡したターゲットの再割り当てです。

  2. 再割り当ての最中にスロットルを変更する必要がある場合は、同じコマンドラインに別のスロットル率を指定して実行します。以下に例を示します。

    kafka-reassign-partitions.sh --zookeeper zookeeper1:2181 --reassignment-json-file reassignment.json --throttle 10000000 --execute
  3. kafka-reassign-partitions.sh コマンドラインツールを使用して、再割り当てが完了したかどうかを定期的に確認します。これは先ほどの手順と同じコマンドですが、--execute オプションの代わりに --verify オプションを使用します。

    kafka-reassign-partitions.sh --zookeeper <ZooKeeperHostAndPort> --reassignment-json-file <ReassignmentJsonFile> --verify

    以下に例を示します。

    kafka-reassign-partitions.sh --zookeeper zookeeper1:2181 --reassignment-json-file reassignment.json --verify
  4. --verify コマンドによって、移動した各パーティションが正常に完了したことが報告されると、再割り当ては終了します。この最終的な --verify によって、結果的に再割り当てスロットルも削除されます。割り当てを元のブローカーに戻すために JSON ファイルを保存した場合は、ここでそのファイルを削除できます。
  5. すべてのパーティションの再割り当てが終了すると、削除されるブローカーはクラスター内のいずれのパーティションにも対応しないはずです。これを確認するには、ブローカーの log.dirs 設定パラメーターで指定された各ディレクトリーを確認します。ブローカーのログディレクトリーに、拡張正規表現 [a-zA-Z0-9.-]+\.[a-z0-9]+-delete$ と一致しないディレクトリーが含まれる場合、ブローカーにはライブパーティションがあるため、停止してはなりません。

    これを確認するには、以下のコマンドを実行します。

    ls -l <LogDir> | grep -E '^d' | grep -vE '[a-zA-Z0-9.-]+\.[a-z0-9]+-delete$'

    上記のコマンドによって出力が生成される場合、ブローカーにはライブパーティションがあります。この場合、再割り当てが終了していないか、再割り当て JSON ファイルが適切ではありません。

  6. ブローカーにライブパーティションがないことを確認したら、それを停止できます。

    su - kafka
    /opt/kafka/bin/kafka-server-stop.sh
  7. Kafka ブローカーが停止していることを確認します。

    jcmd | grep kafka

7.6. ZooKeeper クラスターのスケールアップ

この手順では、Zoo Keeper クラスターにサーバー (ノード) を追加する方法について説明します。Zoo Keeper の 動的再設定 機能は、スケールアッププロセス中に安定した Zoo Keeper クラスターを維持します。

前提条件

  • 動的再設定が ZooKeeper 設定ファイル (reconfigEnabled=true) で有効になっている。
  • ZooKeeper の認証が有効化され、認証メカニズムを使用して新しいサーバーにアクセスできる。

手順

各 ZooKeeper サーバーに対して、1 つずつ以下の手順を実行します。

  1. 「マルチノードの ZooKeeper クラスターの実行」 の説明に従ってサーバーを ZooKeeper クラスターに追加し、ZooKeeper を起動します。
  2. 新しいサーバーの IP アドレスと設定されたアクセスポートをメモします。
  3. サーバーの zookeeper-shell セッションを開始します。クラスターにアクセスできるマシンから次のコマンドを実行します (アクセスできる場合は、Zoo Keeper ノードまたはローカルマシンの 1 つである可能性があります)。

    su - kafka
    /opt/kafka/bin/zookeeper-shell.sh <ip-address>:<zk-port>
  4. シェルセッションで、Zoo Keeper ノードが実行されている状態で、次の行を入力して、新しいサーバーを投票メンバーとしてクォーラムに追加します。

    reconfig -add server.<positive-id> = <address1>:<port1>:<port2>[:role];[<client-port-address>:]<client-port>

    以下に例を示します。

    reconfig -add server.4=172.17.0.4:2888:3888:participant;172.17.0.4:2181

    <positive-id> は、新しいサーバー ID 4 です。

    2 つのポートの <port1> 2888 は ZooKeeper サーバー間の通信用で、<port2> 3888 はリーダーエレクション用です。

    新しい設定は ZooKeeper クラスターの他のサーバーに伝播されます。新しいサーバーはクォーラムの完全メンバーになります。

  5. 追加する他のサーバーについて、手順 1 から 4 を繰り返します。

7.7. ZooKeeper クラスターのスケールダウン

この手順では、ZooKeeper クラスターからサーバー (ノード) を削除する方法を説明します。Zoo Keeper の 動的再設定 機能は、スケールダウンプロセス中に安定した Zoo Keeper クラスターを維持します。

前提条件

  • 動的再設定が ZooKeeper 設定ファイル (reconfigEnabled=true) で有効になっている。
  • ZooKeeper の認証が有効化され、認証メカニズムを使用して新しいサーバーにアクセスできる。

手順

各 ZooKeeper サーバーに対して、1 つずつ以下の手順を実行します。

  1. スケールダウンの後も 維持される サーバーのいずれかで、zookeeper-shell にログインします (例: サーバー1)。

    注記

    ZooKeeper クラスターに設定された認証メカニズムを使用してサーバーにアクセスします。

  2. サーバー (サーバー 5 など) を削除します。

    reconfig -remove 5
  3. 削除したサーバーを無効にします。
  4. ステップ 1 から 3 を繰り返し、クラスターサイズを縮小します。

第8章 JMX を使用したクラスターの監視

Zoo Keeper、Kafka ブローカー、Kafka Connect、および Kafka クライアントはすべて、 Java Management Extensions (JMX) を使用して管理情報を公開します。管理情報の多くは、Kafka クラスターの状態やパフォーマンスを監視するのに役立つメトリクスの形式になっています。他の Java アプリケーションと同様に、Kafka は管理対象 Bean または MBean を介してこの管理情報を提供します。

JMX は、JVM (Java 仮想マシン) のレベルで動作します。管理情報を取得するために、外部ツールは ZooKeeper、Kafka ブローカーなどを実行している JVM に接続できます。デフォルトでは、同じマシン上で、JVM と同じユーザーとして実行しているツールのみが接続できます。

注記

ZooKeeper の管理情報は、ここには記載されていません。JConsole で ZooKeeper メトリクスを表示できます。詳細は、「JConsole を使用した監視」 を参照してください。

8.1. JMX 設定オプション

JVM システムプロパティーを使用して JMX を設定します。AMQ Streams とともに提供されるスクリプト (bin/kafka-server-start.shbin/connect-distributed.sh など) では、環境変数 KAFKA_JMX_OPTS を使用してこれらのシステムプロパティーを設定しています。Kafka プロデューサー、コンシューマー、およびストリームアプリケーションは、通常、異なる方法で JVM を起動しますが、JMX を設定するためのシステムプロパティーは同じです。

8.2. JMX エージェントの無効化

AMQ Streams コンポーネントの JMX エージェントを無効にすることで、ローカルの JMX ツールが (たとえば、コンプライアンスの理由などで) JVM に接続しないようにすることができます。以下の手順では、Kafka ブローカーの JMX エージェントを無効にする方法を説明します。

手順

  1. KAFKA_JMX_OPTS 環境変数を使用して com.sun.management.jmxremotefalse に設定します。

    export KAFKA_JMX_OPTS=-Dcom.sun.management.jmxremote=false
    bin/kafka-server-start.sh
  2. JVM を起動します。

8.3. 別のマシンからの JVM への接続

JMX エージェントがリッスンするポートを設定すると、別のマシンから JVM に接続できます。これは、JMX ツールがどこからでも認証なしで接続できるため、安全ではありません。

手順

  1. KAFKA_JMX_OPTS 環境変数を使用して -Dcom.sun.management.jmxremote.port=<port> を設定します。<port> には、Kafka ブローカーが JMX 接続をリッスンするポートの名前を入力します。

    export KAFKA_JMX_OPTS="-Dcom.sun.management.jmxremote=true
      -Dcom.sun.management.jmxremote.port=<port>
      -Dcom.sun.management.jmxremote.authenticate=false
      -Dcom.sun.management.jmxremote.ssl=false"
    bin/kafka-server-start.sh
  2. JVM を起動します。
重要

リモート JMX 接続をセキュアにするには、認証と SSL を設定することが推奨されます。これを行うために必要なシステムプロパティーの詳細については、JMX のドキュメント を参照してください。

8.4. JConsole を使用した監視

JConsole ツールは Java Development Kit (JDK) とともに配布されます。JConsole を使用して、ローカルまたはリモート JVM に接続し、Java アプリケーションから管理情報を検出および表示できます。JConsole を使用してローカル JVM に接続する場合、AMQ Streams のさまざまなコンポーネントに対応する JVM プロセスの名前は以下のとおりです。

表8.1 AMQ Streams コンポーネントの JVM プロセス
AMQ Streams コンポーネントJVM プロセス

ZooKeeper

org.apache.zookeeper.server.quorum.QuorumPeerMain

Kafka ブローカー

kafka.Kafka

Kafka Connect スタンドアロン

org.apache.kafka.connect.cli.ConnectStandalone

Kafka Connect distributed

org.apache.kafka.connect.cli.ConnectDistributed

Kafka producer、consumer、または Streams application

アプリケーションの main メソッドが含まれるクラスの名前。

JConsole を使用してリモート JVM に接続する場合は、適切なホスト名と JMX ポートを使用します。

その他の多くのツールおよびモニタリング製品を使用して JMX を使用してメトリクスを取得し、そのメトリクスに基づいてモニタリングおよびアラートを提供できます。これらのツールについては、製品ドキュメントを参照してください。

8.5. 重要な Kafka ブローカーメトリクス

Kafka は、Kafka クラスターのブローカーのパフォーマンスを監視するための多くの MBean を提供します。これらは、クラスター全体ではなく、個別のブローカーに適用されます。

以下の表は、サーバー、ネットワーク、ロギング、およびコントローラーメトリクスに編成されるこれらのブローカーレベルの MBean の一部です。

8.5.1. Kafka サーバーメトリクス

以下の表は、Kafka サーバーに関する情報を報告するメトリクスの一部です。

表8.2 Kafka サーバーのメトリクス
メトリクスMBean説明想定される値

1 秒あたりのメッセージ数

kafka.server:type=BrokerTopicMetrics,name=MessagesInPerSec

個々のメッセージがブローカーによって消費されるレート。

クラスターの他のブローカーとほぼ同じです。

1 秒あたりのバイト数

kafka.server:type=BrokerTopicMetrics,name=BytesInPerSec

プロデューサーから送信されたデータがブローカーによって消費されるレート。

クラスターの他のブローカーとほぼ同じです。

1 秒あたりのレプリケーションバイト数

kafka.server:type=BrokerTopicMetrics,name=ReplicationBytesInPerSec

他のブローカーから送信されたデータがフォロワーブローカーによって消費されるレート。

該当なし

1 秒あたりのバイト数

kafka.server:type=BrokerTopicMetrics,name=BytesOutPerSec

コンシューマーによってブローカーからデータを取得および読み取るレート。

該当なし

1 秒あたりのレプリケーションバイト数

kafka.server:type=BrokerTopicMetrics,name=ReplicationBytesOutPerSec

ブローカーから他のブローカーにデータを送信するレート。このメトリクスは、ブローカーがパーティションのグループのリーダーであるかどうかを監視するのに役立ちます。

該当なし

複製の数が最低数未満パーティション

kafka.server:type=ReplicaManager,name=UnderReplicatedPartitions

フォロワーレプリカに完全にレプリケートされていないパーティションの数。

ゼロ

最小 ISR パーティション数

kafka.server:type=ReplicaManager,name=UnderMinIsrPartitionCount

最小の In-Sync Replica (ISR) カウント下のパーティションの数。ISR 数は、リーダーと最新の状態にあるレプリカのセットを示します。

ゼロ

パーティションの数

kafka.server:type=ReplicaManager,name=PartitionCount

ブローカーのパーティション数。

他のブローカーと比較してほぼ同じです。

リーダー数

kafka.server:type=ReplicaManager,name=LeaderCount

このブローカーがリーダーであるレプリカの数。

クラスターの他のブローカーとほぼ同じです。

ISR は 1 秒あたりに縮小します

kafka.server:type=ReplicaManager,name=IsrShrinksPerSec

ブローカー内の ISR の数が減少する割合

ゼロ

1 秒あたりの ISR 拡張

kafka.server:type=ReplicaManager,name=IsrExpandsPerSec

ブローカー内の ISR の数が増大する割合

ゼロ

最大ラグ

kafka.server:type=ReplicaFetcherManager,name=MaxLag,clientId=Replica

メッセージがリーダーレプリカとフォロワーレプリカによって受信される時間の間の最大ラグ。

生成リクエストの最大バッチサイズに比例します。

producer purgatory での要求

kafka.server:type=DelayedOperationPurgatory,name=PurgatorySize,delayedOperation=Produce

producer purgatory の送信リクエストの数。

該当なし

fetch purgatory での要求

kafka.server:type=DelayedOperationPurgatory,name=PurgatorySize,delayedOperation=Fetch

fetch purgatory のフェッチリクエストの数。

該当なし

リクエストハンドラーの平均アイドル率

kafka.server:type=KafkaRequestHandlerPool,name=RequestHandlerAvgIdlePercent

リクエストハンドラー (IO) スレッドが使用されていない時間の割合を示します。

値が小さいほど、ブローカーのワークロードが高いことを示します。

リクエスト (スロットルを除外されるリクエスト)

kafka.server:type=Request

スロットリングから除外される要求の数。

該当なし

Zoo Keeper リクエストのレイテンシー (ミリ秒)

kafka.server:type=ZooKeeperClientMetrics,name=ZooKeeperRequestLatencyMs

ブローカーからの Zoo Keeper リクエストのレイテンシー (ミリ秒単位)。

該当なし

ZooKeeper セッションの状態

kafka.server:type=SessionExpireListener,name=SessionState

ブローカーの ZooKeeper への接続状態。

接続済み

8.5.2. Kafka ネットワークメトリクス

以下の表は、リクエストに関する情報を報告するメトリクスの一部です。

メトリクスMBean説明想定される値

1 秒あたりのリクエスト数

kafka.network:type=RequestMetrics,name=RequestsPerSec,request={Produce|FetchConsumer|FetchFollower}

1 秒あたりの要求タイプに対して行われるリクエストの合計数。ProduceFetchConsumerFetchFollower 要求タイプにはそれぞれ独自の MBean があります。

該当なし

リクエストバイト (バイト単位のリクエストサイズ)

kafka.network:type=RequestMetrics,name=RequestBytes,request=([-.\w]+)

MBean 名の request プロパティーで識別されるリクエストタイプに対して行われたリクエストのサイズ (バイト単位)。RequestBytes ノードの下には、利用可能なすべてのリクエストタイプの個別の MBean が表示されます。

該当なし

バイト単位の一時メモリーサイズ

kafka.network:type=RequestMetrics,name=TemporaryMemoryBytes,request={Produce|Fetch}

メッセージ形式の変換およびメッセージの展開に使用される一時メモリーの量。

該当なし

メッセージ変換時間

kafka.network:type=RequestMetrics,name=MessageConversionsTimeMs,request={Produce|Fetch}

メッセージ形式の変換に費やされた時間 (ミリ秒単位)。

該当なし

ミリ秒単位の合計リクエスト時間

kafka.network:type=RequestMetrics,name=TotalTimeMs,request={Produce|FetchConsumer|FetchFollower}

リクエストの処理に費やされた合計時間 (ミリ秒単位)。

該当なし

ミリ秒単位の要求キュー時間

kafka.network:type=RequestMetrics,name=RequestQueueTimeMs,request={Produce|FetchConsumer|FetchFollower}

request プロパティーで指定されたリクエストタイプに対して、リクエストが現在キューで費やす時間 (ミリ秒単位)。

該当なし

ミリ秒単位の現地時間 (リーダーの現地処理時間)

kafka.network:type=RequestMetrics,name=LocalTimeMs,request={Produce|FetchConsumer|FetchFollower}

リーダーがリクエストを処理するのにかかる時間 (ミリ秒単位)。

該当なし

ミリ秒単位のリモート時間 (リーダーのリモート処理時間)

kafka.network:type=RequestMetrics,name=RemoteTimeMs,request={Produce|FetchConsumer|FetchFollower}

要求がフォロワーを待機する時間の長さ (ミリ秒単位)。すべての利用可能な要求タイプの個別の MBean が RemoteTimeMs ノードの下に一覧表示されます。

該当なし

ミリ秒単位の応答キュー時間

kafka.network:type=RequestMetrics,name=ResponseQueueTimeMs,request={Produce|FetchConsumer|FetchFollower}

要求が応答キューで待機する時間の長さ (ミリ秒単位)。

該当なし

ミリ秒単位の応答送信時間

kafka.network:type=RequestMetrics,name=ResponseSendTimeMs,request={Produce|FetchConsumer|FetchFollower}

応答の送信にかかった時間 (ミリ秒単位)。

該当なし

ネットワークプロセッサーの平均アイドル率

kafka.network:type=SocketServer,name=NetworkProcessorAvgIdlePercent

ネットワークプロセッサーがアイドル状態である時間の平均パーセンテージ。

0 から 1 の間。

8.5.3. Kafka ログメトリクス

次の表は、ロギングに関する情報を報告するメトリクスの選択を示しています。

メトリクスMBean説明想定される値

ログのフラッシュ速度と時間 (ミリ秒)

kafka.log:type=LogFlushStats,name=LogFlushRateAndTimeMs

ログデータがディスクに書き込まれる速度 (ミリ秒単位)。

該当なし

オフラインのログディレクトリー数

kafka.log:type=LogManager,name=OfflineLogDirectoryCount

オフラインログディレクトリーの数 (たとえば、ハードウェア障害後)。

ゼロ

8.5.4. Kafka コントローラーメトリクス

次の表は、クラスターのコントローラーに関する情報を報告するメトリクスの選択を示しています。

メトリクスMBean説明想定される値

アクティブなコントローラーの数

kafka.controller:type=KafkaController,name=ActiveControllerCount

コントローラーとして指定されるブローカーの数。

1 つは、ブローカーがクラスターのコントローラーであることを示します。

リーダーエレクション率と時間 (ミリ秒)

kafka.controller:type=ControllerStats,name=LeaderElectionRateAndTimeMs

新しいリーダーレプリカが選出されるレート。

ゼロ

8.5.5. Yammer メトリクス

レートまたは時間の単位を表すメトリクスは、Yammer メトリクスとして提供されます。Yammer メトリクスを使用する MBean のクラス名には、com.yammer.metrics というプレフィックスがつきます。

Yammer レートメトリクスには、要求を監視する以下の属性があります。

  • Count
  • EventType (バイト)
  • FifteenMinuteRate
  • RateUnit (秒)
  • MeanRate
  • OneMinuteRate
  • FiveMinuteRate

Yammer 時間メトリクスには、要求を監視するための以下の属性があります。

  • Max
  • Min
  • Mean
  • StdDev
  • 75/95/98/99/99.9 パーセンタイル

8.6. プロデューサー MBean

以下の MBean は、Kafka Streams アプリケーションやソースコネクターのある Kafka Connect など、Kafka プロデューサーアプリケーションに存在します。

8.6.1. kafka.producer:type=producer-metrics,client-id=* と一致する MBean

これらはプロデューサーレベルでのメトリクスです。

属性説明

batch-size-avg

要求ごとにパーティションごとに送信されるバイトの平均数。

batch-size-max

リクエストごとおよびパーティションごとに送信されるバイトの最大数。

batch-split-rate

1 秒あたりのバッチスプリットの平均数。

batch-split-total

バッチスプリットの合計数。

buffer-available-bytes

使用されていない (未割り当てまたは空きリストにある) バッファメモリーの合計量。

buffer-total-bytes

クライアントが使用できるバッファメモリーの最大量 (現在使用されているかどうかに関係なく)。

bufferpool-wait-time

アペンダーがスペースの割り当てを待つ時間の割合。

compression-rate-avg

レコードバッチの平均圧縮率。

connection-close-rate

ウィンドウで 1 秒間に閉じられる接続。

connection-count

アクティブな接続の現在の数。

connection-creation-rate

ウィンドウで 1 秒間に確立される新しい接続。

failed-authentication-rate

認証に失敗した接続数。

incoming-byte-rate

すべてのソケットから読み取られたバイト/秒。

io-ratio

I/O スレッドが I/O の実行に費やした時間の割合。

io-time-ns-avg

選択した呼び出しごとの I/O の平均時間 (ナノ秒単位)。

io-wait-ratio

I/O スレッドが待機に費やした時間の割合。

io-wait-time-ns-avg

読み取りまたは書き込みの準備ができたソケットの待機に費やされた I/O スレッドの平均時間 (ナノ秒単位)。

metadata-age

使用されている現在のプロデューサーメタデータの秒単位の経過時間。

network-io-rate

1 秒あたりのすべての接続でのネットワーク操作 (読み取りまたは書き込み) の平均数。

outgoing-byte-rate

すべてのサーバーに 1 秒間に送信する送信バイトの平均数。

produce-throttle-time-avg

リクエストがブローカーによって抑制された平均時間 (ミリ秒)。

produce-throttle-time-max

ブローカーによってリクエストがスロットルされた最大時間 (ミリ秒単位)。

record-error-rate

エラーとなったレコード送信の 1 秒あたりの平均数。

record-error-total

エラーとなったレコード送信の合計数。

record-queue-time-avg

送信バッファーで費やされたレコードバッチの平均時間 (ミリ秒)。

record-queue-time-max

送信バッファーで費やされたレコードバッチの最長時間 (ミリ秒)。

record-retry-rate

再試行されたレコード送信の 1 秒あたりの平均数。

record-retry-total

再試行されたレコード送信の合計数。

record-send-rate

1 秒間に送信するレコードの平均数。

record-send-total

送信されたレコードの総数。

record-size-avg

平均レコードサイズ。

record-size-max

最大レコードサイズ。

records-per-request-avg

リクエストごとの平均レコード数。

request-latency-avg

ミリ秒単位の平均リクエストレイテンシー。

request-latency-max

ミリ秒単位の最大リクエストレイテンシー。

request-rate

1 秒間に送信するリクエストの平均数。

request-size-avg

ウィンドウのすべてのリクエストの平均サイズ。

request-size-max

ウィンドウの送信リクエストの最大サイズ。

requests-in-flight

応答を待機するインフライトリクエストの現在の数。

response-rate

1 秒間に送信される受信レスポンス。

select-rate

I/O レイヤーが実行する新しい I/O をチェックする 1 秒あたりの回数。

successful-authentication-rate

SASL または SSL を使用して正常に認証された接続。

waiting-threads

バッファーメモリーがレコードをキューに入れるのを待機するブロックされたユーザースレッドの数。

8.6.2. kafka.producer:type=producer-metrics,client-id=*,node-id=* と一致する MBean

これらは、各ブローカーへの接続に関するプロデューサーレベルのメトリクスです。

属性説明

incoming-byte-rate

ノードが 1 秒間に受信したレスポンスの平均数。

outgoing-byte-rate

ノードが 1 秒間に送信する送信バイトの平均数。

request-latency-avg

ノードの平均リクエストレイテンシー (ミリ秒単位)。

request-latency-max

ノードの最大リクエストレイテンシー (ミリ秒単位)。

request-rate

ノードが 1 秒間に送信するリクエストの平均数。

request-size-avg

ノードのウィンドウにあるすべてのリクエストの平均サイズ。

request-size-max

ノードのウィンドウに送信されるリクエストの最大サイズ。

response-rate

ノードに対して 1 秒間に送信される受信応答。

8.6.3. kafka.producer:type=producer-topic-metrics,client-id=*,topic=* と一致する MBean

これらは、プロデューサーがメッセージを送信しているトピックに関するトピックレベルのメトリクスです。

属性説明

byte-rate

トピックに対して 1 秒間に送信するバイトの平均数。

byte-total

トピックに対して送信するバイトの合計数。

compression-rate

トピックに対するレコードバッチの平均圧縮率。

record-error-rate

トピックに対してエラーとなったレコード送信の 1 秒あたりの平均数。

record-error-total

トピックに対してエラーとなったレコード送信の合計数。

record-retry-rate

トピックに対して再試行されたレコード送信の 1 秒あたりの平均数。

record-retry-total

トピックに対して再試行されたレコード送信の合計数。

record-send-rate

トピックに対して 1 秒間に送信するレコードの平均数。

record-send-total

トピックに対して送信するレコードの合計数。

8.7. コンシューマー MBean

以下の MBean は、Kafka Streams アプリケーションやシンクコネクターのある Kafka Connect など、Kafka コンシューマーアプリケーションに存在します。

8.7.1. kafka.consumer:type=consumer-metrics,client-id=* と一致する MBean

これらは、コンシューマーレベルのメトリクスです。

属性説明

connection-close-rate

ウィンドウで 1 秒間に閉じられる接続。

connection-count

アクティブな接続の現在の数。

connection-creation-rate

ウィンドウで 1 秒間に確立される新しい接続。

failed-authentication-rate

認証に失敗した接続数。

incoming-byte-rate

すべてのソケットから読み取られたバイト/秒。

io-ratio

I/O スレッドが I/O の実行に費やした時間の割合。

io-time-ns-avg

選択した呼び出しごとの I/O の平均時間 (ナノ秒単位)。

io-wait-ratio

I/O スレッドが待機に費やした時間の割合。

io-wait-time-ns-avg

読み取りまたは書き込みの準備ができたソケットの待機に費やされた I/O スレッドの平均時間 (ナノ秒単位)。

network-io-rate

1 秒あたりのすべての接続でのネットワーク操作 (読み取りまたは書き込み) の平均数。

outgoing-byte-rate

すべてのサーバーに 1 秒間に送信する送信バイトの平均数。

request-rate

1 秒間に送信するリクエストの平均数。

request-size-avg

ウィンドウのすべてのリクエストの平均サイズ。

request-size-max

ウィンドウの送信リクエストの最大サイズ。

response-rate

1 秒間に送信される受信レスポンス。

select-rate

I/O レイヤーが実行する新しい I/O をチェックする 1 秒あたりの回数。

successful-authentication-rate

SASL または SSL を使用して正常に認証された接続。

8.7.2. kafka.consumer:type=consumer-metrics,client-id=*,node-id=* と一致する MBean

これらは、各ブローカーへの接続に関するコンシューマーレベルのメトリクスです。

属性説明

incoming-byte-rate

ノードが 1 秒間に受信したレスポンスの平均数。

outgoing-byte-rate

ノードが 1 秒間に送信する送信バイトの平均数。

request-latency-avg

ノードの平均リクエストレイテンシー (ミリ秒単位)。

request-latency-max

ノードの最大リクエストレイテンシー (ミリ秒単位)。

request-rate

ノードが 1 秒間に送信するリクエストの平均数。

request-size-avg

ノードのウィンドウにあるすべてのリクエストの平均サイズ。

request-size-max

ノードのウィンドウに送信されるリクエストの最大サイズ。

response-rate

ノードに対して 1 秒間に送信される受信応答。

8.7.3. kafka.consumer:type=consumer-coordinator-metrics,client-id=* と一致する MBean

これらは、コンシューマーグループに関するコンシューマーレベルのメトリクスです。

属性説明

assigned-partitions

このコンシューマーに現在割り当てられているパーティションの数。

commit-latency-avg

コミットリクエストにかかる平均時間。

commit-latency-max

コミットリクエストにかかる最大時間。

commit-rate

1 秒あたりのコミットコールの数。

heartbeat-rate

1 秒あたりのハートビートの平均数。

heartbeat-response-time-max

ハートビート要求への応答を受信するのにかかる最大時間。

join-rate

1 秒あたりのグループ参加数。

join-time-avg

グループの再参加にかかる平均時間。

join-time-max

グループの再参加にかかる最大時間。

last-heartbeat-seconds-ago

最後のコントローラーハートビートからの秒数。

sync-rate

1 秒あたりのグループ同期数。

sync-time-avg

グループ同期にかかる平均時間。

sync-time-max

グループ同期にかかる最大時間。

8.7.4. kafka.consumer:type=consumer-fetch-manager-metrics,client-id=* と一致する MBean

これらは、コンシューマーのフェッチャーに関するコンシューマーレベルのメトリクスです。

属性説明

bytes-consumed-rate

1 秒あたり消費される平均のバイト数。

bytes-consumed-total

消費された総バイト数。

fetch-latency-avg

フェッチリクエストにかかる平均時間。

fetch-latency-max

任意のフェッチリクエストにかかる最大時間。

fetch-rate

1 秒あたりのフェッチリクエストの数。

fetch-size-avg

リクエストごとにフェッチされたバイトの平均数。

fetch-size-max

リクエストごとにフェッチされたバイトの最大数。

fetch-throttle-time-avg

ミリ秒単位の平均スロットル時間。

fetch-throttle-time-max

ミリ秒単位の最大スロットル時間。

fetch-total

フェッチリクエストの総数。

records-consumed-rate

1 秒あたり消費される平均のレコード数。

records-consumed-total

消費されるレコードの総数。

records-lag-max

このウィンドウの任意のパーティションのレコード数に関する最大ラグ。

records-lead-min

このウィンドウの任意のパーティションのレコード数に関する最小のリード。

records-per-request-avg

各リクエストの平均レコード数。

8.7.5. kafka.consumer:type=consumer-fetch-manager-metrics,client-id=*,topic=* と一致する MBean

これらは、コンシューマーのフェッチャーに関するトピックレベルのメトリクスです。

属性説明

bytes-consumed-rate

トピックに対して 1 秒あたり消費される平均のバイト数。

bytes-consumed-total

トピックで消費された総バイト数。

fetch-size-avg

トピックに対してリクエストごとにフェッチされたバイトの平均数。

fetch-size-max

トピックに対してリクエストごとにフェッチされたバイトの最大数。

records-consumed-rate

トピックに対して 1 秒あたり消費される平均のレコード数。

records-consumed-total

トピックで消費されたレコードの合計数。

records-per-request-avg

トピックの各リクエストの平均レコード数。

8.7.6. kafka.consumer:type=consumer-fetch-manager-metrics,client-id=*,topic=*,partition=* と一致する MBean

これらは、コンシューマーのフェッチャーに関するパーティションレベルのメトリクスです。

属性説明

preferred-read-replica

パーティションの現在の読み取りレプリカ。リーダーから読み取る場合は -1。

records-lag

パーティションの最新のラグ。

records-lag-avg

パーティションの平均ラグ。

records-lag-max

パーティションの最大ラグ数。

records-lead

パーティションの最新のリード。

records-lead-avg

パーティションの平均リード。

records-lead-min

パーティションの最小リード。

8.8. Kafka Connect MBean

注記

Kafka Connect には、ここに記載されているものに加えて、ソースコネクター用の プロデューサー MBean とシンクコネクター用の コンシューマー MBean が含まれます。

8.8.1. kafka.connect:type=connect-metrics,client-id=* と一致する MBean

これらは接続レベルのメトリクスです。

属性説明

connection-close-rate

ウィンドウで 1 秒間に閉じられる接続。

connection-count

アクティブな接続の現在の数。

connection-creation-rate

ウィンドウで 1 秒間に確立される新しい接続。

failed-authentication-rate

認証に失敗した接続数。

incoming-byte-rate

すべてのソケットから読み取られたバイト/秒。

io-ratio

I/O スレッドが I/O の実行に費やした時間の割合。

io-time-ns-avg

選択した呼び出しごとの I/O の平均時間 (ナノ秒単位)。

io-wait-ratio

I/O スレッドが待機に費やした時間の割合。

io-wait-time-ns-avg

読み取りまたは書き込みの準備ができたソケットの待機に費やされた I/O スレッドの平均時間 (ナノ秒単位)。

network-io-rate

1 秒あたりのすべての接続でのネットワーク操作 (読み取りまたは書き込み) の平均数。

outgoing-byte-rate

すべてのサーバーに 1 秒間に送信する送信バイトの平均数。

request-rate

1 秒間に送信するリクエストの平均数。

request-size-avg

ウィンドウのすべてのリクエストの平均サイズ。

request-size-max

ウィンドウの送信リクエストの最大サイズ。

response-rate

1 秒間に送信される受信レスポンス。

select-rate

I/O レイヤーが実行する新しい I/O をチェックする 1 秒あたりの回数。

successful-authentication-rate

SASL または SSL を使用して正常に認証された接続。

8.8.2. kafka.connect:type=connect-metrics,client-id=*,node-id=* と一致する MBean

これらは、各ブローカーへの接続に関する接続レベルのメトリクスです。

属性説明

incoming-byte-rate

ノードが 1 秒間に受信したレスポンスの平均数。

outgoing-byte-rate

ノードが 1 秒間に送信する送信バイトの平均数。

request-latency-avg

ノードの平均リクエストレイテンシー (ミリ秒単位)。

request-latency-max

ノードの最大リクエストレイテンシー (ミリ秒単位)。

request-rate

ノードが 1 秒間に送信するリクエストの平均数。

request-size-avg

ノードのウィンドウにあるすべてのリクエストの平均サイズ。

request-size-max

ノードのウィンドウに送信されるリクエストの最大サイズ。

response-rate

ノードに対して 1 秒間に送信される受信応答。

8.8.3. kafka.connect:type=connect-worker-metrics と一致する MBean

これらは接続レベルのメトリクスです。

属性説明

connector-count

このワーカーで実行されるコネクターの数。

connector-startup-attempts-total

このワーカーが試みたコネクター起動の合計数。

connector-startup-failure-percentage

このワーカーのコネクター起動のうち、失敗したものの平均割合。

connector-startup-failure-total

失敗したコネクター起動の総数。

connector-startup-success-percentage

このワーカーのコネクター起動のうち、成功したものの平均割合。

connector-startup-success-total

成功したコネクター起動の総数。

task-count

このワーカーで実行されるタスクの数。

task-startup-attempts-total

このワーカーが試みたタスク起動の合計数。

task-startup-failure-percentage

このワーカーのタスク起動のうち、失敗したものの平均割合。

task-startup-failure-total

失敗したタスク開始の合計数。

task-startup-success-percentage

このワーカーのタスク起動のうち、成功したものの平均割合。

task-startup-success-total

成功したタスク開始の合計数。

8.8.4. kafka.connect:type=connect-worker-rebalance-metrics と一致する MBean

属性説明

completed-rebalances-total

このワーカーが完了したリバランスの合計数。

connect-protocol

このクラスターによって使用される Connect プロトコル。

epoch

このワーカーのエポックまたは生成番号。

leader-name

グループリーダーの名前。

rebalance-avg-time-ms

このワーカーがリバランスに費やした平均時間 (ミリ秒単位)。

rebalance-max-time-ms

このワーカーがリバランスするために費やした最大時間 (ミリ秒単位)。

rebalancing

このワーカーが現在リバランス中であるかどうか。

time-since-last-rebalance-ms

このワーカーが最新のリバランスを完了してからのミリ秒単位の時間。

8.8.5. kafka.connect:type=connector-metrics,connector=* と一致する MBean

属性説明

connector-class

コネクタークラスの名前。

connector-type

コネクターのタイプ。「ソース」または「シンク」のいずれか。

connector-version

コネクターによって報告されるコネクタークラスのバージョン。

status

コネクターのステータス。「unassigned」、「running」、「paused」、「failed」、「destroyed」のいずれか。

8.8.6. kafka.connect:type=connector-task-metrics,connector=*,task=* と一致する MBean

属性説明

batch-size-avg

コネクターによって処理されるバッチの平均サイズ。

batch-size-max

コネクターによって処理されるバッチの最大サイズ。

offset-commit-avg-time-ms

このタスクがオフセットをコミットするのに要した平均時間 (ミリ秒単位)。

offset-commit-failure-percentage

このタスクのオフセットコミット試行のうち、失敗したものの平均割合。

offset-commit-max-time-ms

このタスクがオフセットをコミットするのにかかる最大時間 (ミリ秒単位)。

offset-commit-success-percentage

このタスクのオフセットコミット試行のうち、成功したものの平均割合。

pause-ratio

このタスクが pause 状態で費やした時間の割合。

running-ratio

このタスクが running 状態で費やした時間の割合。

status

コネクタータスクのステータス。「unassigned」、「running」、「paused」、「failed」、「destroyed」のいずれか。

8.8.7. kafka.connect:type=sink-task-metrics,connector=*,task=* と一致する MBean

属性説明

offset-commit-completion-rate

正常に完了したオフセットコミット完了の 1 秒あたりの平均数。

offset-commit-completion-total

正常に完了したオフセットコミット完了の合計数。

offset-commit-seq-no

オフセットコミットの現在のシーケンス番号。

offset-commit-skip-rate

受信が遅すぎてスキップ/無視されたオフセットコミット完了の 1 秒あたりの平均数。

offset-commit-skip-total

受信が遅すぎてスキップ/無視されたオフセットコミット完了の合計数。

partition-count

このワーカーの名前付きシンクコネクターに属するこのタスクに割り当てられたトピックパーティションの数。

put-batch-avg-time-ms

このタスクがシンクの記録を一括して行うためにかかった平均時間。

put-batch-max-time-ms

このタスクがシンクの記録を一括して行うためにかかった最大時間。

sink-record-active-count

Kafka から読み込まれたものの、シンクタスクがまだ完全にコミット、フラッシュ、確認していないレコードの数。

sink-record-active-count-avg

Kafka から読み込まれたものの、シンクタスクが完全にコミット、フラッシュ、確認していないレコードの平均数。

sink-record-active-count-max

Kafka から読み込まれたものの、シンクタスクが完全にコミット、フラッシュ、確認していないレコードの最大数。

sink-record-lag-max

任意のトピックパーティションで、シンクタスクがコンシューマーの位置の背後であるレコード数に関する最大ラグ。

sink-record-read-rate

このワーカーの名前付きシンクコネクターに属するこのタスクで、Kafka から読み取られるレコードの 1 秒あたりの平均数。これは、変換が適用される前に行われます。

sink-record-read-total

タスクが最後に再起動されてから、このワーカーの名前付きシンクコネクターに属するこのタスクによって Kafka から読み取られたレコードの合計数。

sink-record-send-rate

変換から出力されたレコードの 1 秒あたりの平均数。このワーカーの名前付きシンクコネクターに属するこのタスクに送信または配置します。これは、変換の適用後で、変換によってフィルタリングされたレコードをすべて除外します。

sink-record-send-total

タスクが最後に再起動されてから、このワーカーの名前付きシンクコネクターに属するこのタスクに送信または配置する、変換から出力されたレコードの合計数。

8.8.8. kafka.connect:type=source-task-metrics,connector=*,task=* と一致する MBean

属性説明

poll-batch-avg-time-ms

このタスクがソースレコードのバッチをポーリングするためにかかった平均時間 (ミリ秒単位)。

poll-batch-max-time-ms

このタスクがソースレコードのバッチをポーリングするためにかかった最大時間 (ミリ秒単位)。

source-record-active-count

このタスクによって生成され、まだ完全に Kafka に書き込まれていないレコードの数。

source-record-active-count-avg

このタスクによって生成され、まだ完全に Kafka に書き込まれていないレコードの平均数。

source-record-active-count-max

このタスクによって生成され、まだ完全に Kafka に書き込まれていないレコードの最大数。

source-record-poll-rate

このワーカーの名前付きソースコネクターに属するこのタスクによって生成/ポーリングされた (変換前) レコードの 1 秒あたりの平均数。

source-record-poll-total

このワーカーの名前付きソースコネクターに属するこのタスクによって生成/ポーリングされた (変換前) レコードの合計数。

source-record-write-rate

変換から出力され、このワーカーの名前付きソースコネクターに属するこのタスクの Kafka に書き込まれたレコードの 1 秒あたりの平均数。これは、変換の適用後で、変換によってフィルタリングされたレコードをすべて除外します。

source-record-write-total

タスクが最後に再起動されてから、変換から出力され、このワーカーの名前付きソースコネクターに属するこのタスクの Kafka に書き込まれたレコードの数。

8.8.9. kafka.connect:type=task-error-metrics,connector=*,task=* と一致する MBean

属性説明

deadletterqueue-produce-failures

デッドレターキューへの書き込み失敗数。

deadletterqueue-produce-requests

デッドレターキューへの書き込み試行の数。

last-error-timestamp

このタスクで最後にエラーが発生したときのエポックタイムスタンプ。

total-errors-logged

ログに記録されたエラーの数。

total-record-errors

このタスクでのレコード処理エラーの数。

total-record-failures

このタスクでのレコード処理の失敗数。

total-records-skipped

エラーによりスキップされたレコードの数。

total-retries

再試行された操作の数。

8.9. Kafka Streams MBean

注記

Streams アプリケーションには、ここで説明したものに加えて、プロデューサーコンシューマー MBean が含まれます。

8.9.1. kafka.streams:type=stream-metrics,client-id=* と一致する MBean

これらのメトリクスは、metrics.recording.level 設定パラメーターが info または debug の場合に収集されます。

属性説明

commit-latency-avg

このスレッドのすべての実行中のタスクにおけるコミットの平均実行時間 (ミリ秒単位)。

commit-latency-max

このスレッドのすべての実行中のタスクにおけるコミットの最大実行時間 (ミリ秒単位)。

commit-rate

1 秒あたりの平均コミット数。

commit-total

すべてのタスクにまたがるコミット呼び出しの合計数。

poll-latency-avg

このスレッドのすべての実行中のタスクにおけるポーリングの平均実行時間 (ミリ秒単位)。

poll-latency-max

このスレッドのすべての実行中のタスクにおけるポーリングの最大実行時間 (ミリ秒単位)。

poll-rate

1 秒あたりの平均ポーリング数。

poll-total

すべてのタスクのポーリングコールの合計数。

process-latency-avg

このスレッドのすべての実行中のタスクにおける処理の平均実行時間 (ミリ秒単位)。

process-latency-max

このスレッドのすべての実行中のタスクにおける処理の最大実行時間 (ミリ秒単位)。

process-rate

1 秒あたりのプロセスコールの平均数。

process-total

すべてのタスクにまたがるプロセスコールの合計数。

punctuate-latency-avg

このスレッドのすべての実行中のタスクにおける punctuate の平均実行時間 (ミリ秒単位)。

punctuate-latency-max

このスレッドのすべての実行中のタスクにおける punctuate の最大実行時間 (ミリ秒単位)。

punctuate-rate

1 秒あたりの punctuate の平均数。

punctuate-total

すべてのタスクの punctuate コールの合計数。

skipped-records-rate

1 秒あたりのスキップされたレコードの平均数。

skipped-records-total

スキップされたレコードの合計数。

task-closed-rate

1 秒間に閉じられたタスクの平均数。

task-closed-total

閉じられたタスクの合計数。

task-created-rate

1 秒あたりの新規作成タスクの平均数。

task-created-total

作成されたタスクの合計数。

8.9.2. kafka.streams:type=stream-task-metrics,client-id=*,task-id=* と一致する MBean

タスクメトリクス

これらのメトリクスは、metrics.recording.level 設定パラメーターが debug のときに収集されます。

属性説明

commit-latency-avg

このタスクの平均コミット時間 (ナノ秒単位)。

commit-latency-max

このタスクの最大コミット時間 (ナノ秒単位)。

commit-rate

1 秒あたりのコミットコールの平均数。

commit-total

コミットコールの合計数。

8.9.3. kafka.streams:type=stream-processor-node-metrics,client-id=*,task-id=*,processor-node-id=* と一致する MBean

プロセッサーノードメトリクス

これらのメトリクスは、metrics.recording.level 設定パラメーターが debug のときに収集されます。

属性説明

create-latency-avg

平均作成実行時間 (ナノ秒単位)。

create-latency-max

最大作成実行時間 (ナノ秒単位)。

create-rate

1 秒あたりの作成操作の平均数。

create-total

呼び出された作成操作の合計数。

destroy-latency-avg

平均破棄実行時間 (ナノ秒単位)。

destroy-latency-max

最大破棄実行時間 (ナノ秒単位)。

destroy-rate

1 秒あたりの破棄操作の平均数。

destroy-total

呼び出された破棄操作の合計数。

forward-rate

ソースノードのみからダウンストリームに転送されるレコードの 1 秒あたりの平均レート。

forward-total

ソースノードのみからダウンストリームに転送されるレコードの合計数。

process-latency-avg

平均プロセス実行時間 (ナノ秒単位)。

process-latency-max

最大プロセス実行時間 (ナノ秒単位)。

process-rate

1 秒あたりのプロセス操作の平均数。

process-total

呼び出されたプロセス操作の合計数。

punctuate-latency-avg

平均 punctuate 実行時間 (ナノ秒単位)。

punctuate-latency-max

最大 punctuate 実行時間 (ナノ秒単位)。

punctuate-rate

1 秒あたりの punctuate 操作の平均数。

punctuate-total

呼び出された punctuate 操作の合計数。

8.9.4. kafka.streams:type=stream-[store-scope]-metrics,client-id=*,task-id=*,[store-scope]-id=* と一致する MBean

ステートストアメトリクス

これらのメトリクスは、metrics.recording.level 設定パラメーターが debug のときに収集されます。

属性説明

all-latency-avg

すべての操作の平均実行時間 (ns)。

all-latency-max

すべての操作の最大実行時間 (ns)。

all-rate

このストアのすべての操作レートの平均。

all-total

このストアのすべての操作コールの合計数。

delete-latency-avg

平均削除実行時間 (ナノ秒単位)。

delete-latency-max

最大削除実行時間 (ナノ秒単位)。

delete-rate

このストアの平均削除レート。

delete-total

このストアの削除コールの合計数。

flush-latency-avg

フラッシュの平均実行時間 (ナノ秒単位)。

flush-latency-max

フラッシュの最大実行時間 (ナノ秒単位)。

flush-rate

このストアの平均フラッシュレート。

flush-total

このストアのフラッシュコールの合計数。

get-latency-avg

get の平均実行時間 (ナノ秒単位)。

get-latency-max

get の最大実行時間 (ナノ秒単位)。

get-rate

このストアの平均 get レート。

get-total

このストアの get コールの総数。

put-all-latency-avg

put-all の平均実行時間 (ナノ秒単位)。

put-all-latency-max

put-all の最大実行時間 (ナノ秒単位)。

put-all-rate

このストアの平均 put-all レート。

put-all-total

このストアの put-all コールの合計数。

put-if-absent-latency-avg

put-if-absent の平均実行時間 (ナノ秒単位)。

put-if-absent-latency-max

put-if-absent の最大実行時間 (ナノ秒単位)。

put-if-absent-rate

このストアの平均 put-if-absent レート。

put-if-absent-total

このストアの put-if-absent コールの合計数。

put-latency-avg

put の平均実行時間 (ナノ秒単位)。

put-latency-max

put の最大実行時間 (ナノ秒単位)。

put-rate

このストアの平均 put レート。

put-total

このストアの put コールの合計数。

range-latency-avg

平均範囲実行時間 (ナノ秒単位)。

range-latency-max

最大範囲実行時間 (ナノ秒単位)。

range-rate

このストアの平均範囲のレート。

range-total

このストアの範囲コールの合計数。

restore-latency-avg

復元の平均実行時間 (ナノ秒単位)。

restore-latency-max

復元の最大実行時間 (ナノ秒単位)。

restore-rate

このストアの平均復元レート。

restore-total

このストアの復元コールの合計数。

8.9.5. kafka.streams:type=stream-record-cache-metrics,client-id=*,task-id=*,record-cache-id=* と一致する MBean

レコードキャッシュメトリクス

これらのメトリクスは、metrics.recording.level 設定パラメーターが debug のときに収集されます。

属性説明

hitRatio-avg

キャッシュ読み取り要求の合計に対するキャッシュ読み取りヒット率として定義される平均キャッシュヒット率。

hitRatio-max

最大キャッシュヒット率。

hitRatio-min

最小キャッシュヒット率。

第9章 Kafka Connect

Kafka Connect は、Apache Kafka と外部システムとの間でデータをストリーミングするためのツールです。スケーラビリティーと信頼性を維持しながら大量のデータを移動するためのフレームワークが提供されます。Kafka Connect は通常、Kafka を Kafka クラスター外のデータベース、ストレージシステム、およびメッセージングシステムと統合するために使用されます。

Kafka Connect は、さまざまな種類の外部システムへの接続を実装するコネクタープラグインを使用します。コネクタープラグインには、シンクとソースの 2 つのタイプがあります。シンクコネクターは、Kafka から外部システムにデータをストリーミングします。ソースコネクターは、外部システムから Kafka にデータをストリーミングします。

Kafka Connect はスタンドアロンまたは分散モードで実行できます。

スタンドアロンモード
スタンドアロンモードでは、Kafka Connect はプロパティーファイルから読み込んだユーザー定義の設定を持つ単一ノードで実行されます。
分散モード
分散モードでは、Kafka Connect は 1 つまたは複数のワーカーノードで実行され、ワークロードはワーカーノード間で分散されます。コネクターとその設定は、HTTP REST インターフェイスを使用して管理します。

9.1. スタンドアロンモードでの Kafka Connect

スタンドアロンモードでは、Kafka Connect は単一ノードで単一のプロセスとして実行されます。スタンドアロンモードの設定は、プロパティーファイルを使用して管理します。

9.1.1. スタンドアロンモードでの Kafka Connect の設定

Kafka Connect をスタンドアロンモードで設定するには、config/connect-standalone.properties 設定ファイルを編集します。以下のオプションが最も重要です。

bootstrap.servers
Kafka へのブートストラップ接続として使用される Kafka ブローカーアドレスのリスト。たとえば、kafka0.my-domain.com:9092,kafka1.my-domain.com:9092,kafka2.my-domain.com:9092 です。
key.converter
メッセージキーを Kafka 形式との間で変換するために使用されるクラス。たとえば、org.apache.kafka.connect.json.JsonConverter です。
value.converter
メッセージペイロードを Kafka 形式との間で変換するために使用されるクラス。たとえば、org.apache.kafka.connect.json.JsonConverter です。
offset.storage.file.filename
オフセットデータが保存されるファイルを指定します。

設定ファイルの例は、config/connect-standalone.properties のインストールディレクトリーにあります。サポートされるすべての Kafka Connect 設定オプションの完全リストは、[kafka-connect-configuration-parameters-str] を参照してください。

コネクタープラグインは、ブートストラップアドレスを使用して Kafka ブローカーへのクライアント接続を開きます。これらの接続を設定するには、標準的な Kafka のプロデューサーとコンシューマーの設定オプションを使用し、producer. または consumer. プレフィックスを付けます。

Kafka プロデューサーおよびコンシューマーの設定に関する詳細は、以下を参照してください。

9.1.2. スタンドアロンモードでの Kafka Connect でのコネクターの設定

プロパティーファイルを使用すると、スタンドアロンモードで Kafka Connect のコネクタープラグインを設定できます。ほとんどの設定オプションは、各コネクターに固有のものです。以下のオプションはすべてのコネクターに適用されます。

name
現在の Kafka Connect インスタンス内で一意である必要があるコネクターの名前。
connector.class
コネクタープラグインのクラス。たとえば、org.apache.kafka.connect.file.FileStreamSinkConnector です。
tasks.max
指定のコネクターが使用できるタスクの最大数。タスクにより、コネクターは並行して作業を実行できます。コネクターは、指定された数よりも少ないタスクを作成する可能性があります。
key.converter
メッセージキーを Kafka 形式との間で変換するために使用されるクラス。これにより、Kafka Connect 設定によって設定されたデフォルト値がオーバーライドされます。たとえば、org.apache.kafka.connect.json.JsonConverter です。
value.converter
メッセージペイロードを Kafka 形式との間で変換するために使用されるクラス。これにより、Kafka Connect 設定によって設定されたデフォルト値がオーバーライドされます。たとえば、org.apache.kafka.connect.json.JsonConverter です。

さらに、シンクコネクターには以下のオプションの 1 つ以上を設定する必要があります。

topics
入力として使用されるトピックのカンマ区切りリスト。
topics.regex
入力として使用されるトピックの Java 正規表現。

その他のオプションについては、利用可能なコネクターのドキュメントを参照してください。

AMQ Streamsには、コネクタ構成ファイルの例が含まれています。AMQ Streamsのインストール・ディレクトリーにある config/connect-file-sink.properties および config/connect-file-source.properties を参照してください。

9.1.3. スタンドアロンモードでの Kafka Connect の実行

この手順では、スタンドアロンモードで Kafka Connect を設定し、実行する方法を説明します。

前提条件

  • インストールされ、実行されている AMQ Streams クラスター。

手順

  1. /opt/kafka/config/connect-standalone.properties Kafka Connect 設定ファイルを編集し、bootstrap.server が Kafka ブローカーを指すように設定します。以下に例を示します。

    bootstrap.servers=kafka0.my-domain.com:9092,kafka1.my-domain.com:9092,kafka2.my-domain.com:9092
  2. 設定ファイルで Kafka Connect を起動し、1 つ以上のコネクター設定を指定します。

    su - kafka
    /opt/kafka/bin/connect-standalone.sh /opt/kafka/config/connect-standalone.properties connector1.properties
    [connector2.properties ...]
  3. KafkaConnect が実行されていることを確認します。

       jcmd | grep ConnectStandalone

関連情報

9.2. 分散モードでの Kafka Connect

分散モードでは、Kafka Connect は 1 つまたは複数のワーカーノードで実行され、ワークロードはワーカーノード間で分散されます。コネクタープラグインとその設定は、HTTP REST インターフェイスを使用して管理します。

9.2.1. 分散モードでの Kafka Connect の設定

Kafka Connect をスタンドアロンモードで設定するには、config/connect-distributed.properties 設定ファイルを編集します。以下のオプションが最も重要です。

bootstrap.servers
Kafka へのブートストラップ接続として使用される Kafka ブローカーアドレスのリスト。たとえば、kafka0.my-domain.com:9092,kafka1.my-domain.com:9092,kafka2.my-domain.com:9092 です。
key.converter
メッセージキーを Kafka 形式との間で変換するために使用されるクラス。たとえば、org.apache.kafka.connect.json.JsonConverter です。
value.converter
メッセージペイロードを Kafka 形式との間で変換するために使用されるクラス。たとえば、org.apache.kafka.connect.json.JsonConverter です。
group.id
分散された Kafka Connect クラスターの名前。これは一意でなければならず、他のコンシューマーグループ ID と競合することはできません。デフォルト値は connect-cluster です。
config.storage.topic
コネクター設定の保存に使用される Kafka トピック。デフォルト値は connect-configs です。
offset.storage.topic
オフセットを保存するために使用される Kafka トピック。デフォルト値は connect-offset です。
status.storage.topic
ワーカーノードのステータスに使用される Kafka トピック。デフォルト値は connect-status です。

AMQ Streams には、分散モードの Kafka Connect の設定ファイル例が含まれています。AMQ Streams のインストールディレクトリーにある config/connect-distributed.properties を参照してください。

サポートされるすべての Kafka Connect 設定オプションの完全リストは、付録F Kafka Connect 設定パラメーター を参照してください。

コネクタープラグインは、ブートストラップアドレスを使用して Kafka ブローカーへのクライアント接続を開きます。これらの接続を設定するには、標準的な Kafka のプロデューサーとコンシューマーの設定オプションを使用し、producer. または consumer. プレフィックスを付けます。

Kafka プロデューサーおよびコンシューマーの設定に関する詳細は、以下を参照してください。

9.2.2. 分散 Kafka Connect でのコネクターの設定

HTTP REST インターフェイス

分散 Kafka Connect のコネクターは、HTTP REST インターフェイスを使用して設定されます。REST インターフェイスはデフォルトで 8083 番ポートをリッスンします。以下のエンドポイントをサポートします。

GET /connectors
既存のコネクターのリストを返します。
POST /connectors
コネクターを作成します。リクエストボディーは、コネクター設定が含まれる JSON オブジェクトである必要があります。
GET /connectors/<name>
特定のコネクターの情報を取得します。
GET /connectors/<name>/config
特定のコネクターの設定を取得します。
PUT /connectors/<name>/config
特定のコネクターの設定を更新します。
GET /connectors/<name>/status
特定のコネクターのステータスを取得します。
PUT /connectors/<name>/pause
コネクターとそのすべてのタスクを一時停止します。コネクターはメッセージの処理を停止します。
PUT /connectors/<name>/resume
一時停止されたコネクターを再開します。
POST /connectors/<name>/restart
コネクターに障害が発生した場合に、コネクターを再起動します。
DELETE /connectors/<name>
コネクターを削除します。
GET /connector-plugins
サポートされるすべてのコネクタープラグインのリストを取得します。

コネクター設定

ほとんどの設定オプションはコネクター固有で、コネクターのドキュメントに含まれています。以下のフィールドは、すべてのコネクターで共通しています。

name
コネクターの名前。特定の Kafka Connect インスタンス内で一意である必要があります。
connector.class
コネクタープラグインのクラス。たとえば、org.apache.kafka.connect.file.FileStreamSinkConnector です。
tasks.max
このコネクターによって使用されるタスクの最大数。タスクは、コネクターが作業を並列処理するために使用します。コネクターは、指定された数よりも少ないタスクを作成する場合があります。
key.converter
メッセージキーを Kafka 形式との間で変換するために使用されるクラス。これにより、Kafka Connect 設定によって設定されたデフォルト値がオーバーライドされます。たとえば、org.apache.kafka.connect.json.JsonConverter です。
value.converter
メッセージペイロードを Kafka 形式との間で変換するために使用されるクラス。これにより、Kafka Connect 設定によって設定されたデフォルト値がオーバーライドされます。たとえば、org.apache.kafka.connect.json.JsonConverter です。

さらに、シンクコネクターには、以下のオプションの 1 つを設定する必要があります。

topics
入力として使用されるトピックのカンマ区切りリスト。
topics.regex
入力として使用されるトピックの Java 正規表現。

その他のオプションについては、特定のコネクターのドキュメントを参照してください。

AMQ Streams には、コネクター設定ファイルのサンプルが含まれています。AMQ Streams インストールディレクトリーの config/connect-file-sink.properties および config/connect-file-source.properties にあります。

9.2.3. 分散 Kafka Connect の実行

この手順では、Kafka Connect を分散モードで設定および実行する方法を説明します。

前提条件

  • インストールされ、実行されている AMQ Streams クラスター。

クラスターの実行

  1. すべての Kafka Connect ワーカーノードで /opt/kafka/config/connect-distributed.properties Kafka Connect 設定ファイルを編集します。

    • bootstrap.server オプションを設定して、Kafka ブローカーを示すようにします。
    • group.id オプションを設定します。
    • config.storage.topic オプションを設定します。
    • offset.storage.topic オプションを設定します。
    • status.storage.topic オプションを設定します。

      以下に例を示します。

      bootstrap.servers=kafka0.my-domain.com:9092,kafka1.my-domain.com:9092,kafka2.my-domain.com:9092
      group.id=my-group-id
      config.storage.topic=my-group-id-configs
      offset.storage.topic=my-group-id-offsets
      status.storage.topic=my-group-id-status
  2. すべての Kafka Connect ワーカーノードで /opt/kafka/config/connect-distributed.properties Kafka Connect ワーカーを起動します。

    su - kafka
    /opt/kafka/bin/connect-distributed.sh /opt/kafka/config/connect-distributed.properties
  3. KafkaConnect が実行されていることを確認します。

    jcmd | grep ConnectDistributed

関連情報

9.2.4. コネクターの作成

この手順では、Kafka Connect REST API を使用して分散モードで Kafka Connect で使用するコネクタープラグインを作成する方法を説明します。

前提条件

  • 分散モードで実行する Kafka Connect インストール。

手順

  1. コネクター設定で JSON ペイロードを準備します。以下に例を示します。

    {
      "name": "my-connector",
      "config": {
      "connector.class": "org.apache.kafka.connect.file.FileStreamSinkConnector",
        "tasks.max": "1",
        "topics": "my-topic-1,my-topic-2",
        "file": "/tmp/output-file.txt"
      }
    }
  2. POST リクエストを <KafkaConnectAddress>:8083/connectors に送信してコネクターを作成します。以下の例では、curl を使用します。

    curl -X POST -H "Content-Type: application/json" --data @sink-connector.json http://connect0.my-domain.com:8083/connectors
  3. <KafkaConnectAddress>:8083/connectors に GET リクエストを送信して、コネクターがデプロイされたことを確認します。以下の例では、curl を使用します。

    curl http://connect0.my-domain.com:8083/connectors

9.2.5. コネクターの削除

この手順では、Kafka Connect REST API を使用して分散モードの Kafka Connect からコネクタープラグインを削除する方法を説明します。

前提条件

  • 分散モードで実行する Kafka Connect インストール。

コネクターの削除

  1. <KafkaConnectAddress>:8083/connectors/<ConnectorName>GET リクエストを送信して、コネクターが存在することを確認します。以下の例では、curl を使用します。

    curl http://connect0.my-domain.com:8083/connectors
  2. コネクターを削除するには、DELETE リクエストを <KafkaConnectAddress>:8083/connectors に送信します。以下の例では、curl を使用します。

    curl -X DELETE http://connect0.my-domain.com:8083/connectors/my-connector
  3. <KafkaConnectAddress>:8083/connectors に GET リクエストを送信して、コネクターがデプロイされたことを確認します。以下の例では、curl を使用します。

    curl http://connect0.my-domain.com:8083/connectors

9.3. コネクタープラグイン

AMQ Streams には以下のコネクタープラグインが含まれています。

FileStreamSink: Kafka トピックからデータを読み取り、ファイルに書き込みます。

FileStreamSource: ファイルからデータを読み取り、データを Kafka トピックに送信します。

必要に応じて、さらにコネクタープラグインを追加できます。Kafka Connect は起動時に、追加のコネクタープラグインを検索し、実行します。Kafka Connect がプラグインを検索するパスを定義するには、plugin.path configuration オプションを設定します。

plugin.path=/opt/kafka/connector-plugins,/opt/connectors

plugin.path 設定オプションには、コンマ区切りのパスのリストを含めることができます。

Kafka Connect を分散モードで実行する場合、プラグインはすべてのワーカーノードで利用可能でなければなりません。

9.4. コネクタープラグインの追加

この手順では、コネクタープラグインを追加する方法を説明します。

前提条件

  • インストールされ、実行されている AMQ Streams クラスター。

手順

  1. /opt/kafka/connector-plugins ディレクトリーを作成します。

    su - kafka
    mkdir /opt/kafka/connector-plugins
  2. /opt/kafka/config/connect-standalone.properties または /opt/kafka/config/connect-distributed.properties Kafka Connect 設定ファイルを編集し、plugin.path オプションを /opt/kafka/connector-plugins に設定します。以下に例を示します。

    plugin.path=/opt/kafka/connector-plugins
  3. コネクタープラグインを /opt/kafka/connector-plugins にコピーします。
  4. Kafka Connect ワーカーを起動または再起動します。

関連情報

第10章 AMQ Streams の MirrorMaker 2.0 との使用

MirrorMaker 2.0 は、データセンター内またはデータセンター全体の 2 台以上の Kafka クラスター間でデータを複製するために使用されます。

クラスター全体のデータレプリケーションでは、以下が必要な状況がサポートされます。

  • システム障害時のデータの復旧
  • 分析用のデータの集計
  • 特定のクラスターへのデータアクセスの制限
  • レイテンシーを改善するための特定場所でのデータのプロビジョニング
注記

MirrorMaker 2.0 には、以前のバージョンの MirrorMaker ではサポートされない機能があります。ただし、MirrorMaker 2.0 をレガシーモードで使用されるように設定 できます。

10.1. MirrorMaker 2.0 のデータレプリケーション

MirrorMaker 2.0 はソースの Kafka クラスターからメッセージを消費して、ターゲットの Kafka クラスターに書き込みます。

MirrorMaker 2.0 は以下を使用します。

  • ソースクラスターからデータを消費するソースクラスターの設定
  • データをターゲットクラスターに出力するターゲットクラスターの設定

MirrorMaker 2.0 は Kafka Connect フレームワークをベースとし、コネクター によってクラスター間のデータ転送が管理されます。MirrorMaker 2.0 の MirrorSourceConnector は、ソースクラスターからターゲットクラスターにトピックを複製します。

あるクラスターから別のクラスターにデータを ミラーリング するプロセスは非同期です。推奨されるパターンは、ソース Kafka クラスターとともにローカルでメッセージが作成され、ターゲットの Kafka クラスターの近くでリモートで消費されることです。

MirrorMaker 2.0 は、複数のソースクラスターで使用できます。

図10.1 2 つのクラスターにおけるレプリケーション

MirrorMaker 2.0 のレプリケーション

10.2. クラスターの設定

active/passive または active/active クラスター設定で MirrorMaker 2.0 を使用できます。

  • active/active 設定では、両方のクラスターがアクティブで、同じデータを同時に提供します。これは、地理的に異なる場所で同じデータをローカルで利用可能にする場合に便利です。
  • active/passive 設定では、アクティブなクラスターからのデータはパッシブなクラスターで複製され、たとえば、システム障害時のデータ復旧などでスタンバイ状態を維持します。

プロデューサーとコンシューマーがアクティブなクラスターのみに接続することを前提とします。

MirrorMaker 2.0 クラスターは、ターゲットの宛先ごとに必要です。

10.2.1. 双方向レプリケーション (active/active)

MirrorMaker 2.0 アーキテクチャーでは、active/active クラスター設定で双方向レプリケーションがサポートされます。

各クラスターは、source および remote トピックの概念を使用して、別のクラスターのデータを複製します。同じトピックが各クラスターに保存されるため、リモートトピックの名前がソースクラスターを表すように自動的に MirrorMaker 2.0 によって変更されます。元のクラスターの名前の先頭には、トピックの名前が追加されます。

図10.2 トピック名の変更

MirrorMaker 2.0 双方向アーキテクチャー

ソースクラスターにフラグを付けると、トピックはそのクラスターに複製されません。

remote トピックを介したレプリケーションの概念は、データの集約が必要なアーキテクチャーの設定に役立ちます。コンシューマーは、同じクラスター内でソースおよびリモートトピックにサブスクライブできます。これに個別の集約クラスターは必要ありません。

10.2.2. 一方向レプリケーション (active/passive)

MirrorMaker 2.0 アーキテクチャーでは、active/passive クラスター設定でー方向レプリケーションがサポートされます。

active/passive のクラスター設定を使用してバックアップを作成したり、データを別のクラスターに移行したりできます。この場合、リモートトピックの名前を自動的に変更したくないことがあります。

IdentityReplicationPolicyKafkaMirrorMaker2 リソースのソースコネクター設定に追加することで、名前の自動変更をオーバーライドできます。この設定が適用されると、トピックには元の名前が保持されます。

10.2.3. トピック設定の同期

トピック設定は、ソースクラスターとターゲットクラスター間で自動的に同期化されます。設定プロパティーを同期化することで、リバランスの必要性が軽減されます。

10.2.4. データの整合性

MirrorMaker 2.0 は、ソーストピックを監視し、設定変更をリモートトピックに伝播して、不足しているパーティションを確認および作成します。MirrorMaker 2.0 のみがリモートトピックに書き込みできます。

10.2.5. オフセットの追跡

MirrorMaker 2.0 では、内部トピックを使用してコンシューマーグループのオフセットを追跡します。

  • オフセット同期 トピックは、複製されたトピックパーティションのソースおよびターゲットオフセットをレコードメタデータからマッピングします。
  • チェックポイント トピックは、各コンシューマーグループの複製されたトピックパーティションのソースおよびターゲットクラスターで最後にコミットされたオフセットをマッピングします。

チェックポイント トピックのオフセットは、設定によって事前定義された間隔で追跡されます。両方のトピックは、フェイルオーバー時に正しいオフセットの位置からレプリケーションの完全復元を可能にします。

MirrorMaker 2.0 は、MirrorCheckpointConnector を使用して、オフセット追跡の チェックポイントを生成します。

10.2.6. 接続性チェック

ハートビート 内部トピックによって、クラスター間の接続性が確認されます。

ハートビート トピックは、ソースクラスターから複製されます。

ターゲットクラスターは、トピックを使用して以下を確認します。

  • クラスター間の接続を管理するコネクターが稼働しているかどうか
  • ソースクラスターが利用可能かどうか

MirrorMaker 2.0 は MirrorHeartbeatConnector を使用して、これらのチェックを実行する ハートビート を生成します。

10.3. ACL ルールの同期

AclAuthorizer が使用されている場合、ブローカーへのアクセスを管理する ACL ルールはリモートトピックにも適用されます。ソーストピックを読み取りできるユーザーは、そのリモートトピックを読み取りできます。

注記

OAuth 2.0 での承認は、このようなリモートトピックへのアクセスをサポートしません。

10.4. MirrorMaker 2.0 を使用した Kafka クラスター間でのデータの同期

MirrorMaker 2.0 を使用して、設定を介して Kafka クラスター間のデータを同期します。

以前のバージョンの MirrorMaker は、レガシーモードで MirrorMaker 2.0 を実行 することにより、引き続きサポートされます。

設定では以下を指定する必要があります。

  • 各 Kafka クラスター
  • TLS 認証を含む各クラスターの接続情報
  • レプリケーションのフローおよび方向

    • クラスター対クラスター
    • トピック対トピック
  • レプリケーションルール
  • コミットされたオフセット追跡間隔

この手順では、プロパティーファイルで設定を作成し、MirrorMaker スクリプトファイルを使用して接続を設定する際にプロパティーを渡し、MirrorMaker 2.0 を実装する方法を説明します。

注記

MirrorMaker 2.0 は Kafka Connect を使用して接続を確立し、クラスター間でデータを転送します。Kafka は、データの複製に MirrorMaker シンクおよびソースコネクターを提供します。MirrorMaker スクリプトの代わりにコネクターを使用する場合は、Kafka Connect クラスターでコネクターを設定する必要があります。詳細は、Apache Kafka のドキュメント を参照してください。

作業を開始する前に

設定プロパティーファイルの例は ./config/connect-mirror-maker.properties にあります。

前提条件

  • 複製している各 Kafka クラスターノードのホストに AMQ Streams がインストールされている必要がある。

手順

  1. テキストエディターでサンプルプロパティーファイルを開くか、新しいプロパティーファイルを作成し、ファイルを編集して接続情報と各 Kafka クラスターのレプリケーションフローを追加します。

    以下の例は、cluster-1 および cluster-2 の 2 つのクラスターを双方向に接続する設定を示しています。クラスター名は、clusters プロパティーで設定できます。

    clusters=cluster-1,cluster-2 1
    
    cluster-1.bootstrap.servers=<my-cluster>-kafka-bootstrap-<my-project>:443 2
    cluster-1.security.protocol=SSL 3
    cluster-1.ssl.truststore.password=<my-truststore-password>
    cluster-1.ssl.truststore.location=<path-to-truststore>/truststore.cluster-1.jks
    cluster-1.ssl.keystore.password=<my-keystore-password>
    cluster-1.ssl.keystore.location=<path-to-keystore>/user.cluster-1.p12
    
    cluster-2.bootstrap.servers=<my-cluster>-kafka-bootstrap-<my-project>:443 4
    cluster-2.security.protocol=SSL 5
    cluster-2.ssl.truststore.password=<my-truststore-password>
    cluster-2.ssl.truststore.location=<path-to-truststore>/truststore.cluster-2.jks
    cluster-2.ssl.keystore.password=<my-keystore-password>
    cluster-2.ssl.keystore.location=<path-to-keystore>/user.cluster-2.p12
    
    cluster-1->cluster-2.enabled=true 6
    cluster-1->cluster-2.topics=.* 7
    cluster-2->cluster-1.enabled=true 8
    cluster-2->cluster-1B->C.topics=.* 9
    
    replication.policy.separator=- 10
    sync.topic.acls.enabled=false 11
    refresh.topics.interval.seconds=60 12
    refresh.groups.interval.seconds=60 13
    1
    各 Kafka クラスターは、そのエイリアスで識別されます。
    2
    ブートストラップアドレス およびポート 443 を使用した、cluster-1 の接続情報。両方のクラスターはポート 443 を使用し、OpenShift Routes を使用して Kafka に接続します。
    3
    ssl. プロパティーは、cluster-1 の TLS 設定を定義します。
    4
    cluster-2 の接続情報。
    5
    ssl. プロパティーは、cluster-2 の TLS 設定を定義します。
    6
    cluster-1 クラスターから cluster-2 クラスターへのレプリケーションフローが有効になりました。
    7
    すべてのトピックを cluster-1 クラスターから cluster-2 クラスターに複製します。
    8
    cluster-2 クラスターから cluster-1 クラスターへのレプリケーションフローが有効になりました。
    9
    すべてのトピックを cluster-2 クラスターから cluster-1 クラスターに複製します。
    10
    リモートトピック名の変更に使用する区切り文字を定義します。
    11
    有効にすると、同期されたトピックに ACL が適用されます。デフォルトは false です。
    12
    新しいトピックの同期をチェックする間隔。
    13
    新しいコンシューマーグループの同期をチェックする間隔。
  2. (オプション)必要に応じて、リモートトピックの名前の自動変更を上書きするポリシーを追加します。その名前の前にソースクラスターの名前を追加するのではなく、トピックが元の名前を保持します。

    このオプションの設定は、active/passive バックアップおよびデータ移行に使用されます。

    replication.policy.class=io.strimzi.kafka.connect.mirror.IdentityReplicationPolicy
  3. ターゲットクラスターで ZooKeeper および Kafka を起動します。

    su - kafka
    /opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties
    /opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties
  4. プロパティーファイルで定義したクラスター接続設定およびレプリケーションポリシーで MirrorMaker を起動します。

    /opt/kafka/bin/connect-mirror-maker.sh /config/connect-mirror-maker.properties

    MirrorMaker はクラスター間の接続を設定します。

  5. ターゲットクラスターごとに、トピックが複製されていることを確認します。

    /bin/kafka-topics.sh --bootstrap-server <BrokerAddress> --list

10.5. レガシーモードでの MirrorMaker 2.0 の使用

この手順では、MirrorMaker 2.0 をレガシーモードで使用する設定方法を説明します。レガシーモードは、以前のバージョンの MirrorMaker をサポートします。

MirrorMaker スクリプト /opt/kafka/bin/kafka-mirror-maker.sh は、レガシーモードで MirrorMaker 2.0 を実行できます。

前提条件

現時点でレガシーバージョンの MirrorMaker と使用しているプロパティーファイルが必要。

  • /opt/kafka/config/consumer.properties
  • /opt/kafka/config/producer.properties

手順

  1. MirrorMakerの consumer.propertiesproducer.properties ファイルを編集して、MirrorMaker 2.0 の機能をオフにします。

    以下に例を示します。

    replication.policy.class=org.apache.kafka.mirror.LegacyReplicationPolicy 1
    
    refresh.topics.enabled=false 2
    refresh.groups.enabled=false
    emit.checkpoints.enabled=false
    emit.heartbeats.enabled=false
    sync.topic.configs.enabled=false
    sync.topic.acls.enabled=false
    1
    MirrorMaker の以前のバージョンをエミュレートします。
    2
    内部 チェックポイントハートビート トピックなど、MirrorMaker 2.0 の機能が無効になりました。
  2. 変更を保存し、以前のバージョンの MirrorMaker で使用していたプロパティーファイルで MirrorMaker を再起動します。

    su - kafka /opt/kafka/bin/kafka-mirror-maker.sh \
    --consumer.config /opt/kafka/config/consumer.properties \
    --producer.config /opt/kafka/config/producer.properties \
    --num.streams=2

    consumer プロパティーはソースクラスターの設定を提供し、producer プロパティーはターゲットクラスターの設定を提供します。

    MirrorMaker はクラスター間の接続を設定します。

  3. ターゲットクラスターで ZooKeeper および Kafka を起動します。

    su - kafka
    /opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties
    su - kafka
    /opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties
  4. ターゲットクラスターごとに、トピックが複製されていることを確認します。

    /bin/kafka-topics.sh --bootstrap-server <BrokerAddress> --list

第11章 Kafka クライアント

kafka-clients JAR ファイルには、Kafka Producer および Consumer API と、Kafka AdminClient API が含まれています。

  • Producer API は、アプリケーションが Kafka ブローカーにデータを送信できるようにします。
  • Consumer API は、アプリケーションが Kafka ブローカーからデータを消費できるようにします。
  • AdminClient API は、トピック、ブローカー、およびその他のコンポーネントなどの Kafka クラスターを管理するための機能を提供します。

11.1. Maven プロジェクトへの依存関係としての Kafka クライアントの追加

この手順では、AMQ Streams Java クライアントを Maven プロジェクトに依存関係として追加する方法を説明します。

前提条件

  • 既存の pom.xml を持つ Maven プロジェクト。

手順

  1. Red Hat Maven リポジトリーを pom.xml ファイルの <repositories> セクションに追加します。

    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    
        <!-- ... -->
    
        <repositories>
            <repository>
                <id>redhat-maven</id>
                <url>https://maven.repository.redhat.com/ga/</url>
            </repository>
        </repositories>
    
        <!-- ... -->
    
    </project>
  2. クライアントを pom.xml ファイルの <dependencies> セクションに追加します。

    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    
        <!-- ... -->
    
        <dependencies>
            <dependency>
                <groupId>org.apache.kafka</groupId>
                <artifactId>kafka-clients</artifactId>
                <version>2.6.0.redhat-00004</version>
            </dependency>
        </dependencies>
    
        <!-- ... -->
    </project>
  3. Maven プロジェクトをビルドします。

第12章 Kafka Streams API の概要

Kafka Streams API を使用すると、アプリケーションは 1 つ以上の入力ストリームからデータを受け取り、マッピング、フィルタリング、または結合などの複雑な操作を実行し、結果を 1 つ以上の出力ストリームに書き込むことができます。これは、Red Hat Maven リポジトリーで利用可能な kafka-streams JAR パッケージの一部です。

12.1. Maven プロジェクトへの依存関係としての Kafka Streams API の追加

この手順では、AMQ Streams Java クライアントを Maven プロジェクトに依存関係として追加する方法を説明します。

前提条件

  • 既存の pom.xml を持つ Maven プロジェクト。

手順

  1. Red Hat Maven リポジトリーを pom.xml ファイルの <repositories> セクションに追加します。

    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    
        <!-- ... -->
    
        <repositories>
            <repository>
                <id>redhat-maven</id>
                <url>https://maven.repository.redhat.com/ga/</url>
            </repository>
        </repositories>
    
        <!-- ... -->
    
    </project>
  2. pom.xml ファイルの <dependencies> セクションに kafka-streams を追加します。

    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    
        <!-- ... -->
    
        <dependencies>
            <dependency>
                <groupId>org.apache.kafka</groupId>
                <artifactId>kafka-streams</artifactId>
                <version>2.6.0.redhat-00004</version>
            </dependency>
        </dependencies>
    
        <!-- ... -->
    </project>
  3. Maven プロジェクトをビルドします。

第13章 Kafka Bridge

本章では、AMQ Streams Kafka Bridge on Red Hat Enterprise Linux について概説し、その REST API を使用して AMQ Streams と対話するためのサポートをします。ローカル環境で Kafka Bridge を試すには、本章で後述する 「Kafka Bridge クイックスタート」 を参照してください。

関連情報

13.1. Kafka Bridge の概要

Kafka Bridge では、HTTP ベースのクライアントと Kafka クラスターとの対話を可能にする RESTful インターフェイスが提供されます。また、クライアントアプリケーションが Kafka プロトコルを変換する必要なく、AMQ Streams で Web API コネクションの利点を活用できます。

API には consumerstopics の 2 つの主なリソースがあります。これらのリソースは、Kafka クラスターでコンシューマーおよびプロデューサーと対話するためにエンドポイント経由で公開され、アクセスが可能になります。リソースと関係があるのは Kafka ブリッジのみで、Kafka に直接接続されたコンシューマーやプロデューサーとは関係はありません。

HTTP 要求

Kafka Bridge は、以下の方法で Kafka クラスターへの HTTP 要求をサポートします。

  • トピックにメッセージを送信する。
  • トピックからメッセージを取得する。
  • トピックのパーティションリストを取得する。
  • コンシューマーを作成および削除する。
  • コンシューマーをトピックにサブスクライブし、このようなトピックからメッセージを受信できるようにする。
  • コンシューマーがサブスクライブしているトピックの一覧を取得する。
  • トピックからコンシューマーのサブスクライブを解除する。
  • パーティションをコンシューマーに割り当てる。
  • コンシューマーオフセットの一覧をコミットする。
  • パーティションで検索して、コンシューマーが最初または最後のオフセットの位置、または指定のオフセットの位置からメッセージを受信できるようにする。

上記の方法で、JSON 応答と HTTP 応答コードのエラー処理を行います。メッセージは JSON またはバイナリー形式で送信できます。

クライアントは、ネイティブの Kafka プロトコルを使用する必要なくメッセージを生成して使用できます。

AMQ Streams のインストールと同様に、Red Hat Enterprise Linux にインストールするために Kafka Bridge ファイルをダウンロードできます。「Kafka Bridge アーカイブのダウンロード」 を参照してください。

KafkaBridge リソースのホストおよびポートの設定に関する詳細は、「Kafka Bridge プロパティーの設定」 を参照してください。

13.1.1. 認証および暗号化

HTTP クライアントと Kafka Bridge 間の認証および暗号化はまだサポートされていません。そのため、クライアントから Kafka Bridge に送信されるリクエストは以下のようになります。

  • 暗号化されず、HTTPS ではなく HTTP を使用する必要がある。
  • 認証なしで送信される。

Kafka Bridge と Kafka クラスターとの間で、TLS または SASL ベースの認証 を設定できます。

プロパティーファイル を使用して、認証用に Kafka Bridge を設定します。

13.1.2. Kafka Bridge への要求

データ形式と HTTP ヘッダーを指定し、有効な要求が Kafka Bridge に送信されるようにします。

API 要求および応答本文は、常に JSON としてエンコードされます。

13.1.2.1. コンテンツタイプヘッダー

すべてのリクエストに対して、Content-Type のヘッダーを提出する必要があります。唯一の例外は、POST リクエストボディが空の場合で、Content-Type ヘッダーを追加するとリクエストが失敗します。

コンシューマー操作 (/consumers エンドポイント) とプロデューサー操作 (/topics エンドポイント) では、異なる Content-Type ヘッダーが必要です。

コンシューマー操作の Content-Type ヘッダー

埋め込まれたデータ形式にかかわらず、コンシューマー操作の POST リクエストは、リクエストボディーにデータが含まれている場合に、以下の Content-Type ヘッダーを提供する必要があります。

Content-Type: application/vnd.kafka.v2+json

プロデューサー操作の Content-Type ヘッダー

プロデューサー操作を行う場合に、POST 要求には、生成されるメッセージの 埋め込みデータ形式 を示す Content-Type ヘッダーを指定する必要があります。これは json または binary のいずれかになります。

表13.1 データフォーマットの Content-Type ヘッダー
埋め込みデータ形式Content-Type ヘッダー

JSON

Content-Type: application/vnd.kafka.json.v2+json

バイナリー

Content-Type: application/vnd.kafka.binary.v2+json

次のセクションで説明されているように、埋め込みデータ形式はコンシューマーごとに設定されます。

POST 要求の本文が空の場合は、Content-Type設定しないでください。空の本文を使用して、デフォルト値のコンシューマーを作成できます。

13.1.2.2. 埋め込みデータ形式

埋め込みデータ形式は、Kafka メッセージが Kafka Bridge によりプロデューサーからコンシューマーに HTTP で送信される際の形式です。サポートされる埋め込みデータ形式には、JSON またはバイナリーの 2 つがサポートされます。

/consumers/groupid エンドポイントを使用してコンシューマーを作成する場合、POST リクエスト本文で JSON またはバイナリーいずれかの埋め込みデータ形式を指定する必要があります。これは、以下の例のようにリクエストボディーの format フィールドで指定します。

{
  "name": "my-consumer",
  "format": "binary", 1
...
}
1
バイナリー埋め込みデータ形式。

コンシューマーの埋め込みデータ形式が指定されていない場合は、バイナリー形式が設定されます。

コンシューマーの作成時に指定する埋め込みデータ形式は、コンシューマーが消費する Kafka メッセージのデータ形式と一致する必要があります。

バイナリー埋め込みデータ形式を指定する場合は、以降のプロデューサー要求で、要求本文にバイナリーデータが Base64 でエンコードされた文字列として含まれる必要があります。たとえば、POST リクエストを /topics/topicname エンドポイントに対して作成してメッセージを送信する場合、value は Base64 でエンコードする必要があります。

{
  "records": [
    {
      "key": "my-key",
      "value": "ZWR3YXJkdGhldGhyZWVsZWdnZWRjYXQ="
    },
  ]
}

プロデューサー要求には、埋め込みデータ形式に対応する Content-Type ヘッダーも含まれる必要があります (例: Content-Type: application/vnd.kafka.binary.v2+json)。

13.1.2.3. メッセージの形式

/topics エンドポイントを使用してメッセージを送信する場合は、records パラメーターの要求本文にメッセージペイロードを入力します。

records パラメーターには、以下のオプションフィールドを含めることができます。

  • Message key
  • Message value
  • Destination partition
  • Message headers

/topicsへのPOST 要求の例

curl -X POST \
  http://localhost:8080/topics/my-topic \
  -H 'content-type: application/vnd.kafka.json.v2+json' \
  -d '{
    "records": [
        {
            "key": "my-key",
            "value": "sales-lead-0001"
            "partition": 2
            "headers": [
              {
                "key": "key1",
                "value": "QXBhY2hlIEthZmthIGlzIHRoZSBib21iIQ==" 1
              }
            ]
        },
    ]
}'

1
バイナリー形式のヘッダー値。Base64 としてエンコードされます。
13.1.2.4. Accept ヘッダー

コンシューマーを作成したら、以降のすべての GET 要求には Accept ヘッダーが以下のような形式で含まれる必要があります。

Accept: application/vnd.kafka.embedded-data-format.v2+json

embedded-data-formatjson または binary です。

たとえば、サブスクライブされたコンシューマーのレコードを JSON 埋め込みデータ形式で取得する場合、この Accept ヘッダーが含まれるようにします。

Accept: application/vnd.kafka.json.v2+json

13.1.3. Kafka Bridge のロガーの設定

AMQ Streams Kafka ブリッジを使用すると、関連する OpenAPI 仕様で定義される操作ごとに異なるログレベルを設定できます。

操作にはそれぞれ、対応の API エンドポイントがあり、このエンドポイントを通して、ブリッジが HTTP クライアントから要求を受信します。各エンドポイントのログレベルを変更すると、受信および送信 HTTP 要求に関する詳細なログ情報を作成できます。

ロガーは log4j.properties ファイルで定義されます。このファイルには healthy および ready エンドポイントの以下のデフォルト設定が含まれています。

log4j.logger.http.openapi.operation.healthy=WARN, out
log4j.additivity.http.openapi.operation.healthy=false
log4j.logger.http.openapi.operation.ready=WARN, out
log4j.additivity.http.openapi.operation.ready=false

その他すべての操作のログレベルは、デフォルトで INFO に設定されます。ロガーは以下のようにフォーマットされます。

log4j.logger.http.openapi.operation.<operation-id>

<operation-id> は、特定の操作の識別子です。以下は、OpenAPI 仕様によって定義される操作の一覧です。

  • createConsumer
  • deleteConsumer
  • subscribe
  • unsubscribe
  • poll
  • assign
  • commit
  • send
  • sendToPartition
  • seekToBeginning
  • seekToEnd
  • seek
  • healthy
  • ready
  • openapi

13.1.4. Kafka Bridge API リソース

リクエストやレスポンスの例などを含む REST API エンドポイントおよび説明の完全リストは、「Kafka Bridge API reference」を参照してください。

13.1.5. Kafka Bridge アーカイブのダウンロード

AMQ Streams Kafka Bridge の zip 形式のディストリビューションは、Red Hat の Web サイトからダウンロードできます。

手順

  • カスタマーポータル から、最新バージョンの Red Hat AMQ Streams Kafka Bridge アーカイブをダウンロードします。

13.1.6. Kafka Bridge プロパティーの設定

この手順では、AMQ Streams Kafka Bridge によって使用される Kafka および HTTP 接続プロパティーの設定方法を説明します。

Kafka 関連のプロパティーに適切な接頭辞を使用して、他の Kafka クライアントと同様に Kafka Bridge を設定します。

  • kafka. は、サーバー接続やセキュリティーなど、プロデューサーとコンシューマーに適用される一般的な設定用です。
  • kafka.consumer. は、コンシューマーにのみ渡されるコンシューマー固有の設定用です。
  • kafka.producer. は、プロデューサーにのみ渡されるプロデューサー固有の設定用です。

HTTP プロパティーは、Kafka クラスターへの HTTP アクセスを有効にする他に、CPRS (Cross-Origin Resource Sharing) により Kafka Bridge のアクセス制御を有効化または定義する機能を提供します。CORS は、複数のオリジンから指定のリソースにブラウザーでアクセスできるようにする HTTP メカニズムです。CORS を設定するには、許可されるリソースオリジンのリストと、それらにアクセスする HTTP メソッドを定義します。リクエストの追加の HTTP ヘッダーには Kafka クラスターへのアクセスが許可されるオリジンが記述 されています。

手順

  1. AMQ Streams Kafka Bridge のインストールアーカイブにある application.properties ファイルを編集します。

    プロパティーファイルを使用して、Kafka および HTTP 関連のプロパティーを指定し、分散トレースを有効にします。

    1. Kafka コンシューマーおよびプロデューサーに固有のプロパティーなど、標準の Kafka 関連のプロパティーを設定します。

      以下を使用します。

      • kafka.bootstrap.servers: Kafkaクラスターへのホスト/ポート接続を定義する。
      • kafka.producer.acks: HTTP クライアントに確認を提供する。
      • kafka.consumer.auto.offset.reset: Kafka のオフセットのリセットを管理する方法を決定する。

        Kafka プロパティーの設定に関する詳細は、Apache Kafka の Web サイトを参照してください。

    2. Kafka クラスターへの HTTP アクセスを有効にするために HTTP 関連のプロパティーを設定します。

      以下に例を示します。

      http.enabled=true
      http.host=0.0.0.0
      http.port=8080 1
      http.cors.enabled=true 2
      http.cors.allowedOrigins=https://strimzi.io 3
      http.cors.allowedMethods=GET,POST,PUT,DELETE,OPTIONS,PATCH 4
      1
      8080 番ポートで Kafka Bridge をリッスンするデフォルトの HTTP 設定。
      2
      CORS を有効にするには true に設定します。
      3
      許可される CORS オリジンのコンマ区切りリスト。URL または Java 正規表現を使用できます。
      4
      CORS で許可される HTTP メソッドのコンマ区切りリスト。
    3. 分散トレースを有効または無効にします。

      bridge.tracing=jaeger

      分散トレースを有効にするため、プロパティーからコードコメントを削除します。

13.1.7. Kafka Bridge のインストール

以下の手順に従って、AMQ Streams Kafka Bridge on Red Hat Enterprise Linux をインストールします。

手順

  1. AMQ Streams KafkaBridge インストールアーカイブを任意のディレクトリーに解凍します (まだ解答していない場合)。
  2. 設定プロパティーをパラメーターとして使用して、Kafka Bridge スクリプトを実行します。

    以下に例を示します。

    ./bin/kafka_bridge_run.sh --config-file=_path_/configfile.properties
  3. インストールが成功したことをログで確認します。

    HTTP-Kafka Bridge started and listening on port 8080
    HTTP-Kafka Bridge bootstrap servers localhost:9092

13.2. Kafka Bridge クイックスタート

このクイックスタートを使用して、AMQ Streams Kafka Bridge on Red Hat Enterprise Linux を試行します。以下の方法について説明します。

  • Kafka Bridge のインストール
  • Kafka クラスターのトピックおよびパーティションへのメッセージを生成する。
  • Kafka Bridge コンシューマーを作成する。
  • 基本的なコンシューマー操作を実行する (たとえば、コンシューマーをトピックにサブスクライブする、生成したメッセージを取得するなど)。

このクイックスタートでは、HTTP 要求はターミナルにコピーアンドペーストできる curl コマンドを使用します。

前提条件を確認し、本章に指定されている順序でタスクを行うようにしてください。

データ形式について

このクイックスタートでは、バイナリーではなく JSON 形式でメッセージを生成および消費します。リクエスト例で使用されるデータ形式および HTTP ヘッダーの詳細は、「認証および暗号化」 を参照してください。

13.2.1. Kafka Bridge のローカルデプロイメント

AMQ Streams Kafka Bridge のインスタンスをホストにデプロイします。インストールアーカイブで提供される application.properties ファイルを使用して、デフォルトの設定を適用します。

手順

  1. application.properties ファイルを開き、デフォルトの HTTP related settings が定義されていることを確認します。

    http.enabled=true
    http.host=0.0.0.0
    http.port=8080

    これにより、Kafka Bridge がポート 8080 でリクエストをリッスンするように設定されます。

  2. 設定プロパティーをパラメーターとして使用して、Kafka Bridge スクリプトを実行します。

    ./bin/kafka_bridge_run.sh --config-file=<path>/application.properties

13.2.2. トピックおよびパーティションへのメッセージの作成

トピック エンドポイントを使用して、トピックへのメッセージを JSON 形式で生成します。

以下のように、メッセージの宛先パーティションをリクエストボディーに指定できます。partitions エンドポイントは、全メッセージの単一の宛先パーティションをパスパラメーターとして指定する代替方法を提供します。

手順

  1. kafka-topics.sh ユーティリティーを使用してトピックを作成します。

    bin/kafka-topics.sh --bootstrap-server localhost:9092 --create --topic bridge-quickstart-topic --partitions 3 --replication-factor 1 --config retention.ms=7200000 --config segment.bytes=1073741824

    3 つのパーティションを指定します。

  2. トピックが作成されたことを確認します。

    bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic bridge-quickstart-topic
  3. Kafka Bridge を使用して、作成したトピックに 3 つのメッセージを生成します。

    curl -X POST \
      http://localhost:8080/topics/bridge-quickstart-topic \
      -H 'content-type: application/vnd.kafka.json.v2+json' \
      -d '{
        "records": [
            {
                "key": "my-key",
                "value": "sales-lead-0001"
            },
            {
                "value": "sales-lead-0002",
                "partition": 2
            },
            {
                "value": "sales-lead-0003"
            }
        ]
    }'
    • sales-lead-0001 は、キーのハッシュに基づいてパーティションに送信されます。
    • sales-lead-0002 は、パーティション 2 に直接送信されます。
    • sales-lead-0003 は、ラウンドロビン方式を使用して bridge-quickstart-topic トピックのパーティションに送信されます。
  4. リクエストが正常に行われると、Kafka Bridge は offsets アレイを 200 (OK) コードと application/vnd.kafka.v2+jsoncontent-type ヘッダーとともに返します。各メッセージで、offsets 配列は以下を記述します。

    • メッセージが送信されたパーティション。
    • パーティションの現在のメッセージオフセット。

      応答の例

      #...
      {
        "offsets":[
          {
            "partition":0,
            "offset":0
          },
          {
            "partition":2,
            "offset":0
          },
          {
            "partition":0,
            "offset":1
          }
        ]
      }

次のステップ

トピックおよびパーティションへのメッセージを作成したら、Kafka Bridge コンシューマーを作成します

関連情報

13.2.3. Kafka Bridge コンシューマーの作成

Kafka クラスターで何らかのコンシューマー操作を実行する前に、consumers エンドポイントを使用して最初にコンシューマーを作成する必要があります。コンシューマーは Kafka Bridge コンシューマー と呼ばれます。

手順

  1. bridge-quickstart-consumer-group という名前の新しいコンシューマーグループに Kafka Bridge コンシューマーを作成します。

    curl -X POST http://localhost:8080/consumers/bridge-quickstart-consumer-group \
      -H 'content-type: application/vnd.kafka.v2+json' \
      -d '{
        "name": "bridge-quickstart-consumer",
        "auto.offset.reset": "earliest",
        "format": "json",
        "enable.auto.commit": false,
        "fetch.min.bytes": 512,
        "consumer.request.timeout.ms": 30000
      }'
    • コンシューマーには bridge-quickstart-consumer という名前を付け、埋め込みデータ形式は json として設定します。
    • コンシューマーはログへのオフセットに自動でコミットしません。これは、enable.auto.commitfalse に設定されているからです。このクイックスタートでは、オフセットを後で手作業でコミットします。

      注記

      リクエストボディーにコンシューマー名を指定しない場合、Kafka Bridge はランダムなコンシューマー名を生成します。

      リクエストが正常に行われると、Kafka Bridge はレスポンス本文でコンシューマー ID (instance_id) とベース URL (base_uri) を 200 (OK) コードとともに返します。

      応答例

      #...
      {
        "instance_id": "bridge-quickstart-consumer",
        "base_uri":"http://<bridge-name>-bridge-service:8080/consumers/bridge-quickstart-consumer-group/instances/bridge-quickstart-consumer"
      }

  2. ベース URL (base_uri) をコピーし、このクイックスタートの他のコンシューマー操作で使用します。

次のステップ

上記で作成した Kafka Bridge コンシューマーをトピックにサブスクライブできます

関連情報

13.2.4. Kafka Bridge コンシューマーのトピックへのサブスクライブ

subscription エンドポイントを使用して、Kafka Bridge コンシューマーを 1 つ以上のトピックにサブスクライブします。サブスクライブすると、コンシューマーはトピックに生成されたすべてのメッセージの受信を開始します。

手順

  • 前述の「トピックおよびパーティションへのメッセージの作成」の手順ですでに作成した bridge-quickstart-topic トピックに、コンシューマーをサブスクライブします。

    curl -X POST http://localhost:8080/consumers/bridge-quickstart-consumer-group/instances/bridge-quickstart-consumer/subscription \
      -H 'content-type: application/vnd.kafka.v2+json' \
      -d '{
        "topics": [
            "bridge-quickstart-topic"
        ]
    }'

    topics アレイには、上述のような単一のトピック、または複数のトピックを含めることができます。正規表現に一致する複数のトピックにコンシューマーをサブスクライブする場合は、topics 配列の代わりに topic_pattern 文字列を使用できます。

    リクエストが正常に行われると、Kafka Bridge によって 204 No Content コードのみが返されます。

次のステップ

Kafka Bridge コンシューマーをトピックにサブスクライブしたら、コンシューマーからメッセージを取得できます。

関連情報

13.2.5. Kafka Bridge コンシューマーからの最新メッセージの取得

records エンドポイントからデータを要求して、Kafka Bridge コンシューマーから最新のメッセージを取得します。実稼働環境では、HTTP クライアントはこのエンドポイントを繰り返し (ループで) 呼び出すことができます。

手順

  1. 「トピックおよびパーティションへのメッセージの生成」の説明に従い、Kafka Bridge コンシューマーに新たなメッセージを生成します。
  2. GET 要求を records エンドポイントに送信します。

    curl -X GET http://localhost:8080/consumers/bridge-quickstart-consumer-group/instances/bridge-quickstart-consumer/records \
      -H 'accept: application/vnd.kafka.json.v2+json'

    Kafka Bridge コンシューマーを作成し、サブスクライブした後に、最初の GET リクエストによって空のレスポンスが返されます。これは、ポーリング操作がリバランスプロセスをトリガーしてパーティションを割り当てるためです。

  3. 手順 2 を繰り返し、Kafka Bridge コンシューマーからメッセージを取得します。

    Kafka Bridge は、レスポンス本文でメッセージのアレイ (トピック名、キー、値、パーティション、オフセットの記述) を 200 (OK) コードとともに返します。メッセージはデフォルトで最新のオフセットから取得されます。

    HTTP/1.1 200 OK
    content-type: application/vnd.kafka.json.v2+json
    #...
    [
      {
        "topic":"bridge-quickstart-topic",
        "key":"my-key",
        "value":"sales-lead-0001",
        "partition":0,
        "offset":0
      },
      {
        "topic":"bridge-quickstart-topic",
        "key":null,
        "value":"sales-lead-0003",
        "partition":0,
        "offset":1
      },
    #...
    注記

    空のレスポンスが返される場合は、「トピックおよびパーティションへのメッセージの生成」の説明に従い、コンシューマーに対して追加のレコードを生成し、メッセージの取得を再試行します。

次のステップ

Kafka Bridge コンシューマーからメッセージを取得したら、ログへのオフセットをコミットします。

関連情報

13.2.6. ログへのオフセットのコミット

offsets エンドポイントを使用して、Kafka Bridge コンシューマーによって受信されるすべてのメッセージに対して、手動でオフセットをログにコミットします。この操作が必要なのは、前述の「Kafka Bridge コンシューマーの作成」で作成した Kafka Bridge コンシューマー が enable.auto.commit の設定で false に指定されているからです。

手順

  • bridge-quickstart-consumer のオフセットをログにコミットします。

    curl -X POST http://localhost:8080/consumers/bridge-quickstart-consumer-group/instances/bridge-quickstart-consumer/offsets

    要求本文は送信されないので、オフセットはコンシューマーによって受信されたすべてのレコードに対してコミットされます。この代わりに、リクエスト本文に、オフセットをコミットするトピックおよびパーティションを指定するアレイ (OffsetCommitSeekList) を含めることができます。

    リクエストが正常に行われると、Kafka Bridge によって 204 No Content コードのみが返されます。

次のステップ

オフセットをログにコミットしたら、オフセットをシークのエンドポイントを試行します。

関連情報

13.2.7. パーティションのオフセットのシーク

positions エンドポイントを使用して、Kafka Bridge コンシューマーを設定し、パーティションのメッセージを特定のオフセットから取得し、さらに最新のオフセットから取得します。これは Apache Kafka では、シーク操作と呼ばれます。

手順

  1. quickstart-bridge-topic トピックで、パーティション 0 の特定のオフセットをシークします。

    curl -X POST http://localhost:8080/consumers/bridge-quickstart-consumer-group/instances/bridge-quickstart-consumer/positions \
      -H 'content-type: application/vnd.kafka.v2+json' \
      -d '{
        "offsets": [
            {
                "topic": "bridge-quickstart-topic",
                "partition": 0,
                "offset": 2
            }
        ]
    }'

    リクエストが正常に行われると、Kafka Bridge によって 204 No Content コードのみが返されます。

  2. GET 要求を records エンドポイントに送信します。

    curl -X GET http://localhost:8080/consumers/bridge-quickstart-consumer-group/instances/bridge-quickstart-consumer/records \
      -H 'accept: application/vnd.kafka.json.v2+json'

    Kafka Bridge は、シークしたオフセットからのメッセージを返します。

  3. 同じパーティションの最後のオフセットをシークし、デフォルトのメッセージ取得動作を復元します。この時点で、positions/end エンドポイントを使用します。

    curl -X POST http://localhost:8080/consumers/bridge-quickstart-consumer-group/instances/bridge-quickstart-consumer/positions/end \
      -H 'content-type: application/vnd.kafka.v2+json' \
      -d '{
        "partitions": [
            {
                "topic": "bridge-quickstart-topic",
                "partition": 0
            }
        ]
    }'

    リクエストが正常に行われると、Kafka Bridge によって別の 204 No Content コードが返されます。

注記

また、positions/beginning エンドポイントを使用して、1 つ以上のパーティションの最初のオフセットをシークすることもできます。

次のステップ

このクイックスタートでは、AMQ Streams Kafka Bridge を使用して Kafka クラスターの一般的な操作をいくつか実行しました。これで、すでに作成した Kafka Bridge コンシューマーを削除 できます。

関連情報

13.2.8. Kafka Bridge コンシューマーの削除

最後に、このクイックスタートを通して使用した Kafa Bridge コンシューマーを削除します。

手順

  • DELETE リクエストを instances エンドポイントに送信し、Kafka Bridge コンシューマーを削除します。

    curl -X DELETE http://localhost:8080/consumers/bridge-quickstart-consumer-group/instances/bridge-quickstart-consumer

    リクエストが正常に行われると、Kafka Bridge によって 204 No Content コードのみが返されます。

関連情報

第14章 Kerberos(GSSAPI)認証の使用

AMQ Streams は、Kafka クラスターへの安全なシングルサインオンアクセスのために、Kerberos (GSSAPI) 認証プロトコルの使用をサポートします。GSSAPI は、Kerberos 機能の API ラッパーで、基盤の実装の変更からアプリケーションを保護します。

Kerberos は、対称暗号化と信頼できるサードパーティーの Kerberos Key Distribution Centre(KDC)を使用して、クライアントとサーバーが相互に認証できるようにするネットワーク認証システムです。

14.1. Kerberos (GSSAPI) 認証を使用するための AMQ Streams の設定

この手順では、Kafka クライアントが Kerberos (GSSAPI) 認証を使用して Kafka および ZooKeeper にアクセスできるように AMQ Streams を設定する方法を説明します。

この手順では、Kerberos krb5 リソースサーバーが Red Hat Enterprise Linux ホストに設定されていることを前提としています。

この手順では、例を用いて以下の設定方法を説明します。

  1. サービスプリンシパル
  2. Kerberos ログインを使用する Kafka ブローカー
  3. Kerberos ログインを使用するための ZooKeeper
  4. Kerberos 認証を使用して Kafka にアクセスするためのプロデューサーおよびコンシューマークライアント

この手順では、単一のホストでの単一の ZooKeeper および Kafka インストールの Kerberos 設定について説明し、プロデューサーおよびコンシューマークライアントの追加設定についても説明します。

前提条件

Kafka および ZooKeeper が Kerberos クレデンシャルを認証および承認するように設定できるようにするには、以下が必要です。

  • Kerberos サーバーへのアクセス
  • 各 Kafka ブローカーホストの Kerberos クライアント

Kerberos サーバー、およびブローカーホストのクライアントを設定する手順の詳細は、example Kerberos on RHEL set up configuration を参照してください。

Kerberos のデプロイ方法は、お使いのオペレーティングシステムによって異なります。Red Hat は、Red Hat Enterprise Linux で Kerberos を設定する際に Identity Management(IdM)を使用することを推奨します。Oracle または IBM JDK のユーザーは、Java Cryptography Extension(JCE)をインストールする必要があります。

認証用のサービスプリンシパルの追加

Kerberos サーバーから、ZooKeeper、Kafka ブローカー、Kafka プロデューサーおよびコンシューマークライアントのサービスプリンシパル (ユーザー) を作成します。

サービスプリンシパルは SERVICE-NAME/FULLY-QUALIFIED-HOST-NAME@DOMAIN-REALM の形式にする必要があります。

  1. Kerberos KDC を使用してサービスプリンシパルと、プリンシパルキーを保存するキータブを作成します。

    以下に例を示します。

    • zookeeper/node1.example.redhat.com@EXAMPLE.REDHAT.COM
    • kafka/node1.example.redhat.com@EXAMPLE.REDHAT.COM
    • producer1/node1.example.redhat.com@EXAMPLE.REDHAT.COM
    • consumer1/node1.example.redhat.com@EXAMPLE.REDHAT.COM

      ZooKeeper サービスプリンシパルは、Kafka config/server.properties ファイルの zookeeper.connect 設定と同じホスト名である必要があります。

      zookeeper.connect=node1.example.redhat.com:2181

      ホスト名が同じでない場合、localhost が使用され、認証に失敗します。

  2. ホストにディレクトリーを作成し、キータブファイルを追加します。

    以下に例を示します。

    /opt/kafka/krb5/zookeeper-node1.keytab
    /opt/kafka/krb5/kafka-node1.keytab
    /opt/kafka/krb5/kafka-producer1.keytab
    /opt/kafka/krb5/kafka-consumer1.keytab
  3. kafka ユーザーがディレクトリーにアクセスできることを確認します。

    chown kafka:kafka -R /opt/kafka/krb5
Kerberos ログインを使用するための ZooKeeper の設定

認証に Kerberos Key Distribution Center (KDC) を使用するように zookeeper のために作成したユーザープリンシパルとキータブを使用して ZooKeeper を設定します。

  1. opt/kafka/config/jaas.conf ファイルを作成または変更して、ZooKeeper クライアントおよびサーバー操作をサポートします。

    Client {
        com.sun.security.auth.module.Krb5LoginModule required debug=true
        useKeyTab=true 1
        storeKey=true 2
        useTicketCache=false 3
        keyTab="/opt/kafka/krb5/zookeeper-node1.keytab" 4
        principal="zookeeper/node1.example.redhat.com@EXAMPLE.REDHAT.COM"; 5
    };
    
    Server {
        com.sun.security.auth.module.Krb5LoginModule required debug=true
        useKeyTab=true
        storeKey=true
        useTicketCache=false
        keyTab="/opt/kafka/krb5/zookeeper-node1.keytab"
        principal="zookeeper/node1.example.redhat.com@EXAMPLE.REDHAT.COM";
    };
    
    QuorumServer {
        com.sun.security.auth.module.Krb5LoginModule required debug=true
        useKeyTab=true
        storeKey=true
        keyTab="/opt/kafka/krb5/zookeeper-node1.keytab"
        principal="zookeeper/node1.example.redhat.com@EXAMPLE.REDHAT.COM";
    };
    
    QuorumLearner {
        com.sun.security.auth.module.Krb5LoginModule required debug=true
        useKeyTab=true
        storeKey=true
        keyTab="/opt/kafka/krb5/zookeeper-node1.keytab"
        principal="zookeeper/node1.example.redhat.com@EXAMPLE.REDHAT.COM";
    };
    1
    true に設定し、キータブからプリンシパルキーを取得します。
    2
    true に設定し、プリンシパルキーを保存します。
    3
    true に設定し、チケットキャッシュから Ticket Granting Ticket (TGT) を取得します。
    4
    keyTab プロパティーは、Kerberos KDC からコピーされた keytab ファイルの場所を示します。その場所とファイルは、kafka ユーザーが読み取りできるものでなければなりません。
    5
    principal プロパティーは、KDC ホストで作成された完全修飾プリンシパル名と一致するように設定され、その形式は SERVICE-NAME/FULLY-QUALIFIED-HOST-NAME@DOMAIN-NAME に従います。
  2. opt/kafka/config/zookeeper.properties を編集して、更新された JAAS 設定を使用します。

    # ...
    
    requireClientAuthScheme=sasl
    jaasLoginRenew=3600000 1
    kerberos.removeHostFromPrincipal=false 2
    kerberos.removeRealmFromPrincipal=false 3
    quorum.auth.enableSasl=true 4
    quorum.auth.learnerRequireSasl=true 5
    quorum.auth.serverRequireSasl=true
    quorum.auth.learner.loginContext=QuorumLearner 6
    quorum.auth.server.loginContext=QuorumServer
    quorum.auth.kerberos.servicePrincipal=zookeeper/_HOST 7
    quorum.cnxn.threads.size=20
    1
    ログイン更新の頻度をミリ秒単位で制御します。これは、チケットの更新間隔に合わせて調整できます。デフォルトは 1 時間です。
    2
    ホスト名がログインプリンシパル名の一部として使用されるかどうかを指定します。クラスターのすべてのノードで単一の keytab を使用する場合、これは true に設定されます。ただし、トラブルシューティングのために、各ブローカーホストに個別のキータブと完全修飾プリンシパルを生成することが推奨されます。
    3
    Kerberos ネゴシエーションのプリンシパル名からレルム名を削除するかどうかを制御します。この設定は、false にすることをお勧めします。
    4
    ZooKeeper サーバーおよびクライアントの SASL 認証メカニズムを有効にします。
    5
    RequireSasl プロパティーは、マスター選出などのクォーラムイベントに SASL 認証を必要とするかどうかを制御します。
    6
    loginContext プロパティーは、指定されたコンポーネントの認証設定に使用される JAAS 設定のログインコンテキストの名前を識別します。loginContext 名は、opt/kafka/config/jaas.conf ファイルの関連セクションの名前に対応します。
    7
    識別に使用されるプリンシパル名を形成するために使用される命名規則を制御します。プレースホルダー _HOST は、実行時に server.1 プロパティーによって定義されたホスト名に自動的に解決されます。
  3. JVM パラメーターで ZooKeeper を起動し、Kerberos ログイン設定を指定します。

    su - kafka
    export EXTRA_ARGS="-Djava.security.krb5.conf=/etc/krb5.conf -Djava.security.auth.login.config=/opt/kafka/config/jaas.conf"; /opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties

    デフォルトのサービス名 (zookeeper) を使用していない場合は、-Dzookeeper.sasl.client.username=NAME パラメーターを使用して名前を追加します。

    注記

    /etc/krb5.conf を場所として使用している場合は、ZooKeeper、Kafka、Kafka プロデューサーおよびコンシューマーの起動時に -Djava.security.krb5.conf=/etc/krb5.conf を指定する必要はありません。

Kerberos ログインを使用するための Kafka ブローカーサーバーの設定

認証に Kerberos Key Distribution Center (KDC) を使用するように kafka のために作成したユーザープリンシパルとキータブを使用して Kafka を設定します。

  1. opt/kafka/config/jaas.conf ファイルを以下の要素で修正します。

    KafkaServer {
        com.sun.security.auth.module.Krb5LoginModule required
        useKeyTab=true
        storeKey=true
        keyTab="/opt/kafka/krb5/kafka-node1.keytab"
        principal="kafka/node1.example.redhat.com@EXAMPLE.REDHAT.COM";
    };
    KafkaClient {
        com.sun.security.auth.module.Krb5LoginModule required debug=true
        useKeyTab=true
        storeKey=true
        useTicketCache=false
        keyTab="/opt/kafka/krb5/kafka-node1.keytab"
        principal="kafka/node1.example.redhat.com@EXAMPLE.REDHAT.COM";
    };
  2. Kafka クラスターの各ブローカーを設定するには、config/server.properties ファイルのリスナー設定を変更して、リスナーが SASL/GSSAPI ログインを使用するようにします。

    リスナーのセキュリティープロトコルのマップに SASL プロトコルを追加し、不要なプロトコルを削除します。

    以下に例を示します。

    # ...
    broker.id=0
    # ...
    listeners=SECURE://:9092,REPLICATION://:9094 1
    inter.broker.listener.name=REPLICATION
    # ...
    listener.security.protocol.map=SECURE:SASL_PLAINTEXT,REPLICATION:SASL_PLAINTEXT 2
    # ..
    sasl.enabled.mechanisms=GSSAPI 3
    sasl.mechanism.inter.broker.protocol=GSSAPI 4
    sasl.kerberos.service.name=kafka 5
    ...
    1
    クライアントとの汎用通信 (通信用の TLS をサポート) と inter-broker 通信用のレプリケーションリスナーの 2 つのリスナーが設定されます。
    2
    TLS 対応のリスナーの場合、プロトコル名は SASL_PLAINTEXT です。TLS に対応していないコネクターの場合、プロトコル名は SASL_PLAINTEXT です。SSL が必要ない場合は、ssl.* プロパティーを削除できます。
    3
    Kerberos 認証のための SASL メカニズムは GSSAPI です。
    4
    inter-broker 通信の Kerberos 認証。
    5
    認証要求に使用するサービスの名前は、同じ Kerberos 設定を使用している他のサービスと区別するために指定されます。
  3. Kafka ブローカーを起動し、JVM パラメーターを使用して Kerberos ログイン設定を指定します。

    su - kafka
    export KAFKA_OPTS="-Djava.security.krb5.conf=/etc/krb5.conf -Djava.security.auth.login.config=/opt/kafka/config/jaas.conf"; /opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties

    ブローカーおよび ZooKeeper クラスターが以前に設定されていて、Kerberos ベース以外の認証システムで動作している場合は、ZooKeeper およびブローカークラスターを起動し、ログで設定エラーを確認することができます。

    ブローカーおよび Zookeeper インスタンスを起動すると、Kerberos 認証用にクラスターが設定されました。

Kerberos 認証を使用ための Kafka プロデューサーおよびコンシューマークライアントの設定

認証に Kerberos Key Distribution Center (KDC) を使用するように producer1 および consumer1 のために作成したユーザープリンシパルとキータブを使用して Kafka プロデューサーおよびコンシューマークライアントを設定します。

  1. プロデューサーまたはコンシューマー設定ファイルに Kerberos 設定を追加します。

    以下に例を示します。

    /opt/kafka/config/producer.properties

    # ...
    sasl.mechanism=GSSAPI 1
    security.protocol=SASL_PLAINTEXT 2
    sasl.kerberos.service.name=kafka 3
    sasl.jaas.config=com.sun.security.auth.module.Krb5LoginModule required \ 4
        useKeyTab=true  \
        useTicketCache=false \
        storeKey=true  \
        keyTab="/opt/kafka/krb5/producer1.keytab" \
        principal="producer1/node1.example.redhat.com@EXAMPLE.REDHAT.COM";
    # ...

    1
    Kerberos (GSSAPI) 認証の設定。
    2
    Kerberos は SASL プレーンテキスト (ユーザー名/パスワード) セキュリティープロトコルを使用します。
    3
    Kerberos KDC で設定された Kafka のサービスプリンシパル (ユーザー)。
    4
    jaas.conf で定義されたものと同じプロパティーを使用した JAAS の設定。

    /opt/kafka/config/consumer.properties

    # ...
    sasl.mechanism=GSSAPI
    security.protocol=SASL_PLAINTEXT
    sasl.kerberos.service.name=kafka
    sasl.jaas.config=com.sun.security.auth.module.Krb5LoginModule required \
        useKeyTab=true  \
        useTicketCache=false \
        storeKey=true  \
        keyTab="/opt/kafka/krb5/consumer1.keytab" \
        principal="consumer1/node1.example.redhat.com@EXAMPLE.REDHAT.COM";
    # ...

  2. クライアントを実行して、Kafka ブローカーからメッセージを送受信できることを確認します。

    プロデューサークライアント:

    export KAFKA_HEAP_OPTS="-Djava.security.krb5.conf=/etc/krb5.conf -Dsun.security.krb5.debug=true"; /opt/kafka/bin/kafka-console-producer.sh --producer.config /opt/kafka/config/producer.properties  --topic topic1 --bootstrap-server node1.example.redhat.com:9094

    コンシューマークライアント:

    export KAFKA_HEAP_OPTS="-Djava.security.krb5.conf=/etc/krb5.conf -Dsun.security.krb5.debug=true"; /opt/kafka/bin/kafka-console-consumer.sh --consumer.config /opt/kafka/config/consumer.properties  --topic topic1 --bootstrap-server node1.example.redhat.com:9094

関連情報

第15章 Cruise Control によるクラスターのリバランス

重要

Cruise Control によるクラスターのリバランスはテクノロジープレビューの機能です。テクノロジープレビュー機能は、Red Hat の実稼働サービスレベルアグリーメント (SLA) でサポートされておらず、機能的に完全でない可能性があります。Red Hat は、本番環境でのテクノロジープレビュー機能の実装は推奨しません。テクノロジープレビューの機能は、最新の技術をいち早く提供して、開発段階で機能のテストやフィードバックの収集を可能にするために提供されます。Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、「テクノロジプレビュー機能のサポート範囲」 を参照してください。

Cruise Control を AMQ Streams クラスターにデプロイし、これを使用して Kafka ブローカー全体で負荷のリバランスを実行できます。

Cruise Control は、クラスターワークロードの監視、事前定義の制約を基にしたクラスターの再分散、異常の検出および修正などの Kafka の操作を自動化するオープンソースのシステムです。これは、4 つのコンポーネント (Load Monitor、Analyzer、Anomaly Detector、Executor) および REST API で構成されます。

AMQ Streams と Cruise Control の両方が Red Hat Enterprise Linux にデプロイされている場合、Cruise Control REST API から Cruise Control 機能にアクセスできます。以下の機能がサポートされます。

  • 最適化の目標容量制限 の設定
  • /rebalance エンドポイントを使用した以下の実行

    • 設定された最適化ゴールまたはリクエストパラメーターとして提供される ユーザー提供ゴール を基にして、最適化プロポーザル をドライランとして生成する
    • 最適化プロポーザルを開始し、Kafka クラスターをリバランスする
  • /user_tasks エンドポイントを使用した、アクティブなリバランス操作の進捗の確認
  • /stop_proposal_execution エンドポイントを使用した、アクティブなリバランス操作の停止

異常検出、通知、独自のゴールの作成、トピックレプリケーションファクターの変更など、その他すべての Cruise Control 機能は現在サポートされていません。Web UI コンポーネント (Cruise Control Frontend) はサポートされていません。

Red Hat Enterprise Linux 上の AMQ Streams の Cruise Control は、個別の zip 形式のディストリビューションとして提供されます。詳細は、「Cruise Control アーカイブのダウンロード」 を参照してください。

15.1. Cruise Control とは

Cruise Control は、Kafka クラスターの効率的な実行に必要な時間および労力を削減し、ブローカー全体でワークロードをより均等に分散します。

通常、クラスターの負荷は時間とともに不均等になります。大量のメッセージトラフィックを処理するパーティションは、使用可能なブローカー全体で不均等に分散される可能性があります。クラスターを再分散するには、管理者はブローカーの負荷を監視し、トラフィックの多いパーティションを容量に余裕のあるブローカーに手作業で再割り当てします。

Cruise Control は、このクラスターのリバランス処理を自動化します。CPU、ディスク、およびネットワークの負荷に基づいて、リソース使用率の ワークロードモデル を構築します。設定可能な最適化ゴールのセットを使用すると、Cruise Control に、よりバランスの取れたパーティション割り当てのためのドライラン最適化プロポーザルを生成するよう指示できます。

ドライランの最適化プロポーザルを確認したら、Cruise Control に対してそのプロポーザルに基づいてクラスターのリバランスを開始するように指示したり、新しいプロポーザルを生成したりすることができます。

クラスターのリバランス操作が完了すると、ブローカーがより効果的に使用され、Kafka クラスターの負荷がより均等に分散されます。

15.2. Cruise Control アーカイブのダウンロード

Red Hat Enterprise Linux 上の AMQ Streams の Cruise Control は zip ディストリビューションとして、Red Hat カスタマーポータル からダウンロードできます。

手順

  1. Red Hat カスタマーポータル から、最新バージョンの Red Hat AMQ Streams Cruise Control アーカイブをダウンロードします。
  2. /opt/cruise-control ディレクトリーを作成します。

    sudo mkdir /opt/cruise-control
  3. Cruise Control ZIP ファイルの内容を新しいディレクトリーに展開します。

    unzip amq-streams-y.y.y-cruise-control-bin.zip -d /opt/cruise-control
  4. /opt/cruise-control ディレクトリーの所有権を kafka ユーザーに変更します。

    sudo chown -R kafka:kafka /opt/cruise-control

15.3. Cruise Control Metrics Reporter のデプロイ

Cruise Control を起動する前に、提供される Cruise Control Metrics Reporter を使用するように Kafka ブローカーを設定する必要があります。

実行時にロードされると、Metrics Reporter は 自動作成された 3 つのトピックの 1 つである __CruiseControlMetrics トピックにメトリクスを送信します。Cruise Control はこれらのメトリクスを使用して、ワークロードモデルを作成および更新し、最適化プロポーザルを計算します。

前提条件

手順

Kafka クラスターの各ブローカーに対して、以下を 1 つずつ実行します。

  1. Kafka ブローカーを停止します。

    /opt/kafka/bin/kafka-server-stop.sh
  2. Cruise Control Metrics Reporter .jar ファイルを Kafka libraries ディレクトリーにコピーします。

    cp /opt/cruise-control/libs/cruise-control-metrics-reporter-y.y.yyy.redhat-0000x.jar /opt/kafka/libs
  3. Kafka 設定ファイル (/opt/kafka/config/server.properties) で、Cruise Control Metrics Reporter を設定します。

    1. CruiseControlMetricsReporter クラスを metric.reporters 設定オプションに追加します。既存の Metrics Reporters を削除しないでください。

      metric.reporters=com.linkedin.kafka.cruisecontrol.metricsreporter.CruiseControlMetricsReporter
    2. 以下の設定オプションおよび値を Kafka 設定ファイルに追加します。

      cruise.control.metrics.topic.auto.create=true
      cruise.control.metrics.topic.num.