# AMP Release 5.3.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)
* [Deprecation Announcements](#deprecation-announcements)
* [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.

## Alert of Future Changes

Cloudsoft Service Broker will not be shipped as part of AMP from the next release onward. Please see
[Deprecation Announcements](#deprecation-announcements) to learn more.

## New Features

#### AMP UI

The 5.3.0 has focussed mainly on UI improvements, with a few other fixes in other areas:

* The code for the AMP Web Console has been open sourced, and donated to Apache Brooklyn.
  See the [Brooklyn UI repo](https://github.com/apache/brooklyn-ui/).

  * End-users will not see noticeable changes due to this, but they will benefit from
    community contributions going forwards.

  * Developers will find it much easier to extend, whitelabel, and embed the UI in
    other applications.

* Some UI enhancements have already been made.  These include a more user-friendly
  configuration, including a wizard and drop-down support in the Blueprint Composer.

#### AMP Core

* The performance of persistence has been significantly improved, which reduces
  CPU load on the AMP server and load on the data store (be it NFS or an object store):

  * Sensors marked with persistence mode as 'NONE' will not be persisted. Similarly,
    a change in that sensor's value will not cause the entity to be re-persisted.

  * When an entity's sensor is repeatedly set to the same value, this will no longer
    cause the entity to be re-persisted. This is particularly important for 'service.isUp'
    which is periodically set to 'true' in some entity implementations.

  * When re-persisting an entity, its adjuncts (locations, policies and enrichers)
    are no longer automatically re-persisted at the same time (these are triggered
    by their own change-listeners).

    The old behaviour can be restored by setting the system property:
    `brooklyn.experimental.feature.referencedObjectsPersistence` to `true`.

* The default log4j2 message format now includes a "mapped diagnostic context" (MDC).
  This indicates the entity id and task id(s) for appropriate log messages.

* Versions of dependencies have been upgraded to eliminate all known CVEs.
  See [Backwards Compatibility](#backwards-compatibility) for more information.

#### REST API

* There is a new endpoint: `/applications/details`.

  This gets details for all applications and optionally selected additional entity items,
  including tags, values for selected sensor and config glob patterns, and recursively
  this info for children, up to a given depth.

  It is intended to replace the pre-existing `/fetch` endpoint, which is now deprecated.

#### Clouds and Container Services

* deploy-to-kubernetes: adds configuration option for `trustCerts`

#### AWS Services Pack

* There is a new entity for integrating with AWS Service Catalog.
  This is named `aws-servicecatalog-product` (the Java class is
  `io.cloudsoft.aws.servicecatalog.ServiceCatalogProduct`).

  This new entity should be considered beta in this release, and may be changed
  in 5.4.0 in response to feedback (backwards compatibility is not guaranteed).

* For use of an AWS location, one can now use 'assume role'. This also works
  with AWS 'instance profile', where temporary credentials are retrieved automatically.

  An example location catalog item is shown below:

  ```yaml
  brooklyn.catalog:
    version: 0.1.0-SNAPSHOT
    items:
      - id: aws-example
        itemType: location
        item:
          type: jclouds:aws-ec2:eu-west-1
          brooklyn.config:
            displayName: Assume AWS Role in Cloudsoft AWS QA Tests
            # role to assume in customer's account
            roleToAssumeArn: "arn:aws:iam::000000000000:role/DevCrossAccountAccess"
            jclouds.computeServiceRegistry:
              $brooklyn:object:
                type: io.cloudsoft.location.jclouds.AwsEc2AssumeRoleComputeServiceRegistry
  ```

## Bug Fixes

#### AMP Core

* BROOKLYN-594: REST api /v1/server/ha/persist/export fails in brooklyn karaf

* BROOKLYN-580: Rebinding to MachineEntity: sometimes fails to reconnect sensor feeds

* BROOKLYN-579: DNS lookups cached for too long

* The default HA mode is now 'AUTO', rather than disabled.
  This now matches the documented behaviour.

* Disable jclouds 'authorizePublicKey', which set extra ssh public key data.
  This is done explicitly by Brooklyn. The jclouds code sometimes caused SSH
  to fail (e.g. when combined with use of keyPair).
  To restore the previous behaviour, set the system property
  `brooklyn.jclouds.authorizePublicKey.extraSshPublicKeyData` to `true`.
  See https://github.com/apache/brooklyn-server/pull/963 for more details.

* Fix docs for copy-state and generate-password cli usage instructions.

#### AMP UI

* [Fix bug with the DSL editor/viewer](https://github.com/apache/brooklyn-ui/pull/63)
  This fixes 2 bugs:
* In the Blueprint Composer's DSL editor, when adding a DSL for an entity spec, The DSL
  editor "Done" button was not redirecting to the spec editor.

* In the Blueprint Composer's DSL editor, viewing a DSL was throwing an error while
  getting the name of the entity for DSL like `$brooklyn:self()` or `$brooklyn:parent()`.

* Upgrade Blueprint Composer to Angular 1.7.2, from Angular 1.7.1, to fix
  angular-bootstrap incompatibility.
  See https://github.com/angular/angular.js/issues/16598 for more details.

#### Entities

* BROOKLYN-590: squid blueprint fails on CentOS 7 on Vexxhost: openssl needed update

## 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 and BROOKLYN-596: Fails with Java 9 and Java 10.
  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.


## 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 upgrade, which may impact authors of
  Java-based blueprints. It is recommended that user's bundles is 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:

  * fasterxml.jackson: 2.7.5 -> 2.9.6
  * groovy: 2.3.7 -> 2.4.15
  * commons-beanutils: 1.9.1 -> 1.9.3
  * commons-collections: 3.2.1 -> 3.2.2
  * snakeyaml: 1.17 -> 1.21

* The `AmpExternalUiModuleEnricher` has been deleted, and replaced by
  `BrooklynExternalUiModuleEnricher` (as part of open-sourcing the UI code).
  Use of the old name will be automatically converted to the new class name at runtime.

## Deprecation Announcements

* The REST API endpoint `/fetch` has been deprecated.
  Instead, use the new endpoint: `/applications/details`.

### Cloudsoft Service Broker

CSB was deprecated in the 5.2 release.

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.

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