Mule アップグレードツール
The Mule upgrade tool is a command line utility for updating and upgrading standalone on-premise instances of Mule 4. Download the tool and integrate it with your existing automated processes and workflows by using scripts and cron jobs.
現在の Mule インスタンスに Runtime Manager エージェントがインストールされている場合、アップグレードツールは、アップグレードプロセスの一環としてエージェントのバージョンも更新します。
Mule インスタンスを正常にアップグレードした後に、アップグレードされた Mule インスタンスに Anypoint Monitoring エージェントがインストールされている場合、エージェントの更新はサポートされていないため、エージェントを再インストールします。「Anypoint Monitoring エージェントの更新」を参照してください。
Mule アップグレードツールは、ツールを使用して各ノードを手動でアップグレードすることにより、クラスター化された Mule インスタンスのアップグレードをサポートしています。アップグレードを続行する方法についての追加情報は、クラスター化された Mule アプリケーションのアップグレードを参照してください。このツールの使用を強くお勧めしますが、現在の Mule インスタンスをアップグレードするのに厳格に必要なわけではありません。完全に手動でのアップグレードについては、「Upgrading an On-Premises Mule Instance Managed Through Runtime Manager (Runtime Manager で管理されているオンプレミス Mule インスタンスのアップグレード)」を参照してください。
始める前に
アップグレードを始める前に、次の準備が整っていることを確認します。
-
最新の修正とセキュリティ機能強化を備えたツールが実行されるように、最新バージョンの Mule アップグレードツールをご使用ください。
ヘルプセンターから Mule アップグレードツールをダウンロードしてください。
-
現在運用中の Mule 4 インスタンスはアップグレードに備えて停止状況にあります。
Mule アップグレードツールを使用して Mule バージョン 4.1.1 ～ 4.1.4 のアップグレードを行う場合は、2022 年 1 月 20 日以降にリリースされたパッチ更新からアップグレードを行う必要があります。2022 年 1 月 20 日より前のバージョン 4.1.1 ～ 4.1.4 のリリースは現在のところツールでサポートされておらず、アップグレードしようとすると、最初にサポートされるバージョンにアップグレードしてからでないと Mule バージョンをアップグレードできない旨のエラーメッセージが表示されます (Mule Upgrades and Patch Updates を参照)。
-
最新の Mule Runtime Engine ディストリビューションをシステムにダウンロードして展開してある。
Mule アップグレードツールには、Mule Runtime のフルディストリビューションが必要です。必ずファイル名に (
patch ではなく) distribution という単語が含まれているフル Mule Runtime ディストリビューションをダウンロードしてください。たとえば、Mule 4.4.0 の 20220221 ディストリビューションであれば、ファイル名は mule-ee-distribution-standalone-4.4.0-20220221.zip となります。ヘルプセンターから Mule Runtime ディストリビューションをダウンロードしてください。
-
ファイルシステムに 2 GB 以上の空きディスクスペースと、Mule ディストリビューションをインストールするためのアクセス権限がある。
-
(Windows 環境の場合) PowerShell スクリプトの実行ポリシーが [Unrestricted] に設定されている。
Mule のアップグレードまたは更新
クラスター化された Mule インスタンスを最新バージョンにアップグレードまたは更新する手順は、次のとおりです。
-
Mule アップグレードツールをダウンロードしてある
$MULE_HOME/tools ディレクトリに移動します。 -
最新の Mule Runtime ディストリビューションをダウンロードして展開してあるディレクトリの絶対パスを引数として指定し、
upgrade -n サブコマンドを実行します。例:$MULE_HOME/tools/upgrade-tool upgrade -n <newMuleDistributionAbsolutePath>このスクリプトの出力は次のようになります。
➜ tools ./upgrade-tool upgrade -n /Users/me/mule-download/upgrade/mule-enterprise-standalone-4.5.0/ Mule Runtime Upgrade Tool ───────────────────────── INFO: Initiating upgrade process... INFO: Upgrading distribution at path [/opt/mule/mule-enterprise-standalone-4.4.0-20221212] with version: [4.4.0-20221212] to distribution at path [/opt/mule/mule-enterprise-standalone-4.4.0-20230217] with version [4.4.0-20230217] ... Do you want to proceed with the upgrade? To confirm please, enter [yes, no] (default: no): yes WARN: Unknown file tools/mule-runtime-upgrade-tool-logs/mule-runtime-upgrade-tool-logs.log was found in the runtime installation, and will be kept. WARN: A version in your MULE_HOME directory name was detected: /opt/mule/mule-enterprise-standalone-4.4.0-20221212, beware it may not match the current installed version inside the directory. INFO: Upgrade process finished successfully. Verifying Mule Agent ──────────────────── INFO: Mule Agent not installed, skipping setup
これで、既存の Mule インスタンスがアップグレードされたため、アップグレードツールで必要でなくなった最近ダウンロードしたバージョン (例では <newMuleDistributionAbsolutePath> として参照) を削除できます。
対象の場所が $MULE_HOME であるため、アップグレードした Mule Runtime インスタンスによって以前のバージョンが置き換えられます。
|
アップグレードまたは更新のロールバック
Mule アップグレードツールは、アップグレードまたは更新プロセスを開始する前にアップグレードまたは更新するクラスター化された Mule インスタンスのバックアップを作成するため、クラスター化された Mule インスタンスをアップグレードまたは更新した後で、以前の状態に復元できます。バックアップは $MULE_HOME/.upgrade-tool-backup フォルダーに保存されます。
ロールバックを実行する手順は、次のとおりです。
-
Mule アップグレードツールをダウンロードしてある
$MULE_HOME/tools ディレクトリに移動します。 -
rollback サブコマンドを次のように実行します。$MULE_HOME/tools/upgrade-tool rollback
ファイルの競合の解決
Mule アップグレードツールは、現在の Mule ディストリビューションと新しいディストリビューションの設定ファイルを比較し、変更された内容を検出して失われないようにします。Mule アップグレードツールが新しい Mule ディストリビューションの設定ファイルで変更を検出すると、自動的に競合を解決し、アップグレードを続行しようとします。競合を自動的に解決できない場合、ツールでは次のアクションを実行します。
-
upgrade サブコマンドの実行を失敗させて、エラーメッセージを表示します。 -
競合が検出された Mule 設定ファイルの名前をログ出力に記録します。
-
競合が検出された設定ファイルを、現在の Mule ディストリビューションの
${MULE_HOME}/conf ディレクトリから ${MULE_HOME}/upgrade-tool/mule-config-conflicts/to_review にコピーします。 -
設定ファイルの元のコンテンツを、新しい Mule ディストリビューションから
${MULE_HOME}/upgrade-tool/mule-configs-conflicts/new-${MULE_HOME_NEW_FOLDER_NAME} フォルダーにコピーします。
設定ファイルの競合によってアップグレードプロセスが失敗した場合は、以下の手順に従って競合を解決してから、アップグレードプロセスを続行してください。
Mule 設定ファイルの競合を解決する手順
アップグレード中に競合を解決する手順は、次のとおりです。
-
アップグレード中の現在の Mule ディストリビューションの
${MULE_HOME}/upgrade-tool/mule-config-conflicts/to_review/ フォルダーで、競合が検出されたファイルのいずれかを選択します。 -
ファイル比較ツール (
diff など) を使用して、次のパスのファイルのコンテンツを比較します。-
${MULE_HOME}/upgrade-tool/mule-config-conflicts/to_review/fileWithConflicts.conf -
${MULE_HOME}/upgrade-tool/mule-configs-files/new-${MULE_HOME_NEW_FOLDER_NAME}/fileWithConflicts.conf
-
-
相違点を確認したら、変更内容をマージするか、または破棄してください。
-
変更内容をマージする場合は、新しい設定ファイル
${MULE_HOME}/upgrade-tool/mule-config-conflicts/new-${MULE_HOME_NEW_FOLDER_NAME}/fileWithConflicts.conf ファイルから目的の変更内容を追加して前の設定ファイル ${MULE_HOME}/upgrade-tool/mule-config-conflicts/to_review/fileWithConflicts.conf を変更します。次に、マージしたファイルを ${MULE_HOME}/upgrade-tool/mule-config-conflicts/ready フォルダーにコピーします。 -
変更内容を破棄して前の設定を保持する場合は、前の設定ファイル
${MULE_HOME}/upgrade-tool/mule-config-conflicts/to_review/fileWithConflicts.conf を ${MULE_HOME}/upgrade-tool/mule-config-conflicts/ready フォルダーに移動します。変更内容を破棄すると、古い設定が新しい Mule ディストリビューションで使用される場合があります。
-
-
${MULE_HOME}/upgrade-tool/mule-config-conflicts/to_review フォルダー内の各設定ファイルに対してステップ 1 ～ 3 を繰り返します。 -
upgrade サブコマンドの実行を再試行します。アップグレードが正常に完了すると、ツールは
${MULE_HOME}/upgrade-tool/mule-config-conflicts フォルダーを削除し、将来のアップグレードに備えてクリーンな環境に戻します。
無人のアップグレードまたは更新
対象環境でアップグレードを実行する前に、別の環境で競合を解決しておけば、アップグレードや更新を無人で実行できます。この手順は、別の環境で設定する現在の Mule ディストリビューションと新しい Mule ディストリビューションが、メイン環境の現在の Mule ディストリビューションと新しい Mule ディストリビューションのバージョンと一致する場合にのみ使用できます。
-
ユーザーインタラクションが可能な環境で、Mule 設定ファイルの競合を解決する手順の説明に従ってすべての競合を確認して解決します。
-
対象環境で、
${MULE_HOME_WITH_USER_INTERACTION}/upgrade-tool/mule-config-conflicts/ready/ から ${MULE_HOME_WITHOUT_USER_INTERACTION}/upgrade-tool/mule-config-conflicts/ready/ にファイルをコピーします。 -
対象環境で
upgrade サブコマンドを実行します。
Mule アップグレードツールのログの設定
デバッグのログを有効化することで、Mule アップグレードツールの各操作の詳細情報を追加したり、ツールがログを保存するフォルダーを変更したり、カスタマイズされたログ設定ファイルを使用したりできます。
カスタム Log4j ファイルの指定
デフォルトでは、Mule アップグレードツールは $MULE_HOME/tools/upgrade-tool フォルダーにある log4j2-upgrade-tool.xml ファイルを使用します。
カスタム Log4j ファイルを使用するには、-l パラメーターを使用して、使用するカスタム Log4j 設定ファイルのファイル名を指定します。例:
$MULE_HOME/tools/upgrade-tool -l myLog4j2File.xml upgradeデバッグレベルログの有効化
デバッグログを有効化する手順は、次のとおりです。
-
ツールで使用する Log4j ファイルを開きます。
-
Log4j ファイルの次の行で、
level プロパティの値を INFO から DEBUG に変更します。<Logger level="INFO" name="com.mulesoft.runtime.upgrade.tool.service" additivity="false">
ログ出力のカスタマイズ
デフォルトでは、Mule アップグレードツールは ./mule-Runtime-upgrade-tool-logs ディレクトリにログファイルを保存します。
ファイル名、出力パス、ログパターンを変更する手順は、次のとおりです。
-
ツールで使用する Log4j ファイルを開きます。
-
fileName プロパティと filePattern プロパティに希望する値を指定します。<RollingFile name="RollingFile" fileName="./mule-runtime-upgrade-tool-logs/mule-runtime-upgrade-tool-logs.log" filePattern="./mule-runtime-upgrade-tool-logs/$${date:yyyy-MM}/mule-runtime-upgrade-tool-logs-%d{-dd-MMMM-yyyy}-%i.log.gz" >
Mule アップグレードツールのサブコマンドとオプション
Mule アップグレードツールの実行時に使用できるサブコマンドとオプションを下表に示します。
| サブコマンド | 説明 | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
ローカル Mule インスタンスを、使用できる最新バージョンにアップグレードします。
|
||||||||||||
|
Mule インスタンスを以前の状態に戻します。このサブコマンドは、ツールでアップグレードを正常に完了した後でのみ使用できます。
|
||||||||||||
|
現在の Mule インスタンスに関して、次のような情報を提供します。
|
一般的なエラーのトラブルシューティング
以下に、アップグレードツールから返される最も一般的なエラーメッセージの一部と、それぞれの説明および解決策を示します。
Missing required subcommand (必要なサブコマンドがありません)
./upgrade-tool Mule Runtime Upgrade Tool ───────────────────────── Missing required subcommand Usage: upgrade-tool [-hV] [COMMAND] Try 'upgrade-tool --help' for more information.
Missing required option (必須のオプションがありません)
./upgrade-tool upgrade Mule Runtime Upgrade Tool ───────────────────────── Missing required option: '--new-mule-distro=<newMuleDistro>' Usage: upgrade-tool upgrade [-dfh] -n=<newMuleDistro> [-o=<oldMuleDistro>] Try 'upgrade-tool upgrade --help' for more information.
解決策
次のコマンドを実行して、特定のサブコマンドで必要な引数に関する情報を確認します。
./upgrade-tool upgrade --help
このコマンドを実行すると、追加情報が次のように表示されます。
Mule Runtime Upgrade Tool
─────────────────────────
Usage: upgrade-tool upgrade [-dfh] -n=<newMuleDistro> [-o=<oldMuleDistro>]
Upgrades a Mule Runtime to a newer version
-d, --dry-run Simulate upgrade process without performing any permanent
changes to the current Mule Runtime Distribution.
-f, --force Perform all the destructive operations like overwriting the
backup or removing the applied patches without user
confirmation
-h, --help Display this help message
-n, --new-mule-distro=<newMuleDistro>
File path of the newer Mule Runtime distribution used for the
upgrade
-o, --old-mule-distro=<oldMuleDistro>
File path of Mule Runtime distribution to upgrade
Usage: 行では、省略可能なオプションと引数が角括弧 ([,]) 内に示されます。角括弧が付いていないオプションと引数は必須です。
No space left on device (デバイスにスペースがありません)
$ ./upgrade-tool upgrade -n /tmp/mule-enterprise-standalone-4.4.0-20211104 Mule Runtime Upgrade Tool ───────────────────────── INFO: Initiating upgrade process... INFO: Upgrading distribution at path [/opt/mule-enterprise-standalone-4.4.0-20211026] with version: [4.4.0-20211104] to distribution at path [/tmp/mule-enterprise-standalone-4.4.0-20211104] with version [4.4.0-20211104] ... ERROR: Version of new Mule distribution 4.4.0-20211104 should be newer than old Mule distribution: 4.4.0-20211104 ERROR: There's not enough disk space for performing the upgrade. ERROR: No space left on device No space left on device
Version should be newer (新しいバージョンが必要です)
./upgrade-tool upgrade -n /tmp/mule-enterprise-standalone-4.4.0-20211104 Mule Runtime Upgrade Tool ───────────────────────── INFO: Initiating upgrade process... INFO: Upgrading distribution at path [/opt/mule-enterprise-standalone-4.4.0-20211026] with version: [4.4.0-20211104] to distribution at path [/tmp/mule-enterprise-standalone-4.4.0-20211104] with version [4.4.0-20211104] ... ERROR: Version of new Mule distribution 4.4.0-20211104 should be newer than old Mule distribution: 4.4.0-20211104
Missing reading permissions (参照権限がありません)
./upgrade-tool upgrade -n /tmp/mule-enterprise-standalone-4.4.0-20211104 Mule Runtime Upgrade Tool ───────────────────────── INFO: Initiating upgrade process... INFO: Upgrading distribution at path [/opt/mule-enterprise-standalone-4.4.0-20211026] with version: [4.4.0-20211026] to distribution at path [/tmp/mule-enterprise-standalone-4.4.0-20211104] with version [4.4.0-20211104] ... ERROR: Error validating required reading permissions under Mule distribution [/tmp/mule-enterprise-standalone-4.4.0-20211104] java.nio.file.AccessDeniedException: /tmp/mule-enterprise-standalone-4.4.0-20211104/lib/mule/mule-module-cache-ee-4.4.0-20211104.jar [...]
Missing writing permissions (書き込み権限がありません)
./upgrade-tool upgrade -n /tmp/mule-enterprise-standalone-4.4.0-20211104 Mule Runtime Upgrade Tool ───────────────────────── INFO: Initiating upgrade process... INFO: Upgrading distribution at path [/opt/mule-enterprise-standalone-4.4.0-20211026] with version: [4.4.0-20211026] to distribution at path [/tmp/mule-enterprise-standalone-4.4.0-20211104] with version [4.4.0-20211104] ... ERROR: Error validating required writing permissions under Mule distribution [/opt/mule-enterprise-standalone-4.4.0-20211026] java.nio.file.AccessDeniedException: /opt/mule-enterprise-standalone-4.4.0-20211026/lib/boot/libwrapper-linux-ppcle-64.so [...]
Mule Runtime should be stopped (Mule Runtime を停止する必要があります)
./upgrade-tool upgrade -n /tmp/mule-enterprise-standalone-4.4.0-20211104 Mule Runtime Upgrade Tool ───────────────────────── INFO: Initiating upgrade process... INFO: Upgrading distribution at path [/opt/mule-enterprise-standalone-4.4.0-20211026] with version: [4.4.0-20211026] to distribution at path [/tmp/mule-enterprise-standalone-4.4.0-20211104] with version [4.4.0-20211104] ... ERROR: Mule Runtime should be stopped. ERROR: Not all preconditions are met to perform the upgrade. Review the log for details. Not all preconditions are met to perform the upgrade. Review the log for details.
Mule version is not supported for an upgrade (アップグレードでサポートされていない Mule バージョンです)
./upgrade-tool upgrade -n /tmp/mule-enterprise-standalone-4.4.0-20211104 Mule Runtime Upgrade Tool ───────────────────────── INFO: Initiating upgrade process... INFO: Upgrading distribution at path [/tmp/mule-enterprise-standalone-4.1.1-20211222] with version: [4.1.1] to distribution at path [/tmp/mule-enterprise-standalone-4.4.0-20211026] with version [4.4.0-20211026] ... ERROR: Your Mule version cannot be upgraded to the new one, you need to upgrade to a version greater than 4.1.5, or for versions between 4.1.1 to 4.1.4, then packages released after January 20, 2022. ERROR: Not all preconditions are met to perform the upgrade. Review the log for details. Not all preconditions are met to perform the upgrade. Review the log for details.
クラスター化された Mule アプリケーションのアップグレード
クラスター化された Mule インスタンスをアップグレードするには、Mule アップグレードツールを使用して各ノードを手動でアップグレードすることにより、ローカル Mule インスタンスのアップグレードプロセスを自動化します。
始める前に
アップグレードを始める前に、次の準備が整っていることを確認します。
-
新しい Mule Runtime ディストリビューション (対象バージョン) と、アップグレードする各ノードにコピーされた Mule アップグレードツール (ダウンタイムを短縮するため)。
-
最新の修正とセキュリティ機能強化を備えたツールが実行されるように、最新バージョンの Mule アップグレードツールをご使用ください。
ヘルプセンターから Mule アップグレードツールをダウンロードしてください。
-
現在運用中の Mule 4 インスタンスはアップグレードに備えて停止状況にあります。
Mule アップグレードツールを使用して Mule バージョン 4.1.1 ～ 4.1.4 のアップグレードを行う場合は、2022 年 1 月 20 日以降にリリースされたパッチ更新からアップグレードを行う必要があります。2022 年 1 月 20 日より前のバージョン 4.1.1 ～ 4.1.4 のリリースは現在のところツールでサポートされておらず、アップグレードしようとすると、最初にサポートされるバージョンにアップグレードしてからでないと Mule バージョンをアップグレードできない旨のエラーメッセージが表示されます (Mule Upgrades and Patch Updates を参照)。
-
最新の Mule Runtime Engine ディストリビューションをシステムにダウンロードして展開してある。
Mule アップグレードツールには、Mule Runtime のフルディストリビューションが必要です。必ずファイル名に (
patch ではなく) distribution という単語が含まれているフル Mule Runtime ディストリビューションをダウンロードしてください。たとえば、Mule 4.4.0 の 20220221 ディストリビューションであれば、ファイル名は mule-ee-distribution-standalone-4.4.0-20220221.zip となります。ヘルプセンターから Mule Runtime ディストリビューションをダウンロードしてください。
-
ファイルシステムに 2 GB 以上の空きディスクスペースと、Mule ディストリビューションをインストールするためのアクセス権限がある。
-
(Windows 環境の場合) PowerShell スクリプトの実行ポリシーが [Unrestricted] に設定されている。
Mule のアップグレードまたは更新
クラスター化された Mule インスタンスを最新バージョンにアップグレードまたは更新する手順は、次のとおりです。
-
Mule アップグレードツールをダウンロードしてある
$MULE_HOME/tools ディレクトリに移動します。 -
最新の Mule Runtime ディストリビューションをダウンロードして展開してあるディレクトリの絶対パスを引数として指定し、
upgrade -n サブコマンドを実行します。例:$MULE_HOME/tools/upgrade-tool upgrade -n <newMuleDistributionAbsolutePath>このスクリプトの出力は次のようになります。
➜ tools ./upgrade-tool upgrade -n /Users/me/mule-download/upgrade/mule-enterprise-standalone-4.5.0/ Mule Runtime Upgrade Tool ───────────────────────── INFO: Initiating upgrade process... INFO: Upgrading distribution at path [/opt/mule/mule-enterprise-standalone-4.4.0-20221212] with version: [4.4.0-20221212] to distribution at path [/opt/mule/mule-enterprise-standalone-4.4.0-20230217] with version [4.4.0-20230217] ... Do you want to proceed with the upgrade? To confirm please, enter [yes, no] (default: no): yes WARN: Unknown file tools/mule-runtime-upgrade-tool-logs/mule-runtime-upgrade-tool-logs.log was found in the runtime installation, and will be kept. WARN: A version in your MULE_HOME directory name was detected: /opt/mule/mule-enterprise-standalone-4.4.0-20221212, beware it may not match the current installed version inside the directory. INFO: Upgrade process finished successfully. Verifying Mule Agent ──────────────────── INFO: Mule Agent not installed, skipping setup
これで、既存の Mule インスタンスがアップグレードされたため、アップグレードツールで必要でなくなった最近ダウンロードしたバージョン (例では <newMuleDistributionAbsolutePath> として参照) を削除できます。
対象の場所が $MULE_HOME であるため、アップグレードした Mule Runtime インスタンスによって以前のバージョンが置き換えられます。
|
すべてのノードを同じ Mule Runtime バージョンにアップグレードまたは更新しないと正常に動作しませんのでご注意ください。
アップグレードまたは更新のロールバック
Mule アップグレードツールは、アップグレードまたは更新プロセスを開始する前にアップグレードまたは更新するクラスター化された Mule インスタンスのバックアップを作成するため、クラスター化された Mule インスタンスをアップグレードまたは更新した後で、以前の状態に復元できます。バックアップは $MULE_HOME/.upgrade-tool-backup フォルダーに保存されます。
ロールバックを実行する手順は、次のとおりです。
-
Mule アップグレードツールをダウンロードしてある
$MULE_HOME/tools ディレクトリに移動します。 -
rollback サブコマンドを次のように実行します。$MULE_HOME/tools/upgrade-tool rollback
すべてのノードを同じ Mule Runtime バージョンにロールバックしないと正常に動作しませんのでご注意ください。