Upgrades

This section provides all necessary information to upgrade Apache Brooklyn for both the RPM/DEB and Tarball packages.

Backwards Compatibility

Apache Brooklyn version 0.12.0 onward runs primarily inside a Karaf container. When upgrading from 0.11.0 or below, this update changes the mechanisms for launching Brooklyn. This will impact any custom scripting around the launching of Brooklyn, and the supplying of command line arguments.

Use of the lib/dropins and lib/patch folders will no longer work (because Karaf does not support that kind of classloading). Instead, code must be built and installed as OSGi bundles.

Upgrading Brooklyn

  • Use of RPM and DEB is now recommended where possible, rather than the tar.gz. This entirely replaces the previous install.

  • CentOS 7.x is recommended over CentOS 6.x (note: the RPM will not work on CentOS 6.x)

Upgrade from Apache Brooklyn 0.12.0 onward

Hint: in the top right of this page are buttons to select an installation method. Choose your installation method to see the most appropriate instructions here.

Upgrading an RPM or DEB package

  1. Important! Backup persisted state and custom configuration, in case you need to rollback to a previous version.

    1. By default, persisted state is located at /var/lib/brooklyn. The persistenceDir and persistenceLocation are configured in the file /etc/brooklyn/org.apache.brooklyn.osgilauncher.cfg. The persistence details will be logged in /var/log/brooklyn/brooklyn.info.log at startup time.

    2. Configuration files are in /etc/brooklyn.

  2. Upgrade Apache Brooklyn:

    1. Download the new RPM/DEB package

    2. Upgrade Apache Brooklyn:

      # CentOS / RHEL
sudo yum upgrade apache-brooklyn-xxxx.noarch.rpm

# Ubuntu / Debian
sudo dpkg -i apache-brooklyn-xxxx.deb

      If there are conflicts in configuration files (located in /etc/brooklyn), the upgrade will behave differently based on the package you are using:

      • RPM: the upgrade will keep the previously installed one and save the new version, with the suffix .rpmsave. You will then need to check and manually resolve those.
      • DEB: the upgrade will ask you what to do.

  3. Start Apache Brooklyn:

    # CentOS 7 / RHEL
sudo systemctl start brooklyn
# CentOS 6 and older
sudo initctl start brooklyn

# Ubuntu / Debian
start brooklyn

    Wait for Brooklyn to be running (i.e. its web-console is responsive)

Upgrading using a .tar.gz archive

  1. Stop Apache Brooklyn:

    ./bin/stop brooklyn

    If this does not stop it within a few seconds (as checked with sudo ps aux | grep karaf), then use sudo kill <JAVA_PID>

  2. Important! Backup persisted state and custom configuration.

    1. By default, persisted state is located at ~/.brooklyn/brooklyn-persisted-state. The persistenceDir and persistenceLocation are configured in the file ./etc/org.apache.brooklyn.osgilauncher.cfg. The persistence details will be logged in ./log/brooklyn.info.log at startup time.

    2. Configuration files are in ./etc/. Any changes to these configuration files will need to be re-applied after reinstalling Brooklyn.

  3. Install new version of Apache Brooklyn:

    1. Download the new tarball zip package.

    2. Install Brooklyn:

      tar -zxf apache-brooklyn-xxxx.tar.gz
cd apache-brooklyn-xxxx

  4. Restore any changes to the configuration files (see step 2).

  5. Validate that the new release works, by starting in "HOT_BACKUP" mode.

    1. Before starting Brooklyn, reconfigure ./etc/org.apache.brooklyn.osgilauncher.cfg and set highAvailabilityMode=HOT_BACKUP. This way when Brooklyn is started, it will only read and validate the persisted state and will not write into it.

    2. Start Apache Brooklyn:

      ./bin/start brooklyn

    3. Check whether you have rebind ERROR messages in ./log/brooklyn.info.log, e.g. sudo grep -E "WARN|ERROR" /opt/brooklyn/log/brooklyn.debug.log. If you do not have such errors you can proceed.

    4. Stop Apache Brooklyn:

      ./bin/stop brooklyn

    5. Change the highAvailabilityMode to the default (AUTO) by commenting it out in ./etc/org.apache.brooklyn.osgilauncher.cfg.

  6. Start Apache Brooklyn:

    ./bin/start brooklyn

    Wait for Brooklyn to be running (i.e. its web-console is responsive).

  7. Update the catalog, using the br command:

    1. Download the br tool.

    2. Login with br: br login http://localhost:8081 <user> <password>.

    3. Update the catalog: br catalog add /opt/brooklyn/catalog/catalog.bom.

Upgrade from Apache Brooklyn 0.11.0 and below

