JBoss EAP XP のアップグレードおよび移行ガイド

Red Hat JBoss Enterprise Application Platform 7.4

JBoss EAP XP 2.0.x から JBoss EAP XP 3.0.0 へのアップグレードおよび移行のガイダンス

概要

本書では、JBoss EAP XP 2.0.x を JBoss EAP XP 3.0.0 にアップグレードし、必要なアプリケーション移行に関する情報を提供します。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施して参ります。詳細は、弊社 の CTO、Chris Wright のメッセージを参照してください。

Red Hat ドキュメントへのフィードバック

弊社のドキュメントに関するご意見やご感想をお寄せください。フィードバックをお寄せいただくには、ドキュメントのテキストを強調表示し、コメントを追加できます。以下の手順に従って、Red Hat ドキュメントのフィードバックをお寄せください。

要件

  • Red Hat カスタマーポータルにログインします。
  • Red Hat カスタマーポータルで、Multi-page HTML 形式のドキュメントを表示します。

手順

  1. フィードバック をクリックして、既存のリーダーコメントを表示します。

    注記

    フィードバック機能は、マルチページ HTML 形式でのみ有効です。

  2. フィードバックを提供するドキュメントのセクションを強調表示します。
  3. 選択したテキストの近くに表示されるプロンプトメニューで、Add Feedback をクリックします。

    ページの右側のフィードバックセクションにテキストボックスが開きます。

  4. テキストボックスにフィードバックを入力し、Submit をクリックします。

    ドキュメントに関する問題を作成しました。

  5. 問題を表示するには、フィードバックビューで問題トラッカーリンクをクリックします。

第1章 JBoss EAP XP のアップグレード

1.1. アップグレードおよび移行

JBoss EAP XP のアップグレードおよび移行ガイドで説明されている手順を使用して、JBoss EAP XP 2.0.x 製品を JBoss EAP XP 3.0.0 製品の準備、アップグレード、および移行を行います。JBoss EAP XP 3.0.0 は JBoss EAP 7.4 のみと互換性があります。JBoss EAP 7.3 でサーバーを取得し、JBoss EAP XP 3.0.0 パッチを適用する場合は、最初に JBoss EAP 7.3 インスタンスを JBoss EAP 7.4 にアップグレードする必要があります。

このガイドでは、アップグレードおよび移行プロセスに使用できるツールを参照します。これらのツールは以下のとおりです。

  • Migration Toolkit for Applications (MTA)
  • JBoss Server Migration Tool

JBoss EAP XP 2.0.x リリースを正常に JBoss EAP XP 3.0.0 にアップグレードおよび移行した後、JBoss EAP 7.4 インスタンスのアプリケーション移行を実装できます。

参考情報

1.2. アップグレードと移行の準備

JBoss EAP 拡張パックをアップグレードした後は、アプリケーションコードを更新する必要がある場合があります。

JBoss EAP XP 3.0.0 では、JBoss EAP XP 2.0.x アプリケーションには後方互換性がいくつか存在する可能性があります。しかし、JBoss EAP XP 2.0.x で非推奨なった機能や削除された機能がアプリケーションによって使用される場合は、アプリケーションコードの変更が必要になることがあります。

移行プロセスを開始する前に、以下の項目を新たに確認してください。

  • JBoss EAP XP 3.0.0 リリースに追加された JBoss EAP XP 機能。
  • JBoss EAP XP 3.0.0 に追加された MicroProfile 機能。
  • 既存の MicroProfile 機能の強化
  • JBoss EAP XP 3.0.0 で非推奨となった機能および機能。
  • JBoss EAP XP 3.0.0 から削除された機能および機能。
  • EAP XP リリースから別のリリースに移行するために使用できるツール。

一覧表示されている項目を確認したら、環境を分析し、アップグレードプロセスおよび移行プロセスを計画してください。JBoss EAP XP 3.0.0 に移行する予定のアプリケーションを必ずバックアップしてください。

現在の JBoss EAP XP 2.0.x リリースを JBoss EAP XP 3.0.0 にアップグレードできるようになりました。アップグレードプロセス後にすべてのアプリケーション移行を実装できます。

参考情報

1.3. JBoss EAP XP の新機能

JBoss EAP XP 3.0.0 には、JBoss EAP アプリケーションの MicroProfile 仕様の Red Hat 実装を強化する機能が含まれています。

注記

