Migration Guide

• For Automatic updates, when a new version of the Fuse Online operator is available, the OpenShift Operator Lifecycle Manager (OLM) automatically upgrades the running instance of the Fuse Online without human intervention.
• For Manual updates, when a newer version of an Operator is available, the OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Fuse Online operator updated to the new version as described in the Manually approving a pending Operator upgrade section of the OpenShift documentation.

• From Fuse Online 7.9 to Fuse Online 7.10
• From a Fuse Online 7.10 version to a newer Fuse Online 7.10 version

Prerequisites

• You installed and are running version 7.9 of Fuse Online on OCP 3.11 on-site OR you installed and are running a version of 7.10 of Fuse Online on OCP 3.11 and you want to upgrade to fresh application images.

  For earlier versions:

  • If you are running version 7.8 of Fuse Online on OCP, then you must upgrade to 7.9 and then you can upgrade to 7.10.
  • If you are running version 7.7 of Fuse Online on OCP, then you must upgrade to 7.8 and then you can upgrade to 7.9.
  • If you are running version 7.6 of Fuse Online on OCP, then you must upgrade to 7.7 and then you can upgrade to 7.8.
  • If you are running version 7.5 of Fuse Online on OCP, then you must upgrade to 7.6 and then you can upgrade to 7.7.
  • If you are running version 7.4 of Fuse Online on OCP, then you must upgrade to 7.5 and then you can upgrade to 7.6.
  • If you are running version 7.3 of Fuse Online on OCP, then you must upgrade to 7.4 and then you can upgrade to 7.5.
  • If you are running version 7.2 of Fuse Online on OCP, then you must upgrade to 7.3.
  • If you are running version 7.1 of Fuse Online on OCP, then you must upgrade to 7.2.
• You installed the oc client tool and it is connected to the OCP cluster in which Fuse Online is installed.
• You have cluster administration permissions, which are required for the first two steps in this procedure.

• Upgrade to the latest 1.5.x version

  • Before you start, upgrade to the latest 1.5.x available version. This is to ensure that you are building against the most recent dependencies of that line.

• Review dependencies

  • The migration to Spring Boot 2 will result in upgrading a number of dependencies. Review the dependency management for 1.5.x with the dependency management for 2.0.x to assess how your project is affected.
  • Identify the compatible versions for the dependencies that are not managed by Spring Boot and then define the explicit versions for these.

• Review custom configuration

  • Any custom configuration that your project defines might need to be reviewed on upgrade. If this can be replaced by the use of standard auto-configuration, do it so before upgrading.

• Review system requirements

  • Spring Boot 2.0 requires Java 8 or later.
  • It also requires Spring Framework 5.0.
  • Java 6 and 7 are no longer supported.

• Update your applications to create the connection bean as a com.mongodb.client.MongoClient instance.

  For example, create a connection to MongoDB as follows:

  import com.mongodb.client.MongoClient;

  You can then create the MongoClient bean as shown in following example:

  return MongoClients.create("mongodb://admin:password@192.168.99.102:32553");

• Evaluate and, if needed, refactor any code related to the methods exposed by the MongoClient class.

• Camel has upgraded from Spring Boot v1 to v2 and therefore v1 is no longer supported.
• Upgraded to Spring Framework 5. Camel should work with Spring 4.3.x as well, but going forward Spring 5.x will be the minimum Spring version in future releases.
• Upgraded to Karaf 4.2. You may run Camel on Karaf 4.1 but we only officially support Karaf 4.2 in this release.
• Optimized using toD DSL to reuse endpoints and producers for components where it is possible. For example, HTTP based components will now reuse producer (HTTP clients) with dynamic URIs sending to the same host.
• The File2 consumer with read-lock idempotent/idempotent-changed can now be configured to delay the release tasks to expand the window when a file is regarded as in-process, which is usable in active/active cluster settings with a shared idempotent repository to ensure other nodes don’t too quickly see a processed file as a file they can process (only needed if you have readLockRemoveOnCommit=true).
• Allow to plugin a custom request/reply correlation id manager implementation on Netty4 producer in request/reply mode. The Twitter component now uses extended mode by default to support tweets greater than 140 characters
• Rest DSL producer now supports being configured in REST configuration by using endpointProperties.
• The Kafka component now supports HeaderFilterStrategy to plugin custom implementations for controlling header mappings between Camel and Kafka messages.
• REST DSL now supports client request validation to validate that Content-Type/Accept headers are possible for the REST service.
• Camel now has a Service Registry SPI which allows you to register routes to a service registry (such as consul, etcd, or zookeeper) by using a Camel implementation or Spring Cloud.
• The SEDA component now has a default queue size of 1000 instead of unlimited.