Hint: in the top right of this page are buttons to select an installation method. Choose your installation method to see the most appropriate instructions here.

Upgrading an RPM or DEB package

  1. Stop Apache Brooklyn:

    # CentOS 7 / RHEL
sudo systemctl stop brooklyn
# CentOS6 and older
sudo initctl stop brooklyn

# Ubuntu / Debian
stop brooklyn

    If this does not stop it within a few seconds (as checked with sudo ps aux | grep brooklyn), then use sudo kill <JAVA_PID>.

  2. Important! Backup persisted state and custom configuration.

    1. By default, persisted state is located at /opt/brooklyn/.brooklyn/.. The persistenceDir and persistenceLocation are configured in the file ./etc/org.apache.brooklyn.osgilauncher.cfg. The persistence details will be logged in ./log/brooklyn.info.log at startup time.

    2. Configuration files are in ./etc/. Any changes to these configuration files will need to be re-applied after reinstalling Brooklyn.

  3. Delete the existing Apache Brooklyn install:

    1. Remove Brooklyn package:

      # CentOS / RHEL
sudo yum erase apache-brooklyn

# Ubuntu / Debian
sudo dpkg -r apache-brooklyn

      1. On CentOS 7 run sudo systemctl daemon-reload.

      2. Confirm that Brooklyn is definitely not running (see step 1 above).

      3. Delete the Brooklyn install directory: sudo rm -r /opt/brooklyn as well as the Brooklyn log directory: sudo rm -r /var/log/brooklyn/

  4. Make sure you have Java 8. By default CentOS images come with JRE6 which is incompatible version for Brooklyn. If CentOS is prior to 6.8 upgrade nss: yum -y upgrade nss

  5. Install new version of Apache Brooklyn:

    1. Download the new RPM/DEB package.

    2. Install Apache Brooklyn:

      # CentOS / RHEL
sudo yum install apache-brooklyn-xxxx.noarch.rpm

# Ubuntu / Debian
sudo dpkg -i apache-brooklyn-xxxx.deb

  6. Restore the persisted state and configuration.

    1. Stop the Brooklyn service:

      # CentOS 7 / RHEL 
sudo systemctl stop brooklyn
# CentOS 6 and older
sudo initctl stop brooklyn

# Ubuntu / Debian
stop brooklyn

      Confirm that Brooklyn is no longer running (see step 1).

    2. Restore the persisted state directory into /var/lib/brooklyn and any changes to the configuration files (see step 2). Ensure owner/permissions are correct for the persisted state directory, e.g.: sudo chown -r brooklyn:brooklyn /var/lib/brooklyn

  7. Validate that the new release works, by starting in "HOT_BACKUP" mode.

    1. Before starting Brooklyn, reconfigure /etc/brooklyn/org.apache.brooklyn.osgilauncher.cfg and set highAvailabilityMode=HOT_BACKUP. This way when Brooklyn is started, it will only read and validate the persisted state and will not write into it.

    2. Start Apache Brooklyn:

      # CentOS 7 / RHEL
sudo systemctl start brooklyn
# CentOS 6 and older
sudo initctl start brooklyn

# Ubuntu / Debian
start brooklyn

    3. Check whether you have rebind ERROR messages in the Brooklyn logs, e.g. sudo grep -E "Rebind|WARN|ERROR" /var/log/brooklyn/brooklyn.debug.log. If you do not have such errors you can proceed.

    4. Stop Brooklyn:

      # CentOS 7 / RHEL 
sudo systemctl stop brooklyn
# CentOS 6 and older
sudo initctl stop brooklyn

# Ubuntu / Debian
stop brooklyn

    5. Change the highAvailabilityMode to the default (AUTO) by commenting it out in ./etc/org.apache.brooklyn.osgilauncher.cfg.

  8. Start Apache Brooklyn:

    # CentOS 7 / RHEL
sudo systemctl start brooklyn
# CentOS 6 and older
sudo initctl start brooklyn

# Ubuntu / Debian
start brooklyn

    Wait for Brooklyn to be running (i.e. its web-console is responsive).

  9. Update the catalog, using the br command:

    1. Download the br tool (i.e. from the "CLI Download" link in the web-console).

    2. Login with br: br login http://localhost:8081 <user> <password>.

    3. Update the catalog: br catalog add /opt/brooklyn/catalog/catalog.bom.

Upgrading using a .tar.gz archive

Same instructions as above.

Rollback

This section applies only with you are using the RPM/DEB packages. To perform a rollback, please follow these instructions:

# CentOS / RHEL
yum downgrade apache-brooklyn.noarch

# Ubuntu Debian
dpkg -i apache-brooklyn-xxxx.deb