MicroProfile Reactive Messaging サブシステムは Red Hat AMQ Streams をサポートします。この機能は MicroProfile Reactive Messaging 1.0 API を実装し、Red Hat は JBoss EAP XP 3.0.0 のテクノロジープレビューとして機能を提供します。

Red Hat は、JBoss EAP で Red Hat AMQ Streams 2021.Q2 をテストしました。ただし、JBoss EAP XP 3.0.0 でテストされた最新の Red Hat AMQ Streams バージョンについては、「Red Hat JBoss Enterprise Application Platform でサポートされる構成」ページを参照してください。

JBoss EAP XP 3.0.0 には、本リリースに以下の新機能が含まれています。

  • アプリケーションの起動後に CLI スクリプトを実行します。
  • --cli-script=<path to CLI script> 引数を使用して、起動時に起動可能な JAR ファイルのサーバー設定を更新します。
  • MicroProfile Reactive Messaging 1.0 API を使用してマイクロサービス間でメッセージを送受信します。
  • MicroProfile Reactive Messaging 1.0 API を使用してユーザーアプリケーションを書き込み、設定し、アプリケーションがイベントストリームを効率的かつ非同期的に送信、受信、および処理できるようにします。
  • MicroProfile Reactive Messaging はサーバーに事前インストールされているため、サーバー設定で MicroProfile Reactive Messaging 機能を有効にします。
  • 「MicroProfile Reactive Messaging with MicroProfile Reactive Messaging with Kafka クイックスタート」を表示して、サーバーで次のタスクを実行する方法を確認します。

    • MicroProfile Reactive Messaging サブシステムを有効にします。
    • MicroProfile Reactive Messaging を使用してデータを送信し、Red Hat AMQ Streams からデータを受信してアプリケーションを実行し、テストします。

参考情報

  • Red Hat AMQ Streams の詳細は、『Using AMQ Streams on OpenShift』ガイドの「Overview of AMQ Streams」を参照してください。
  • テクノロジープレビュー機能の情報は、Red Hat カスタマーポータルの「テクノロジープレビュー機能のサポート範囲」を参照してください。
  • Red Hat AMQ Streams バージョンの詳細は、製品ドキュメントページの Red Hat AMQ を参照してください。
  • Kafka クイックスタートでの MicroProfile Reactive Messaging の詳細は、「jboss-eap-quickstarts」を参照し、リストされた MicroProfile Reactive Messaging with Kafka クイックスタートを選択します。

1.4. MicroProfile 機能の強化

JBoss EAP XP 3.0.0 リリースには、以下の MicroProfile 4.0 コンポーネントのサポートが含まれています。

  • MicroProfile Config
  • MicroProfile Fault Tolerance
  • MicroProfile Health
  • MicroProfile JWT
  • MicroProfile Metrics
  • MicroProfile OpenAPI
  • MicroProfile OpenTracing
  • MicroProfile REST クライアント

参考情報

  • MicroProfile 4.0 およびその仕様の詳細は、GitHubMicroProfile 4.0 を参照してください。
  • MicroProfile 4.0 仕様コンポーネントの詳細は、『 Using MicroProfile with JBoss EAP XP 3.0.0』の「About JBoss EAP XP 」を参照してください。

1.5. 非推奨となった機能およびサポートされない MicroProfile 機能

アプリケーションを JBoss EAP XP 3.0.0 に移行する前に、JBoss EAP XP 2.0.x で利用可能な機能の一部が非推奨またはサポート対象外となった可能性があることに注意してください。

メンテナンスコストの高さ、コミュニティーの関心の低さ、より優れた代替ソリューションなど、Red Hat のサポートが削除されました。

サポートされない機能および非推奨の機能について、『Red Hat JBoss EAP XP 3.0.0 リリースノート』ガイドと『7.4.0 リリースノート』を確認してください。

参考情報

第2章 JBoss EAP XP 2.0.x サーバーから JBoss EAP XP 3.0.0 サーバーに移行するツール

以下のツールのいずれかを選択して、JBoss EAP XP 2.0.x 製品を JBoss EAP XP 3.0.0 製品にアップグレードおよび移行できます。

  • Migration Toolkit for Applications (MTA)
  • JBoss Server Migration Tool

2.1. JBoss Server Migration Tool を使用したサーバー設定の移行

サーバー設定を更新して JBoss EAP XP 3.0.0 の新機能および設定を追加する場合は、JBoss Server Migration Tool を使用します。JBoss EAP XP 3.0.0 が設定に対応していると、既存の JBoss EAP XP 2.0.x サーバー設定を保持することができます。