• The following noteworthy issues have been fixed:

  • Fixed a CXF continuation timeout issue with camel-cxf consumer that could cause the consumer to return a response with data instead of triggering a timeout to the calling SOAP client.
  • Fixed camel-cxf consumer doesn’t release UoW when using a robust one-way operation.
  • Fixed using AdviceWith and using weave methods on onException etc. not working.
  • Fixed Splitter in parallel processing and streaming mode may block, while iterating message body when the iterator throws an exception in the first invoked next() method call.
  • Fixed Kafka consumer to not auto commit if autoCommitEnable=false.
  • Fixed file consumer was using markerFile as read-lock by default, which should have been none.
  • Fixed using manual commit with Kafka to provide the current record offset and not the previous (and -1 for first).
  • Fixed Content Based Router in Java DSL may not resolve property placeholders in when predicates.

• Upgraded to Spring Boot 2.1.
• Additional component-level options can now be configured by using spring-boot auto-configuration. These options are included in the spring-boot component metadata JSON file descriptor for tooling assistance.
• Added a documentation section that includes all the Spring Boot auto configuration options for all the components, data-formats, and languages.
• All the Camel Spring Boot starter JARs now include META-INF/spring-autoconfigure-metadata.properties file in their JARs to optimize Spring Boot auto-configuration.
• The Throttler now supports correlation groups based on dynamic expression so that you can group messages into different throttled sets.
• The Hystrix EIP now allows inheritance for Camel’s error handler so that you can retry the entire Hystrix EIP block again if you have enabled error handling with redeliveries.
• SQL and ElSql consumers now support dynamic query parameters in route form. Note that this feature is limited to calling beans by using simple expressions.
• The swagger-restdsl maven plugin now supports generating DTO model classes from the Swagger specification file.

• The following noteworthy issues have been fixed:

  • The Aggregator2 has been fixed to not propagate control headers for forcing completion of all groups, so it will not happen again if another aggregator EIP is in use later during routing.
  • Fixed Tracer not working if redelivery was activa†ed in the error handler.
  • The built-in type converter for XML Documents may output parsing errors to stdout, which has now been fixed to output by using the logging API.
  • Fixed SFTP writing files by using the charset option would not work if the message body was streaming-based.
  • Fixed Zipkin root id to not be reused when routing over multiple routes to group them together into a single parent span.
  • Fixed optimized toD when using HTTP endpoints had a bug when the hostname contains an IP address with digits.
  • Fixed issue with RabbitMQ with request/reply over temporary queues and using manual acknowledge mode. It would not acknowledge the temporary queue (which is needed to make request/reply possible).
  • Fixed various HTTP consumer components that may not return all allowed HTTP verbs in Allow header for OPTIONS requests (such as when using rest-dsl).
  • Fixed the thread-safety issue with FluentProducerTemplate.

• Defines versions for Maven dependencies, so that you do not need to specify the version when you add a dependency to your pom.xml file.
• Defines a set of curated dependencies that are fully tested and supported for a specific version of Fuse.
• Simplifies upgrades of Fuse.

