Whether out-of-the-box or custom, before being used optimization packs need to be installed on an Akamas installation before being used.

Since optimization packs are global resources that are shared across all the workspaces on the same Akamas installation, an account with administrative privileges is required to manage them.

Optimization packs that are not yet installed are displayed as grayed out in the Akamas UI (this is the case for the AWS and Docker packs in the following figure).

The content of the store can be also inspected from the store container on the Akamas server:

docker exec -it store bash
root@ff16b64e84db:/store# cd /store_data/
root@ff16b64e84db:/store_data# ls -l
total 120
-rw-r--r--. 1 root  root   3136 Jul 21 07:11 Docker_1-1-0.json
-rw-r--r--. 1 root  root  19130 Jul 21 07:11 Java-OpenJDK_1-2-6.json
-rw-r--r--. 1 root  root  70391 Jul 21 07:11 Linux_1-2-1.json
-rw-r--r--. 1 root  root   4661 Jul 21 07:11 MongoDB_1-0-0.json
-rw-r--r--. 1 root  root   6432 Jul 21 07:11 MySQL_1-2-0.json
-rw-r--r--. 1 39073 11537  5633 Sep  7 11:31 web-application_1-1-0.json

which also provides the list of the associated JSON file (the optimization pack descriptor).

Downloading descriptors

An Akamas installation comes with the latest optimization packs already loaded in the store and is able to check the central repository for updates.

The following command describes how to download the file descriptor https://akamas.s3.us-east-2.amazonaws.com/optimization-packs/Linux/1.3.0/Linux_1-3-0.json related to the version 1.3.0 of the Linux optimization pack:

curl -O https://akamas.s3.us-east-2.amazonaws.com/optimization-packs/Linux/1.3.0/Linux_1-3-0.json akamas install optimization-pack Linux_1-3-0.json

Installing

There are two ways of installing an optimization pack:

• online installation - this is the general case when the optimization pack is already in the store

• offline installation - this may apply to custom optimization packs available as a JSON file (refer to the Creating custom optimization pack page)

Only in the first case, an optimization pack can be installed from the UI. See here below the command line commands to get an optimization pack installed.

Online installation

Execute the following command by specifying the name of the optimization pack that is already available in the store:

akamas install optimization-pack OPTIMIZATION_PACK_NAME

Offline installation

Execute the following command to install an optimization pack by specifying the name of the optimization pack and the full path to the JSON descriptor file:

akamas install optimization-pack PATH_TO_JSON_DESCRIPTOR

Forcing installation

When installing an optimization pack, the following checks are executed to identify potential clashes with already existing resources:

• name of the optimization pack

• metrics

• parameters

• component types

• telemetry providers

In case one of those checks is positive (i.e. a clash exists), the installation failed and a message notifies that a "force" option needs to be used to get the optimization pack installed anyway

akamas install -f optimization-pack OPTIMIZATION_PACK_NAME

Please be aware that when forcing the installation of an optimization pack, Akamas replaces (or merges) all the conflicting resources, except that if there is at least one custom resource, the installation is stopped. In this case, the custom resource needs to be manually removed first in order to proceed.

Uninstalling

The following command uninstalls an optimization pack

akamas uninstall --force OPTIMIZATION_PACK_NAME

Notice that this also deletes all the components built using that optimization pack.

Updating

In case a new optimization pack needs to be installed from a descriptor, the procedure is the following:

• uninstall the optimization pack

• remove the old version of the optimization pack descriptor file from the store container;

• install the new optimization pack with the new JSON descriptor

After identifying the components that are required to model a system, the following step is to model each identified key component.

Akamas provides the corresponding for their specific technology (and possibly version) and describing all the tunable parameters and metrics of interest. The full list of Akamas optimization packs is available on the o page of the Akamas reference guide.

The section of the reference guide describes the template required to define a system component, while the commands for creating a system component are listed on the page.

While the optimization process does not necessarily require component types and optimization packs to be defined, it is recommended to leverage this construct to facilitate modularization and reuse.

This is possible as the Akamas optimization pack model is extensible: custom optimization packs can be easily created without any programming to allow Akamas optimization capabilities to be applied to virtually any technology.

To create a custom optimization pack, the following fixed directory structure and several YAML manifests need to be created.

Optimization pack directory structure

my_dir
|_ optimizationPack.yaml
|_ component-types
|  |_ componentType1.yaml
|
|_ metrics
|  |_ metricsGroup1.yaml
|
|_ parameters
|  |_ parametersGroup1.yaml
|
|_ telemetry-providers
|_ provider1.yaml

Optimization pack manifest

The optimizationPack.yaml file is the manifest of the optimization pack to be created, which should always be named optimizationPack and have the following structure:

name: Java_8_Optimization_Pack
description: An optimization pack for the Java Hotspot JVM version 8
weight: 1
version: 1.0.0
tags:
- java
- jvm

where:

Component types

The component-types directory should contain the manifests of the component types to be included in the optimization pack. No particular naming constraint is enforced on those manifests.

See Component Types template for details on the structure of those manifests.

Metrics

The metrics directory should contain the manifests of the groups of metrics to be included in the optimization pack. No particular naming constraint is enforced on those manifests.

See Metric template for details on the structure of those manifests.

Parameters

The parameters directory should contain the manifests of the groups of parameters to be included in the optimization pack. No particular naming constraint is enforced on those manifests.

See Parameter template for details on the structure of those manifests.

Telemetry providers

The telemetry-providers directory should contain the manifests of the groups of parameters to be included in the optimization pack. No particular naming is enforced on those manifests.

See Telemetry Provider template for details on the structure of those manifests.

Building optimization pack descriptor

The following command need to be executed in order to produce the final JSON descriptor:

akamas build optimization-pack PATH_TO_THE_DIRECTORY

After this, the optimization pack can be installed (and then used) as described on the Managing optimization packs page.