JBoss Server Migration Tool は既存の JBoss EAP XP 2.0.x サーバー設定ファイルを読み取り、必要な新しいサブシステムをこれらのファイルに追加します。このツールは、既存のサブシステム設定を新機能で更新し、廃止されているサブシステム設定を削除します。

JBoss Server Migration Tool を使用して、JBoss EAP XP 3.0.0 設定の管理対象ドメインのスタンドアロンサーバーおよびサーバーを移行できます。

JBoss EAP XP 3.0.0 には JBoss Server Migration Tool が含まれるため、ファイルをダウンロードしたり、ツールをインストールしたりする必要はありません。EAP_HOME/bin ディレクトリーにある jboss-server-migration スクリプトを実行してツールを起動します。

参考情報

  • JBoss Server Migration Tool の設定および実行方法に関する詳細は、『JBoss サーバー移行ツールの使用』の「Running the JBoss Server Migration Tool」を参照してください。

2.2. Migration Toolkit for Applications を使用して移行用にアプリケーションを分析

Migration Toolkit for Applications (MTA) には、Jakarta アプリケーションの移行を簡素化する拡張可能かつカスタマイズ可能なルールベースのツールが含まれています。ツールキットを使用して、アプリケーションの API、テクノロジー、およびアーキテクチャーを分析します。ツールキットは、JBoss EAP XP 2.0.x から JBoss EAP XP 3.0.0 に移行する予定のアプリケーションのレポートを提供します。

MTA を使用して、標準の JBoss EAP アプリケーションおよび起動可能な JAR アプリケーションを分析できます。

MTA は、以下の情報を出力します。

  • 必要なすべての移行変更の詳細な説明。
  • 変更が必須または任意であるかどうか。
  • 変更が複雑または単純であるかどうか。
  • 移行更新を必要とするコードへのリンク。
  • 必要な移行変更を完了するのに役立つヒントおよび情報へのリンク。
  • 見つかった各移行問題の推定作業量レベルおよびアプリケーションを移行するための推定合計作業量。

MTA を使用して、JBoss EAP XP 3.0.0 に移行する前に、JBoss EAP XP 2.0.x アプリケーションのコードおよびアーキテクチャーを分析することもできます。アプリケーションを JBoss EAP XP 2.0.x から JBoss EAP XP 3.0.0 へ移行する MTA ルールセットは、JBoss EAP XP 3.0.0 に移行する時に別の設定に置き換える必要がある XML 記述子、特定のアプリケーションコード、およびパラメーターでレポートします。

関連情報

  • 起動可能な JAR の詳細は、『 JBoss EAP XP 3.0.0 での MicroProfile の使用 』の「 起動可能な JAR について 」を参照してください。
  • JBoss EAP XP 2.0.x アプリケーションを分析する Migration Toolkit for Applications の詳細は、『Migration Toolkit for Applications Getting Started Guide』の「About Migration Toolkit for Applications」を参照してください。
  • 管理 CLI で Migration Toolkit for Applications を使用する方法は、『Migration Toolkit for Applications CLI ガイド』 の「CLI の実行」を参照してください。
  • 管理コンソールで Migration Toolkit for Applications の使用方法は、『Migration Toolkit for Applications Web コンソール ガイド』の「Web コンソールを使用したアプリケーションの分析」を参照してください。

2.3. JBoss EAP 7.3 以前からのアップグレード

JBoss EAP XP 3.0.0 は JBoss EAP 7.4 でのみサポートされます。

JBoss EAP 7.3 以前でサーバーを操作するため、JBoss EAP XP を使用する場合は、サーバーを JBoss EAP 7.4 にアップグレードします。JBoss EAP XP のインストールを試行する前に、必要な移行を完了します。

参考情報

  • サーバー設定の移行に関する情報は、『移行ガイド』 の「サーバー設定の変更」を参照してください。

2.4. MicroProfile アプリケーションの移行

MicroProfile 4.0 は Jakarta EE 8 プラットフォームに基づいています。Jakarta EE 8 は Java EE 8 と後方互換性がありますが、Jakarta EE 8 依存関係はすべての MicroProfile 仕様の Java EE 8 依存関係を置き換えます。

MicroProfile 4.0 には、すべての主要な MicroProfile 仕様への更新が含まれています。

以下の仕様には、MicroProfile 4.0 の API 互換性のない変更が含まれます。

  • MicroProfile Config
  • MicroProfile Fault Tolerance
  • MicroProfile Health
  • MicroProfile Metrics
  • MicroProfile OpenAPI

