Este conteúdo não está disponível no idioma selecionado.
Chapter 17. Patching
17.1. Patching a Fabric Container with a Rollup Patch
Abstract
Follow the procedures described in this section to patch a Fabric container with a rollup patch.
Overview
A rollup patch updates bundle JARs, other Maven artifacts, libraries, and static files in a Fabric. The following aspects of the fabric are affected:
- Distribution of patched artifacts
- Profiles
- Configuration of the underlying container
Important
The instructions in this section apply only to JBoss A-MQ versions 6.2.1 and later, which support the new patching mechanism.
Distribution of patch artifacts
When patching an entire fabric of containers, you need to consider how the patch artifacts are distributed to the containers in the fabric. You can adopt one of the following approaches:
- Through the Maven proxy (default approach)—when you add a rollup patch to your root container (using the
patch:addcommand), the patch artifacts are installed into the root container'ssystem/directory, whose directory structure is laid out like a Maven repository. The root container can then serve up these patch artifacts to remote containers by behaving as a Maven proxy, enabling remote containers to download the required Maven artifacts (this process is managed by the Fabric agent running on each Fabric container). Alternatively, if you have installed the rollup patch to a container that is not hosting the Maven proxy, you can ensure that the patch artifacts are uploaded to the Maven proxy by invoking thepatch:fabric-installcommand with the--uploadoption.The Maven proxy approach sufferes from a potential drawback, however. If the Fabric ensemble consists of multiple containers, it can happen that the Maven proxy fails over to a different ensemble container (not the original root container). This can result in the patch artifacts suddenly becoming unavailable to other containers in the fabric. If this occurs during the patching procedure, it will cause problems.For more details, see Chapter 14, Fabric Maven Proxies. - Through a local repository (recommended approach)—to overcome the limitations of the Maven proxy approach, we recommend that you make the patch artifacts available directly to all of the containers in the Fabric by setting up a local repository on the file system. Assuming that you have a networked file system, all containers will be able to access the patch artifacts directly.For example, you might set up a local repository of patch artifacts, as follows:
- Given a rollup patch file, extract the contents of the
system/directory from the rollup patch file into therepositories/subdirectory of a local Maven repository (which could be~/.m2/repositoriesor any other location). - Configure the Fabric agent and the Maven proxy to pick up artifacts from the local repository by editing the current version of the
defaultprofile, as follows:profile-edit --append --pid io.fabric8.agent/org.ops4j.pax.url.mvn.defaultRepositories="file:///PathToRepository" default
ReplacePathToRepositoryby the actual location of the local repository on your file system.NoteMake sure that you make the edits to thedefaultprofile for all relevant profile versions. If some of your containers are using a non-default profile version, repeat theprofile-editcommands while specifying the profile version explicitly as the last parameter.
Profiles
The rollup patching process updates all of the standard profiles, so that they reference the patched dependencies. Any custom profiles that you created yourself remain unaffected by these updates. However, in cases where you have already made some changes directly to the standard profiles (such as
default, fabric, karaf, and so on), the patching mechanism attempts to merge your changes with the changes introduced by the patch.
Important
In the case where you have modified standard profiles, it is recommended that you verify your custom changes are preserved after patching. This is particularly important with respect to any changes made to the location of Maven repositories (which are usually configured in the
default profile).
Configuration of the underlying container
If required, the rollup patching mechanism is capable of patching the underlying container (that is, files located under
etc/, lib/, and so on). When a Fabric container is upgraded to a patched version (for example, using the fabric:container-upgrade command), the container's Fabric agent checks whether the underlying container must be patched. If yes, the Fabric agent triggers the patching mechanism to update the underlying container. Moreover, if certain critical files are updated (for example, lib/karaf.jar), the container status changes to requires full restart after the container is upgraded. This status indicates that a full manual restart is required (an automatic restart is not possible in this case).
io.fabric.version in the default profile
The
io.fabric.version resource in the default profile plays a key role in the patching mechanism. This resource defines the version and build of JBoss A-MQ and of all of its main components. When upgrading (or rolling back) a Fabric container to a new version, the Fabric agent checks the version and build of JBoss A-MQ as defined in the io.fabric.version resource. If the JBoss A-MQ version changes between the original profile version and the upgraded profile version, the Fabric agent knows that an upgrade of the underlying container is required when upgrading to this profile version.
Patching the patch mechanism
Before upgrading JBoss A-MQ with a rollup patch, you must patch the patch mechanism to a higher level. Since the original GA version of JBoss A-MQ 6.2 was released, significant improvements have been made to the patch mechanism. If you were to upgrade straight to the latest rollup patch version of JBoss A-MQ, the improved patch mechanism would become available after you completed the upgrade. But at that stage, it would be too late to benefit from the improvements in the patch mechanism.
To circumvent this bootstrap problem, the improved patch mechanism is made available as a separate download, so that you can patch the patch mechanism itself, before you upgrade to the new patch level. To patch the patch mechanism, proceed as follows:
- Download the appropriate patch management package. From the JBoss A-MQ 6.2.0 Software Downloads page, select a package named Red Hat JBoss A-MQ 6.2.1 Rollup N on Karaf Update Installer, where N is the number of the particular rollup patch you are about to install.ImportantThe rollup number, N, of the downloaded patch management package must match the rollup number of the rollup patch you are about to install.NoteThe 6.2.1 patch management packages are made available from the 6.2.0 Software Downloads page. This is because the 6.2.1 patch management packages can also be used when upgrading from version 6.2.0.
- Install the patch management package,
patch-management-for-amq-620-TargetVersion.zip, on top of every Karaf container installation (root container, SSH containers, and so on). Use an archive utility to extract the contents on top of the existing container installation (installing files under thesystem/andpatches/subdirectories).NoteIt does not matter whether the container is running or not when you extract these files. - Start the root container, if it is not already running.
- Create a new version, using the
fabric:version-createcommand (where we assume that the current profile version is1.0):JBossFuse:karaf@root> fabric:version-create --parent 1.0 1.0.1 Created version: 1.0.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. - Update the
patchproperty in theio.fabric8.versionPID in the version1.0.1of thedefaultprofile, by entering the following Karaf console command:profile-edit --pid io.fabric8.version/patch=1.2.0.redhat-621xxx default 1.0.1
Where you must replace1.2.0.redhat-621xxxwith the actual build version of the patch commands you are installing (for example, the build versionxxxcan be taken from the last three digits of theTargetVersionin the downloaded patch management package file name). - Reconfigure the Fabric agent so that the version of the patch mechanism it uses is determined by the
patchversion property (set in the previous step). Enter the following console command:profile-edit --pid 'io.fabric8.agent/repository.fabric8-patch=mvn:io.fabric8.patch/patch-features/${version:patch}/xml/features' default 1.0.1 - Upgrade the root container to use the new patching mechanism, as follows:
container-upgrade 1.0.1 root
- Likewise, for all other containers in your fabric that need to be patched (SSH, child, and so on), provision them with the new patching mechanism by upgrading them to profile version
1.0.1. For example:container-upgrade 1.0.1 container1 container2 container3
Applying a rollup patch
To apply a rollup patch to a Fabric container:
- Before applying the rollup patch to your fabric, you must patch the patch mechanism, as described in the section called “Patching the patch mechanism”.
- For every top-level container (that is, any container that is not a child container), perform these steps, one container at a time:
- In the Karaf installation, remove the
lib/endorsed/org.apache.karaf.exception-2.4.0.redhat-621xxx.jarfile (where the build number,xxx, depends on the build being patched). - Restart the container.
- Add the patch to the root container's environment using the patch:add command. For example, to add the
patch.zippatch file:JBossFuse:karaf@root> patch:add file://patch.zip [name] [installed] [description] PatchID false Description
ImportantIf you have decided to use a local repository to distribute the patch artifacts (recommended), set up the local repository now—see the section called “Distribution of patch artifacts”. - 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.1
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
patch:fabric-installcommand. Note that in order to run this command you must provide the credentials,UsernameandPassword, of a user withAdministratorprivileges. For example, to apply thePatchIDpatch to version1.1:patch:fabric-install --username Username --password Password --upload --version 1.1 PatchID
NoteWhen you invoke thepatch:fabric-installcommand with the--uploadoption, Fabric looks up the ZooKeeper registry to discover the URL of the currently active Maven proxy, and uploads all of the patch artifacts to this URL. Using this approach it is possible to make the patch artifacts available through the Maven proxy, even if the container you are currently logged into is not hosting the Maven proxy. - Synchronize the patch information across the fabric, to ensure that the profile changes in version
1.1are propagated to all containers in the fabric (particularly remote SSH containers). Enter the following console command:patch:fabric-synchronize
- Upgrade each existing container in the fabric using the
fabric:container-upgradecommand (but leaving the root container, where you installed the patch, until last). For example, to upgrade a container namedremote, enter the following command:JBossFuse:karaf@root> fabric:container-upgrade 1.1 remote Upgraded container remote from version 1.0.1 to 1.1
At this point, not only does the Fabric agent download and install the patched bundles into the specified container, but the agent also applies the patch to the underlying container (updating any static files in the container, if necessary). If necessary, the agent will then restart the target container automatically or set the container status torequires full restart(if an automatic restart is not possible), so that any changes made to the static files are applied to the running container.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. - If the current status of the upgraded container is
requires full restart, you must now use one of the standard mechanisms to stop and restart the container manually. In some cases, it will be possible to do this using Fabric commands from the console of the root container.For example, you could stop theremotecontainer as follows:fabric:container-stop remote
And restart theremotecontainer as follows:fabric:container-start remote
- Upgrade the root container last (that is, the container that you originally installed the patch on):
fabric:container-upgrade 1.1 root
- (Windows only) If the root container status has changed to
requires full restartand it is running on a Windows operating system, you must first shut down all of the root container's child containers (if any) before manually restarting the root container.For example, if the root container has three child containers,child1,child2, andchild3, you would first shut them down, as follows:fabric:container-stop child1 child2 child3
You can then shut down the root container with theshutdowncommand:shutdown
Rolling back a rollup patch
To roll back a rollup 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 remote container back to the unpatched version 1.0 as follows:
fabric:container-rollback 1.0 remote
At this point, not only does the Fabric agent roll back the installed profiles to an earlier version, but the agent also rolls back the patch on the underlying container (restoring any static files to the state they were in before the patch was applied, if necessary). If necessary, the agent will then restart the target container automatically or set the container status to
requires full restart (if an automatic restart is not possible), so that any changes made to the static files are applied to the running container.
Warning
Rolling back the patch level from version 6.2.1 to 6.2.0 is not supported in JBoss A-MQ Fabric. This is a special case, because the version 6.2.0 Fabric agent does not support the new patching mechanism.
