Skip to content

プラグイン管理 ​

このページでは、EMQXプラグインのデプロイおよび管理方法について説明します。プラグインは、ダッシュボード、CLI、REST APIを通じてクラスター全体で管理することができ、また事前にデプロイされたプラグインを個々のノードにピン留めすることも可能です。

EMQXは以下のプラグイン管理モードをサポートしています。

  • クラスター管理プラグイン:EMQXはプラグインパッケージと設定をクラスターのノードに配布し、その有効状態をplugins.statesに記録します。
  • ノードピン留めプラグイン:EMQX 6.2.4以降、ノードはnode.pinned_pluginsに名前とバージョンを記載することで、クラスターのプラグイン設定とは独立して事前にデプロイされたプラグインを単独で実行できます。

プラグインのライフサイクル ​

クラスター管理プラグインは主に以下の3つのライフサイクル状態を経ます。

  • インストール済み:プラグインのコードと設定は読み込まれていますが、アプリケーションはまだ起動していません。
  • 起動済み:プラグインが実行中で、EMQXと積極的に連携しています。
  • アンインストール済み:プラグインがシステムから完全に削除されています。

インストールプロセス ​

インストールの流れは以下の通りです。

  1. プラグインパッケージ(make relコマンドで作成されたtarball)をダッシュボード、API、またはCLI経由でアップロードします。詳細なインストール手順はプラグインのインストールと管理を参照してください。
  2. プラグインパッケージはEMQXクラスターの各ノードに転送されます。
  3. 各ノード上で以下の処理が行われます:
    • tarballはEMQXルートディレクトリのpluginsサブディレクトリに保存されます(plugins.install_dirオプションで上書き可能):$EMQX_ROOT/plugins/my_emqx_plugin-1.0.0.tar.gz
    • 同じディレクトリに展開されます:$EMQX_ROOT/plugins/my_emqx_plugin-1.0.0/
    • 初期設定(メインプラグインのアプリからのconfig.hocon)が$EMQX_DATA_DIR/plugins/my_emqx_plugin/config.hoconにコピーされます。
    • Avroスキーマが存在する場合は検証のために読み込まれます。
    • プラグインコードはノードにロードされますが、アプリケーションは起動されません。
    • プラグインはEMQX設定のplugins.statesにdisabledとして登録されます。

TIP

クラスター管理プラグインの場合、EMQX設定にはプラグインの状態(enableフラグのtrueまたはfalse)のみが保存されます。完全なプラグイン設定はノード上の$EMQX_DATA_DIR/plugins/my_emqx_plugin/config.hoconファイルにあります。

設定 ​

インストール後、プラグイン設定はダッシュボードまたはAPIを通じて更新可能です。

  • 新しい設定はAvroスキーマ(存在する場合)に対して検証されます。
  • 更新は同じバージョンのプラグインを報告するノードに配布されます。
  • プラグインのon_config_changed/2コールバック関数が呼び出されます。プラグインが新しい設定を受け入れた場合、$EMQX_DATA_DIR/plugins/my_emqx_plugin/config.hoconファイルに永続化されます。

TIP

アプリケーションが起動していなくてもon_config_changed/2コールバック関数は呼び出されます。

TIP

on_config_changed/2コールバックは設定更新を受け取った各ノードで実行されます。ローカルシステム状態(例:ネットワークの可用性チェック)に依存した設定検証は避けてください。ノード間で結果が不整合になる可能性があります。代わりにon_health_check/1を使用してランタイムチェックを行い、リソースが利用できない場合は不健康状態を報告してください。

設定ファイルの場所 ​

関連する設定ファイルの場所は2つあります。

  • インストールされたプラグインパッケージ内のバンドル済みデフォルトファイル:

    • Docker環境: /opt/emqx/plugins/my_emqx_plugin-1.0.0/my_emqx_plugin-1.0.0/priv/config.hocon
    • deb/rpm環境: /usr/lib/emqx/plugins/my_emqx_plugin-1.0.0/my_emqx_plugin-1.0.0/priv/config.hocon
  • ダッシュボードまたはAPI経由で設定が保存された後にEMQXが管理する永続化されたプラグイン設定ファイル:

    • Docker環境: /opt/emqx/data/plugins/my_emqx_plugin/config.hocon
    • deb/rpm環境: /var/lib/emqx/plugins/my_emqx_plugin/config.hocon

priv/config.hoconはパッケージ化されたデフォルトテンプレートであり、data/plugins/.../config.hoconはEMQXが設定変更を保存した後に使用する永続化されたプラグイン設定ファイルです。

起動 ​

プラグインはダッシュボード、API、またはCLIから手動で起動します。起動時には:

  • プラグインのアプリケーションが起動されます。
  • プラグインはEMQX設定のplugins.statesにenabledとして登録されます。

プラグインが起動している状態で情報が要求されると、on_health_check/1コールバック関数が呼び出され、プラグインの状態が取得されます。

停止 ​

プラグインを停止すると:

  • プラグインのアプリケーションが停止されます。
  • プラグインはEMQX設定のplugins.statesにdisabledとして登録されます。