これらの仕様を使用するアプリケーションを最新の Jakarta EE 8 仕様に更新する必要があります。

以下の方法のいずれかを選択して、アプリケーションを MicroProfile 4.0 に更新できます。

  • MicroProfile 4.0 依存関係をプロジェクトの pom.xml ファイルに追加します。
  • JBoss EAP XP BOM を使用して、サポートされるアーティファクトをプロジェクトの pom.xml ファイルの JBoss EAP XP 依存関係管理にインポートします。

参考情報

  • MicroProfile 4.0 を使用するようにアプリケーションを更新する MicroProfile 4.0 およびオプションに関する詳細は、GitHubMicroProfile 4.0 を参照してください。

2.5. 起動可能な JAR アプリケーション移行

JBoss EAP XP 2.0.0 の起動可能な JAR アプリケーションを JBoss EAP XP 3.0.0 に移行する前に、JBoss EAP XP の起動可能な JAR Maven プラグイン設定を更新する必要がある場合があります。

JBoss EAP XP 3.0.0 の場合、extraServerContentDirs 設定 要素は extraServerContent 設定要素 を 置き換えます。この要素の命名置換は、既存の extra-server-content-dirs 要素に合わせます。

JBoss EAP Maven プラグイン設定で extraServerContent 要素を使用した場合は、この要素を extraServerContentDirs 要素に置き換える必要が あり ます。extra-server-content-dirs 要素を使用した場合、設定を変更する必要はありません。

関連情報

第3章 Thorntail アプリケーション Maven プロジェクト移行

Thorntail の Red Hat ビルドは、ライフサイクルの終わりに近づいています。Thorntail アプリケーションがある場合は、アプリケーションの Maven プロジェクトを JBoss EAP XP に移行できます。Thorntail アプリケーションは 2 つの方法でパッケージ化されます。

  • Thorntail ランタイムを Uberjar、実行可能な JAR としてパッケージ化します。
  • ランタイムのみの実行可能 JAR でデプロイおよび実行する標準の WAR アーカイブにパッケージ化されます。

JBoss EAP XP に移行すると、Thorntail アプリケーションを起動可能な JAR としてパッケージ化し、JBoss EAP XP ランタイムをスケールダウンして MicroProfile プラットフォームやアプリケーションが依存する他のテクノロジーを含めることができます。

アプリケーションを JBoss EAP XP に移行する場合は、Thorntail 分を削除し、必要な MicroProfile および Jakarta EE 8 仕様のアーティファクトを Maven プロジェクトの依存関係に追加する必要があります。

注記

ランタイム時に JBoss CLI ツールまたは JBoss EAP Web コンソールを使用し、サーバー設定を変更できます。ただし、パッケージ化中に行われる設定変更とは異なり、起動時に設定への変更は永続化されず、起動可能な JAR を再起動すると失われます。

3.1. Thorntail アプリケーション Maven プロジェクトの JBoss EAP XP への移行

Jakarta Enterprise Beans、Jakarta Server Faces、Jakarta Connector API、SOAP Web サービス、または CORBA などの技術に依存する Thorntail アプリケーションがある場合、アプリケーションの Maven プロジェクトを JBoss EAP XP に移行できます。

Galleon レイヤーは、起動可能な JAR でパッケージ化された JBoss EAP XP ランタイムの機能を設定するために使用されます。Jakarta EE 8 仕様を使用する Thorntail アプリケーションを移行する場合、関連する Galleon レイヤーを起動可能な JAR Maven プラグイン設定に追加する必要があります。

Galleon レイヤーを使用する場合、JBoss EAP XP はサーバー設定を生成し、起動可能な JAR 内にパッケージ化します。Galleon レイヤーが使用されていない場合、デフォルトの standalone-microprofile.xml と同じ設定が起動可能な JAR にパッケージ化されます。

<cloud> 設定要素を使用してクラウド用の起動可能な JAR を構築する場合、デフォルトの standalone-microprofile-ha.xml と同様の OpenShift 設定が起動可能な JAR に適用されます。

起動可能な JAR Maven プラグインは、起動可能な JAR をパッケージ化しながら JBoss CLI スクリプトを実行します。

