クラスターの作成と管理

EMQXクラスターは手動または自動のいずれかの方法で作成できます。本ページでは、手動クラスタリングと自動クラスタリングの両方の方法を紹介し、これら2つの異なるアプローチを用いたEMQXクラスターの作成および管理方法を案内します。

注意

クラスターモードは有効なライセンスキーがある場合にのみ利用可能です。

基本概念

EMQXクラスターの基本知識や動作については、クラスターおよびアーキテクチャをご覧ください。クラスターを作成するには、以下の概念にも精通しておく必要があります。

ノード名

EMQXのノードは名前によって識別されます。すべてのノードは name@host という形式の一意のノード名が設定されており、hostにはIPアドレスまたは完全修飾ドメイン名（FQDN）を指定する必要があります。例：

サーバーs1.emqx.ioにデプロイされたEMQXノードの場合、ノード名は emqx@s1.emqx.io となります。
このサーバーが固定IP（192.168.0.10）を持つ場合、ノード名は emqx@192.168.0.10 となります。

TIP

EMQXノード名はデータベーススキーマやデータファイルに組み込まれているため変更できません。そのため、EMQXノード名には静的なFQDNの使用を推奨します。

ノードディスカバリー

ノードディスカバリーはクラスター作成に必須のプロセスであり、個々のEMQXノードがお互いを発見し、場所やIPアドレスに関係なく通信できるようにします。

手動クラスタリングと自動クラスタリング

ノードディスカバリーストラテジーに基づき、クラスター作成方法は手動クラスタリングと自動クラスタリングに分けられます。

手動クラスタリングは、どのノードをクラスターに含めるかを手動で指定してEMQXクラスターを作成する方法です。自動クラスタリングは、複数のEMQXノードが手動設定なしに自動的にクラスターを形成する方法で、クラスターの設定を簡素化し、動的にノードの追加・削除を容易にします。EMQXは静的ノードリスト、DNSレコード、etcd、Kubernetesなどに基づく自動クラスタリングをサポートしています。

以下の表は、EMQXがサポートするノードディスカバリーストラテジーとクラスター作成方法を示しています。

ストラテジー	説明
`manual`	コマンドで手動によりクラスターを作成
`static`	静的ノードリストによる自動クラスタリング
`dns`	DNSのAレコードおよびSRVレコードによる自動クラスタリング
`etcd`	etcdによる自動クラスタリング
`k8s`	Kubernetesによる自動クラスタリング
`singleton`	クラスタリング無効。ノードは他ノードとの接続をすべて拒否。

EMQXはErlang/OTPアプリケーション向けに開発されたEkkaライブラリに基づく自動クラスター作成をサポートしています。EkkaはErlangノードの自動発見（サービスディスカバリー）や自動クラスタリング（Autocluster）だけでなく、ネットワークパーティションの自動修復（Network Partition Autoheal）やダウンしたノードの自動削除（Autoclean）などの機能も実装しています。

クラスターの作成方法は、emqx.conf設定ファイルのノードディスカバリーストラテジーを設定することで定義できます。デフォルトは手動クラスタリングです。

bash

cluster {
    ## Options: manual | static | dns | etcd | k8s | singleton
    discovery_strategy  =  manual
}

はじめる前に

このセクションでは、クラスター作成前にノードおよびネットワーク環境をどのように設定するかについて説明します。

ノード名の設定

クラスターを作成する前に、クラスターに参加するノードの名前付け方法を理解しておく必要があります。例えば、s1.emqx.ioとs2.emqx.ioにそれぞれデプロイされた2つのノードのクラスターを作成する場合、以下の手順に従います。

1つ目のノードのemqx.conf設定ファイルにノード名を設定します。例：

bash

node.name = emqx@s1.emqx.io

ノード名は環境変数で上書きすることも可能です。例えば、docker runコマンドの-eオプションやsystemdのemqx.serviceファイルで以下のように定義します。

bash

EMQX_NODE__NAME='emqx@s1.emqx.io'

クラスターに参加する他のノードでも同様の手順を繰り返します。

これでクラスターに参加する2つのノード、emqx@s1.emqx.ioとemqx@s2.emqx.ioの名前付けが完了しました。手動または自動のいずれかの方法でクラスターを作成できます。