プラグインのアプリケーションは停止されますが、コードはノードにロードされたままです。停止したプラグインでも設定は可能です。

アンインストールプロセス ​

アンインストールの流れは以下の通りです。

  1. プラグインが実行中の場合は停止します。
  2. プラグインのコードをノードからアンロードします。
  3. パッケージファイルをノードから削除します(設定ファイルは保持されます)。
  4. プラグインはEMQX設定のplugins.statesから登録解除されます。

プラグインパッケージはダッシュボードまたはCLIからアンインストール可能です。詳細はプラグインのインストールと管理を参照してください。

クラスター参加時の挙動 ​

EMQXノードがクラスターに参加するとき、プラグインとその設定はノードのローカルファイルシステムに存在するため、実際にインストールおよび設定されていない場合があります。

新規ノードは以下の処理を行います。

  • クラスター参加プロセスの一環としてグローバルなEMQX設定を取得します。
  • EMQX設定からプラグインの状態(どのプラグインがインストールされ有効か)を把握します。
  • 他のノードからプラグインとその実際の設定を要求します。
  • プラグインをインストールし、有効なものを起動します。

プラグインのインストールと管理 ​

EMQXは、EMQX起動前にノードピン留めプラグインを事前デプロイする方法と、ダッシュボード、CLI、APIを通じてクラスター管理プラグインをインストール・管理する方法をサポートしています。

ノードピン留めプラグインの事前デプロイ ​

EMQX 6.2.4以降、個々のノードに事前デプロイされたプラグインをピン留めできます。このモードは、プラグインがコンテナイメージやノード固有のデプロイアーティファクトに組み込まれている場合に有用です。

  1. プラグインパッケージを<plugins.install_dir>に展開します。EMQX起動前に、展開されたファイルは<plugins.install_dir>/<name-vsn>に配置され、そのディレクトリ直下にrelease.jsonが存在している必要があります。例:

    dockerfile
    COPY --chown=emqx:emqx my_emqx_plugin-1.0.0.tar.gz /tmp/my_emqx_plugin-1.0.0.tar.gz
    
    RUN mkdir -p /opt/emqx/plugins/my_emqx_plugin-1.0.0 && \
        tar zxf /tmp/my_emqx_plugin-1.0.0.tar.gz \
        -C /opt/emqx/plugins/my_emqx_plugin-1.0.0
  2. 読み取り専用のnode.pinned_plugins設定にプラグイン名とバージョンを追加します。コンテナイメージの場合は対応する環境変数を設定します。

    dockerfile
    ENV EMQX_NODE__PINNED_PLUGINS="my_emqx_plugin-1.0.0"

    その他のデプロイ方法ではemqx.confに以下を設定します。

    hocon
    node.pinned_plugins = ["my_emqx_plugin-1.0.0"]

    複数のプラグインをリストできます。各エントリは有効な<name-vsn>識別子でなければならず、同じプラグイン名の異なるバージョンをリストに含めることはできません。EMQXはnode.pinned_pluginsに設定された順序でプラグインを起動し、その後plugins.statesのプラグインを起動します。リストを変更するにはノード設定を更新し、ノードを再起動してください。クラスター参加、API呼び出し、設定インポートではこの設定を変更できません。

ノードピン留めプラグインの動作は以下の通りです。

  • EMQXは展開済みディレクトリから直接プラグインを実行します。クラスター参加時にプラグインパッケージの配布や設定の同期は行いません。

  • プラグインは常に有効であり、plugins.statesのエントリ、emqx ctl plugins allowの許可、インストールコマンドを必要としません。同じプラグイン名のplugins.statesのエントリはバージョンに関わらず制御しません。

  • EMQXはパッケージのpriv/config.hoconから初期設定を構築し、存在する場合はetc/plugins/<name>.hoconを深くマージします。ダッシュボードまたはAPIで設定を保存すると、EMQXはdata/plugins/<name>/config.hoconを完全な設定として使用します。設定変更は同じプラグインバージョンを報告するノードにのみ適用されます。

  • emqx ctl plugins start|stop|restart <name-vsn>コマンドでピン留めされたノード上のプラグインを管理します。CLIで停止されたノードピン留めプラグインは、ノードがすべてのプラグインを再起動するまで(ノード再起動やクラスター参加後など)停止状態のままです。

  • ダッシュボードとREST APIはプラグイン設定を更新できますが、ピン留めされたインスタンスのライフサイクル管理はできません。ライフサイクル操作は以下の場合にHTTP 409エラーとPLUGIN_PINNEDエラーコードを返します。

    • リクエストを処理するノードがnode.pinned_pluginsに同名プラグインを設定している場合。
    • リクエストされたプラグインバージョンを報告するすべてのノードがそのバージョンをノードピン留めプラグインとして設定している場合。

    別のノードが同じプラグインバージョンをクラスター管理プラグインとして実行している場合、そのノードから開始されたクラスター全体の操作はクラスター管理インスタンスにのみ影響します。

  • プラグインディレクトリが存在しないか起動に失敗した場合、EMQXはpinned_plugin_unavailable:<name-vsn>アラームを発生させ、ノードの起動を継続します。後に起動に成功するとアラームはクリアされます。

