How to use JBoss Server Migration Tool to upgrade from one version of JBoss EAP 7.x to another version of JBoss EAP 7.x

Solution Verified - Updated

Environment

  • Red Hat JBoss Enterprise Application Platform (EAP)
    • 7.x

Issue

  • Upgrade from older JBoss EAP 7.x to a newer JBoss EAP 7.x release when the older release is two or more versions behind the current release.
  • System requires an upgrade from JBoss EAP 7.1 to JBoss EAP 7.3.
  • The JBoss Server Migration Tool only allows upgrades from JBoss EAP 7.2 to JBoss EAP 7.3.
  • Is there a different way to upgrade from JBoss EAP 7.1 to JBoss EAP 7.3?
  • How to Upgrade from JBoss EAP 7.2 to JBoss EAP 7.4?
  • microprofile exception when upgrading:
"Migration failed: org.jboss.migration.core.ServerMigrationFailureException: org.jboss.migration.wfly10.config.management.ManagementOperationException: WFLYCTL0369: Required capabilities are not available:
    org.wildlfy.microprofile.config; There are no known registration points which can provide this capability."

Resolution

As per JBoss EAP 7.3 documentation, JBoss Server Migration Tool supports migration to JBoss EAP 7.3 from the previous major release of the product, which is JBoss EAP 6.4, and from the previous minor release of the product, which is JBoss EAP 7.2.

JBoss EAP 7.4

The JBoss Server Migration Tool can perform migration from JBoss EAP 7.x (any version) to JBoss EAP 7.4.2+.
Please note that CP Patch 02 must be applied on top of JBoss EAP 7.4 for this to work.

However, non-XP JBoss EAP 7.x cannot be migrated to JBoss EAP 7.x XP. For example JBoss EAP 7.3 to JBoss EAP 7.4 XP, it doesn't recognize since these are different products.

JBoss EAP 7.3 Path

The migration process from JBoss EAP 7.1 to JBoss EAP 7.3 is a two-step process. First, it requires migration from JBoss EAP 7.1 to JBoss EAP 7.2 followed by another migration from JBoss EAP 7.2 to JBoss EAP 7.3.

For any JBoss EAP 7 version earlier than JBoss EAP 7.2, it is required to first migrate to JBoss EAP 7.2 before migrating to JBoss EAP 7.3. Note that failure may occur if updating to JBoss EAP 7.3 from a patch level earlier than JBoss EAP 7.2 CP Patch 02 i.e. older than JBoss EAP 7.2.2.

Example of valid paths:

  • JBoss EAP 7.0 or JBoss EAP 7.1 or JBoss EAP 7.2 or JBoss EAP 7.3 --> JBoss EAP 7.4.2+
  • JBoss EAP 6.4.24 --> JBoss EAP 7.2.2+ --> JBoss EAP 7.3
  • JBoss EAP 7.0 --> JBoss EAP 7.2.2+ --> JBoss EAP 7.3
  • JBoss EAP 6.4.24 --> JBoss EAP 7.4.2+

Direct migration to JBoss EAP 7.4 from JBoss EAP 7.x is only possible to JBoss EAP 7.4.2+ onwards.

Usage Example 7.0 to EAP 7.4

Assuming you have a valid target (i.e. JBoss EAP 7.4.2+) and a valid source (i.e. JBoss EAP 7.0), follow the below steps of migration:

  1. See if the path is valid as explained above (the JBoss Server Migration Tool only supports one minor version at a time).

  2. Go to JBoss EAP 7.4's bin directory.
    Run the below command to migrate:
    $./jboss-server-migration.sh --source /path/to/$JBOSS_HOME_of_7.0/

  3. This will prompt standalone migration, select yes & hit enter.

  4. Then select yes to migrate all configuration files.

  5. If you have deployed applications in the source server (e.g. old JBoss EAP 7.0) then select no here to migrate the deployed application. Technically, the application is not migrated, just deployed in the target (i.e. copied to the deployment of the target installation).

  6. Select no to the mode-domain migration.

  7. Complete migration

  8. See the migration output/log.

Custom scripts and directories

The JBoss Server Migration Tool does not look for or move any custom scripts, etc, from the old installation. One will need to supplement the migration process to accommodate this.

Also, the JBoss Server Migration Tool is not able to recreate multiple configuration directories during the migration. The command you ran would place the migrated files in the target server's standalone/configuration directory unless told otherwise.

Migrating custom instances of JBoss EAP

For migrating renamed standalone/domain custom directories, refer to this article.

Microprofile Issue

There is a known issue This content is not included.JBEAP-19320 when upgrading from any version earlier than 7.2 to 7.3, which is related to the microprofile subsystem, introduced in JBoss EAP 7.2.

Datasource/Datasource driver

The datasource should be later migrated as well, in the configuration below the driver-jar should be deployed on the new server as well:

                <datasource jndi-name="java:/Example" pool-name="ExampleDataSourcePool" enabled="true">
                    <connection-url>jdbc:oracle:thin:@27.0.0.1:9999:user</connection-url>
                    <driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
                    <driver>ojdbc6.jar</driver>

Also, consider the JDK versions, when migrating the JDBC driver version, e.g. ojdbc6.jar only works with JDK 6/7, whereas JBoss EAP 7.2+ only supports OpenJDK 8/11.

Migrating inside a POD

Although the jboss-migration.sh is inside the pod, one cannot migrate inside a pod because the jars for migration are just not there.

Therefore, one cannot migrate inside a pod, it won't work and it will return a parsing error since the module.xml cannot find the migration cli jars.

Migrating of Jboss EAP for windows

The migration process is same as that of Linux with the only difference being in the migration script used as below:

$jboss-server-migration.bat --source \path\to\$JBOSS_HOME_of_7.0\

Migrating from Linux to Windows - or Windows to Linux

Moving from one operating system to another same version is not considered "migration". Migration would be changing to a different version with some substantial differences. If it is the same JBoss EAP version, it should be the same configuration, from one platform to another is not a migration. To move from one platform to another one would just move the configs/deployments/etc then make any changes for the new server, such as IPs. The only major aspect that would change between Linux & Windows is the startup scripts. *.bat vs *.sh, and their related *.conf.bat vs *.conf. And if started as a service, the procedure is different.

Application migration

MTA can be used for migrating applications to the cloud, whereas MTR can be used for application migration in VM for example, as in:

  • application migration non-OCP scenarios: MTR
  • application migration into OCP scenarios: MTA

See more details here: This content is not included.MTR Overview and This content is not included.MTA Overview.

Root Cause

About JBoss EAP 8

EAP 8 has a This content is not included.separate download for the server migration tool. So does not work like EAP 7.x like above described. The EAP 8 migration tool supports migration from any version of EAP 7.x.

Diagnostic Steps

  1. Verify the migration.log in $JBOSS_HOME/migration/logs
  2. Do not migrate invalid or deprecated files/attributes. Do not migrate standalone-openshift.xml files.
  3. In case trouble in any subsystem, remove/comment it, and try again.
SBR
Product(s)
Components
Category
Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.