ノードクッキーの設定

セキュリティ上の理由から、クラスターに参加するすべてのノードのemqx.confでデフォルトのクッキー設定をSecretクッキーに変更してください。クラスターに参加するすべてのノードは同じSecretクッキーを使用する必要があります。使用されるマジッククッキーの詳細はDistributed Erlang - Securityをご参照ください。

node {
  cookie = "<Secretクッキー>"
}

ネットワーク環境の設定

ノード間のネットワーク接続が正常に機能していることを確認してください。ノード間にファイアウォールやセキュリティグループがある場合は、内部クラスター通信に必要な以下のポートを開放してください。

4370：Erlang分散トランスポートポート
5370：クラスターRPCポート（物理マシン環境向け）
5369：クラスターRPCポート（Docker環境向け）

1台のサーバーに複数のEMQXノードをデプロイする場合、各ノードは異なるクラスター通信ポートを使用します。ファイアウォール設定の詳細はクラスター内通信ポートをご覧ください。

クイックスタート

このセクションでは、Dockerネットワーク上で2つの異なるクラスタリング方法を使ってクラスターを素早く作成する方法を示します。

TIP

複数の物理マシンにまたがるDocker環境でEMQXを実行しクラスターを形成する場合は、追加の設定が必要です。コンテナ内で必要なクラスター通信ポートをマッピングし、ファイアウォールでこれらのポートが開放されていることをネットワーク環境の設定で確認してください。

任意のノード上でemqx ctl cluster statusコマンドを実行し、クラスター状態を確認します。クラスター状態が正常な場合、以下のような情報が出力されます。

bash

$ docker exec -it emqx1 emqx ctl cluster status
Cluster status: #{running_nodes =>
                    ['emqx@node1.emqx.com','emqx@node2.emqx.com'],
                stopped_nodes => []}

これで簡単なクラスター作成が完了しました。次に、以下のセクションの手順に従い、必要なクラスター作成方法を選択して設定・デプロイを行えます。

手動クラスタリング

このセクションでは、手動でクラスターを作成する手順を説明します。手動クラスタリングでは、クラスター内の各ノードを手動で設定し、ノード間のネットワーク接続も構築する必要があります。自動クラスタリングと比較して、カスタムネットワークトポロジーの細かな調整が可能であり、自動クラスタリングが利用できないまたは不適切な状況に適しています。

TIP

手動クラスタリングはコアノードにのみ使用可能です。コア-レプリカノードのデプロイアーキテクチャを使用している場合は、自動クラスタリングを利用してクラスターを管理してください。

例として、emqx@node1.emqx.comとemqx@node2.emqx.comの2つのノードがある場合、以下の手順で手動クラスターを作成できます。

クラスターのディスカバリーストラテジーをmanualに設定します。

bash

cluster {
    ## Options: manual | static | dns | etcd | k8s | singleton
    discovery_strategy  =  manual
}

2つのノードを起動後、いずれかのノード上でクラスター参加コマンドを実行します。
bash
```
$ ./bin/emqx ctl cluster join emqx@node1.emqx.com

Join the cluster successfully.
Cluster status: [{running_nodes,['emqx@node1.emqx.com','emqx@node2.emqx.com']}]
```
TIP
- このコマンドはクラスターに参加するノード上で実行する必要があります。つまり、招待ではなく参加要求です。
- emqx@s2.emqx.ioがemqx@s1.emqx.ioに参加してクラスターを形成すると、ローカルデータはクリアされ、emqx@s1.emqx.ioのデータに同期されます。
- emqx@s2.emqx.ioが別のクラスターに参加したい場合、まず現在のクラスターから離脱する必要があります。離脱方法はクラスターからの離脱を参照してください。

任意のノード上でクラスター状態を確認します。

bash

$ ./bin/emqx ctl cluster status

Cluster status: [{running_nodes,['emqx@node1.emqx.com','emqx@node2.emqx.com']}]

2ノードでクラスター作成に成功したので、クラスター状態の確認、クラスターノードの管理、ネットワークプロトコルの設定のセクションを参照し、クラスター状態の監視や管理方法を学んでください。

