JBoss EAP XP upgrade and migration guide
Guidance for upgrading and migrating from JBoss EAP XP 2.0.x to JBoss EAP XP 3.0.0
Abstract
Making open source more inclusive
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
Providing feedback on Red Hat documentation
We appreciate your feedback on our documentation. To provide feedback, you can highlight the text in a document and add comments. Follow the steps in the procedure to learn about submitting feedback on Red Hat documentation.
Prerequisites
- Log in to the Red Hat Customer Portal.
- In the Red Hat Customer Portal, view the document in Multi-page HTML format.
Procedure
Click Feedback to see existing reader comments.
NoteThe feedback feature is enabled only in the Multi-page HTML format.
- Highlight the section of the document where you want to provide feedback.
In the prompt menu that displays near the text you selected, click Add Feedback.
A text box opens in the feedback section on the right side of the page.
Enter your feedback in the text box and click Submit.
You have created a documentation issue.
- To view the issue, click the issue tracker link in the feedback view.
Chapter 1. JBoss EAP XP upgrades
1.1. Upgrades and migrations
Use the steps outlined in the JBoss EAP XP upgrade and migration guide to prepare, upgrade, and migrate your JBoss EAP XP 2.0.x product to the JBoss EAP XP 3.0.0 product. JBoss EAP XP 3.0.0 is compatible with only JBoss EAP 7.4. If you operate servers on JBoss EAP 7.3 and you want to apply the JBoss EAP XP 3.0.0 patch on it, you must first upgrade your JBoss EAP 7.3 instance to JBoss EAP 7.4.
The guide references tools that you can use for the upgrading and migration process. These tools are as follows:
- Migration Toolkit for Applications (MTA)
- JBoss Server Migration Tool
After you successfully upgrade and migrate JBoss EAP XP 2.0.x release to JBoss EAP XP 3.0.0, you can begin to implement any applications migrations for your JBoss EAP 7.4 instance.
Additional resources
- For information about archiving applications that you plan to migrate to JBoss EAP XP 3.0.0, see Back Up Important Data and Review Server State in the Migration Guide.
1.2. Preparation for upgrade and migration
After you upgrade the JBoss EAP Expansion Pack, you might have to update application code.
For JBoss EAP XP 3.0.0, some backward compatibility might exist for JBoss EAP XP 2.0.x applications. However, if your application uses features that were deprecated or functionality that was removed from JBoss EAP XP 2.0.x, you might need to make changes to your application code.
Please review the following new items before you begin the migration process:
- JBoss EAP XP features added in the JBoss EAP XP 3.0.0 release.
- MicroProfile capabilities added in the JBoss EAP XP 3.0.0.
- Enhancements to existing MicroProfile capabilities.
- Capabilities and features that are deprecated in the JBoss EAP XP 3.0.0.
- Capabilities and features that have been removed from JBoss EAP XP 3.0.0.
- Tools that you can use to migrate from one EAP XP release to another release.
After you have reviewed the listed items, analyze your environment and plan for the upgrade process and migration process. Ensure you back up any applications that you plan to migrate to JBoss EAP XP 3.0.0.
You can now upgrade your current JBoss EAP XP 2.0.x release to JBoss EAP XP 3.0.0. You can implement any applications migrations after the upgrade process
Additional resources
- For information about archiving applications that you plan to migrate to JBoss EAP XP 3.0.0, see Back Up Important Data and Review Server State in the Migration Guide.
1.3. New JBoss EAP XP capabilities
The JBoss EAP XP 3.0.0 includes new features that enhance the use of Red Hat implementation of the MicroProfile specification for JBoss EAP applications.
The MicroProfile Reactive Messaging subsystem supports Red Hat AMQ Streams. This feature implements the MicroProfile Reactive Messaging 1.0 API and Red Hat provides the feature as a technology preview for JBoss EAP XP 3.0.0.
Red Hat tested Red Hat AMQ Streams 2021.Q2 on JBoss EAP. However, check the Red Hat JBoss Enterprise Application Platform supported configurations page for information about the latest Red Hat AMQ Streams version that has been tested on JBoss EAP XP 3.0.0.
JBoss EAP XP 3.0.0 includes the following new features in its release:
- Run CLI scripts after you have started your application.
-
Use the
--cli-script=<path to CLI script>
argument to update the server configuration of a bootable JAR file at runtime. - Use the MicroProfile Reactive Messaging 1.0 API to send and receive messages between microservices.
- Use the MicroProfile Reactive Messaging 1.0 API to write and configure a user application, so the application can send, receive, and process event streams efficiently and asynchronously.
- Enable MicroProfile Reactive Messaging functionality in your server configuration, as MicroProfile Reactive Messaging only comes pre-installed on your server.
View the MicroProfile Reactive Messaging with MicroProfile Reactive Messaging with Kafka quickstart to learn how you can complete the following tasks on your server:
- Enable the MicroProfile Reactive Messaging subsystem.
- Run and test applications by using MicroProfile Reactive Messaging to send data and receive data from Red Hat AMQ Streams.
Additional resources
- For information about Red Hat AMQ Streams, see Overview of AMQ Streams in the Using AMQ Streams on OpenShift guide.
- For information about Technology Preview features. see Technology Preview Features Support Scope on the Red Hat Customer Portal.
- For information on the Red Hat AMQ Streams versions, see Red Hat AMQ on the Product Documentation page.
-
For more information about the MicroProfile Reactive Messaging with Kafka quickstart, see
jboss-eap-quickstarts
and select the listed MicroProfile Reactive Messaging with Kafka quickstart.
1.4. Enhancements to MicroProfile capabilities
The JBoss EAP XP 3.0.0 release includes support for the following MicroProfile 4.0 components:
- MicroProfile Config
- MicroProfile Fault Tolerance
- MicroProfile Health
- MicroProfile JWT
- MicroProfile Metrics
- MicroProfile OpenAPI
- MicroProfile OpenTracing
- MicroProfile REST Client
Additional resources
- For more information about MicroProfile 4.0 and its specifications, see MicroProfile 4.0 on GitHub.
- For more information about MicroProfile 4.0 specification components, see About JBoss EAP XP in the Using JBoss EAP XP 3.0.0 guide.
1.5. Deprecated and unsupported MicroProfile capabilities
Before you migrate your application to JBoss EAP XP 3.0.0 be aware that some features that were available in JBoss EAP XP 2.0.x might be deprecated or no longer supported.
Red Hat removed support for some technologies due to the high maintenance cost, low community interest, and much better alternative solutions.
Ensure that you review the Red Hat JBoss EAP XP 3.0.0 Release Notes guide and the 7.4.0 Release Notes guide for any unsupported and deprecated features.
Additional resources
- For more information about any unsupported and deprecated features for JBoss EAP XP 3.0.0, see the Using JBoss EAP XP 3.0.0 guide.
- For more information about any unsupported and deprecated features for JBoss EAP 7.4, see the 7.4.0 Release Notes guide.
Chapter 2. Tools for migrating from JBoss EAP XP 2.0.x servers to JBoss EAP XP 3.0.0 servers
You can choose one of the following tools to upgrade and migrate your JBoss EAP XP 2.0.x product to the JBoss EAP XP 3.0.0 product:
- Migration Toolkit for Applications (MTA)
- JBoss Server Migration Tool
2.1. Use the JBoss Server Migration Tool to migrate your server configurations
Use the JBoss Server Migration Tool when updating your server configuration to include the new features and settings of JBoss EAP XP 3.0.0. You can keep your existing JBoss EAP XP 2.0.x server configuration, provided that JBoss EAP XP 3.0.0 supports the configurations.
The JBoss Server Migration Tool reads your existing JBoss EAP XP 2.0.x server configuration files and adds any new required subsystems to these files. The tool also updates existing subsystem configurations with new features, and removes any obsolete subsystem configurations.
You can use the JBoss Server Migration Tool to migrate standalone servers and servers in a managed domain for your JBoss EAP XP 3.0.0 configuration.
JBoss EAP XP 3.0.0 includes the JBoss Server Migration Tool, so you do not need to download a file and install the tool. Issue the jboss-server-migration
script, which is located in the EAP_HOME/bin
directory, to start the tool.
Additional resources
- For more information about how to configure and run the JBoss Server Migration Tool, see Running the JBoss Server Migration Tool in the Using the JBoss Server Migration Tool guide.
2.2. Use the Migration Toolkit for Applications to analyze applications for migration
The Migration Toolkit for Applications (MTA) includes extensible and customizable rule-based tools that simplify migration of Jakarta applications. You can use the toolkit to analyze an application’s APIs, technologies, and architectures. The toolkit provides reports for the application you plan to migrate from JBoss EAP XP 2.0.x to JBoss EAP XP 3.0.0.
You can use MTA to analyze standard JBoss EAP applications and bootable JAR applications.
The MTA reports output the following information:
- Detailed explanations of all required migration changes.
- Whether the change is mandatory or optional.
- Whether the change is complex or simple.
- Links to code that requires a migration update.
- Hints and links to information for helping you complete the required migration changes.
- An estimate of the level of effort for each migration issue found and the total estimated effort to migrate the application .
You can also use MTA to analyze the code and architecture of your JBoss EAP XP 2.0.x applications before you migrate them to JBoss EAP XP 3.0.0. The MTA rule set for migrating applications from JBoss EAP XP 2.0.x to JBoss EAP XP 3.0.0 reports on XML descriptors, specific application code, and parameters, that you need to replace with alternative configurations when migrating to JBoss EAP XP 3.0.0.
Additional resources
- For information about the bootable JAR, see About the bootable JAR in the Using MicroProfile with JBoss EAP XP 3.0.0 guide.
- For more information about the Migration Toolkit for Applications to analyze your JBoss EAP XP 2.0.x applications, see the Product documentation for Migration Toolkit for Applications.
- For more information about using Migration Toolkit for Applications with the management CLI, see Run the CLI in the Migration Toolkit for Applications CLI Guide.
- For more information about using Migration Toolkit for Applications with the management console, see Using the Web Console to Analyze Applications in the Migration Toolkit for Applications Web Console Guide.
2.3. Upgrades from JBoss EAP 7.3 and earlier
JBoss EAP XP 3.0.0 is only supported on JBoss EAP 7.4.
If you operate servers on JBoss EAP 7.3 or earlier and want to use JBoss EAP XP, upgrade the servers to JBoss EAP 7.4. Complete any necessary migration before attempting to install JBoss EAP XP.
Additional resources
- For information about migrating your server configuration, see Server Configuration Changes in the Migration Guide.
2.4. MicroProfile application migration
MicroProfile 4.0 is based on the Jakarta EE 8 platform. Although Jakarta EE 8 is API backward compatible with Java EE 8, Jakarta EE 8 dependencies replace Java EE 8 dependencies for all MicroProfile specifications.
MicroProfile 4.0 includes updates to all the major MicroProfile specifications.
The following specifications include API incompatible changes for MicroProfile 4.0:
- MicroProfile Config
- MicroProfile Fault Tolerance
- MicroProfile Health
- MicroProfile Metrics
- MicroProfile OpenAPI
You must update your applications that use these specifications to the latest Jakarta EE 8 specifications.
You can update your applications to MicroProfile 4.0 by choosing one of the following methods:
-
Adding the MicroProfile 4.0 dependency to your project’s
pom.xml
file. -
Using the JBoss EAP XP BOMs to import supported artifacts to the JBoss EAP XP dependency management of your project’s
pom.xml
file.
Additional resources
- For more information about MicroProfile 4.0 and options for updating your applications to use MicroProfile 4.0, see MicroProfile 4.0 on GitHub.
2.5. Bootable JAR application migration
Before you migrate a JBoss EAP XP 2.0.0 bootable JAR application to JBoss EAP XP 3.0.0, you might need to update your JBoss EAP XP bootable JAR Maven plug-in configuration.
For JBoss EAP XP 3.0.0, the extraServerContentDirs
configuration element replaces the extraServerContent
configuration element. This element naming replacement aligns with the pre-existing extra-server-content-dirs
element.
If you used the extraServerContent
element in your JBoss EAP Maven plug-in configuration, you must replace this element with the extraServerContentDirs
element. If you used the extra-server-content-dirs
element then you do not need to make any configuration changes.
Additional resources
-
For more information about the
extra-server-content-dirs
configuration element, see Enabling HTTP authentication for bootable JAR with a CLI script in the Using MicroProfile with JBoss EAP XP 3.0.0 guide.
Chapter 3. Thorntail application Maven project migration
The Red Hat build of Thorntail is approaching its end of life. If you have a Thorntail application, you can migrate your application’s Maven project into JBoss EAP XP. Thorntail applications are packaged in two ways:
- Packaged with the Thorntail runtime as an as Uberjar, an executable JAR,
- Packaged in a standard WAR archive to be deployed and run in a Thorntail hollow JAR, a runtime-only executable JAR.
When migrated to JBoss EAP XP, a Thorntail application can be packaged as a bootable JAR and trim down the JBoss EAP XP runtime to include the MicroProfile platform and other technologies that the application depends on.
When migrating an application to JBoss EAP XP, you must remove any Thorntail fraction dependency, and add the artifacts of any required MicroProfile and Jakarta EE 8 specifications to the Maven Project dependencies.
You can use the JBoss CLI tool or JBoss EAP web console at runtime to make changes to the server configuration. However, unlike the configuration changes made during packaging, any changes made to the configuration at runtime are not persisted and are lost when you restart the bootable JAR.
3.1. Migrating a Thorntail application Maven project into JBoss EAP XP
If you have a Thorntail application that relies on technologies such as Jakarta Enterprise Beans, Jakarta Server Faces, Jakarta Connector API, SOAP web services, or CORBA, you can migrate your application’s Maven project into JBoss EAP XP.
Galleon layers are used to configure the capabilities of the JBoss EAP XP runtime packaged in a bootable JAR. When you migrate a Thorntail application that uses Jakarta EE 8 specifications, you must add the relevant Galleon layers to the bootable JAR Maven plug-in configuration.
When using Galleon layers, JBoss EAP XP generates a server configuration and packages it inside the bootable JAR. If no Galleon layers are used, a configuration identical to the default standalone-microprofile.xml
is packaged in the bootable JAR.
If you are building a bootable JAR for cloud by using the <cloud>
configuration element, an OpenShift configuration similar to the default standalone-microprofile-ha.xml
is applied to your bootable JAR.
The bootable JAR Maven plug-in executes JBoss CLI scripts while packaging the bootable JAR .
Procedure
Remove any Thorntail BOM import.
Example of removing the
io.thorntail
Thorntail BOM import from thepom.xml
file.<dependencyManagement> <dependencies> <dependency> <groupId>io.thorntail</groupId> <artifactId>bom</artifactId> <version>${version.thorntail}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>
Use the JBoss EAP XP BOMs to import supported artifacts to JBoss EAP XP dependency management.
Example of using the
jboss-eap-jakartaee8-with-tools
BOM to import supported artifacts to a project.<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>
NoteImport the
jakartaee8-with-tools
BOM only if your application depends on Jakarta EE 8 specifications that are not included in the MicroProfile platform.Replace the Thorntail Maven plug-in with the JBoss EAP XP bootable JAR Maven plug-in.
Example showing the replacement of the Thorntail Maven plug-in with the JBoss EAP XP bootable JAR Maven plug-in.
<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>
NoteThe previous example specifies the following property for the Maven plug-in version:
${bootable.jar.maven.plugin.version}
You must set your Maven plug-in version in place of this property in your project. For example:
<properties> <bootable.jar.maven.plugin.version>4.0.3.Final-redhat-00001</bootable.jar.maven.plugin.version> </properties>
-
The bootable JAR plug-in builds an UberJAR by default, which means it packages the JBoss EAP XP runtime with the application deployed. To build a hollow JAR, add
<hollow-jar>true</hollow-jar>
to the configuration of the plug-in.
-
The bootable JAR plug-in builds an UberJAR by default, which means it packages the JBoss EAP XP runtime with the application deployed. To build a hollow JAR, add
Make the following changes to the Thorntail fractions in the Maven project.
Remove the Thorntail fraction dependencies.
Example showing the removal of the
io.thorntail
Thorntail fractions from a Maven project.<dependencies> <dependency> <groupId>io.thorntail</groupId> <artifactId>jaxrs</artifactId> </dependency> </dependencies>
Configure Maven dependencies.
Example of using an XML snippet to add dependencies to the artifacts of the Jakarta EE 8 JAX-RS and MicroProfile Config APIs.
<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>
- Remove Thorntail YAML files, system properties and environment properties.
Configure Galleon layers.
Example of configuring Galleon layers in the bootable JAR Maven plug-in for an application that requires JAX-RS.
<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>
Additional resources
- For more information about configuring Galleon layers, see Specifying Galleon layers for your bootable JAR server in the Using MicroProfile with JBoss EAP XP 3.0.0 book.
- For more information about using CLI scripts,see CLI scripts in the Using MicroProfile with JBoss EAP XP 3.0.0 book.
- For more information about the Red Hat build of Thorntail approaching its end of life, see Red Hat build of Thorntail 2.7 - End of Life in the Thorntail documentation.
- For more information about building and running a JBoss EAP XP bootable JAR, see The bootable JAR in the Using MicroProfile with JBoss EAP XP 3.0.0 book.
- For more information about Thorntail BOMs, see Using a BOM in the Thorntail documentation.
- For more information about Thorntail compatible Maven artifacts and BOMs, see Red Hat build of Thorntail 2.7.1 Component Details on the Red Hat Customer Portal.
- For more information about the supported JBoss EAP MicroProfile BOM, see Supported JBoss EAP MicroProfile BOM in the Using MicroProfile with JBoss EAP XP 3.0.0 book.