EMQX Enterprise

日本語

简体中文
English

日本語

简体中文
English

Appearance

お問い合わせ
お問い合わせ

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

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

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

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

create_cluster_linking

設定ページで、以下のフィールドの設定を行います。

  • Cluster Name：リモートクラスターの名前を入力します。
  • Server：リモートクラスターのMQTTホストとポートを指定します。
  • Client ID Prefix：リモートクラスターへのMQTT接続で使用されるClientIDのプレフィックスを定義します。詳細はMQTT接続の設定を参照してください。
  • Username：リモートクラスターへの認証に必要な場合のユーザー名を入力します。
  • Password：リモートクラスターへの認証に必要な場合のパスワードを入力します。
  • Topics：ローカルクラスターがリモートクラスターから受信するメッセージの対象となるMQTTトピックフィルターのリストです。デフォルトでは空です。プラス記号をクリックしてトピックを追加したり、トピックを削除して空のままにすることも可能です。詳細はトピックの設定を参照してください。
  • 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を基盤プロトコルとして使用しており、リモートクラスターのMQTTリスナーエンドポイントを server として指定する必要があります。

クラスターの規模や設定によっては、リモートクラスターへの複数のMQTTクライアント接続が確立されます。各クライアントは一意の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/ へのアクセスを禁止し、デフォルト拒否ルールで締める完全な認可設定が必要です。詳細はセキュアなクラスターリンクと authorization.no_match = deny 設定を参照してください。

クラスターリンクは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 を返します。