# AMP Release 5.5.0

* [Introduction](#introduction)
* [New Features](#new-features)
* [Bug Fixes](#bug-fixes)
* [Known Issues](#known-issues)
* [Backwards Compatibility](#backwards-compatibility)
* [Deprecation Announcements](#deprecation-announcements)
* [Installation and Upgrade Instructions](#installation-and-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

* TOSCA support improvements for artifacts, CSARs and functions, along with better error messages.

* AMP install improvements:

  * The RPM install directory is now configurable, defaulting to `/opt`.

  * Add an after clause to amp.service for delaying service start on systemd based systems.  
    On reboot this now waits until the multi-user target has been reached to ensure all 
    system services have been started before the amp service is started.

* VMware VSphere integration improvements:

  * Improved support for selecting the cluster compute resource.

  * Improved support for selecting the resource pool.

  * Improved support for VM template selection, including regex.

  * Improved support for specifying fixed IP addresses on VM creation.

* Windows WinRM blueprint support:

  * support `install.dir` and `run.dir`
  * pass `shell.env` when executing scripts over WinRM

* Finer-grained entitlements controls (i.e. user permissions). Added: `adjunct.delete`, `location.add`, 
  `location.delete`, `location.see`, `policy.add`, `policy.delete`, `policy.start`, `policy.stop`, 
  `system.admin`, `system.ha.stats`, `system.ha.admin`, `system.shutdown`, `system.usage`.

* CLI `br login` now support oauth.

* Kubernetes "deploy to" improvements, including support for Oauth Token when deploying to AWS EKS.

* Support 'maxSessionAge' for use of the REST API and UI with oauth.
  This is configured using `org.apache.brooklyn.server.maxSessionAge`
  and `org.apache.brooklyn.server.maxInactiveInterval`.

* Blueprint DSL support for $brooklyn:formatString(...) to accept nested DSL parameter.

* New Contention Management policies have been added to AMP.
  These can be used to track the resources consumed, with what priority, to handle requests for additional 
  resources.

* Improvements to License and Notice file generation, to facilitate license audits.


### AMP UI

* BROOKLYN-620: Order blueprint deployment history by date deployed

* Improved reporting and handling of session-timeouts.

* Quick-launch improvements:
  * auto-set a default name for the application.
  * if there is a single location select it automatically,
  * apply catalog_quick_launch tag to filtering locations,
  * if tags are used, suppress the "create a new location" message (for a simpler user experience
    where a single preferred location is tagged).
  * add 'Open in Composer' button to quick-launch.

* Show application/entity icons in the app-inspector tree view and summary

* Allow bigger 'zoom in', useful for larger screens

* Blueprint Composer imported support for defining parameters - including field-based and JSON modes.


## Bug Fixes

### AMP Core

* Security fixes via version bumps for a number of dependencies to fix CVEs. 
  See [Backwards Compatibility](#backwards-compatibility) section for lists of versions.

* AMP Cluster, when using Nginx load balancer component, now sets ulimits for `nofile` and `nproc`.
  The low default values previously caused problems for some users when run at large scale.

* Fix leak where policies and enrichers associated with an entity were not always destroyed 
  when the entity was destroyed.

* Improved error messages when attempting to deploy an invalid blueprint, or add an invalid item to the catalog.

* Fix issue when Azure ARM endpoint not specified. Previously this could cause extreme performance 
  issues at blueprint deployment time. Now the endpoint is a required configuration parameter when using Azure ARM.

* Support for more AWS instance types, but upgrading to jclouds 2.1.2 (from 2.1.0). This includes
  r5, t3, x1 instance types.

* Fix blueprint YAML parsing problems for quotes and nulls (by upgrading snakeyaml and jackson dependencies).

* Fix Ansible integration to use `-b` (i.e. 'become') instead of deprecated `-s` (i.e. 'sudo').

* Fix for `PerRoleEntitlementManager` to load external Role Resolver from user-supplied OSGi bundles.
  The <bundle:class> of the Role Resolver can now be specified.

* Fix for VMware VSphere integration: space leak that could happen when machines were 'unmanaged'.

* Fix display and default logging of cloud locations to not show 'identity' (e.g. AWS access key ID).
  Though separate from the actual 'secret key', this should still not be exposed by default.

* BROOKLYN-616: Fix REST API swagger validation error when AMP runs in private (isolated) environment.


### AMP UI

* Fix tracking of inactive session when user has multiple browser tabs.

* Fix quick-launch "Open in Composer" button, which previously gave errors in some edge cases.

* Fix Blueprint Importer validation, which previously erroneously reported errors.

* Fix Firefox issue where it navigated to 'dropped' entity icons in Composer.

* Fix for Composer's DSL Viewer ignoring literal values.

* Fix errors around locations in composer:

  * now supports map syntax in the visual editor (previously gave errors)
  * now works without complaining if no services set
  * leaves a marker in place if a location is removed (so consumers can avoid applying defaults or reset defaults)
  * fixes bug where images broke during d3 transitions
  * improves layout and ordering of fields

* BROOKLYN-624: File upload to catalog via file picker does not work

* BROOKLYN-619: Blueprint Composer: Missing pagination when switching to compact list and back to another mode


## 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.

* It is recommended that Java-based blueprints are recompiled against the latest AMP version.

* 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:

  * brooklyn: 1.0.0-20190320.1101 (pre 1.0.0 GA) -> 1.1.0-1.1.0-20200518.1447 (post 1.0.0 GA)
  * jclouds: 2.1.0 -> 2.1.2
  * karaf: 4.2.2 -> 4.2.8
  * felix: 5.6.10 -> 5.6.12
  * cxf: 3.2.7 -> 3.3.5
  * org.eclipse.jetty: 9.4.14 -> 9.4.22
  * ch.qos.logback: 1.0.7 -> 1.2.3
  * com.thoughtworks.xstream: 1.4.8 -> 1.4.11.1
  * com.fasterxml.jackson: 2.9.7 -> 2.10.1
  * org.yaml:snakeyaml: 1.23 -> 1.25
  * org.bouncycastle: 1.51 -> 1.61
  * com.hierynomus.sshj: 0.20.0 -> 0.22.0
  * io.cloudsoft.windows:winrm4j: 0.6.1 -> 0.9.0
  * io.fabric8.kubernetes-client: 1.4.27 -> 4.9.0
  * javax.ws.rs-api: 2.1.1 -> 2.1.99
  * io.fabric8.kubernetes-client: 1.4.27 -> 4.9.0
  * org.apache.httpcomponents.httpclient: 4.5.6 -> 4.5.10
  * org.apache.httpcomponents.core: 4.4.9 -> 4.4.12

* Clocker no longer ships with AMP.
  These blueprints previously gave support for deploying Kubernetes and Docker Swarm.
  The Kubernetes ecosystem has since moved on, making these blueprints obsolete.
  Please contact Cloudsoft for any further requirements.

* Support for Azure-Classic has been removed, as of upgrading to jclouds 2.1.2.
  Azure Resource Manager (ARM) is the correct way to interact with Azure.


## 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/