クラスターの作成と管理

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

注意

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

基本概念

EMQXクラスターの基本知識や動作については、ClusterおよびArchitectureをご参照ください。クラスターを作成するには、以下の概念にも慣れておく必要があります。

ノード名

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クラスターのセットアップを簡素化し、ノードの動的な追加・削除を容易にします。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のnode.cookieで設定します。設定ファイルにクッキー値を直接書きたくない場合は、file:// URLを利用します。

hocon

node.cookie = "file:///run/secrets/emqx-cookie"

EMQX_NODE__COOKIE環境変数もfile:// URLを受け付けます。通常ファイル、FIFO、起動時読み込みの詳細はLoad the Node Cookie from a Fileを参照してください。マジッククッキーの詳細はDistributed Erlang - Securityをご覧ください。

ネットワーク環境の設定

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

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

1台のサーバーに複数のEMQXノードを展開する場合、各ノードは異なるクラスター通信ポートを使用します。ファイアウォール設定の詳細はIntra-cluster communication portを参照してください。

クイックスタート

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

TIP

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

任意のノード上で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が別のクラスターに参加したい場合、まず現在のクラスターから離脱する必要があります。離脱方法はLeave Clusterを参照してください。

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

bash

$ ./bin/emqx ctl cluster status

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

これで2ノードのクラスター作成に成功しました。クラスター状態の監視や管理方法は、Query Cluster Status、Manage Cluster Nodes、Configure Network Protocolsをご覧ください。

EMQX v5.9.0以降はダッシュボードからノードの招待や管理も可能で、より直感的かつ使いやすくなっています。詳細はCluster Settingsをご参照ください。

自動クラスタリング

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

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

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

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

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

例：

bash

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

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

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

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

DNS（Domain Name System）は、ドメイン名の問い合わせに対して対応するIPアドレス（Aレコード）を返す仕組みです。DNSは1つのドメイン名に複数のAレコード（複数IPアドレス）を持てるため、1つの名前に対して複数IPアドレスを対応付けることができます。EMQXのDNS自動クラスタリングはこの1対多のマッピングを利用し、クラスター内のすべてのノードを特定し、各ノードがクラスターに参加できるようにします。

DNSサービスの設定

ほとんどのパブリッククラウドサービスはDNSサービスを提供しています。ドメイン名を割り当てた後、すべてのEMQXノードのIPアドレスをそのドメインのAレコードに追加するだけで設定が完了します。プライベートクラウドや内部ネットワークに展開する場合は、BINDなどのDNSソフトウェアで独自の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）を示す期間です。

設定完了後、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 APIServerからendpointsリソース経由でクラスターのノード情報を取得できるようRBACを作成する必要があります。設定方法はUsing RBAC Authorizationをご覧ください。

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 はノード名のサフィックスで、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'

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

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

Kubernetes

EMQX Operator

EMQX クラスター管理

API リファレンス

パスワード認証

監視

アクセスコントロール

統合

管理

Prometheus との統合

OpenTelemetry との統合

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

プラグインカタログ

JT/T 808 ゲートウェイ

GB/T 32960 ゲートウェイ

Volcengine RTC

シナリオ

GPT-Realtime

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

基本概念 ​

ノード名 ​

ノードディスカバリー ​

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

はじめる前に ​

ノード名の設定 ​

ノードクッキーの設定 ​

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

クイックスタート ​

手動クラスタリング ​

自動クラスタリング ​

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

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

DNSサービスの設定 ​

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

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

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

クラスターの管理 ​

クラスター状態の確認 ​

クラスターからの離脱 ​

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

疑似分散クラスター ​

クラスターの作成と管理

基本概念

ノード名

ノードディスカバリー

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

はじめる前に

ノード名の設定

ノードクッキーの設定

ネットワーク環境の設定

クイックスタート

手動クラスタリング

自動クラスタリング

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

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

DNSサービスの設定

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

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

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

クラスターの管理

クラスター状態の確認

クラスターからの離脱

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

疑似分散クラスター