# AMP Release 5.2.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 Web Console

* Add support for pattern validation in configuration keys. If a config key has a regex as a constraints, this validation
  is applied client side.
  
* Add location information on the summary tab (app inspector). The app inspector's entity summary tab now shows location
  information, including availability zone and multi-location information where applicable.

* DSL editor for the blueprint composer. There is now a new DSL editor for entities' config keys in the blueprint composer.
  It adds a button on each field - even values for config key of type `Map` or `Array` - that takes the user to a new
  `dsl-editor` panel where one can choose a "kind". That can be either:
  - a config key
  - a sensor
  - an entity
  
### AWS Service Pack

* Add Route53 Alias record entity.

* Add healthcheck sensors for ALB entity. A new feed queries the ALB health checks and reports them back onto:
  - each target group member:
    - adds `HEALTH_CHECK_STATE` which contains the current state of the health check associated to this entity.
    - adds `HEALTH_CHECK_NOT_HEALTHY` which contains a map of what happens if the health check status is different than `healthy`.
  - the ALB entity:
    - adds `TARGET_GROUP_SIZE` which contains the number of members within the target group.
    - adds `TARGET_GROUP_NOT_HEALTHY` which is a map of `{ ID: { status: '', reason: '', description: ''}}`.
  
  The feed that polls the sensors uses the same configuration key as the ALB, i.e. `TARGET_GROUP_HEALTH_CHECK_INTERVAL_SECONDS`.

### Miscellaneous

* BROOKLYN-583: Upgrade jclouds version to 2.1.0.
  See https://issues.apache.org/jira/browse/BROOKLYN-583

* BROOKLYN-584: Add support for recent jclouds's ContextLinking.
  See https://issues.apache.org/jira/browse/BROOKLYN-584

## Bug Fixes

### AMP Web Console
 
* Fix menu colors and accessibility.
  This improves the UI module colors as well as accessibility:
  - items are not gray anymore.
  - on smaller screens, menu items have titles.
  - on smallest screens, the UI module menu displays a list rather than a grid.
  - fixed a bug where the menu wasn't display on smallest screen.
  
* Blueprint composer: The config keys were missing when one selected an entity spec for a cluster.

* Blueprint composer: The contrast was too low for the arrow symbolising a relationship.

* Blueprint composer: The free-form tile generated by the `catalog-selector` for a location was doing nothing when
  dragged and dropped.

* Blueprint composer: It was impossible to search by entity ID in the `dsl-editor`. This also adds the possibility to
  specify an ID for the target entity if one is not set yet.

* Catalog: There was an issue preventing the config keys to be displayed.
  
* Blueprint composer: Fix a bug where the memberspec selection was added as child.
  A bug was introduced in AMP 5.1 which removed the ability to add memberspec to an entity: all additions where considered
  as a child addition instead of memberspec.
  
* Blueprint composer: when an icon was clicked, the configuration filters did not appear.
  
* Inspector: Fix auto-update for stream views, such as the activity view for ssh stdout and stderr.
  
* Blueprint composer: Improve configuration filters.
  Move the configuration filters, as well as the "Add configuration" form out of a popover. Those forms are now inlined
  on top of the accordions which make them easier to use.

### apache/brooklyn-library

* Fix issue with JBoss 7 installation, which failed with Java 7u171 onwards.
  Note this entity has also been deprecated.

### apache/brooklyn-server

* BROOKLYN-580: Rebind machine entity feeds.
  See https://issues.apache.org/jira/browse/BROOKLYN-580

* BROOKLYN-568: Fix NPE on SshFeed rebind.
  See https://issues.apache.org/jira/browse/BROOKLYN-568

* Disable use of jclouds for handling extra public key data in authorizePublicKey.
  This could previously sometimes interfere with the use of key-pairs in AWS.
  These keys are still uploaded to `.ssh/authorized_keys` by Brooklyn.
    
  The previous behaviour can be re-enabled using the system property 
  `-Dbrooklyn.jclouds.authorizePublicKey.extraSshPublicKeyData=true`.

* Fix SshCommandSensor rebind. More specifically, this:
  * fixes the big problem that rebind to historic persisted state is broken.
  * improves the `SshCommandSensor` so that we don't use anonymous inner classes (making our persisted state easier to
    support long-term)

* On feed failure (e.g. connection error or invalid response), avoid excessive logging.
  Only logs once at level 'warn'.

### cloudsoft/brooklyn-blockstore

* Fixes race condition when adding additional Windows HDDs.

### cloudsoft/amp-jumphost

* When using AMP Jumphost, fixes WinRM over HTTPS.
  Fixes issue where methods in `MahcineMetadata` such as `useHttps()` were not following the Java standard of prefixing
  getters with 'get' and were thus ignored by the serializer.
  
#### cloudsoft/aws-services-pack

* Fix various bugs with ELB entity.

* Deprecate (and fix) ELB bind-to-existing configuration key, i.e. `BIND_TO_EXISTING` and `REPLACE_EXISTING`

* Fix Route53 entity.
  When a route 53 node failed to stop (e.g. due to an AWS api error) then the subsequent stops would also failed because
  the actual route53 entry was already been deleted. This changes the behaviour so that if stop fails on the first
  invocation, the subsequent ones will properly remove the entity.

#### brooklyncentral/brooklyn-alfresco

* Fix download url.
  The previous download URL had stopped working, giving a `403 Forbidden` response.

## Other Changes

#### AMP Web Console