• Update your applications to create the connection bean as a com.mongodb.client.MongoClient instance.

  For example, create a connection to MongoDB as follows:

  import com.mongodb.client.MongoClient;

  You can then create the MongoClient bean as shown in following example:

  return MongoClients.create("mongodb://admin:password@192.168.99.102:32553");

• Evaluate and, if needed, refactor any code related to the methods exposed by the MongoClient class.

• Camel has upgraded from Spring Boot v1 to v2 and therefore v1 is no longer supported.
• Upgraded to Spring Framework 5. Camel should work with Spring 4.3.x as well, but going forward Spring 5.x will be the minimum Spring version in future releases.
• Upgraded to Karaf 4.2. You may run Camel on Karaf 4.1 but we only officially support Karaf 4.2 in this release.
• Optimized using toD DSL to reuse endpoints and producers for components where it is possible. For example, HTTP based components will now reuse producer (HTTP clients) with dynamic URIs sending to the same host.
• The File2 consumer with read-lock idempotent/idempotent-changed can now be configured to delay the release tasks to expand the window when a file is regarded as in-process, which is usable in active/active cluster settings with a shared idempotent repository to ensure other nodes don’t too quickly see a processed file as a file they can process (only needed if you have readLockRemoveOnCommit=true).
• Allow to plugin a custom request/reply correlation id manager implementation on Netty4 producer in request/reply mode. The Twitter component now uses extended mode by default to support tweets greater than 140 characters
• Rest DSL producer now supports being configured in REST configuration by using endpointProperties.
• The Kafka component now supports HeaderFilterStrategy to plugin custom implementations for controlling header mappings between Camel and Kafka messages.
• REST DSL now supports client request validation to validate that Content-Type/Accept headers are possible for the REST service.
• Camel now has a Service Registry SPI which allows you to register routes to a service registry (such as consul, etcd, or zookeeper) by using a Camel implementation or Spring Cloud.
• The SEDA component now has a default queue size of 1000 instead of unlimited.

• The following noteworthy issues have been fixed:

  • Fixed a CXF continuation timeout issue with camel-cxf consumer that could cause the consumer to return a response with data instead of triggering a timeout to the calling SOAP client.
  • Fixed camel-cxf consumer doesn’t release UoW when using a robust one-way operation.
  • Fixed using AdviceWith and using weave methods on onException etc. not working.
  • Fixed Splitter in parallel processing and streaming mode may block, while iterating message body when the iterator throws an exception in the first invoked next() method call.
  • Fixed Kafka consumer to not auto commit if autoCommitEnable=false.
  • Fixed file consumer was using markerFile as read-lock by default, which should have been none.
  • Fixed using manual commit with Kafka to provide the current record offset and not the previous (and -1 for first).
  • Fixed Content Based Router in Java DSL may not resolve property placeholders in when predicates.

• Upgraded to Spring Boot 2.1.
• Additional component-level options can now be configured by using spring-boot auto-configuration. These options are included in the spring-boot component metadata JSON file descriptor for tooling assistance.
• Added a documentation section that includes all the Spring Boot auto configuration options for all the components, data-formats, and languages.
• All the Camel Spring Boot starter JARs now include META-INF/spring-autoconfigure-metadata.properties file in their JARs to optimize Spring Boot auto-configuration.
• The Throttler now supports correlation groups based on dynamic expression so that you can group messages into different throttled sets.
• The Hystrix EIP now allows inheritance for Camel’s error handler so that you can retry the entire Hystrix EIP block again if you have enabled error handling with redeliveries.
• SQL and ElSql consumers now support dynamic query parameters in route form. Note that this feature is limited to calling beans by using simple expressions.
• The swagger-restdsl maven plugin now supports generating DTO model classes from the Swagger specification file.

