19.7. Patching a Fabric Container with an Incremental Patch

Abstract

Follow the procedures described in this section to patch a Fabric container with an incremental patch.

Overview

An incremental patch makes updates only to the bundle JARs in a Fabric. The following aspects of the fabric are affected:
  • Distribution of patched artifacts through Maven proxy
  • Profiles

Distribution of patched artifacts through Maven proxy

When you install the incremental patch on your local container, the patch artifacts are installed into the local system/ directory, whose directory structure is laid out like a Maven repository. The local container distributes these patch artifacts to remote containers by behaving as a Maven proxy, enabling remote containers to upload bundle JARs as needed (this process is managed by the Fabric agent running on each Fabric container). For more details, see chapter "Fabric Maven Proxies" in "Fabric Guide".

Profiles

The incremental patching process defines bundle overrides, so that profiles switch to use the patched dependencies (bundle JARs). This mechanism works as follows:
  1. The patch mechanism creates a new profile, patch-PatchProfileID, which defines bundle overrides for all of the patched bundles.
  2. The new patch profile, patch-PatchProfileID, is inserted as the parent of the default profile (at the base of the entire profile tree).
  3. All of the profiles that inherit from default now use the bundle versions defined by the overrides in patch-PatchProfileID. The contents of the existing profiles themselves are not modified in any way.

Is it necessary to patch the underlying container?

Usually, when patching a fabric with an incremental patch, it is not necessary to patch the underlying container as well. Fabric has its own mechanisms for distributing patch artifacts (for example, using a git repository for the profile data, and Apache Maven for the OSGi bundles), which are independent of the underlying container installation.
In exceptional cases, however, it might be necessary to patch the underlying container (for example, if there was an issue with the fabric:create command). Always read the patch README file to find out whether there are any special steps required to install a particular patch. In these cases, however, it is more likely that the patch would be distributed in the form of a rollup patch, which has the capability to patch the underlying container automatically—see Section 19.6, “Patching a Fabric Container with a Rollup Patch”.

Applying an incremental patch

To apply an incremental patch to a Fabric container:
  1. Before you proceed to install the incremental patch, make sure to read the text of the README file that comes with the patch, as there might be additional manual steps required to install a particular incremental patch.
  2. Create a new version, using the fabric:version-create command:
    JBossFuse:karaf@root> fabric:version-create 1.1
    Created version: 1.1 as copy of: 1.0
    Important
    Version names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this: 1.3 <.description > .If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax.
  3. Apply the patch to the new version, using the fabric:patch-apply command. For example, to apply the activemq.zip patch file to version 1.1:
    JBossFuse:karaf@root> fabric:patch-apply --version 1.1 file:///patches/activemq.zip
  4. Upgrade a container using the fabric:container-upgrade command, specifying which container you want to upgrade. For example, to upgrade the child1 container, enter the following command:
    JBossFuse:karaf@root> fabric:container-upgrade 1.1 child1
    Upgraded container child1 from version 1.0 to 1.1
    Important
    It is recommended that you upgrade only one or two containers to the patched profile version, to ensure that the patch does not introduce any new issues. Upgrade the root container (the one that you applied the patch to, using the fabric:patch-apply command) last.
  5. You can check that the new patch profile has been created using the fabric:profile-list command, as follows:
    BossFuse:karaf@root> fabric:profile-list --version 1.1 | grep patch
    default                                  0              patch-activemq-patch
    patch-activemq-patch
    Where we presume that the patch was applied to profile version 1.1.
    Note
    If you want to avoid specifying the profile version (with --version) every time you invoke a profile command, you can change the default profile version using the fabric:version-set-default Version command.
    You can also check whether specific JARs are included in the patch, for example:
    JBossFuse:karaf@root> list | grep -i activemq
    [ 131] [Active     ] [Created     ] [       ] [   50] activemq-osgi (5.9.0.redhat-61037X)
    [ 139] [Active     ] [Created     ] [       ] [   50] activemq-karaf (5.9.0.redhat-61037X)
    [ 207] [Active     ] [            ] [       ] [   60] activemq-camel (5.9.0.redhat-61037X)

Rolling back an incremental patch

To roll back an incremental patch on a Fabric container, use the fabric:container-rollback command. For example, assuming that 1.0 is an unpatched profile version, you can roll the child1 container back to the unpatched version 1.0 as follows:
fabric:container-rollback 1.0 child1