# AMP Release 5.0.0 * [Introduction](#introduction) * [Important Changes](#important-changes) * [New Features](#new-features) * [Bug Fixes](#bug-fixes) * [Known Issues](#known-issues) * [Backwards Compatibility](#backwards-compatibility) * [Upgrade Instructions](#upgrade-instructions) ## Introduction Thank you to our community who have contributed a lot of improvements and feedback! Thanks also go to Brooklyn's commercial users who have funded this development and made some major contributions. For more information, please visit https://cloudsoft.io/amp, https://docs.cloudsoft.io and http://brooklyn.apache.org This is a major upgrade from AMP version 4.8.0. ## Important Changes In this major release, some code has been deprecated. Deprecated code may be removed in a future release as per our deprecation policy and steps should be taken now to avoid their use. One of the biggest changes, as described below, is the ability to group blueprints in bundles. Users are strongly encourage to manage their catalog using bundles now: upgrading and versioning relies on this. When adding .bom files directly to the catalog, these are auto-wrapped as bundles. If a `bundle` name is not supplied in the BOM it may make subsequent upgrade and versioning harder. Other changes and deprecated code areas are described below. ## New Features ### Catalog Uses Bundles The AMP catalog now uses bundles throughout. A bundle is a zip file or OSGi bundle containing zero or more catalog items, which are then stored by AMP as versioned OSGi bundles under-the-covers. Use of bundles makes it much simpler to deploy and manage the resources associated with a catalog item, such as scripts and icons. It is also simpler to deploy and manage multiple related catalog items at the same time, and to declare the (versioned) dependencies between bundles. Backwards compatibility is preserved for deploying .bom files directly by auto-wrapping it in a bundle. The `br` tool has been updated to take advange of bundles. For example, the command below will automatically zip up the directory and add it to the catalog as a bundle: br catalog add /path/to/myproject/ The initial AMP catalog is now defined as a list of bundles. When a bundle is added to the catalog, it is also persisted in the `/bundles` sub-dir of the persisted state. The `/catalog` persisted state directory is no longer used (but is still read, to preserve backwards compatibility). ### Merging of Initial Catalog and Persisted Catalogs When AMP is started with existing persisted state, AMP will first set up the initial catalog that it is configured with. The catalog items from persisted state will then be overlaid on top of this. This differs from the behaviour in AMP 4.x where the initial catalog was ignored if there was existing persisted state. ### AMP Packaging AMP now ships with an "extras" folder where additional components of the product are included, as opposed to them previously being available online in separate locations. Extras include: * Metering microservice * Jumphost * AMP Cluster * Cloudsoft Service Broker (CSB) The "extras" includes catalog bundles for these where appropriate. These catalog items are no longer included in the default initial AMP catalog, and should now be manually installed where required as per the online documentation. ### Improved Support for Policies The AMP web-console's app inspector has a new "Management" tab, which provides a superset of functionality in the old "Policies" tab. The tab now shows all policies, enrichers, and feeds associated with the selected entity. The tab adds key "highlights" for each, such as recent actions and triggers. Drilling into an enricher or policy shows further details such as its full activities view and its configuration. Additional policies have been added, including failover policies ("elect-primary") and time-of-day policies. ### AMP Cluster AMP Cluster is now GA. If you have previously deployed a beta version of AMP Cluster (e.g. from AMP 4.8 or earlier), please first delete the cluster before upgrading the AMP server. AMP Cluster includes many improvements since the beta release, including bug fixes, robustness, performance and scalability improvements. See the documentation on AMP "extras" for deploying an AMP Cluster. ### AMP Executive Dashboard The web-console's dashboard has been reworked. It now gives more relevant information for high-level operations, to better suit the needs of general and business users at the top level. For example, it can show a summary of each app including the total resource usage across clouds/locations and price information. To include this information, dashboard enrichers must be attached to applications. These are available from Cloudsoft through professional services engagements. The dashboard will see further improvements in subsequent 5.x releases. ### UI Branding and Embedding AMP customers can now brand the AMP UI and can create their own UI that re-uses AMP widgets. ### Externalised configuration AMP now has a default external config supplier. This should never be used in production, but is useful for examples and demos because it requires no additional configuration of the AMP server. The DSL below resolves to the value "br00k11n": $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password") ### REST API The rest API now better supports querying and modifying adjuncts (e.g. policies and enrichers). This is done through the endpoint: /applications/{application}/entities/{entity}/adjuncts The rest endpoint `/applications/fetch` now supports a "sensors" query parameter. When used, the details of the selected entities will include values for the given sensors. This allows clients to efficiently get selected sensors they are interested in. ### Miscellaneous * General performance and scalability improvements * AMP RPM install sets limits in systemd for NOFILE and NPROC, each to 16384. This is configured in the systemd amp.service file. * Added support for registering listeners that are notified when the AMP server's state changes (e.g. transitioning from standby to master). This is done by implementing the interface `ManagementNodeStateListener`, and configuring it in brooklyn.cfg using the config key `brooklyn.managementNodeState.listeners`. * Added to jclouds locations support for `maxConcurrentMachineDeletions`, which controls for a given app the maximum number of VMs that can be terminated concurrently. This is a partial workaround for https://issues.apache.org/jira/browse/BROOKLYN-533. * Added to `VanillaSoftwareProcess` the config key `sshMonitoring.enabled`. When set to false, it will not do its health check by periodically executing an ssh script. * Added `FunctionSensor`, which can be used to add a `FunctionFeed` in a pure-YAML blueprint. * The AMP node blueprint has additional configuration options: * `setenv.additions` text included here will be appended to the end of the bin/setenv file; and * `amp.maxMem` the 'Xmx' value to use when starting AMP The AMP node blueprint no longer polls over ssh for health checks, instead using http(s). This greatly improves performance and scalability. ## Bug Fixes * Workaround for https://issues.apache.org/jira/browse/JCLOUDS-1332, which causes keypairs to sometimes not be deleted * `br` cli: * BROOKLYN-553: `br` uses default login port of 80/443 if not supplied * AMP-1949: `br` cli gives error if user supplies `-v` or `--verbose` * UI fixes: * AMP-1950: Fix hover position for popup on catalog items * Fixes for Blueprint Composer location handling and error reporting * Improved naming of tasks, which appear in the app inspector's Activities view. * For MySqlNode entity, when using a pre-existing `mysql.datadir`, handle the case where the database password is already set. * Config set dynamically on an entity will not have its "anonymous config key" added to its persisted state. * Improvements to the catalog for icons and descriptions of items. * The cluster's config key `dynamiccluster.memberspec` (or alias `memberSpec`) is no longer re-inherited. If there is a cluster of clusters, the memberSpec config set on the top-level cluster will not be inherited by the child clusters. * Improved error reporting when adding to the catalog. * BROOKLYN-537: NPE listing catalog items * BROOKLYN-532: UI / rest api not available after a very long rebind * Fix null pointer exceptions that can occur with WinRM when no subnet IP * BROOKLYN-526: server crash caused empty files in persisted state * Fix for Azure ARM, where previously AMP could not deploy if there was a VM with `AdditionalUnattendedContent`. * AMP-1948: Deadlock in entity.getAttribute and and EntityManagementSupport.onManagementStarting ## 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-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 * Some config key names have changed, with the old name being deprecated but still supported. Use if the old name will result in a warning in the log when the item is added to the catalog: entity.started -> skip.start entity.running -> skip.start.ifRunning install.skip -> skip.install provision.latch -> latch.provision start.latch -> latch.start stop.latch -> latch.stop setup.latch -> latch.setup resources.preInstall.latch -> latch.preInstall.resources resources.install.latch -> latch.install.reources install.latch -> latch.install resources.customize.latch -> latch.customize.resources customize.latch -> latch.customize resources.runtime.latch -> latch.launch.resources launch.latch -> latch.launch * Some old deprecated code has been deleted, in line with our deprecation policy. * The Java `@Catalog` annotation is deprecated. It was previously used on catalog items that were implemented as Java classes. Instead, use a `catalog.bom` file to give the metadata about the catalog items. * Use of a config value of type `Task` is deprecated - Java users who previously did this should consider instead using a `TaskFactory`. * AMP-1925: AMP now disables external maven bundle resolution. Previously, the default was that a bundle could be retrieved from sites such as maven central. This can be reconfigured in the karaf file `org.ops4j.pax.url.mvn.cfg`. * BOM files that do not declare a version now give the version of the bundle to their entities, rather than the default `0.0.0-SNAPSHOT` version. When loading types, the version can now be specified as any Brooklyn-valid version string equivalent to the OSGi version (e.g. `1-SNAPSHOT` or `1.0.0.SNAPSHOT`). * Some catalog methods may return the same type multiple times, if contained in multiple bundles. Previously only one of the bundle's definition of the type was returned. Except for anonymous bundles it is no longer allowed to have give items with the same name and version. (This is required to prevent Brooklyn from getting in to a state where it cannot rebind.) * Value resolution is now supported for config default values. Previously these would be coerced but not resolved beyond that -- i.e. TaskFactory values would not have tasks evaluated, and Map and Collection values would not be deeply resolved with their internals coerced or evaluated. This makes the semantics of default values consistent with explicit config values. * Deep config resolution of nested items has changed to be consistent with when deep config applies. Deep config applies to maps and collections, but previously any Iterable contained therein would have a recursive deep config evaluation. Now this is limited to nested Collection types (Lists, Sets, etc) and Maps; nested Iterable instances that are not also Collections are no longer traversed and resolved recursively. This makes their nested resolution consistent with when such instances are non-nested config value, as deep resolution was not applied there. This mainly affects PortRange, where previously if set directly on a config key it would return the PortRange value but if accessed in a map such as `shell.env` any non-default value would be expanded as a list `[1, 2]` (but default values would not be expanded, as per previous point, but now they are). * For backwards compatibility with 3.x, please see the release notes for AMP 4.x (especially 4.0.0). * For backwards compatibility with 4.x please see the intermediate release notes. ## Upgrade Instructions * See detailed upgrade instructions at https://docs.cloudsoft.io/operations/upgrade.html * Use of RPM and DEB is now recommended, rather than the tar.gz. * CentOS 7.x is recommended, though CentOS 6 and Ubuntu 16.04 are also tested.