EMQX v5.9.0以降はダッシュボードからノードの招待や管理も可能で、より直感的で使いやすい操作ができます。詳細はクラスター設定をご覧ください。

自動クラスタリング

このセクションでは、さまざまな自動クラスタリング方法によるクラスターの自動作成方法を説明します。

静的ノードリストによる自動クラスタリング

EMQXの静的ノードリストによる自動クラスタリングは、各ノードに事前定義された静的ノードリストを設定し、起動後にノードリストに従って自動的にクラスターを形成する方法です。

静的クラスタリングは、他のネットワークコンポーネントやサービスに依存せず、TCPプロトコルで相互通信できる限り最も簡単にEMQXクラスターを自動作成できる方法です。

この機能を有効にするには、emqx.confでクラスターモードとノードリストを設定します。

設定例：

bash

cluster {
    discovery_strategy = static
    static {
        seeds = ["emqx@s1.emqx.io", "emqx@s2.emqx.io"]
    }
}

discovery_strategyはノードディスカバリーストラテジーで、staticに設定します。
seedsは配列で、クラスターに参加するノード名を複数カンマ区切りで指定します。

すべてのノードが起動すると、クラスターが自動的に形成されます。

DNSレコードによる自動クラスタリング

DNSはドメインネームシステムの略称です。DNSサーバーはドメイン名の問い合わせに対し、そのドメイン名に対応するIPアドレス（Aレコード）を返します。DNSは1つのドメイン名に複数のAレコード（複数IPアドレス）を持つことができ、1つの名前に対して複数のIPアドレスを対応させるマッピングを形成します。EMQXのDNS自動クラスタリングはこの1対多のマッピングを利用し、クラスター内のすべてのノードを特定し、各独立したノードがクラスターに参加できるようにします。

DNSサービスの設定

ほとんどのパブリッククラウドサービスはDNSサービスを提供しています。ドメイン名を割り当てた後、このドメインのAレコードに各EMQXノードのIPアドレスを追加するだけで設定は完了します。EMQXをプライベートクラウドや内部ネットワークにデプロイする場合は、BINDなどのソフトウェアで独自のDNSシステムを構築する必要があります。

DNSレコードによる自動クラスタリングの設定

DNSサービスが準備できたら、emqx.confのcluster.dns設定項目にクラスターに参加するすべてのノードを追加します。

設定例：

bash

cluster {
    discovery_strategy = dns
    dns {
        name = "localhost"
        ## DNS AレコードおよびDNS SRVレコードをサポート
        record_type = a
    }
}

discovery_strategyはノードディスカバリーストラテジーで、dnsに設定します。
cluster.dns.nameはDNS名／ドメイン名を文字列で指定します。例：localhost
cluster.dns.record_typeは列挙型で、aまたはsrvのいずれかを指定します。

すべてのノードが起動すると、クラスターが自動的に形成されます。

etcdによる自動クラスタリング

etcdはCoreOSが開始したオープンソースプロジェクトで、分散システムにおけるサービスディスカバリーや接続確立に広く使われています。これはまさにEMQXの自動クラスタリングが必要とする機能です。

ネットワーク内にetcdサーバー（クラスター）をデプロイした後、EMQXはetcdを介して自動的にクラスターを作成できます。etcdのインストールや設定方法はetcd Installをご覧ください。

etcdを使った自動クラスタリングを有効にするには、emqx.confのcluster.etcd設定項目を設定します。

設定例：

bash

cluster {
    discovery_strategy = etcd
    etcd {
        server = "http://127.0.0.1:2379"
        prefix = emqxcl
        node_ttl = 1m
    }
}

discovery_strategyはノードディスカバリーストラテジーで、etcdに設定します。
cluster.etcd.serverはetcdサーバーのアドレスで、複数ノードはカンマ区切りで指定可能です。
cluster.etcd.prefixはEMQXサービスディスカバリーに使うetcdのキーのプレフィックスです。
cluster.etcd.node_ttlはetcdキーの有効期限を示す期間で、デフォルトは1m（1分）です。

設定完了後、EMQXノードを順に起動し、etcdctlツールでetcdサーバーの状態を確認できます。

bash

