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:
- The patch mechanism creates a new profile,
patch-PatchProfileID, which defines bundle overrides for all of the patched bundles. - The new patch profile,
patch-PatchProfileID, is inserted as the parent of thedefaultprofile (at the base of the entire profile tree). - 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:
- Before you proceed to install the incremental patch, make sure to read the text of the
READMEfile that comes with the patch, as there might be additional manual steps required to install a particular incremental patch. - Create a new version, using the
fabric:version-createcommand:JBossFuse:karaf@root> fabric:version-create 1.1 Created version: 1.1 as copy of: 1.0
ImportantVersion 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. - Apply the patch to the new version, using the
fabric:patch-applycommand. For example, to apply theactivemq.zippatch file to version1.1:JBossFuse:karaf@root> fabric:patch-apply --version 1.1 file:///patches/activemq.zip
- Upgrade a container using the
fabric:container-upgradecommand, specifying which container you want to upgrade. For example, to upgrade thechild1container, enter the following command:JBossFuse:karaf@root> fabric:container-upgrade 1.1 child1 Upgraded container child1 from version 1.0 to 1.1
ImportantIt 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 therootcontainer (the one that you applied the patch to, using thefabric:patch-applycommand) last. - You can check that the new patch profile has been created using the
fabric:profile-listcommand, 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.TipIf 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 thefabric:version-set-default Versioncommand.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
