このコンテンツは選択した言語では利用できません。
Migration Guide
Migrating to Red Hat Fuse 7.4
Abstract
Preface
This guide provides information on updating Red Hat Fuse and Fuse applications:
If you want to migrate from Fuse 6 to the latest Fuse 7 release, before you follow the instructions in this guide, you should follow the instructions in the Red Hat Fuse 7.0 Migration Guide.
Chapter 1, Upgrading Fuse applications on Spring Boot standalone
Chapter 2, Upgrading Fuse applications on JBoss EAP standalone
Chapter 1. Upgrading Fuse applications on Spring Boot standalone
To upgrade your Fuse applications on Spring Boot, you must update your Fuse project’s Maven dependencies to ensure that you are using the correct version of Fuse.
Typically, you use Maven to build Fuse applications. Maven is a free and open source build tool from Apache. Maven configuration is defined in a Fuse application project’s pom.xml file. While building a Fuse project, the default behavior is that Maven searches external repositories and downloads the required artifacts. You add a dependency for the Fuse Bill of Materials (BOM) to the pom.xml file so that the Maven build process picks up the correct set of Fuse supported artifacts.
The following sections provide information on Maven dependencies and how to update them in your Fuse projects.
1.1. About Maven dependencies
The purpose of a Maven Bill of Materials (BOM) file is to provide a curated set of Maven dependency versions that work well together, saving you from having to define versions individually for every Maven artifact.
There is a dedicated BOM file for each container in which Fuse runs.
You can find these BOM files here: https://github.com/jboss-fuse/redhat-fuse. Alternatively, go to the latest Release Notes for information on BOM file updates.
The Fuse BOM offers the following advantages:
-
Defines versions for Maven dependencies, so that you do not need to specify the version when you add a dependency to your
pom.xmlfile. - Defines a set of curated dependencies that are fully tested and supported for a specific version of Fuse.
- Simplifies upgrades of Fuse.
Only the set of dependencies defined by a Fuse BOM are supported by Red Hat.
1.2. Updating your Fuse project’s Maven dependencies
To upgrade your Fuse application for Spring Boot, update your project’s Maven dependencies.
Procedure
-
Open your project’s
pom.xmlfile. Add a
dependencyManagementelement in your project’spom.xmlfile (or, possibly, in a parentpom.xmlfile), as shown in the following example:<?xml version="1.0" encoding="UTF-8" standalone="no"?> <project ...> ... <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <!-- configure the versions you want to use here --> <fuse.version>7.4.0.fuse-740036-redhat-00002</fuse.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.jboss.redhat-fuse</groupId> <artifactId>fuse-springboot-bom</artifactId> <version>${fuse.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> ... </project>NoteEnsure you update your Spring Boot version as well. This is typically found under the Fuse version in the
pom.xmlfile:<properties> <!-- configure the versions you want to use here --> <fuse.version>7.4.0.fuse-740036-redhat-00002</fuse.version> <spring-boot.version>1.5.19.RELEASE</spring-boot.version> </properties>-
Save your
pom.xmlfile.
After you specify the BOM as a dependency in your pom.xml file, it becomes possible to add Maven dependencies to your pom.xml file without specifying the version of the artifact. For example, to add a dependency for the camel-velocity component, you would add the following XML fragment to the dependencies element in your pom.xml file:
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-velocity</artifactId> <scope>provided</scope> </dependency>
Note how the version element is omitted from this dependency definition.
Chapter 2. Upgrading Fuse applications on JBoss EAP standalone
To upgrade your Fuse applications on JBoss EAP, you must update your Fuse project’s Maven dependencies to ensure that you are using the correct version of Fuse.
Typically, you use Maven to build Fuse applications. Maven is a free and open source build tool from Apache. Maven configuration is defined in a Fuse application project’s pom.xml file. While building a Fuse project, the default behavior is that Maven searches external repositories and downloads the required artifacts. You add a dependency for the Fuse Bill of Materials (BOM) to the pom.xml file so that the Maven build process picks up the correct set of Fuse supported artifacts.
The following sections provide information on Maven dependencies and how to update them in your Fuse projects.
2.1. About Maven dependencies
The purpose of a Maven Bill of Materials (BOM) file is to provide a curated set of Maven dependency versions that work well together, saving you from having to define versions individually for every Maven artifact.
There is a dedicated BOM file for each container in which Fuse runs.
You can find these BOM files here: https://github.com/jboss-fuse/redhat-fuse. Alternatively, go to the latest Release Notes for information on BOM file updates.
The Fuse BOM offers the following advantages:
-
Defines versions for Maven dependencies, so that you do not need to specify the version when you add a dependency to your
pom.xmlfile. - Defines a set of curated dependencies that are fully tested and supported for a specific version of Fuse.
- Simplifies upgrades of Fuse.
Only the set of dependencies defined by a Fuse BOM are supported by Red Hat.
2.2. Updating your Fuse project’s Maven dependencies
To upgrade your Fuse application for JBoss EAP, update your project’s Maven dependencies.
Procedure
-
Open your project’s
pom.xmlfile. Add a
dependencyManagementelement in your project’spom.xmlfile (or, possibly, in a parentpom.xmlfile), as shown in the following example:<?xml version="1.0" encoding="UTF-8" standalone="no"?> <project ...> ... <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <!-- configure the versions you want to use here --> <fuse.version>7.4.0.fuse-740036-redhat-00002</fuse.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.jboss.redhat-fuse</groupId> <artifactId>fuse-eap-bom</artifactId> <version>${fuse.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> ... </project>-
Save your
pom.xmlfile.
After you specify the BOM as a dependency in your pom.xml file, it becomes possible to add Maven dependencies to your pom.xml file without specifying the version of the artifact. For example, to add a dependency for the camel-velocity component, you would add the following XML fragment to the dependencies element in your pom.xml file:
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-velocity</artifactId> <scope>provided</scope> </dependency>
Note how the version element is omitted from this dependency definition.
Chapter 3. Upgrading Fuse applications on Karaf standalone
To upgrade your Fuse applications on Karaf, you must update your Fuse project’s Maven dependencies to ensure that you are using the correct version of Fuse.
Typically, you use Maven to build Fuse applications. Maven is a free and open source build tool from Apache. Maven configuration is defined in a Fuse application project’s pom.xml file. While building a Fuse project, the default behavior is that Maven searches external repositories and downloads the required artifacts. You add a dependency for the Fuse Bill of Materials (BOM) to the pom.xml file so that the Maven build process picks up the correct set of Fuse supported artifacts.
The following sections provide information on Maven dependencies and how to update them in your Fuse projects.
3.1. About Maven dependencies
The purpose of a Maven Bill of Materials (BOM) file is to provide a curated set of Maven dependency versions that work well together, saving you from having to define versions individually for every Maven artifact.
There is a dedicated BOM file for each container in which Fuse runs.
You can find these BOM files here: https://github.com/jboss-fuse/redhat-fuse. Alternatively, go to the latest Release Notes for information on BOM file updates.
The Fuse BOM offers the following advantages:
-
Defines versions for Maven dependencies, so that you do not need to specify the version when you add a dependency to your
pom.xmlfile. - Defines a set of curated dependencies that are fully tested and supported for a specific version of Fuse.
- Simplifies upgrades of Fuse.
Only the set of dependencies defined by a Fuse BOM are supported by Red Hat.
3.2. Updating your Fuse project’s Maven dependencies
To upgrade your Fuse application for Karaf, update your project’s Maven dependencies.
Procedure
-
Open your project’s
pom.xmlfile. Add a
dependencyManagementelement in your project’spom.xmlfile (or, possibly, in a parentpom.xmlfile), as shown in the following example:<?xml version="1.0" encoding="UTF-8" standalone="no"?> <project ...> ... <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <!-- configure the versions you want to use here --> <fuse.version>7.4.0.fuse-740036-redhat-00002</fuse.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.jboss.redhat-fuse</groupId> <artifactId>fuse-karaf-bom</artifactId> <version>${fuse.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> ... </project>-
Save your
pom.xmlfile.
After you specify the BOM as a dependency in your pom.xml file, it becomes possible to add Maven dependencies to your pom.xml file without specifying the version of the artifact. For example, to add a dependency for the camel-velocity component, you would add the following XML fragment to the dependencies element in your pom.xml file:
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-velocity</artifactId> <scope>provided</scope> </dependency>
Note how the version element is omitted from this dependency definition.
Chapter 4. Upgrading Fuse Standalone on Karaf
The Fuse on Apache Karaf upgrade mechanism enables you to apply fixes to an Apache Karaf container without needing to reinstall an updated version of Fuse on Karaf. It also allows you to roll back the upgrade, if the upgrade causes problems with your deployed applications.
The upgrade installer file is the same file that you use to install Fuse on Apache Karaf.
To obtain the upgrade installer file, go to the Downloads page of the Red Hat customer portal and download the latest version of the installation archive for Fuse on Apache Karaf (for example, fuse-karaf-7.4.0.fuse-740028-redhat-00001.zip).
4.1. Impact of upgrading Fuse on Karaf
The upgrade mechanism can make updates to any installation files including bundle JARs and static files (including, for example, configuration files under the etc/ directory). The Fuse on Apache Karaf upgrade process:
- Updates any files, including bundle JARs, configuration files, and any static files.
-
Patches both the current container instance (and its runtime storage under the
data/directory) and the underlying installation. Hence, patches are preserved after deleting a container instance. - Updates all of the files related to Karaf features, including the features repository files and the features themselves. Hence, any features installed after the rollup patch will reference the correct patched dependencies.
-
If necessary, updates configuration files (for example, files under
etc/), automatically merging any configuration changes you have made with the configuration changes made by the patch. If merge conflicts occur, see the patch log for details of how they are handled. - Most of the merge conflicts are resolved automatically. For example, the patch mechanism detects conflicts at property level for the property files. It detects whether it was a user or patch that changed any property. The change is preserved, if only one side changed the property.
Tracks all of the changes made to the installation (including to static files), so that it is possible to roll back the patch.
NoteThe rollup patching mechanism uses an internal git repository (located under
patches/.management/history) to track the changes made.
4.2. Upgrading Fuse Standalone on Karaf
The following instructions guide you through upgrading Fuse on Apache Karaf. Ensure all prerequisites are completed before commencing the upgrade procedure.
Prerequisites
- Ensure you have a full backup of your Fuse on Apache Karaf installation before upgrading.
- Start the container, if it is not already running.
If the container is running in the background (or remotely), connect to the container using the SSH console client, bin/client.
Add the upgrade installer file to the container’s environment by invoking the
patch:addcommand. For example, to add thefuse-karaf-7.4.0.fuse-740028-redhat-00001.zipupgrade installer file:patch:add file:///path/to/fuse-karaf-7.4.0.fuse-740028-redhat-00001.zip
Procedure
Run the
patch:updatecommand. There is no need to restart the container.karaf@root()> patch:update Current patch mechanism version: 7.1.0.fuse-710023-redhat-00001 New patch mechanism version detected: 7.2.0.fuse-720035-redhat-00001 Uninstalling patch features in version 7.1.0.fuse-710023-redhat-00001 Installing patch features in version 7.2.0.fuse-720035-redhat-00001
Invoke the
patch:listcommand to display a list of upgrade installers. In this list, the entries under the[name]heading are upgrade IDs. For example:karaf@root()> patch:list [name] [installed] [rollup] [description] fuse-karaf-7.2.0.fuse-720035-redhat-00001 false true fuse-karaf-7.2.0.fuse-720035-redhat-00001
Simulate the upgrade by invoking the
patch:simulatecommand and specifying the upgrade ID for the upgrade that you want to apply, as follows:karaf@root()> patch:simulate fuse-karaf-7.2.0.fuse-720035-redhat-00001 INFO : org.jboss.fuse.modules.patch.patch-management (226): Installing rollup patch "fuse-karaf-7.2.0.fuse-720035-redhat-00001" ========== Repositories to remove (9): - mvn:io.hawt/hawtio-karaf/2.0.0.fuse-710018-redhat-00002/xml/features ... ========== Repositories to add (9): - mvn:io.hawt/hawtio-karaf/2.0.0.fuse-720044-redhat-00001/xml/features ... ========== Repositories to keep (10): - mvn:org.apache.activemq/artemis-features/2.4.0.amq-711002-redhat-1/xml/features ... ========== Features to update (100): [name] [version] [new version] aries-blueprint 4.2.0.fuse-710024-redhat-00002 4.2.0.fuse-720061-redhat-00001 ... ========== Bundles to update as part of features or core bundles (100): [symbolic name] [version] [new location] io.hawt.hawtio-log 2.0.0.fuse-710018-redhat-00002 mvn:io.hawt/hawtio-log/2.0.0.fuse-720044-redhat-00001 ... ========== Bundles to reinstall as part of features or core bundles (123): [symbolic name] [version] [location] com.fasterxml.jackson.core.jackson-annotations 2.8.11 mvn:com.fasterxml.jackson.core/jackson-annotations/2.8.11 ... Simulation only - no files and runtime data will be modified. karaf@root()>
This generates a log of the changes that will be made to the container when the upgrade is performed, but will not make any actual changes to the container. Review the simulation log to understand the changes that will be made to the container.
Upgrade the container by invoking the
patch:installcommand and specifying the upgrade ID for the upgrade that you want to apply. For example:karaf@root()> patch:install fuse-karaf-7.4.0.fuse-740028-redhat-00001
Validate the upgrade, by searching for one of the upgrade artifacts. For example, if you had just upgraded Fuse 7.1.0 to Fuse 7.2.0, you could search for bundles with the build number, 740028, as follows:
karaf@root()> bundle:list -l | grep 740028 22 │ Active │ 80 │ 7.4.0.fuse-740028-redhat-00001 │ mvn:org.jboss.fuse.modules/fuse-pax-transx-tm-narayana/7.4.0.fuse-740028-redhat-00001 188 │ Active │ 80 │ 7.4.0.fuse-740028-redhat-00001 │ mvn:org.jboss.fuse.modules.patch/patch-commands/7.4.0.fuse-740028-redhat-00001
After upgrading, you also see the new version and build number in the Welcome banner when you restart the container.
4.3. Rolling back an upgrade for Fuse on Karaf
Occasionally an upgrade might not work or might introduce new issues to a container. In these cases, you can easily roll back the upgrade and restore your system to its previous state using the patch:rollback command. This set of instructions guides you through this procedure.
Prerequisites
- You have recently upgraded Fuse on Karaf.
- You want to rollback the upgrade.
Procedure
-
Invoke the
patch:listcommand to obtain the upgrade ID,UPGRADE_ID, of the most recently installed patch. Invoke the
patch:rollbackcommand, as follows:patch:rollback UPGRADE_ID
NoteIn some cases the container needs to restart to roll back the upgrade. In these cases, the container restarts automatically. Due to the highly dynamic nature of the OSGi runtime, during the restart you might see some occasional errors related to incompatible classes. These errors are related to OSGi services that have just started or stopped and can be safely ignored.