$ etcdctl ls /emqxcl/emqxcl --recursive

/emqxcl/emqxcl/nodes
/emqxcl/emqxcl/nodes/emqx@s1.emqx.io
/emqxcl/emqxcl/nodes/emqx@s2.emqx.io

この結果は、すべてのノードが正常に起動し、自動的にクラスターに参加したことを示しています。

Kubernetes上での自動クラスタリング

EMQX Kubernetes Operatorは、Kubernetes環境でのEMQXクラスターの作成と管理を迅速に行うためのツールで、デプロイや管理作業を低コストでラベル付けされた繰り返し可能なジョブに変換し、EMQXクラスターの展開と管理を大幅に簡素化します。

自分でEMQXをデプロイ・管理したい場合でも、Kubernetes APIを使ったノードディスカバリーと自動クラスタリングは利用可能です。この機能を使うには、EMQX PodがKubernetes APIサーバーからエンドポイントリソースを通じてクラスターのノード情報を取得できるようにRBACを作成する必要があります。設定方法はRBAC認可の使用をご覧ください。

Kubernetes上でEMQX自動クラスタリングを有効にするには、emqx.confのcluster.k8s設定項目を設定します。

bash

cluster {
    discovery_strategy = k8s
    K8s {
        apiserver = "http://10.110.111.204:8080"
        service_name = emqx
        address_type = ip
        namespace = default
    }
}

discovery_strategyはノードディスカバリーストラテジーで、k8sに設定します。
cluster.K8s.apiserverはKubernetes APIエンドポイントURLで、デフォルトはhttp://10.110.111.204:8080です。
cluster.K8s.service_nameはEMQXサービス名で、デフォルトはemqxです。
cluster.K8s.address_typeは検出したノードに接続するためのアドレス種別で、デフォルトはipです。選択肢はip、dns、hostnameです。
（オプション）cluster.K8s.suffixはノード名のサフィックスで、cluster.K8s.address_typeがdnsの場合のみ必要です。デフォルトはpod.localです。
cluster.K8s.namespaceはKubernetesのネームスペースで、文字列型です。デフォルトはdefaultです。

設定後、ノードを順に起動するとクラスターが自動的に形成されます。

TIP

Kubernetes上でEMQX自動クラスタリングを利用する場合、FannelプラグインよりもCalicoの利用を推奨します。

クラスターの管理

クラスターを作成した後は、クラスター状態の監視やノード管理が可能です。

クラスター状態の確認

任意のクラスター内ノード上で以下のコマンドを実行し、クラスター状態を確認します。

bash

$ ./bin/emqx ctl cluster status

Cluster status: [{running_nodes,['emqx@s1.emqx.io','emqx@s2.emqx.io']}]

クラスターからの離脱

クラスターから離脱する方法は2つあります。

cluster leaveコマンドを実行：現在のノードがクラスターから離脱します。クラスター内の他ノードに通知し、クラスター運用から停止します。離脱前に進行中のタスクは完了します。
cluster force-leave <node@host>コマンドを実行：指定したノードをクラスターから強制的に削除します。通常、ノードが故障または応答しない場合に使用します。

例として、先に作成したクラスターでemqx@s2.emqx.ioが離脱したい場合、emqx@s2.emqx.io上で以下を実行します。

bash

./bin/emqx ctl cluster leave

またはemqx@s1.emqx.io上で以下を実行し、emqx@s2.emqx.ioをクラスターから削除します。

bash

./bin/emqx ctl cluster force-leave emqx@s2.emqx.io

ネットワークプロトコルの設定

クラスター作成後、ノード間のネットワークプロトコルを設定できます。EMQXはTCPまたはTLSによるノード間接続をサポートしています。接続方法はemqx.confで設定します。

TCP IPv4およびTCP IPv6を使用する場合は、emqx.confのcluster.proto_distを設定します。

TCP IPv4：inet_tcp（デフォルト）
TCP IPv6：inet6_tcp

SSLを有効にするには、まずcluster.proto_distをinet_tlsに設定し、etcフォルダ内のssl_dist.confファイルでTLS証明書を指定します。詳細はUsing TLS for Erlang Distributionをご覧ください。

疑似分散クラスター

