JBoss EAP XP upgrade and migration guide

Red Hat JBoss Enterprise Application Platform 7.3

Guidance for upgrading and migrating from JBoss EAP XP 1.0.x to JBoss EAP XP 2.0.0

Red Hat Customer Content Services

Abstract

This document provides information about upgrading JBoss EAP XP 1.0.x to JBoss EAP XP 2.0.0 and any necessary application migration.

Chapter 1. JBoss EAP XP upgrades

JBoss EAP XP 2.0.0 introduces new features. Upgrade JBoss EAP XP 1.0.x to JBoss EAP XP 2.0.0 to add these features and capabilities to your installation:

  • Bootable JAR creation: a bootable JAR contains the server, a packaged application, and the runtime required to launch the server.

  • Additional server health probes:

    • server-status: Indicates whether the server is running.
    • boot-errors: Indicates whether boot errors were detected.
    • deployment-status: Indicates the status of deployments.

1.1. Upgrading JBoss EAP XP 1.0.x to 2.0.0

Upgrade JBoss EAP XP 1.0.x to 2.0.0 using the upgrade command that is provided in JBoss EAP XP manager.

Note

JBoss EAP XP 2.0.0 is certified with JBoss EAP 7.3.4 and 7.3.z versions.

Prerequisites

  • The base JBoss EAP server is updated to patch 7.3.4 or a later patch.
  • You have downloaded the JBoss EAP XP 2.0.0 patch from the Product download page.

Procedure

  1. Verify that your server is on the correct patch and has JBoss EAP XP 1.0.x installed: 

    $ java -jar jboss-eap-xp-manager.jar status --jboss-home=__<path_to_eap>__
...
You are currently on JBoss EAP XP 1.
You are using an old version of JBoss EAP XP. The current version is 2, please upgrade.
Enabled patch streams and their cumulative patch ids:
- Patch stream: 'JBoss EAP'; Cumulative patch id: 'jboss-eap-7.3.4'
- Patch stream: 'jboss-eap-xp-1.0'; Cumulative patch id: 'jboss-eap-xp-1.0.0.CP'
Available commands in this state are: [remove, upgrade]

    This output indicates that your server is ready for upgrade to JBoss EAP XP 2.0.0.

    If you see other output, refer to the troubleshooting recommendations.

  2. Use the upgrade command to upgrade JBoss EAP XP 1.0.x to 2.0.0 and apply the JBoss EAP XP 2.0.0 patch. 

    $ java -jar jboss-eap-xp-manager.jar upgrade --jboss-home=__<path_to_eap>__ --xp-patch=__<path_to_patch>__/jboss-eap-xp-2.0.0-patch.zip

  3. Accept the support policy prompt by entering yes.

    Your server is ready to manage the JBoss EAP XP 2.0.0 patch stream and is updated with the JBoss EAP XP 2.0.0 patch.

Additional resources

1.2. JBoss EAP XP 2.0.0 upgrade troubleshooting

If the JBoss EAP XP manager status command returns an error output, consult the following troubleshooting recommendations.

Incompatible version of JBoss EAP

The JBoss EAP XP manager setup command returns an error such as the following: 

JBoss EAP version 7.3.1 is incompatible with the JBoss EAP XP stream. To run this manager, please upgrade to at least JBoss EAP 7.3.4.

This message indicates JBoss EAP is not on the correct patch for JBoss EAP XP 2.0.0. Download and apply patch 7.3.4.

Existing patch in an inconsistent state

The JBoss EAP XP manager status command returns an error such as the following: 

The JBoss EAP XP patch stream setup in the JBoss EAP server seems broken.

This message indicates that JBoss EAP XP is in an inconsistent state. This state might occur if a user modified a file in JBoss EAP XP or if problem occurred in the previous installation. Remove the existing patch and install JBoss EAP XP 2.0.0.

More than one JBoss EAP XP patch stream installed

The JBoss EAP XP manager status command returns an error such as the following: 

You have more than one JBoss EAP XP patch stream set up in the JBoss EAP server.

This message indicates that patches from different versions of JBoss EAP XP exist on JBoss EAP. This state might occur if you installed an older patch after installing a more recent patch. Remove the existing patches and install JBoss EAP XP 2.0.0.

Additional resources

1.2.1. Removing and reinstalling JBoss EAP XP

You must remove and reinstall JBoss EAP XP to solve some status errors.

Procedure

  1. Remove the JBoss EAP XP patch stream by using the remove command of JBoss EAP XP manager 2.0.0: 

    $ java -jar jboss-eap-xp-manager.jar remove --jboss-home=__<path_to_eap>__
  2. Reinstall JBoss EAP XP 2.0.0.

Additional resources

1.3. Patching JBoss EAP XP 2.0.0

If Red Hat releases a patch for JBoss EAP XP, use the JBoss EAP XP manager patch-apply command to apply it.

Procedure

  1. Download the patch from the Product downloads page.

  2. Run the following command: 

    $ java -jar jboss-eap-xp-manager.jar patch-apply --jboss-home=__<path_to_eap>__ --patch=__<path_to_eap_patch>__/jboss-eap-xp-2.0.1-patch.zip

    Replace placeholder eap_home_path with the path to the JBoss EAP installation directory. Replace path_to_eap_patch with the path to the location where you downloaded the JBoss EAP XP. Replace jboss-eap-xp-2.0.0-patch.zip with the name of the patch file that you downloaded.

    Your server is updated with the specified patch.

Additional resources

Legal Notice

Copyright © 2021 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.