* Blueprint composer: Allow json editing in the composer UI.
  Specifically where a value is a complex object, previously it would render as e.g. `[object Object]`, and editing it
  would reset the data; and other times it would render as a JSON string, but then when converting back to YAML
  it would change it to be stringified not the JSON object.
  
* Blueprint composer: Palette now display entity tags.

* Blueprint composer: Listing of config keys and values has changed to have key and value on one line.

* Blueprint composer: Config filters are now additive and the default being "suggested, required, or in-use".
  
* Catalog and web console table rendering improvements. This includes improved column resize.

#### apache/brooklyn-client

* The Brooklyn CLI (br) now supports timeout for invoking an effector.
  Passes the timeout arg (if supplied) when making the REST api call to Brooklyn. The response from this is written to
  stdout.
  
  If it times out, the REST api still gives back a 202 response code with a json payload describing the executing task.
  This will typically include a stack trace but that does not mean there is an error.

#### apache/brooklyn-dist

* Add MDC to pax logging config.
  See https://github.com/apache/brooklyn-server/pull/940 for details.

#### apache/brooklyn-library

* Adds AbstractController changeServerPool.
  Purpose of the new `changeServerPool` effector is to switch the group of target servers, and thus reconfigure the
  load balancer in one step.
  
  This would be useful for example in blue-green upgrades: the load balancer could start by pointing at the "blue"
  cluster, and could then be switched to point at the "green" cluster.

#### apache/brooklyn-server

* High Availability mode defaults to 'auto', rather than 'disabled'.
  This now matches the previously documented default behavior.

* Allow tags to be set on catalog items.
  It was already supported in code and in the rest api, but is only now possible to set from a catalog `.bom` file.

* SSH Sensor value-on-error.
  Adds `value.on.error` config key to SshCommandSensor to allow a value to be specified for use when an exception
  occurs when executing the ssh command.

* Defers reading of config in SshCommandSensor.
  This allows DSL to be used in the command, env and execution dir.

* Support iteration of hashes in templates.
  DotSplittingTemplateModel implements `TemplateHashModelEx2` (rather than just `TemplateHashModel`), meaning
  config/sensor map key/vals can be iterated in templates.
  
  For example:
  ```
  <#list config['sections'] as k, v>
    ${k} = ${v}
  </#list>
  ```
  
  Until now a snippet like this would have caused an exception with message "NonExtendedHashException: For "#list"
  list source: Expected an extended hash, but this has evaluated to a hash (wrapper: org.apache.brooklyn.util.core.text.TemplateProcessor$DotSplittingTemplateModel)"

* BROOKLYN-576: Fix excessive debug logging.
  See https://issues.apache.org/jira/browse/BROOKLYN-576

* BROOKLYN-580: Rebinding to MachineEntity: sometimes fails to reconnect sensor feeds.
  See https://issues.apache.org/jira/browse/BROOKLYN-580

#### cloudsoft/amp

* Add required parameter into alfresco template.
  This adds the `alfresco.admin.password` config key into the alfresco template.
  
  The `alfresco` entity requires `alfresco.admin.password`. But as the template wraps this entity into a
  `BasicApplication`, this config key is not suggested, nor it does appear into the config key dropdown when one
  uses the quick launch or composer.

#### cloudsoft/brooklyn-blockstore

* Support choice of volume type on AWS EBS, such as `gp2` (i.e. SSD).

#### cloudsoft/brooklyn-couchdb

* Update brooklyn-couchdb download URL.
  The previous download URL had stopped working, giving a `404 Not found` response.

#### cloudsoft/amp-node

* For amp-node blueprint, ensure Java 1.8.0 JRE is selected.
  On OS images that preinstall Java, when we install Java 1.8 the preinstalled version of Java may still be the default
  version. This changes adds a call to update `alternatives` to ensure that the 1.8 JRE is selected by default.

#### cloudsoft/aws-services-pack

* Update config key label, description and tags for existing catalog items.

* Add official icons from AWS, and parameters for existing catalog items.

* Clean up orphaned security groups when deleting VPC.
  
* Add application load balancer (ELB).

* Various improvements:
  - ELB: Allow either AZs or Subnets to be explicitly set
  - RouteTable: Support `vpcPeering` and `egressOnlyInternetGateway`
  - Adds SecurityGroup entity
  - ELB: Add retrying client
  - ELB: Add more logging
  - ELB: Create security group if non provided
  - ELB: Add support for sticky sessions config

* Add bundle headers for Upgrade/Force-Remove.
  Needed because the bundle contains java code - we must replace previous versions of the catalog items with the latest
  versions, because older versions of the bundle will not have been compiled against the latest amp.

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

* 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 `instanceType` 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

* From 5.0.0 onwards, AMP will always first load the "initial catalog" (from the `etc/default.catalog.bom`
  file). If persisted state contains bundle (or legacy catalog items), these are then added.
  
* 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.

* `org.apache.brooklyn.util.core.mutex.WithMutexes.acquireMutex()` no longer throws a checked
  `InterruptedException`, but instead throws a `RuntimeInterruptedException`. Code that calls
  this (internal) method and that catches or expects the `InterruptedException` will need to be
  modified.

* If upgrading from a version older than 5.1.0, please see the intermediate release notes

## Deprecation Announcements

* Deprecated JBoss 7 application server entity.
  JBoss 7 is end-of-life (EOL), and thus no longer maintained or supported by JBoss.
  See http://jbossas.jboss.org/downloads
  
* Deprecated JBoss 6 application server entity.
  JBoss 6 is end-of-life (EOL), and thus no longer maintained or supported by JBoss.
  See http://jbossas.jboss.org/downloads
  
### Cloudsoft Service Broker 

CSB is 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 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/