• The following noteworthy issues have been fixed:

  • The Aggregator2 has been fixed to not propagate control headers for forcing completion of all groups, so it will not happen again if another aggregator EIP is in use later during routing.
  • Fixed Tracer not working if redelivery was activa†ed in the error handler.
  • The built-in type converter for XML Documents may output parsing errors to stdout, which has now been fixed to output by using the logging API.
  • Fixed SFTP writing files by using the charset option would not work if the message body was streaming-based.
  • Fixed Zipkin root id to not be reused when routing over multiple routes to group them together into a single parent span.
  • Fixed optimized toD when using HTTP endpoints had a bug when the hostname contains an IP address with digits.
  • Fixed issue with RabbitMQ with request/reply over temporary queues and using manual acknowledge mode. It would not acknowledge the temporary queue (which is needed to make request/reply possible).
  • Fixed various HTTP consumer components that may not return all allowed HTTP verbs in Allow header for OPTIONS requests (such as when using rest-dsl).
  • Fixed the thread-safety issue with FluentProducerTemplate.

• Defines versions for Maven dependencies, so that you do not need to specify the version when you add a dependency to your pom.xml file.
• Defines a set of curated dependencies that are fully tested and supported for a specific version of Fuse.
• Simplifies upgrades of Fuse.

• Update your applications to create the connection bean as a com.mongodb.client.MongoClient instance.

  For example, create a connection to MongoDB as follows:

  import com.mongodb.client.MongoClient;

  You can then create the MongoClient bean as shown in following example:

  return MongoClients.create("mongodb://admin:password@192.168.99.102:32553");

• Evaluate and, if needed, refactor any code related to the methods exposed by the MongoClient class.

• Camel has upgraded from Spring Boot v1 to v2 and therefore v1 is no longer supported.
• Upgraded to Spring Framework 5. Camel should work with Spring 4.3.x as well, but going forward Spring 5.x will be the minimum Spring version in future releases.
• Upgraded to Karaf 4.2. You may run Camel on Karaf 4.1 but we only officially support Karaf 4.2 in this release.
• Optimized using toD DSL to reuse endpoints and producers for components where it is possible. For example, HTTP based components will now reuse producer (HTTP clients) with dynamic URIs sending to the same host.
• The File2 consumer with read-lock idempotent/idempotent-changed can now be configured to delay the release tasks to expand the window when a file is regarded as in-process, which is usable in active/active cluster settings with a shared idempotent repository to ensure other nodes don’t too quickly see a processed file as a file they can process (only needed if you have readLockRemoveOnCommit=true).
• Allow to plugin a custom request/reply correlation id manager implementation on Netty4 producer in request/reply mode. The Twitter component now uses extended mode by default to support tweets greater than 140 characters
• Rest DSL producer now supports being configured in REST configuration by using endpointProperties.
• The Kafka component now supports HeaderFilterStrategy to plugin custom implementations for controlling header mappings between Camel and Kafka messages.
• REST DSL now supports client request validation to validate that Content-Type/Accept headers are possible for the REST service.
• Camel now has a Service Registry SPI which allows you to register routes to a service registry (such as consul, etcd, or zookeeper) by using a Camel implementation or Spring Cloud.
• The SEDA component now has a default queue size of 1000 instead of unlimited.

• The following noteworthy issues have been fixed:

  • Fixed a CXF continuation timeout issue with camel-cxf consumer that could cause the consumer to return a response with data instead of triggering a timeout to the calling SOAP client.
  • Fixed camel-cxf consumer doesn’t release UoW when using a robust one-way operation.
  • Fixed using AdviceWith and using weave methods on onException etc. not working.
  • Fixed Splitter in parallel processing and streaming mode may block, while iterating message body when the iterator throws an exception in the first invoked next() method call.
  • Fixed Kafka consumer to not auto commit if autoCommitEnable=false.
  • Fixed file consumer was using markerFile as read-lock by default, which should have been none.
  • Fixed using manual commit with Kafka to provide the current record offset and not the previous (and -1 for first).
  • Fixed Content Based Router in Java DSL may not resolve property placeholders in when predicates.