Note that to downgrade a DEB package is essentially installing a previous version therefore you need to download the version you want to downgrade to before hand.

How to stop your service

On systemd: 

systemctl stop brooklyn

On upstart: 

stop brooklyn

Web login credentials

  • User credentials should now be recorded in brooklyn.cfg.

  • Brooklyn will still read them from both brooklyn.cfg and ~/.brooklyn/brooklyn.properties.

  • Configure a username/password by modifying brooklyn.cfg. An example entry is:

brooklyn.webconsole.security.users=admin
brooklyn.webconsole.security.user.admin.password=password2

Persistence

If you have persisted state you wish to rebind to, persistence is now configured in the following files:

For example, to use S3 for the persisted state, add the following to brooklyn.cfg:

brooklyn.location.named.aws-s3-eu-west-1:aws-s3:eu-west-1
brooklyn.location.named.aws-s3-eu-west-1.identity=<ADD CREDS>
brooklyn.location.named.aws-s3-eu-west-1.credential=<ADD CREDS>

To continue the S3 example, for the persisted state, add the following to org.apache.brooklyn.osgilauncher.cfg:

persistenceLocation=aws-s3-eu-west-1
persistenceDir=<ADD HERE>

Apache Brooklyn should be stopped before this file is modified, and then restarted with the new configuration.

Note that you can not store the credentials (for e.g. aws-s3-eu-west-1) in the catalog because that catalog is stored in the persisted state. Apache Brooklyn needs to know it in order to read the persisted state at startup time.

If binding to existing persisted state, an additional command is required to update the existing catalog with the Brooklyn 0.12.0 versions. Assuming Brooklyn has been installed to /opt/brooklyn (as is done by the RPM and DEB):

    br catalog add /opt/brooklyn/catalog/catalog.bom

All existing custom jars previously added to lib/plugins (e.g. for Java-based entities) need to be converted to OSGi bundles, and installed in Karaf. The use of the "brooklyn.libraries" section in catalog.bom files will continue to work.

Upgrading Blueprints and Bundles

You can install and deploy new versions of blueprints at any time. Brooklyn tracks multiple versions of the blueprints you install, as can be seen in the catalog.

Defining and Forcing Upgrade Paths

Bundles can declare what bundles and types they can upgrade, and they can also force the removal of installed bundles and types on startup/rebind. Forcing can be useful when upgrading Brooklyn to replace any installed bundle not compatible with the newer version of Brooklyn.

To add these definitions, use the following headers in the bundle's OSGi META-INF/MANIFEST.MF:

  • Brooklyn-Catalog-Force-Remove-Bundles
  • Brooklyn-Catalog-Force-Remove-Legacy-Items
  • Brooklyn-Catalog-Upgrade-For-Bundles
  • Brooklyn-Catalog-Upgrade-For-Types

The most common patterns are to indicate that a bundle can replace all previous versions of itself and all types therein with types in the current bundle of the same name, using:

Brooklyn-Catalog-Upgrade-For-Bundles: *

And you can indicate that previous bundles should be uninstalled, forcing the above upgrades, with:

Brooklyn-Catalog-Force-Remove-Bundles: *

The above items can also take a range syntax, e.g. "*:[1,2)" when releasing a 2.0.0 to restrict to versions equal to or greater than 1.0.0 but less than 2.0.0. (Note that ranges must be quoted.) Entries can also take comma-separated lists, and in the case of replacements, they can define explicit renamed targets using sourceNameAndVersionRanges=targetNameAndVersion entries.
These fields are defined in full in the BundleUpgradeParser's javadoc.

Upgrading the Version of Deployed Blueprints

New versions of blueprints are not automatically applied to existing deployments from older versions. This requires a rebind using the above techniques, or programmatic intervention: please ask on the mailing list for more information (and to help us identify the most common wishes in this area!).

Upgrading Systems Under Management

Blueprints can encode update processes for the systems they describe. The mechanisms for updating systems vary, depending whether it is stateless or stateful, whether following an immutable pattern (replacing components) or doing it on box (traditional, possibly taking systems out of action while upgrading), and whether applying an upgrade to many resources on a rolling fashion (repaving, blue-green). For this reason there is not a one-size-fits-all upgrade pattern to use in blueprints, but there are some common patterns that may be applicable:

  • Defining an upgrade effector on nodes, and on a cluster to apply to all nodes
  • Using a config key such as version which can be updated and reapplied
  • Exposing a deploy effector to pass files that should be run, such as WAR files, and invoking this effector with newer versions of WAR files to install

There are many more, and if you've written some good pieces to share, please consider contributing them so others can take advantage of them!

results matching ""

    No results matching ""