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

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

## ダッシュボードでのクラスターリンクの設定と管理

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

![create_cluster_linking](./assets/create_cluster_linking.png)

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

- **Cluster Name**：リモートクラスターの名前を入力します。
- **Server**：リモートクラスターのMQTTリスナーのエンドポイントを指定します。対応するアドレス形式については、[Configure MQTT Connections](#configure-mqtt-connections) を参照してください。
- **Client ID Prefix**：リモートクラスターへのMQTT接続で使用されるClientIDのプレフィックスを定義します。詳細は [Configure MQTT Connections](#configure-mqtt-connections) を参照してください。
- **Username**：リモートクラスターへの認証に必要な場合のユーザー名を入力します。
- **Password**：リモートクラスターへの認証に必要な場合のパスワードを入力します。
- **Topics**：ローカルクラスターがリモートクラスターから受信するメッセージの対象となるMQTTトピックフィルターのリストです。デフォルトでは空です。プラスアイコンをクリックしてトピックを追加したり、不要なトピックを削除して空にすることも可能です。詳細は [Configure Topics](#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を基盤プロトコルとして使用し、リモートクラスターのMQTTリスナーエンドポイントを `server` に指定します。対応する形式は `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`）も設定可能です。リモートクラスターはこれらの接続を[認証](../../guides/access-control/authn/authn.md)し、クラスターリンク設定で指定された特定のMQTTトピックに対してメッセージのパブリッシュを[認可](../../guides/access-control/authz/authz.md)できる必要があります。例えば、上記設定に対応するリモートクラスターの[ACLルール](../../guides/access-control/authz/file.md)は以下のようになります。

```erlang
%% クラスターリンクMQTTクライアントが"$LINK/#"トピックを操作できるよう許可
{allow, {clientid, {re, "^clink-us-east"}}, all, ["$LINK/#"]}.
...
```

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

上記の単一ルールはリンクを機能させるための最低限の設定です。実運用では、非クラスターリンククライアントによる `$LINK/` トピックへのアクセスを禁止し、デフォルト拒否ルールで締める完全な認可設定が必要です。詳細は [Secure Cluster Linking](./security.md) と `authorization.no_match = deny` 設定を参照してください。

::: warning リスナーのマウントポイントとの非互換性
クラスターリンク接続を受け入れるリスナーには、[マウントポイント](../../guides/configuration/listener.md#mountpoint)を設定してはいけません。EMQXはマウントポイントを `$LINK/` 制御トピックのマッチング前に適用するため、リンクトラフィックが通常のメッセージとしてルーティングされ、リンクが機能しなくなります。
:::

クラスターリンクは[TLS接続](../../guides/network/overview.md)をサポートしています。パブリックインターネットや信頼できないネットワーク上でクラスター間通信を行う場合はTLSが必須です。EMQXは相互TLS認証もサポートし、安全で機密性が高く信頼できる通信を実現します。

## REST APIでのクラスターリンク管理

EMQXのクラスターリンクは、クラスター間リンクの管理や監視を行うための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}`  | 指定したクラスターリンクを削除し、クラスター間接続を終了します。 |

### クラスターリンクの状態およびメトリクスの監視

設定操作に加え、以下のエンドポイントでリンクの状態やパフォーマンスを監視できます。

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

- **エンドポイント**：`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` を返します。