手順

  1. Thorntail BOM インポートを削除します。

    pom.xml ファイルから io.thorntail Thorntail BOM インポートを削除する例。

    <dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>io.thorntail</groupId>
          <artifactId>bom</artifactId>
          <version>${version.thorntail}</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
      </dependencies>
    </dependencyManagement>

  2. JBoss EAP XP BOM を使用して、サポートされるアーティファクトを JBoss EAP XP 依存関係管理にインポートします。

    jboss-eap-jakartaee8-with-tools BOM を使用して、サポートされるアーティファクトをプロジェクトにインポートする例。

    <dependencyManagement>
            <dependencies>
                <!-- importing the jakartaee8-with-tools BOM adds specs and other useful artifacts as managed dependencies -->
                <dependency>
                    <groupId>org.jboss.bom</groupId>
                    <artifactId>jboss-eap-jakartaee8-with-tools</artifactId>
                    <version>${version.server.bom}</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
                <!-- importing the microprofile BOM adds MicroProfile specs -->
                <dependency>
                    <groupId>org.jboss.bom</groupId>
                    <artifactId>jboss-eap-xp-microprofile</artifactId>
                    <version>${version.microprofile.bom}</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
            </dependencies>
        </dependencyManagement>

    注記

    jakartaee8-with-tools BOM は、アプリケーションが MicroProfile プラットフォームに含まれていない Jakarta EE 8 仕様に依存する場合のみインポートします。

  3. Thorntail Maven プラグインを JBoss EAP XP の起動可能な JAR Maven プラグインに置き換えます。

    JBoss EAP XP の起動可能な JAR Maven プラグインを使用した Thorntail Maven プラグインの置き換え例。

    <plugin>
       <groupId>org.wildfly.plugins</groupId>
       <artifactId>wildfly-jar-maven-plugin</artifactId>
       <version>${bootable.jar.maven.plugin.version}</version>
       <configuration>
          <feature-pack-location>${org.jboss.eap:wildfly-galleon-pack:${jboss.xp.galleon.feature.pack.version}</feature-pack-location>
          <layers>
             <layer>microprofile-platform</layer>
          </layers>
       </configuration>
       <executions>
          <execution>
             <goals>
                <goal>package</goal>
             </goals>
          </execution>
       </executions>
    </plugin>

    注記

    前述の例は、Maven プラグインバージョンの以下のプロパティーを指定します。

    ${bootable.jar.maven.plugin.version}

    このプロパティーの代わりに Maven プラグインバージョンをプロジェクトに設定する必要があります。例を以下に示します。

    <properties>
        <bootable.jar.maven.plugin.version>4.0.3.Final-redhat-00001</bootable.jar.maven.plugin.version>
    </properties>
    • 起動可能な JAR プラグインはデフォルトで UberJAR をビルドします。これは、アプリケーションがデプロイされた状態で JBoss EAP XP ランタイムをパッケージ化することを意味します。hollow JAR をビルドするには、プラグインの設定に <hollow-jar>true</hollow-jar> を追加します。
  4. Maven プロジェクトの Thorntail 分に以下の変更を加えます。

    1. Thorntail による分数の依存関係を削除します。

      Maven プロジェクトから io.thorntail Thorntail 分の削除例

      <dependencies>
        <dependency>
          <groupId>io.thorntail</groupId>
          <artifactId>jaxrs</artifactId>
        </dependency>
      </dependencies>

    2. Maven 依存関係を設定します。

      XML スニペットを使用して、依存関係を Jakarta EE 8 JAX-RS および MicroProfile Config API のアーティファクトに追加します。

      <dependencies>
          <!-- Import the MicroProfile Config API, we use provided scope as the API is included in the server -->
          <dependency>
            <groupId>org.eclipse.microprofile.config</groupId>
            <artifactId>microprofile-config-api</artifactId>
            <scope>provided</scope>
          </dependency>
          <!-- Import the Jakarta REST API, we use provided scope as the API is included in the server -->
          <dependency>
            <groupId>org.jboss.spec.javax.ws.rs</groupId>
            <artifactId>jboss-jaxrs-api_2.1_spec</artifactId>
            <scope>provided</scope>
          </dependency>
        </dependencies>

    3. Thorntail YAML ファイル、システムプロパティーおよび環境プロパティーを削除します。
    4. Galleon レイヤーを設定します。

      JAX-RS を必要とするアプリケーションの起動可能な JAR Maven プラグインで Galleon レイヤーを設定する例。

      <plugin>
        <groupId>org.wildfly.plugins</groupId>               <artifactId>wildfly-jar-maven-plugin</artifactId>                  <configuration>
         ...
            <layers>
              <layer>jaxrs-server</layer>
              <layer>microprofile-platform</layer>
            </layers>
        </configuration>
         ...
      </plugin>

関連情報