# AMP Release 5.4.0

* [Introduction](#introduction)
* [Alert of Future Changes](#alert-of-future-changes)
* [New Features](#new-features)
* [Bug Fixes](#bug-fixes)
* [Other Changes](#other-changes)
* [Known Issues](#known-issues)
* [Backwards Compatibility](#backwards-compatibility)
* [Upgrade Instructions](#upgrade-instructions)

## Introduction

Thank you to our customers and users for their feedback and support.
Thanks also go to the Apache Brooklyn community for the many code contributions and
evolution of ideas at the heart of this product.

For more information, visit https://cloudsoft.io/amp, https://docs.cloudsoft.io
and http://brooklyn.apache.org.

## New Features

#### AMP core

* Security provider implementations can now indicate that they don't use Basic auth,
  and can throw exceptions to return a specific response.
  This allows OAuth providers to be written, returning a 302 or 307 redirect instead of a 401 unauthorized
  when a user is not logged in so that they authenticate first with the OAuth site.
  Related improvements have been made requiring authentication to access static content,
  sharing session information such as login status among all bundles,
  and invoking the security provider's logout call when the user logs out.

* Config key constraints now support more sophisticated relationships.
  For example, a given config key can be 'requiredIf' another key is specified.
  The new constraints supported are:
  `forbiddenIf: <key>`: setting a value is disallowed if the config key `<key>` has a value set
  `forbiddenUnless: <key>`: setting a value is disallowed if the config key `<key>` does not have a value set
  `requiredIf: <key>`: a value is required if the config key `<key>` has a value set
  `requiredUnless: <key>`: a value is required if the config key `<key>` does not have a value set

  See documentation at https://docs.cloudsoft.io/blueprints/syntax-entity-configuration.html#config-key-constraints

* The Brooklyn DSL now supports reference to an entity's locations. For example,
  a blueprint author could write:

  ```yaml
  config1: $brooklyn:location()
  config2: $brooklyn:location("0")
  ```


#### AMP UI

* The Blueprint Composer has a new layout. The palette of catalog items is shown
  on the left, and the configuration view for the selected entity is shown on the right.

* The Blueprint Composer's palette of catalog items improvements:

  * More filters are now supported, including a `Recent` filter (click the gear icon to see these options).

  * The user can select different views. These include 'compact' (to see more icons at once),
    'large' and 'list'.

  * Catalog items are sorted by 'relevance', based on recency of use.

  * Selecting of a catalog item adds it as a child of the entity that has focus,
    rather than a child of the top-level application. The newly added entity then
    has focus.

  * The information hover-over is improved, including a link to 'Open in catalog'.

  * Search will now include entities that have matching text in their tag(s).

* Blueprint Composer now shows relationships that are in the 'member spec' of a cluster.

* The Blueprint Composer's "Add to catalog" dialog has been simplified and improved:

  * The dialog has an 'advanced' section, to simplify the user experience.

  * Bundle ID and bundle symbolic name are inferred from the display name, if not
    entered explicitly. This reduces the number of fields that must be filled in.

  * The blueprint type can be chosen ('application', 'template', or 'entity').

* Improvements to Blueprint Composer's DSL Editor:

  * The Blueprint Composer's DSL Editor lets you choose an entity for any config key
    (rather than only if it is of type 'Entity'). This is more consistent with the
    rest of the DSL editor, and means it can be used with keys of type 'Object'.

  * For a blueprint using `brooklyn.parameters`, these can be referenced using the
    DSL editor.

* Palette layout, as well as widget for configuration keys in the spec editor can now be
  customised by downstream projects.

* Graphical entities can now be removed when pressing the backspace key. Note that this
  works on the selected item.

## Bug Fixes

#### AMP core

* BROOKLYN-607: azure-arm failure on `yum update` (due to image choice).

* BROOKLYN-602: priority of parameters should not be reset by extending a config key in yaml

* BROOKLYN-600: Failed blueprint deployment: entities not cleaned up under-the-covers

* BROOKLYN-599: Brooklyn DSL fails if unrelated entity getParent() throws exception

* BROOKLYN-602: fix config key order for yaml overrides

* For Windows, the maximum memory is now set to 2G. Previously, users would get an
  OutOfMemoryError with the default memory allocated to the JVM.

* Persisted state from aws-services-pack entities that referenced AWS-SDK objects
  could cause rebind problems on upgrade.

  The persisted state contained an auto-generated bundle name due to the default
  behaviour of 'wrap'. On upgrade, the auto-generated bundle name could be different.

  Blueprint authors using 'wrap' to turn jars in OSGi bundles are strongly encouraged
  to supply an explicit bundle symbolic name. See documentation at
  https://docs.cloudsoft.io/blueprints/java/bundle-dependencies.html#converting-non-osgi-dependencies-to-bundles

  See BROOKLYN-605 for more details.

* Type coercion has been improved, particularly for config keys whose type uses generics
  (e.g. for `ConfigKey<Set<Integer>>`). This improves the type checking, and automatically
  coerces values where appropriate. Previously, the generics were not respected when
  coercing values.


#### AMP UI

* Fix a bug where removing a policy or enricher did nothing.

* General improvement and stability of the spec editor.

* Improve statibility of the DSL editor + fix various bugs.

* Add Firefox support for multi-line fields in the spec editor. This can be achieve by using either
  `shift+enter`, `ctrl+enter` or `option+enter` to create a new line.

## Other Changes

* REST API response for objects includes a new `iconUrlSource` field if there is a URL set different to the value 
  of `IconUrl` (the latter should be used for getting the image, but the former may be useful to tell where the 
  latter originally comes from)

* Catalog items can declare `itemType` as "application".
  Previously, "template" was used for this purpose, but that has the additional
  effect of tagging the catalog item with `catalog_template`.


## Known Issues

See Apache Brooklyn JIRA for list of known issues relating to Brooklyn and thus AMP.

Some issues are called out below, with suggested workarounds:

* BROOKLYN-595, BROOKLYN-596: AMP fails to run with Java 9, 10 and 11.
  It is recommended to use Java 8.

* BROOKLYN-592: Windows entities fail with JDK 8u172
  The underlying cause is a JDK bug: https://bugs.openjdk.java.net/browse/JDK-8196491,
  The workaround is to use Java 8u192 or later when available, or to downgrade to
  8u151 or earlier.

* When deploying Windows VMs on GCE with the `Administrator` account, the provisioning will fail because this particular
  account is disabled.

  It is recommended to use instead the following location configuration:
  ```
  autoCreateWindowsPassword: true
  loginUser: something-different-than-Administrator
  ```

  The login specified by `loginUser` will be automatically created and used by AMP.

* JCLOUDS-1379: when deploying on AWS, AMP might try to use non-available instance type if you use new regions

  It is recommended to set the `hardwareId` as part of your location to avoid this.

* BROOKLYN-559: on restart/rebind, the backup directory for persisted state (created automatically)
  may be missing some bundle JAR files

  The AMP upgrade instructions recommend making a manual backup copy of persisted state,
  and not use the automatically created backup directory. If this is done the bug will not affect users.

  If it is desired to revert to automatically created backup copies of persisted state,
  any extra bundles that had been installed to AMP these should be copied from the regular
  persisted state `bundles/` folder into the backup copy being used.
  Alternatively references to any such bundles can be added to the initial catalog as `brooklyn.libraries`.

* BROOKLYN-555, BROOKLYN-556, BROOKLYN-557: for some software process entities, calling stop to
  terminate the VM and then calling start may break some entities.

  If terminating the VM causes problems, it is recommended to instead replace the entity.

* BROOKLYN-550: some blueprints can break if AMP is running as a user whose name
  matches a pre-existing privileged user on machines it is provisioning.

  It is recommended to run AMP as an `amp` user or other normal user,
  and not to run it as `ec2-user`, `centos`, `ubuntu` or `root`.
  Alternatively locations can specify an explicit `user: ...` config.

* BROOKLYN-605: for jars that are converted to OSGi bundles using
  [PAX URL Wrap protocol](https://ops4j1.jira.com/wiki/display/paxurl/Wrap+Protocol)
  these can cause problems with persisted state and subsequent rebind due to the
  auto-generated bundle symbolic name changing.

  Blueprint authors using are strongly encouraged to supply an explicit bundle
  symbolic name.

  See documentation at
  https://docs.cloudsoft.io/blueprints/java/bundle-dependencies.html#converting-non-osgi-dependencies-to-bundles

* BROOKLYN-601: VM Provisioning can take a very long when using a vanilla RPM package
  install of AMP. This is because it tries to connect to the VM without any SSH credentials,
  and retries repeatedly. Possible workarounds include:
   * During AMP install, generate SSH keys for the AMP system user
   * In the location .bom file, reference an SSH key (e.g. using externalised configuration).

* BROOKLYN-598: ssh based activities fail if remote shell is `fish`.
  Workaround is to use an alternative shell, such as `bash`.


## Backwards Compatibility

When upgrading from a version that is more than one release old, also see
the backwards compatibility notes for the intermediate AMP versions.

* When rebinding to old persisted state that includes Java code in bundles compiled against old version(s)
  of AMP, it is important to forcibly replace these with new versions of the bundles compiled against
  the latest AMP. This is described in more detail in the upgrade instructions.

* Several internal libraries have been upgraded, which may impact authors of
  Java-based blueprints. It is recommended that user's bundles are compiled
  against the same library version as AMP, and that multiple (minor) versions of
  the same bundle are not included in Karaf. The library upgrades include:

  * karaf: 4.1.2 -> 4.2.2
  * felix: 5.6.1 -> 5.6.10
  * cxf: 3.1.10 -> 3.2.7
  * org.eclipse.jetty: 9.3.14.v20161028 -> 9.4.12.v20180830
  * org.ow2.asm: 5.0.4 -> 5.2
  * javax.ws.rs-api: 2.0.1 -> 2.1.1
  * com.fasterxml.jackson: 2.9.6 -> 2.9.7
  * org.apache.httpcomponents:httpclient: 4.5.2 -> 4.5.6
  * org.apache.httpcomponents:httpcore: 4.4.4 -> 4.4.9
  * org.yaml:snakeyaml: 1.21 -> 1.23
  * io.cloudsoft.windows:winrm4j: 0.5.0 -> 0.6.1

* Hyperledger blueprints are no longer shipped with or supported as part of AMP.
  The blueprints can still be found at https://github.com/cloudsoft/brooklyn-hyperledger.

* Cloudsoft Service Broker (CSB) is no longer shipped with or supported as part of AMP.

  As described in previous AMP releases, this choice has been taken due to the rapid changes
  in the service broker space and many different customer demands. The open-source
  Brooklyn Service Broker, a key component of CSB remains part of the Cloud Foundry foundation.

  Customers may continue to use CSB from previous versions or use Brooklyn Service Broker (BSB)
  as standalone.

  Please contact Cloudsoft for any further requirements.

## Deprecation Announcements

* The REST API endpoint `/fetch` was deprecated in AMP 5.3.0.
  Instead, use the new endpoint: `/applications/details`.

## Installation and Upgrade Instructions

To install see https://docs.cloudsoft.io/operations/production-installation.html

To upgrade existing installations see https://docs.cloudsoft.io/operations/upgrades/