AMP Upgrade

This guide provides all necessary information to upgrade AMP for both the RPM/DEB and Tarball packages.

Upgrading Older Versions of AMP

• RPM / DEB Packages
• Tarball

Rollback

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

Note there are no “forwards compatibility” guarantees, that persisted state generated with a new version of AMP will work with older versions of AMP. Therefore persisted state written by a newer version of AMP will not necessarily work when rolling back to an older version of AMP.

1. Stop AMP:

   # e.g. on CentOS / RHEL
   sudo systemctl stop amp
   

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

2. Restore the persisted state and custom configuration from the backup you made during the previous upgrade.

   1. By default, persisted state is located at /var/lib/amp.

      The persistence dir is configured with the environment variable export AMP_PERSISTENCE_DIR=... Alternatively, persistenceDir can be configured in the file /etc/amp/org.apache.brooklyn.osgilauncher.cfg. The persistenceLocation can also be configured in that file. The persistence details will be logged in /var/log/amp/amp.info.log at startup time.

   2. Configuration files are in /etc/amp.

3. Downgrade AMP:

   # e.g. for CentOS / RHEL
   sudo yum downgrade cloudsoft-amp-karaf-x.x.x.rpm
   

   Note this creates a new directory at /opt/amp-x.x.x, if necessary, and updates the symbolic link at /opt/amp to point at this. The previous AMP directory is left as-is.

   Check if there are any conflicts in configuration files (located in /etc/amp), for example if there are any files with the suffix .rpmnew, and resolve those conflicts.

4. Validate that the new release works, by starting in “HOT_BACKUP” mode.

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

   2. Start AMP:

      # e.g. on CentOS / RHEL sudo systemctl start amp

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

   4. Stop AMP:

      # e.g. on CentOS / RHEL
      sudo systemctl stop amp
      

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

5. Start AMP:

   # e.g. on CentOS / RHEL
   sudo systemctl start amp
   

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

   Confirm that there are no errors reported in the log (/var/log/amp/amp.info.log).

Migrating AMP to a Different Server

Moving AMP to a different server has much in common with upgrade. The steps are described below, which assume that you are running AMP 4.3 or later. If upgrading AMP at the same time, see the additional steps described in the appropriate upgrade instructions.

1. On the old server:

   1. Stop AMP:

      # CentOS / RHEL
      sudo systemctl stop amp
      

      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. Make a copy of the persisted state and custom configuration.

      1. By default, persisted state is located at /var/lib/amp.

         The persistence dir is configured with the environment variable export AMP_PERSISTENCE_DIR=... Alternatively, persistenceDir can be configured in the file /etc/amp/org.apache.brooklyn.osgilauncher.cfg. The persistenceLocation can also be configured in that file. The persistence details will be logged in /var/log/amp/amp.info.log at startup time.

         If using an external object store (e.g. S3), you do not have to copy the persisted state. The new AMP server can instead be configured to point at the same object store.

      2. Configuration files are in /etc/amp.

2. On the new server:

   1. Install AMP, but do not start the service.

   2. Apply any configuration file customizations from the old server, on the new server.

   3. If using file-based persistence, unpack the persisted state to the appropriate location.

   4. Validate that the new release works, by starting in “HOT_BACKUP” mode.

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

      2. Start AMP:

         # e.g. on CentOS / RHEL
         sudo systemctl start amp
         

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

      4. Stop AMP:

         # e.g. on CentOS / RHEL
         sudo systemctl stop amp
         

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

   5. Start AMP:

      # CentOS / RHEL
      sudo systemctl start amp
      

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

      Confirm that there are no errors reported in the log (/var/log/amp/amp.info.log).

How to stop your service

On systemd:

systemctl stop amp 

On upstart:

stop amp

Web login credentials

• User credentials should now be recorded in ${karaf.home}/etc/brooklyn.cfg

• AMP will still read them from both ${karaf.home}/etc/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:

• brooklyn.cfg
• org.apache.brooklyn.osgilauncher.cfg

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>

AMP 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. AMP needs to know it in order to read the persisted state at startup time.

High Availability mode can not be specified via a CLI parameter (as was the case in v3.x) but should be configured in org.apache.brooklyn.osgilauncher.cfg.

For details on how to configure HA, see the HA tutorial.

Upgrading Blueprints and Bundles

You can install and deploy new versions of blueprints at any time. AMP 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 AMP to replace any installed bundle not compatible with the newer version of AMP.

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!

~~~~