• Upgraded to Spring Boot 2.1.
• Additional component-level options can now be configured by using spring-boot auto-configuration. These options are included in the spring-boot component metadata JSON file descriptor for tooling assistance.
• Added a documentation section that includes all the Spring Boot auto configuration options for all the components, data-formats, and languages.
• All the Camel Spring Boot starter JARs now include META-INF/spring-autoconfigure-metadata.properties file in their JARs to optimize Spring Boot auto-configuration.
• The Throttler now supports correlation groups based on dynamic expression so that you can group messages into different throttled sets.
• The Hystrix EIP now allows inheritance for Camel’s error handler so that you can retry the entire Hystrix EIP block again if you have enabled error handling with redeliveries.
• SQL and ElSql consumers now support dynamic query parameters in route form. Note that this feature is limited to calling beans by using simple expressions.
• The swagger-restdsl maven plugin now supports generating DTO model classes from the Swagger specification file.

• The following noteworthy issues have been fixed:

  • The Aggregator2 has been fixed to not propagate control headers for forcing completion of all groups, so it will not happen again if another aggregator EIP is in use later during routing.
  • Fixed Tracer not working if redelivery was activa†ed in the error handler.
  • The built-in type converter for XML Documents may output parsing errors to stdout, which has now been fixed to output by using the logging API.
  • Fixed SFTP writing files by using the charset option would not work if the message body was streaming-based.
  • Fixed Zipkin root id to not be reused when routing over multiple routes to group them together into a single parent span.
  • Fixed optimized toD when using HTTP endpoints had a bug when the hostname contains an IP address with digits.
  • Fixed issue with RabbitMQ with request/reply over temporary queues and using manual acknowledge mode. It would not acknowledge the temporary queue (which is needed to make request/reply possible).
  • Fixed various HTTP consumer components that may not return all allowed HTTP verbs in Allow header for OPTIONS requests (such as when using rest-dsl).
  • Fixed the thread-safety issue with FluentProducerTemplate.

• Defines versions for Maven dependencies, so that you do not need to specify the version when you add a dependency to your pom.xml file.
• Defines a set of curated dependencies that are fully tested and supported for a specific version of Fuse.
• Simplifies upgrades of Fuse.

• 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.

  Note

  The rollup patching mechanism uses an internal git repository (located under patches/.management/history) to track the changes made.

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.

• Add the upgrade installer file to the container’s environment by invoking the patch:add command. For example, to add the fuse-karaf-7.10.0.fuse-7_10_0-00010-redhat-00001.zip upgrade installer file:

  patch:add file:///path/to/fuse-karaf-7.10.0.fuse-7_10_0-00010-redhat-00001.zip

  Note

  The patch:find command can only be used to find and add the latest hot fix patches to the container’s environment; it cannot be used to apply full upgrade patches.

  Procedure

  1. Run the patch:update command. 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

  2. Invoke the patch:list command 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

  3. Simulate the upgrade by invoking the patch:simulate command 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.

  4. Upgrade the container by invoking the patch:install command and specifying the upgrade ID for the upgrade that you want to apply. For example:

     karaf@root()> patch:install fuse-karaf-7.10.0.fuse-7_10_0-00010-redhat-00001

  5. 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, 7_10_0-00010-redhat-00001, as follows:

     karaf@root()> bundle:list -l | grep 7_10_0-00010-redhat-00001
      22 │ Active │  80 │ 7.10.0.fuse-7_10_0-00010-redhat-00001  │ mvn:org.jboss.fuse.modules/fuse-pax-transx-tm-narayana/7.10.0.fuse-7_10_0-00010-redhat-00001
     188 │ Active │  80 │ 7.10.0.fuse-7_10_0-00010-redhat-00001  │ mvn:org.jboss.fuse.modules.patch/patch-commands/7.10.0.fuse-7_10_0-00010-redhat-00001

Prerequisites

• You have recently upgraded Fuse on Karaf.
• You want to rollback the upgrade.