EMQX Enterprise

日本語

简体中文
English

日本語

简体中文
English

Appearance

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

プラグインの管理 ​

このページでは、EMQXにおけるプラグインのライフサイクルについて説明し、ダッシュボード、CLI、REST APIを使用してプラグインのインストール、設定、起動、停止、アンインストール、アップグレードを行う方法を解説します。

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

EMQXプラグインは主に以下の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コールバック関数はEMQXクラスターの各ノードで呼び出されます。ローカルシステムの状態（例：ネットワークの可用性）に依存した設定検証は避けてください。ノード間で結果が不整合になる恐れがあります。代わりに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はダッシュボード、CLI、APIを通じてプラグインパッケージのインストール、アンインストール、管理をサポートしています。

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

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

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

セキュリティ上の理由から、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のtarballが用意されているとします。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のtarballが用意されているとします。APIを使用してプラグインをインストールするには、以下の手順に従ってください。

  1. インストールを許可します。以下のコマンドを実行してプラグインのインストールを有効にします。

    emqx ctl plugins allow my_emqx_plugin-1.0.0

  2. curlを使用してAPIに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起動前にプラグインを事前インストールする ​

EMQX起動時にプラグインを即時利用可能にしたい場合（例：カスタムDockerイメージをビルドする場合）、プラグインパッケージを展開し、EMQXを事前に設定しておくことが可能です。

以下の手順はDockerfileの例ですが、deb/rpmやベアメタルなど他のデプロイ方法にも同様に適用できます。

  1. プラグインtarballをpluginsディレクトリにコピーし展開します。

    dockerfile
    COPY --chown=emqx:emqx my_emqx_plugin-1.0.0.tar.gz /opt/emqx/plugins/my_emqx_plugin-1.0.0.tar.gz

RUN cd /opt/emqx/plugins && \
    mkdir -p my_emqx_plugin-1.0.0 && \
    tar zxf my_emqx_plugin-1.0.0.tar.gz -C my_emqx_plugin-1.0.0

  2. EMQXのベース設定ファイルにプラグインを登録し、起動時に自動的に起動するようにします。以下をbase.hoconに追記します。

    dockerfile
    RUN cat <<EOF >> /opt/emqx/etc/base.hocon
plugins {
    states = [
        {
            name_vsn = "my_emqx_plugin-1.0.0"
            enable = true
        }
    ]
}
EOF

    enable = trueに設定すると自動起動し、enable = falseにするとインストールのみで起動しません。

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

EMQXでは同一プラグインの複数バージョンを同時にインストールすることはできません。

新しいバージョンをインストールするには：

  • まず古いバージョンをアンインストールします。
  • その後、新しいバージョンをインストールします。

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