EMQXはテストや開発目的のために疑似分散クラスター機能を提供しています。これは、1台のマシン上で複数のEMQXインスタンスを実行し、それぞれをクラスター内のノードとして設定する構成を指します。

最初のノードを起動：

bash

  EMQX_NODE__NAME='emqx1@127.0.0.1' \
  EMQX_LOG__FILE_HANDLERS__DEFAULT__FILE='log1/emqx.log' \
  EMQX_LISTENERS__TCP__DEFAULT__BIND='127.0.0.1:1883' \
  EMQX_LISTENERS__SSL__DEFAULT__BIND='127.0.0.1:8883' \
  EMQX_LISTENERS__WS__DEFAULT__BIND='127.0.0.1:8083' \
  EMQX_LISTENERS__WSS__DEFAULT__BIND='127.0.0.1:8084' \
  EMQX_DASHBOARD__LISTENERS__HTTP__BIND=18083 \
  EMQX_NODE__DATA_DIR="./data1" \
./bin/emqx start

次に、以下のコマンドで2つ目のノードを起動し、手動でクラスターに参加させます。ポート競合を避けるため、ノードごとに異なるリスニングポートを使用し、ログファイルや内部データベース用のディレクトリも分ける必要があります。

bash

  EMQX_NODE__NAME='emqx2@127.0.0.1' \
  EMQX_LOG__FILE_HANDLERS__DEFAULT__FILE='log2/emqx.log' \
  EMQX_LISTENERS__TCP__DEFAULT__BIND='127.0.0.1:1882' \
  EMQX_LISTENERS__SSL__DEFAULT__BIND='127.0.0.1:8882' \
  EMQX_LISTENERS__WS__DEFAULT__BIND='127.0.0.1:8082' \
  EMQX_LISTENERS__WSS__DEFAULT__BIND='127.0.0.1:8085' \
  EMQX_DASHBOARD__LISTENERS__HTTP__BIND=18082 \
  EMQX_NODE__DATA_DIR="./data2" \
./bin/emqx start
  EMQX_NODE__NAME='emqx2@127.0.0.1' ./bin/emqx ctl cluster join 'emqx1@127.0.0.1'

上記は手動でクラスターを作成する例です。自動クラスタリングによる作成方法は自動クラスタリングセクションを参照してください。

なお、この構成は本番環境での利用は推奨されません。

Kubernetes

EMQX Operator

EMQX クラスター管理

API リファレンス

パスワード認証

監視

アクセスコントロール

統合

管理

OpenTelemetry との統合

エンドツーエンドトレース

プラグインカタログ

JT/T 808 ゲートウェイ

GB/T 32960 ゲートウェイ

Volcengine RTC

シナリオ

GPT-Realtime

クラスターの作成と管理 ​

基本概念 ​

ノード名 ​

ノードディスカバリー ​

手動クラスタリングと自動クラスタリング ​

はじめる前に ​

ノード名の設定 ​

ノードクッキーの設定 ​

ネットワーク環境の設定 ​

クイックスタート ​

手動クラスタリング ​

自動クラスタリング ​

静的ノードリストによる自動クラスタリング ​

DNSレコードによる自動クラスタリング ​

DNSサービスの設定 ​

DNSレコードによる自動クラスタリングの設定 ​

etcdによる自動クラスタリング ​

Kubernetes上での自動クラスタリング ​

クラスターの管理 ​

クラスター状態の確認 ​

クラスターからの離脱 ​

ネットワークプロトコルの設定 ​

疑似分散クラスター ​

クラスターの作成と管理

基本概念

ノード名

ノードディスカバリー

手動クラスタリングと自動クラスタリング

はじめる前に

ノード名の設定

ノードクッキーの設定

ネットワーク環境の設定

クイックスタート

手動クラスタリング

自動クラスタリング

静的ノードリストによる自動クラスタリング

DNSレコードによる自動クラスタリング

DNSサービスの設定

DNSレコードによる自動クラスタリングの設定

etcdによる自動クラスタリング

Kubernetes上での自動クラスタリング

クラスターの管理

クラスター状態の確認

クラスターからの離脱

ネットワークプロトコルの設定

疑似分散クラスター