クラスターリンクユーザーガイド

このページでは、EMQXダッシュボード、設定ファイル、およびREST APIを通じてクラスターリンク機能を設定および管理するためのガイドラインを提供します。

ダッシュボードによるクラスターリンクの設定と管理

EMQXダッシュボードにアクセスし、左メニューから Management -> Cluster Linking をクリックします。Cluster Linking ページの右上にある Create をクリックしてクラスターリンクの作成を開始します。

create_cluster_linking

設定ページでは、以下の項目を設定します。

Cluster Name：リモートクラスターの名前を入力します。
Server：リモートクラスターのMQTTリスナーのエンドポイントを指定します。対応するアドレス形式については Configure MQTT Connections を参照してください。
Client ID Prefix：リモートクラスターへのMQTT接続で使用されるClientIDのプレフィックスを定義します。詳細は Configure MQTT Connections をご覧ください。
Username：リモートクラスターへの認証に必要な場合のユーザー名を入力します。
Password：リモートクラスターへの認証に必要な場合のパスワードを入力します。
Topics：ローカルクラスターがリモートクラスターから受信するメッセージの対象となるMQTTトピックフィルターのリストです。デフォルトでは空リストです。プラスアイコンをクリックしてトピックを追加したり、不要なトピックを削除して空リストに戻すことも可能です。詳細は Configure Topics を参照してください。
Enable TLS：クラスター間通信にTLS暗号化が必要な場合はこのオプションを有効にし、SSL証明書などの設定を行います。
Advanced Settings：MQTTプロトコルパラメータなどの追加設定を行います。

設定が完了したら Create をクリックします。

新しいエントリがクラスターリンクページに表示され、デフォルトで有効になります。クラスターリンク一覧には、クラスター名、サーバーアドレス、トピック、状態などの詳細が表示されます。Actions 列の Settings または Delete ボタンから設定の変更やエントリの削除が可能です。

クラスター名をクリックすると Overview タブに移動し、メッセージ送受信の統計やクラスターリンクの実行状況を監視できます。ページ右上の削除アイコンをクリックするとクラスターリンクエントリを完全に削除できます。あるいはスイッチを切り替えて一時的に無効化し、設定を保持したまま将来再利用することも可能です。

設定ファイルによるクラスターリンクの設定

EMQXの設定ファイル内の cluster.links リストに複数のクラスターリンクを設定できます。各リンクはリモートクラスター名が一意であり、個別に有効・無効を切り替えられます。

リンクの正しい動作には、各リンク間でクラスター名を一貫して維持することが重要です。以下の例では、リモートクラスター名は対応する設定ファイルで emqx-eu-west とする必要があります。

bash

cluster {
  name = "emqx-us-east"
  links = [
    {
      name = "emqx-eu-west"
      server = "emqx.us-east.myinfra.net:11883"
      username = "clink-user:us-east"
      password = "clink-password-no-one-knows"
      clientid = "clink-us-east"
      topics = ["global/#", "fwd/#", "cluster/+/status", ...]
      ssl {
        enable = true
        verify = verify_peer
        certfile = "etc/certs/client/emqx-us-east.pem"
        ...
      }
    }
    ...
  ]
}

リモートの emqx-eu-west クラスターも同様に emqx-us-east へのリンクを設定している必要があります。

リンクの有効化と無効化

設定済みのリンクはデフォルトで有効です。enable パラメータを false に設定することで無効化できます。

リンクを無効化するとEMQXはリモートクラスターとの通信を停止しますが、リモートクラスター側が通信を停止するわけではないため、リモート側で警告やアラームが発生する可能性があります。これを避けるため、リンクは両側で無効化することを必ず行ってください。

トピックの設定

topics パラメータは、ローカルクラスターが関心を持つMQTTトピックフィルターのリストです。ローカルクラスターはリモートクラスターからこれらのトピックにパブリッシュされたメッセージを受信します。リストが空の場合、ローカルクラスターはリモートクラスターからメッセージを受信しません。

MQTT接続の設定

クラスターリンクは標準のMQTTを基盤プロトコルとして使用し、server にリモートクラスターのMQTTリスナーのエンドポイントを指定します。対応する形式は host:port、[IPv6]:port、mqtt://host:port、mqtt://[IPv6]:port、mqtts://host:port、mqtts://[IPv6]:port です。ポート番号が省略された場合は、EMQXはデフォルトのMQTTポート 1883 を使用します。その他のURIスキームはサポートされていません。mqtt と mqtts スキームはアドレス解析のためだけに使用されます。TLS対応のMQTTリスナーに接続する場合は、リンクのTLS設定を別途行ってください。

クラスターの規模や設定により、リモートクラスターへの複数のMQTTクライアント接続が確立されることがあり、各クライアントは一意のClientIDを持つ必要があります。clientid パラメータはこれらの接続のClientIDプレフィックスとして機能し、ClientIDの割り当てを制御します。