ダッシュボード経由でのパッケージインストール ​

プラグインがすでにビルドされ、my_emqx_plugin-1.0.0.tar.gzが用意されているとします。ダッシュボードから直接コンパイル済みプラグインパッケージをインストールするには、以下の手順に従ってください。

重要なセキュリティアップデート

セキュリティ上の理由から、EMQXはダッシュボード経由のプラグインインストールに対して明示的な許可を要求するようになりました。

  • インストール開始前に許可を与える必要があります。
  • 許可状態は一時的で、インストール完了後に自動的に取り消されます。
  • クラスター環境では、すべてのノードで許可を与える必要があります。
  1. CLIで以下のコマンドを実行し、プラグインインストールを明示的に許可します。

    bash
    emqx ctl plugins allow $NAME-$VSN
    • {NAME}:プラグイン名(例:my_emqx_plugin)
    • {VSN}:プラグインのバージョン(例:1.0.0)

    このコマンド実行後、ダッシュボードからインストールを進められます。

  2. EMQXダッシュボードの Management -> Plugins に移動します。

  3. + Install plugin ボタンをクリックし、インストールページを開きます。

  4. プラグインパッケージを選択またはドラッグしてアップロードします。

    plugin-list-empty

  5. Install ボタンをクリックしてインストールを完了します。プラグインリストに新しいプラグインが表示されます。

    plugin-list-installed

これでプラグインの起動・停止や設定が可能です。ダッシュボードからプラグインパッケージをアンインストールするには、プラグインリストページのActions列のMoreメニューからUninstallボタンをクリックしてください。

以前に許可したプラグインの許可を取り消すには、以下のいずれかの方法を実行します。

  1. プラグインをアンインストールする(すでにインストール済みの場合)。
  2. 以下のコマンドで明示的に許可を取り消す。
bash
emqx ctl plugins disallow $NAME-$VSN

CLI経由でのパッケージインストール ​

プラグインがすでにビルドされ、my_emqx_plugin-1.0.0.tar.gzが用意されているとします。CLIから直接コンパイル済みプラグインパッケージをインストールするには、以下の手順に従ってください。

  1. EMQXノード上で、tarballをEMQXプラグインディレクトリにコピーします。

    $ cp my_emqx_plugin-1.0.0.tar.gz $EMQX_HOME/plugins
  2. プラグインをインストールします。

    $ emqx ctl plugins install my_emqx_plugin-1.0.0

    クラスター内のすべての稼働ノードにインストールする場合は、--clusterフラグを追加します。

    $ emqx ctl plugins install my_emqx_plugin-1.0.0 --cluster
  3. プラグインリストを確認します。

    $ emqx ctl plugins list
  4. プラグインを起動・停止します。

    $ emqx ctl plugins start my_emqx_plugin-1.0.0
    $ emqx ctl plugins stop my_emqx_plugin-1.0.0
  5. プラグインをアンインストールします。

    $ emqx ctl plugins uninstall my_emqx_plugin-1.0.0

API経由でのパッケージインストール ​

プラグインがすでにビルドされ、my_emqx_plugin-1.0.0.tar.gzが用意されているとします。APIを使ってプラグインをインストールするには、以下の手順に従ってください。

  1. インストールを許可します。以下のコマンドを実行してプラグインのインストールを許可してください。

    emqx ctl plugins allow my_emqx_plugin-1.0.0
  2. プラグインをインストールします。curlコマンドでPOSTリクエストを送信します。

    $ curl -u $KEY:$SECRET -X POST http://$EMQX_HOST:18083/api/v5/plugins/install -H "Content-Type: multipart/form-data" -F "plugin=@my_emqx_plugin-1.0.0.tar.gz"
  3. プラグインリストを確認します。インストールが成功したかを確認するには以下を実行します。

    $ curl -u $KEY:$SECRET http://$EMQX_HOST:18083/api/v5/plugins | jq
  4. プラグインを起動・停止します。以下のコマンドを使用してください。

    $ curl -s -u $KEY:$SECRET -X PUT "http://$EMQX_HOST:18083/api/v5/plugins/my_emqx_plugin-1.0.0/start"
    $ curl -s -u $KEY:$SECRET -X PUT "http://$EMQX_HOST:18083/api/v5/plugins/my_emqx_plugin-1.0.0/stop"

プラグインのアップグレード ​

クラスター管理プラグインをアップグレードするには:

  • まず古いバージョンをアンインストールします。
  • 次に新しいバージョンをインストールします。

プラグインの設定はインストール間で保持されます。

EMQX 6.2.4以降、クラスター内の異なるノードが同じプラグインの異なるバージョンをピン留めできます。ノードがnode.pinned_pluginsにプラグインバージョンをリストしている場合、EMQXはそのピン留めされたバージョンのみを実行し、同じプラグインのすべてのバージョンに対するplugins.statesのエントリは無視されます。プラグイン開発者は、これらのバージョンが共有データベーステーブル、ノード間RPC、プラグイン設定フォーマットに関して互換性を保つように注意する必要があります。