認証や認可パラメータ（username、password）など、他のMQTTプロトコル関連の設定も可能です。リモートクラスターはこれらの接続を認証し、クラスターリンク設定で指定された特定のMQTTトピックへのパブリッシュを認可できる必要があります。例えば、上記の設定に対してリモートクラスターは以下のようなACLルールを持つことで正常に動作します。

erlang

%% クラスターリンクMQTTクライアントが"$LINK/#"トピックで動作可能にする
{allow, {clientid, {re, "^clink-us-east"}}, all, ["$LINK/#"]}.
...

このルールは、ClientIDが正規表現 ^clink-us-east にマッチするMQTTクライアントに対し、$LINK/ で始まる任意のトピックのパブリッシュおよびサブスクライブを許可します。$LINK/ はクラスターリンク関連の制御トピックのプレフィックスであり、サブスクライブするエンティティがクラスターリンクの維持・管理に必要なすべてのメッセージを受信できるようにします。

上記の単一ルールはリンクを機能させるための最低限の設定です。実運用では、クラスターリンク以外のクライアントが$LINK/にアクセスできないように禁止し、最後にデフォルト拒否ルールを設定する必要があります。詳細は Secure Cluster Linking と authorization.no_match = deny 設定を参照してください。

リスナーのマウントポイントとの非互換性

クラスターリンク接続を受け入れるリスナーにはマウントポイントを設定してはいけません。EMQXはマウントポイントを$LINK/制御トピックのマッチング前に適用するため、リンクトラフィックが通常のメッセージとしてルーティングされ、リンクが機能しなくなります。

クラスターリンクはTLS接続をサポートしています。パブリックインターネットやその他の信頼できないネットワーク経由でクラスター間通信を行う場合はTLSが必須です。EMQXは相互TLS認証もサポートし、通信の安全性、機密性、信頼性を確保します。

REST APIによるクラスターリンクの管理

EMQXのクラスターリンクには、クラスター間リンクの管理を行うREST APIが用意されており、設定作業やリンク状態の監視が可能です。APIは基本操作と高度な操作の両方を提供し、多様な管理ニーズに対応します。

基本的なREST API操作

シンプルな用途向けに、以下のエンドポイントで基本的なREST API操作がサポートされています。

クラスターリンクの設定：
- エンドポイント：PUT /cluster/links
- 機能：必要な設定パラメータを一括で送信し、クラスターリンクの更新または新規作成を行います。簡単なホット設定に適しています。
クラスターリンク情報の取得：
- エンドポイント：GET /cluster/links
- 機能：既存のすべてのクラスターリンクの現在の設定と状態を返します。アクティブなリンクの確認に便利です。

高度なCRUD API操作

クラスターリンクをより細かく制御するために、以下のCRUD（作成、取得、更新、削除）操作が利用できます。

操作	エンドポイント	機能
クラスターリンクの作成	`POST /cluster/links`	クラスター間の新規リンクを確立し、初期設定を行います。
特定クラスターリンクの取得	`GET /cluster/links/{name}`	名前で指定した特定のクラスターリンクの詳細情報を取得します。
クラスターリンクの更新	`PUT /cluster/links/{name}`	既存リンクの設定を変更し、トピックやサーバーアドレス、認証情報などを更新します。
クラスターリンクの削除	`DELETE /cluster/links/{name}`	指定したクラスターリンクを削除し、接続を終了します。

クラスターリンクの状態とメトリクスの監視

設定操作に加え、APIはクラスターリンクの状態やパフォーマンスの監視用エンドポイントも提供しています。

クラスターリンクの状態取得：

エンドポイント：GET /cluster/links または GET /cluster/links/{name}
機能：すべてのクラスターリンクまたは特定リンクの状態を返します。レスポンスには全体の状態（running、stoppedなど）やノードごとの詳細な状態情報が含まれます。

レスポンス例：

json

{
  ...
  "server": "broker.emqx.io:1883",
  "topics": ["t/#"],
  "status": "running",
  "node_status": [
    {"node": "emqx@127.0.0.1", "status": "running"}
  ]
}

クラスターリンクのメトリクス取得：

エンドポイント：GET /cluster/links/{name}/metrics
説明：アクティブルート数（ゲージタイプ）など、リンクの負荷やパフォーマンスを評価するためのメトリクスを提供します。

レスポンス例：

json

{
  "metrics": {"routers": 10240},
  "node_metrics": [{}]
}

特定クラスターリンクのメトリクスリセット

エンドポイント：PUT /cluster/links/link/:name/metrics/reset
説明：指定したクラスターリンクの累積メトリクスをリセットします。リセット後はパフォーマンス統計がクリアされ、新たに計測が開始されます。設定変更後の監視やトラブルシューティングに有用です。
レスポンス例：内容なしの 204 が返されます。

スキーマレジストリ

LLM ベースの MQTT データ処理

サブスクリプションフィルター

メッセージキュー

MQTT ストリーム

MQTT over QUIC