Akamas is an on-premise product running on a dedicated machine within the customer environment:

• on a virtual or physical machine in your data center

• on a virtual machine managed running on a cloud, by any cloud provider (e.g. AWS EC2)

• on your own laptop

Akamas also provides a Free Trial option which can be requested here.

Refer to your Cloud Provider website for information about cloud hosting options and related cost information.

AWS EC2

For AWS EC2 costs visit the EC2 Pricing page and use the AWS Pricing Calculator to estimate the cost for your architecture.

Akamas offers a Free Trial option to quickly understand Akamas concepts and capabilities and experience the power of its AI-based optimization platform.

You can join Akamas Free Trial quickly:

1. Fill out this form on the Akamas website;

2. Receive credentials to access your dedicated Akamas server (a cloud instance on AWS EC2) - optimally you can also download & install the Akamas CLI and learn how to fully automate the optimization process;

3. Explore already executed optimization studies or create & run new studies to optimize a microservice app at both the JVM runtime and Kubernetes level - here you can take advantage of Akamas Quick Guides.

What you will get:

• Understand the Akamas methodology

• See Akamas AI-powered optimization in action

• Learn to use Akamas by following the how-to guides

• Familiarize yourself with Akamas UI and CLI

• Touch the benefits Akamas can deliver to your organization

Enjoy!

Software Licenses

Akamas software licensing model is subscription-based (typically on a yearly basis). For more information on Akamas' cost model and software licensing costs, please contact info@akamas.io.

Maintenance & Support Services

Akamas software licenses include Maintenance & Support Services which also include access to Customer Support Services.

Other billable services

Akamas also provides optional professional services for deployment, training, and integration activities. For more information about Akamas professional services, please contact info@akamas.io.

Akamas takes security seriously and provides enterprise-grade software where customer data is kept safe at all times. This page describes some of the most important security aspects of Akamas software and information related to processes and tools used by the Akamas company (Akamas S.p.A) to develop its software products.

Information managed by Akamas

Akamas manages the following types of information:

• System configuration and performance metrics: technical data related to optimized systems. Examples of such data include the number of CPUs available in a virtual machine or the memory usage of a Java application server;

• User accounts: accounts assigned to users to securely access the Akamas platform. For each user account, Akamas currently requires an account name and a password. Akamas does not collect any other personal identifying information;

• Service Credentials: credentials used by Akamas to automate manual tasks and to integrate with external tools. In particular, Akamas leverages the following types of interaction:

  • Integration with monitoring and orchestration tools, e.g., collecting IT performance metrics and system configuration. As a best practice, Akamas recommends using dedicated service accounts with minimal read-only privileges.

  • Integration with the target systems to apply changes to configuration parameters. As a best practice, Akamas recommends using dedicated service accounts with minimal privileges to read/write identified parameters.

GDPR Compliance

Akamas is a fully GDPR-compliant product.

Akamas is a company owned by the Moviri Group. The Moviri Group and all its companies are fully compliant with GDPR. Moviri Group Data Privacy Policy and Data Breach Incident Response Plan which apply to all the owned companies can be requested from Akamas Customer Support.

Security certifications

Akamas is an on-premises product and does not transmit any data outside the customer network. Considering the kind of data that is managed within Akamas (see section "Which information is managed by Akamas"), specific security certifications like PCI or HIPAA are not required as the platform does not manage payment or health-related information.

Data encryption

Akamas takes the need for security seriously and understands the importance of encrypting data to keep it safe at rest and in-flight.

In-Flight encryption

All the communications between Akamas UI and CLI and the back-end services are encrypted via HTTPS. The customer can configure Akamas to use customer-provided SSL certificates in all communications.

Communications between Akamas services and other integrated tools within the customer network rely on the security configuration requirements of the integrated tool (e.g.: HTTPS calls to interact with REST services).

At-Rest encryption

Akamas is an on-premises product and runs on dedicated virtual machines within the customer environment. At-rest encryption can be achieved following customer policies and best practices, for example, leveraging operating system-level techniques.

Akamas also provides an application-level encryption layer aimed at extending the scope of at-rest encryption. With this increased level of security, sensitive data managed by Akamas (e.g. passwords, tokens, or keys required to interact with external systems) are safely stored in Akamas databases using industry-standard AES 256-bit encryption.

Encryption option for Akamas on EC2

In the case of Akamas hosted on an AWS machine you may optionally create an EC2 instance with an encrypted EBS volume before installing OS and Akamas, to achieve a higher level of security.

Password management

Password Security

Passwords are securely stored using a one-way hash algorithm.

Password complexity

Akamas comes with a default password policy with the following requirements:

• has a minimum length of 8 characters.

• contains at least 1 uppercase and 1 lowercase character.

• contains at least 1 special character.

• is different from the username.

• must be different from the last password set.

Customers can modify this policy by providing a custom one that matches their internal security policies.

Password rotation

Akamas enforces no password rotation mechanism.

Credential storage

• When running on a Linux installation with KDE's KWallet enabled or GNOME's Keyring enabled, the credentials will be stored in the default wallet/keyring.

• When running on Windows, the credentials will be stored in Windows Credential Locker.

• When running on a macOS, the credential will be stored in Keychain.

• When running on a Linux headless installation, the credentials will be stored in CLEAR TEXT in a file in the current Akamas configuration folder.

Resources visibility model

Akamas provides fine granularity control over resources managed within the platform. In particular, Akamas features two kinds of resources:

• Workspace resources: entities bound to one of the isolated virtual environments (named workspaces) that can only be accessed in reading or writing mode by users to whom the administrators explicitly granted the required privileges. Such resources typically include sensitive data (e.g.: passwords, API tokens). Examples of such resources include the system to be optimized, the set of configurations, optimization studies, etc.

• Shared resources: entities that can be installed and updated by administrators and are available to all Akamas users. Such resources only contain technology-related information (e.g.: the set of performance metrics for a Java application server). Examples of such resources include Optimization Packs, which are libraries of technology components that Akamas can optimize, such as a Java application server.

Akamas Logs

Akamas logs traffic from UI and APIs. Application level logs include user access via APIs and UI and any action taken by Akamas on integrated systems.

Akamas' logs are retained on the dedicated virtual machine within the customer environment, by default, for 7 days. The retention period can be configured according to customer policies. Logs can be accessed either via UI or via log dump within the retention period. Additionally, logs have a format that can be easily integrated with external systems like log engines and SIEM to support forensic analysis.

Code scanning policy

Akamas is developed according to security best practices and the code is scanned regularly (at least daily).

The Akamas development process leverages modern continuous integration approaches and the development pipeline includes SonarQube, a leading security scanning product that includes comprehensive support for established security standards including CWE, SANS, and OWASP. Code scanning is automatically triggered in case of a new build, a release, and every night.

Vulnerability scanning and patch management policy

Akamas features modern micro-service architecture and is delivered as a set of docker containers whose images are hosted on a private Elastic Container Registry (ECR) repository on the AWS cloud. Akamas leverages the vulnerability scanning capabilities of AWS ECR to identify vulnerabilities within the product container images. AWS ECR uses the Common Vulnerabilities and Exposures (CVEs) database from the open-source Clair project.

If a vulnerability is detected, Akamas will perform a security assessment of the security risk in terms of the impact of the vulnerability, and evaluate the necessary steps (e.g.: dependency updates) required to fix the vulnerability within a timeline related to the outcome of the security assessment.

After the assessment, the vulnerability can be fixed by either recommending the upgrade to a new product version or delivering a patch or a hotfix for the current version.

Akamas is the AI-powered optimization platform designed to maximize service quality and cost efficiency without compromising on application performance. Akamas supports both production environments under live, dynamic workloads, and in test/pre-production environments against any what-if scenario and workload.

Thanks to Akamas, performance engineers, DevOps, CloudOps, FinOps and SRE teams can keep complex applications, such as Kubernetes microservices applications, optimized to avoid any unnecessary cost and any performance risks.

Akamas Optimization platform

The Akamas optimization platform leverages patented AI techniques that can autonomously identify optimal full-stack configurations driven by any custom-defined goals and constraints (SLOs), without any human intervention, any agents, and any code or byte-code changes.

Akamas optimal configurations can be applied either i) under human approval (human-in-the-loop mode) or ii) automatically, as a continuous optimization step in a CI/CD pipeline (in-the-pipe) or iii) autonomously by Akamas (autopilot).

Akamas coverage

Akamas can optimize any system with respect to any set of parameters chosen from the application, middleware, database, cloud, and any other underlying layers.

Akamas provides dozens of out-of-the-box Optimization Packs available for key technologies such as JVM, Go, Kubernetes, Docker, Oracle, MongoDB, ElasticSearch, PostgreSQL, Spark, AWS EC2 and Lambda, and more. Optimization Pack provides parameters, relationships, and metrics to accelerate the optimization process setup and support company-wide best practices. Custom Optimization Packs can be easily created without any coding.

The following figure is illustrative of Akamas coverage for both managed technologies and integrated components of the ecosystem.

Akamas integrations

Akamas can integrate with any ecosystem thanks to out-of-the-box and custom integrations with the following components:

• telemetry & monitoring tools and other sources of KPIs and cost data, such as Dynatrace, Prometheus, CloudWatch, and CSV files

• configuration management tools, repositories and interfaces to apply configurations, such as Ansible, Openshift, and Git

• value stream delivery tools to support a continuous optimization process, such as Jenkins, Dynatrace Cloud Automation, and GitLab

• load testing tools to generate simulated workloads in test/pre-production, such as LoadRunner, NeoLoad, and JMeter

Akamas has been designed around Infrastructure-as-Code (IaC) and DevOps principles. Thanks to a comprehensive set of APIs and integration mechanisms, it is possible to extend the Akamas optimization platform to manage any system and integrate with any ecosystem.

Use Cases

Akamas optimization platform supports a variety of use cases, including:

• Improve Service Quality: optimize application performance (e.g. maximize throughput, minimize response time and job execution time) and stability (lower fluctuations and peaks);

• Increase Business Agility: identify resource bottlenecks in early stages of the delivery cycle, avoid delays due to manual remediations - release higher quality services and reduce production incidents;

• Increase Service Resilience: improve service resilience under higher workloads (e.g. expected business growth) or failure scenarios identified by chaos engineering practices - improve SRE practice;

• Reduce IT Cost / Cloud Bill: reduce on-premise infrastructure cost and cloud bills due to resource over-provisioning - improve cost efficiency of Kubernetes microservices applications;

• Optimize Cloud Migration: safely migrate on-premise applications to cloud environments for optimal cost efficiency evaluate options to migrate to managed services (e.g. AWS Fargate);

• Improve Operational Efficiency: save engineering time spent on manual tuning tasks and enable Performance Engineering teams to do more in less time (and with less external consulting).

Different levels of support are provided for software versions of Akamas products, starting from its general availability (GA) date, and depending on the release of following software versions.

Version Numbering

Akamas adopts a three-place numbering scheme MA.MI.SP to designate released versions of its Software, where:

• MA is the Major Version

• MI is the Minor Version

• SP is the Service Pack or Patch number

Support levels

The following table describes the three levels of support for a software version.

End-of-Life (EOL)

At any time, Akamas reserves the right to "end of life" (EOL) a software product and to terminate any Maintenance & Support Services for such product, provided that Licensor has notified the Licensee at least 12 months prior to the above-mentioned termination.

The period of time occurring between the "end of life" notification and the actual termination of Maintenance & Support Services is provided as follows:

• No new enhancements will be introduced.

• No enhancements will be made to support new or updated versions of the platform on which the product runs or which it integrates.

• New hotfixes for problems of high technical impact or business exposure for customers may still be developed. Based on customer input, Akamas Support Agents will determine the degree of impact and exposure and the consequent activities.

• Reasonable efforts will be done to inform the Customer of any fixes, service packs, patches, or workarounds applicable to the reported case if any.

This page is intended as a first introduction to Akamas Maintenance & Support (M&S) Services.

Please refer to the specific contract in place with your Company.

Akamas M&S Services include:

• access to Software versions released as major and minor versions, service packs, patches, and hotfixes according to .

• assistance from for inquiries about the Akamas product and issues encountered while using Akamas products where there is a reasonable expectation that issues are caused by Akamas products, according to

Akamas M&S Services do not include any installation and upgrade services, creation of any custom optimization packs, telemetry providers, or workflow operators, or implementation of any custom features and integrations that are not provided out-of-the-box by the Akamas products.

Preliminary steps

Please make sure to read the Getting Started section before installing Akamas.

Before installing Akamas, please follow these steps:

1. Review hardware, software, and network prerequisites

2. Install all Akamas dependencies

Installation steps

Please follow these steps to install the Akamas Server:

1. Install the Akamas Server

2. Install the Akamas CLI

3. Verify the Akamas Server

4. Install an Akamas license

Please also read the section on how to troubleshoot the installation and how to manage the Akamas Server. Finally, read the relevant sections of Integrating Akamas to integrate Akamas into your specific ecosystem.

Before installing the Akamas Server please make sure to review all the following requirements:

• Hardware requirements

• Software requirements

• Network requirements

This page will guide you through the installation of software components that are required to get the Akamas Server installed on a machine. Please read the Akamas dependencies for a detailed list of these software components for each specific OS.

While some links to official documentation and installation resources are provided here, please make sure to refer to your internal system engineering department to ensure that your company deployment processes and best practices are correctly matched.

Dependencies Setup

As a preliminary step before installing any dependency, it is strongly suggested to create a user named akamas on your machine hosting Akamas Server.

Docker

Follow the reference documentation to install docker on your system.

Docker installation guide: https://docs.docker.com/engine/install

Docker compose is already installed since Docker 23+. To install it on previous versions of Docker follow this installation guide: https://docs.docker.com/compose/install/

AWS CLI v2: https://docs.aws.amazon.com/cli/latest/userguide

Verify dependencies

As a quick check to verify that all dependencies have been correctly installed, you can run the following commands

• Docker:

  Copy

  docker run hello-world

• Docker compose :

  Copy

  docker compose --version

• AWS CLI:

  Copy

  aws --version

Akamas Customer Support Services are delivered by Akamas support engineers, also called Support Agents, who will work remotely with Customer to provide a temporary remedy for the incident and, ultimately, a permanent resolution. Akamas Support Agents automatically escalate issues to the appropriate technical group within Akamas and notify Customers of any relevant progress. Akamas provides Customers with the ability to escalate issues when appropriate.

Please notice that Customer Support services are not to be considered as alternatives to product documentation and training, or to professional and consulting services, so adequate knowledge of Akamas products is assumed when interacting with Akamas Customer Support. Thus, during the resolution of a reported issue Support Agents may redirect Customer to training or professional services (that are not part of the scope of this service).

Akamas is deployed as a set of containerized services running on Docker and managed via Docker Compose. The latest version of the Akamas Docker Compose file and all the images required by Docker can be downloaded from the AWS ECR repository.

Two installation modes are available:

• online installation mode, in case the Akamas Server has access to the Internet - installation behind a proxy server is also supported.

• offline installation mode, in case the Akamas Server does not have access to the Internet.

Akamas is deployed as a set of containerized services running on Docker and managed via Docker Compose. In the online installation mode, the latest version of the Akamas Docker Compose file and all the images required by Docker can be downloaded from the AWS ECR repository.

In case the Akamas Server is behind a proxy server please also read how to setup Akamas behind a Proxy.

Get Akamas Docker artifacts

It is suggested first to create a directory akamas in the home directory of your user, and then run the following command to get the latest compose file:

cd ~
mkdir akamas
cd akamas
curl -O https://s3.us-east-2.amazonaws.com/akamas/compose/3.5.2/docker-compose.yml

Configure Akamas environment variables

To log into AWS ECR and pull the most recent Akamas container images, you need to set the AWS authentication variables to the appropriate values provided by Akamas Customer Support Services by running the following command. To configure Akamas, you should set the following environment variables:

To configure Akamas, you should set the following environment variables:

• AKAMAS_CUSTOMER: the customer name matching the one referenced in the Akamas license.

• AWS_ACCESS_KEY_ID: the access key for pulling the Akamas images

• AWS_SECRET_ACCESS_KEY: the secret access key for pulling the Akamas images

• AWS_DEFAULT_REGION: Unless specified by the support team keep the value to us-east-2

• AKAMAS_BASE_URL: the endpoint in the Akamas APIs that will be used to interact with the CLI, typically https://<akamas server DNS address>

To avoid losing your environment variables for future upgrades, it is suggested to keep them in the .env file. Launch the following command from the same folder where the docker-compose.yml is stored, replacing the parameters in the brackets <>:

# Required variables
AKAMAS_CUSTOMER=<your name or your organization name>
AWS_ACCESS_KEY_ID=<your access key id>
AWS_SECRET_ACCESS_KEY=<your secret access key>
AKAMAS_BASE_URL=https://<akamas server DNS address>
AWS_DEFAULT_REGION=us-east-2

# Optional variables
# Database passwords
DEFAULT_DATABASE_PASSWORD=
KEYCLOAK_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_keycloak}
ANALYZER_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_analyzer}
CAMPAIGN_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_campaign}
LICENSE_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_license}
OPTIMIZER_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_optimizer}
ORCHESTRATOR_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_orchestrator}
SYSTEM_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_system}
TELEMETRY_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_telemetry}
# Docker volumes prefix
COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME:-akamas}

Start Akamas

To log into AWS ECR and pull the most recent Akamas container images you also need to set the AWS authentication variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION) with the values provided by Akamas Customer Support Services. You can leverage the .env file previously created with the following command:

source ./.env
aws ecr get-login-password --region us-east-2 | docker login -u AWS --password-stdin https://485790562880.dkr.ecr.us-east-2.amazonaws.com

You can start installing the Akamas server by running the following AWS CLI commands:

docker compose up -d

Based on the Support levels for software versions, the following table describes the level of support of the Akamas versions after the version 3.2 GA date (2023 May, 1st).

Akamas Customer Support Services provides different standard levels of support. Please verify the level of support specified in the contract in place with your Company.

Severity levels

The following table describes the different severity levels for Customer Support.

Support conditions

The contract in place with the Customer specifies the level of support provided by Akamas Agents, according at least to the following items:

• Maximum number of support seats: this is the maximum number of named users within the Customer organization who can request Akamas Customer Support.

• Language(s): these are the languages that can be used for interacting with Akamas Support Agents - the default is English.

• Channel(s): these are the different communication channels that can be used to interact with Akamas Agents - these may include one or more options among web ticketing, email, phone, and Slack channel.

• Max Initial Response Time: this refers to the time interval occurring from the time a request is opened by Customer to Customer Support and the time a Support Agent responds with a first notification (acknowledgment).

• Severity: this is the level of severity associated with a reported issue, which initially corresponds to the severity level originally indicated by the Customer. Notice that the severity level may change, for example as new information becomes available or if Support Agents and Customer agree to re-evaluate it. Please notice that the severity level may be downgraded by Support Agents if Customer is not able to provide adequate resources or responses to enable Akamas to continue with its resolution efforts.

• Initial Remedy: this refers to any operation aimed at addressing a reported issue by restoring a minimal level of operations, even if it may cause some performance degradation of the Customer service or operations. A workaround is to be considered a valid Initial Remedy.

Please notice that Support Agents may refuse to serve a service request to Customer Support either in case Customer does not have a valid Maintenance & Support subscription or in case the above-mentioned conditions or other conditions stated in the contract in place are not met. In any case, the Customer is expected to provide all the information required by Support Agent in order to serve service requests Customer Support.

Running in your data center

The following table provides the minimal hardware requirements for the virtual or physical machine used to install the Akamas server in your data center.

Running on AWS EC2

To run Akamas on an AWS Instance you need to create a new virtual machine based on one of the supported operating systems. You can refer to AWS documentation for step-by-step instructions on creating the instance.

As shown in the following diagram, you can create the Akamas instance in the same AWS region, Virtual Private Cloud (VPC), and private subnet as your own already existing EC2 machines and by creating/configuring a new security group that allows communication between your application instances and Akamas instance. The inbound/outbound rules of this security group must be configured as explained in the Networking Requirements section of this page.

It is recommended to use an m6a.xlarge instance with at least 70GB of disks of type GP2 or GP3 and select the latest LTS version of Ubuntu.

Supported AWS Regions

Akamas can be run in any EC2 region.

You can find the latest version supported for your preferred region here.

AWS Service Limits

Before installing Akamas on an AWS Instance please make sure to meet your AWS service limits (please refer to the official AWS documentation here).

Akamas is based on a microservices architecture where each service is deployed as a container and communicates with other services via REST APIs. Akamas can be deployed on a dedicated machine (Akamas Server) or on a Kubernetes cluster.

The following figure represents the high-level Akamas architecture.

Interact with Akamas

Users can interact with Akamas via either the Graphical User Interface (GUI), Command-Line Interface (CLI), or via Application Programmatic Interface (API).

Both the GUI and CLI leverage HTTP/S APIs which pass through an API gateway (based on Kong), which also takes care of authenticating users by interacting with Akamas access management and routing requests to the different services.

The Akamas CLI can be invoked on either the Akamas Server itself or on a different machine (e.g. a laptop or another server) where the Akamas CLI has been installed.

Repositories

Akamas data is securely stored in different databases:

• time series data gathered from telemetry providers are stored in Elasticsearch;

• application logs are also stored in Elasticsearch;

• data related to systems, studies, workflows, and other user-provided data are stored in a Postgres database.

Notice: both Postgres and Elasticsearch and any other service included within Akamas are provided by Akamas as part of the Akamas installation package.

Services

Core Services

The following Spring-based microservices represent Akamas core services:

• System Service: holds information about metrics, parameters, and systems that are being optimized

• Campaign Service: holds information about optimization studies, including configurations and experiments

• Metrics Service: stores raw performance metrics (in Elasticsearch)

• Analyzer Service: automates the analysis of load tests and provides related functionalities such as smart windowing

• Telemetry Service: takes care of integrating different data sources by supporting multiple Telemetry Providers

• Optimizer Service: combines different optimization engines to generate optimized configurations using ML techniques

• Orchestrator Service: manages the execution of user-defined workflows to drive load tests

• User Service: takes care of user management activities such as user creation or password changes

• License Service: takes care of license management activities, optimization pack, and study export.

Ancillary Services

Akamas also provides advanced management features like logging, self-monitoring, licensing, user management, and more.

Internet access

Internet access is required for Akamas online installation and updated procedures and allows retrieving the most updated Akamas container images from the Akamas private Amazon Elastic Container Registry (ECR).

If internet access is not available for policies or security reasons, Akamas installation and updates can be executed offline.

Internet access from the Akamas server is not mandatory but it’s strongly recommended.

Ports

The following table provides a list of the ports on the Akamas server that have to be reachable by Akamas administrators and users to properly operate the system.

In the specific case of AWS instance and customer instances sharing the same VPC/Subnet inside AWS, you should:

• open all of the ports listed in the table above for all inbound URLs (0.0.0.0/32) on your AWS security group

• open outbound rules to all traffic and then attach this AWS security group (which must reside inside a private subnet) to the Akamas machine and all customer application AWS machines

Akamas APIs and UI use plain HTTP when they are first installed. To enable the use of HTTPS you will need to:

1. Ask your security team to provide you with a valid certificate for your server. The certificate usually consists of two files with ".key" and ".pem" extensions. You will need to provide the Akamas server DNS name.

2. Create a folder named "certs" in the same directory as Akamas' docker-compose file;

3. Copy the ".key" and ".pem" files in the created "certs" folder and rename them to "akamas.key" and "akamas.pem" respectively. Ensure the files belong to the same user and group you use to run Akamas.

4. Restart two Akamas services by running the following commands:

After the containers' reboot is complete you will be able to access the UI over HTTPS from your browser:

If you previously set up AKAMAS_BASE_URL variable with http (e.g. http://my.domain) you should update it to use https (e.g. http://my.domain) then issue

Setup CLI to use HTTPS

Now that your Akamas server is configured to use HTTPS you can update the Akamas CLI configuration to use the secure protocol.

If you have not installed the Akamas CLI, follow the . If you already have the CLI available, you can run the following command:

You will be prompted to enter some input, please value it as follows:

You can test the connection by running:

It should return 'OK', meaning Akamas has been properly configured to work over HTTPS.

This section describes how to setup an Akamas Server behind a proxy server and to allow Docker to connect to the Akamas repository on AWS ECR.

Configure Docker daemon

First, create the /etc/systemd/system/docker.service.d directory if it does not already exists. Then create or update the /etc/systemd/system/docker.service.d/http-proxy.conf file with the variables listed below, taking care of replacing <PROXY> with the address and port (and credentials if needed) of your target proxy server:

Once configured, flush the changes and restart Docker with the following commands:

For more details, refer to the official documentation page: .

Configure the Akamas containers

To allow the Akamas services to connect to addresses outside your intranet, the Docker instance needs to be configured to forward the proxy configuration to the Akamas containers.

Update the ~/.docker/config.json file adding the following field to the JSON, taking care to replace <PROXY> with the address (and credentials if needed) of your target proxy server:

Run Akamas

Set the following variables to configure your working environment, taking care to replace <PROXY> with the address (and credentials if needed) of your target proxy server:

Once configured, you can log into the ECR repository through the AWS CLI and start the Akamas services manually.

Akamas is deployed as a set of containerized services running on Docker and managed via Docker Compose. In the offline installation mode, the latest version of the Akamas Docker Compose file and all the images required by Docker cannot be downloaded from the AWS ECR repository.

Get Akamas Docker artifacts

Get in contact with Akamas Customer Services to get the latest versions of the Akamas artifacts uploaded to a location of your choice on the dedicated Akamas Server.

Akamas installation artifacts will include:

• images.tar.gz: a tarball containing Akamas main images.

• docker-compose.yml: docker-compose file for Akamas.

• akamas: the binary file of the Akamas CLI that will be used to verify the installation.

Import Docker images

A preliminary step in the offline installation mode is to import the shipped Docker images by running the following commands in the same directory where the tar files have been stored:

Mind that this import procedure could take some time!

Configure Akamas environment variables

To configure Akamas, you should set the following environment variables:

• AKAMAS_CUSTOMER: the customer name matching the one referenced in the Akamas license.

• AKAMAS_BASE_URL: the endpoint in the Akamas APIs that will be used to interact with the CLI, typically https://<akamas server DNS address>

To avoid losing your environment variables for future upgrades, it is suggested to keep them in the .env file, stored in the same directory as the docker-compose.yml:

Run installation

To start Akamas you can now simply navigate into the akamas folder and run a docker-compose command:

You may get the following error:

• Ubuntu

• RHEL

Operating System

The following table provides a list of the supported operating systems and their versions.

On RHEL systems Akamas containers might need to be run in privileged mode depending on how Docker was installed on the system.

Software packages

The following table provides a list of the required Software Packages (also referred to as Akamas dependencies) together with their versions.

The exact version of these prerequisites is listed in the following table:

Akamas user

To install and run Akamas it is recommended to create a dedicated user (usually "akamas"). The Akamas user is not required to be in the sudoers list but can be added to the docker (dockeroot) group so it can run docker and docker-compose commands.

Make sure that the Akamas user has the read, write, and execute permissions on /tmp. If your environment does not allow writing to the whole /tmp folder, please create a folder /tmp/build and assign read and write permission to the Akamas user on that folder.

Issues when installing Docker

Centos 7 and RHEL 7

Notice: this distro features a known issue since Docker default execution group is named dockerroot instead of docker . To make docker work edit (or create) /etc/docker/daemon.json to include the following fragment:

After editing or creating the file, please restart Docker and then check the group permission of the Docker socket (/var/run/docker.sock), which should show dockerroot as a group:

Then, add the newly created akamas user to the dockerroot group so that it can run docker containers:

and check the akamas user has been correctly added to dockerroot group by running:

Issues when running AWS CLI

In case of issues in logging in through AWS CLI, when executing the following command:

Please check that:

• Environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION are correctly set

• AWS CLI version is 2.0+

Issue when starting Akamas services

Akamas failed to start some services

Please notice that the very first time Akamas is started, up to 30 minutes might be required to initialize the environment.

In case the issue persists you can run the following command to identify which service is not able to start up correctly

License service unable to access docker socket

In some systems, the Docker socket, usually located in /var/run/docker.sock can not be accessed within a container. This causes Akamas to signal this behavior by reporting the Access Denied error in the license service logs.

To overcome this limitation edit the docker-compose.yaml file adding the line privileged: true to the following services:

• License

• Optimizer

• Telemetry

• Airflow

The following is a sample configuration where this change is applied to the license service:

Finally, you can issue the following command to apply these changes

Missing Akamas Customer variable

You can easily inspect which value of this variable has been used when starting Akamas by running the following command on the Akamas server:

If you find out that the value is not the one you expect, you can update the .env file and then start again the license service by running:

Once Akamas is up and running you can re-install your license.

Other issues

By default, Akamas uses the following ports for its UI:

• 80 (HTTP)

• 443 (HTTPS)

Depending on the configuration of your environment, you may want to change the default settings: to do so, you’ll have to update the Akamas docker-compose file.

Inside the docker-compose.yml file, scroll down until you come across the akamas-ui service. There you will find a specification as follows:

  akamas-ui:
    ports:
      - "443:443"
      - "80:80"

Update the YAML file by remapping the UI ports to the desired ports of the host.

  akamas-ui:
    ports:
      - "<YOUR_HTTPS_PORT_OF_CHOICE>:443"
      - "<YOUR_HTTP_PORT_OF_CHOICE>:80"

In case you were running Akamas with host networking, you are allowed to bind different ports in the container itself. To do so you can expand the docker-compose service by adding a couple of environment variables like this:

  akamas-ui:
    environment:
      - HTTP_PORT=<HTTP_CONTAINER_PORT>
      - HTTPS_PORT=<HTTPS_CONTAINER_PORT>
    ports:
      - "<YOUR_HTTPS_PORT_OF_CHOICE>:<HTTP_CONTAINER_PORT>"
      - "<YOUR_HTTP_PORT_OF_CHOICE>:<HTTPS_CONTAINER_PORT>"

Finally, apply the new configuration after updating the AKAMAS_BASE_URL environment variable to match the new protocol or port.

This page describes the requirements that should be fulfilled by the user when installing or managing an Akamas installation on Kubernetes. The software below is usually installed on the user's workstation or laptop.

Kubectl

Kubectl must be installed and configured to interact with the desired cluster. Refer to the official kubectl documentation to set up the client.

To interact with the Kubernetes APIs, you will need kubectl, preferably with a version matching the cluster. To check both the client and cluster versions, run the following:

kubectl version --short

Helm

Installing Akamas requires Helm 3.0 or higher. To check the version, run the following:

helm version --short

Privileged access

Akamas uses Elasticsearch to store logs and time series. When running Akamas on Kubernetes, Elasticsearch is installed automatically using the official Elasticsearch helm chart. This chart required running an init container with privileged access to set up a configuration on the Elasticsearch pod host. If running such a container is not permitted in your environment, you can add the following snippet to the akamas.yaml file when installing Akamas to disable this feature.

# Disable ES privileged initialization container. 
elasticsearch:
  sysctlInitContainer:
    enabled: false

Preliminary steps

Before installing Akamas, please follow these steps:

1. Review the cluster requirements

2. Install the software requirements

Installation steps

Please follow these steps to install the Akamas application:

1. Install the application

2. Install the CLI

3. Verify the installation

4. Install the license

Please also read the section on how to manage Akamas. Finally, read the relevant sections of Integrating Akamas to integrate Akamas into your specific ecosystem.

Before starting the installation, make sure the requirements are met.

Create the configuration file

Akamas on Kubernetes is provided as a set of templates packaged in a chart archive managed by Helm.

To proceed with the installation, you need to create a Helm Values file, called akamas.yaml in this guide, containing the mandatory configuration values required to customize your application. The following template contains the minimal set required to install Akamas:

# AWS credentials to fetch ECR images (required)
awsAccessKeyId: <AWS_ACCESS_KEY_ID>
awsSecretAccessKey: <AWS_SECRET_ACCESS_KEY>

# Akamas customer name. Must match the value in the license (required)
akamasCustomer: <CUSTOMER_NAME>

# Akamas administrator password. If not set a random password will be generated
akamasAdminPassword: <ADMIN_PASSWORD>

# The URL that will be used to access Akamas, for example 'http://akamas.kube.example.com' (required)
akamasBaseUrl: <INSTANCE_HOSTNAME>

You can also download the template file running the following snippet:

curl -so akamas.yaml  http://helm.akamas.io/templates/1.5.4/akamas.yaml.template

Replace in the file the following placeholders:

• AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY: the AWS credentials for pulling the Akamas images

• CUSTOMER_NAME: customer name provided with the Akamas license

• ADMIN_PASSWORD: initial administrator password

• INSTANCE_HOSTNAME: the URL that will be used to expose the Akamas installation, for example https://akamas.k8s.example.com when using an Ingress, or http://localhost:9000 when using port-forwarding. Refer to Accessing Akamas for the list of the supported access methods and a reference for any additional configuration required.

Define Size

Akamas can be installed in three sizes Small, Medium, and Large as explained in the cluster prerequisite section. By default, the chart installs the Small size. If you want to install a specific size add the following snippet to your values.yaml file.

Medium

#Medium
airflow:
  config:
    core:
      parallelism: 102
  scheduler:
    resources:
      limits:
        cpu: 2500m         
        memory: 21000Mi    
      requests:
        cpu: 1000m         
        memory: 21000Mi   

Large

#Large
airflow:
  config:
    core:
      parallelism: 202
  scheduler:
    resources:
      limits:
        cpu: 2500m         
        memory: 28000Mi    
      requests:
        cpu: 1000m         
        memory: 28000Mi    
telemetry:
  parallelism: 50

Start the installation

With the configuration file you just created (and the new variables you added to override the defaults), you can start the installation with the following command:

helm upgrade --install \
  --create-namespace --namespace akamas \
  --repo http://helm.akamas.io/charts \
  --version '1.5.4' \
  -f akamas.yaml \
  akamas akamas

This command will create the Akamas resources within the specified namespace. You can define a different namespace by changing the argument --namespace <your-namespace>

An example output of a successful installation is the following:

Release "akamas" does not exist. Installing it now.
NAME: akamas
LAST DEPLOYED: Thu Sep 21 10:39:01 2023
NAMESPACE: akamas
STATUS: deployed
REVISION: 1
NOTES:
Akamas has been installed

NOTES:
Akamas has been installed

To get the initial password use the following command:

kubectl get secret akamas-admin-credentials -o go-template='{{ .data.password | base64decode }}'

Check the installation

To monitor the application startup, run the command kubectl get pods. After a few minutes, the expected output should be similar to the following:

NAME                           READY   STATUS    RESTARTS   AGE
airflow-6ffbbf46d8-dqf8m       3/3     Running   0          5m
analyzer-67cf968b48-jhxvd      1/1     Running   0          5m
campaign-666c5db96-xvl2z       1/1     Running   0          5m
database-0                     1/1     Running   0          5m
elasticsearch-master-0         1/1     Running   0          5m
keycloak-66f748d54-7l6wb       1/1     Running   0          5m
kibana-6d86b8cbf5-6nz9v        1/1     Running   0          5m
kong-7d6fdd97cf-c2xc9          1/1     Running   0          5m
license-54ff5cc5d8-tr64l       1/1     Running   0          5m
log-5974b5c86b-4q7lj           1/1     Running   0          5m
logstash-8697dd69f8-9bkts      1/1     Running   0          5m
metrics-577fb6bf8d-j7cl2       1/1     Running   0          5m
optimizer-5b7576c6bb-96w8n     1/1     Running   0          5m
orchestrator-95c57fd45-lh4m6   1/1     Running   0          5m
store-5489dd65f4-lsk62         1/1     Running   0          5m
system-5877d4c89b-h8s6v        1/1     Running   0          5m
telemetry-8cf448bf4-x68tr      1/1     Running   0          5m
ui-7f7f4c4f44-55lv5            1/1     Running   0          5m
users-966f8f78-wv4zj           1/1     Running   0          5m

At this point, you should be able to access the Akamas UI using the endpoint specified in the akamasBaseUrl, and interact through the Akamas CLI with the path /api.

If you haven't already, you can update your configuration file to use a different type of service to expose Akamas' endpoints. To do so, pick from the Accessing Akamas the configuration snippet for the service type of your choice, add it to the akamas.yaml file, update the akamasBaseUrl value, and re-run the installation command to update your Helm release.

Before installing the Akamas please make sure to review all the following requirements:

• Cluster requirements

• Software requirements

Akamas is deployed on your Kubernetes cluster through a Helm chart, and all the required images can be downloaded from the AWS ECR repository.

Two installation modes are available:

• online installation, in case the Kubernetes cluster can access the Internet.

• offline installation, in case the Kubernetes cluster does not have access to the Internet or you need to use a private image registry.

You may find helpful some of the commands listed in the sections below.

Read database passwords

By default, access to each service database is assigned to a user with randomly generated passwords. For example, to read the campaign service database password, execute the following command:

kubectl get secret database-user-credentials -o go-template='{{ .data.campaign | base64decode }}'

The username for the campaign service can be found in the configuration file under each service section. To read the username for the campaign service set during the installation, launch the following command:

helm get values akamas --all --output json | jq '.campaign.database.user'

You can connect to the campaign_service database with the user and password above.

If you want to show all the passwords, execute this command:

kubectl get secret database-user-credentials -o go-template='{{range $k,$v := .data}} {{printf "%s: %s\n" $k ( $v |base64decode ) }}{{end}}'

Linux

To get Akamas CLI installed on Linux, run the following commands:

curl -o akamas_cli https://s3.us-east-2.amazonaws.com/akamas/cli/$(curl -s https://s3.us-east-2.amazonaws.com/akamas/cli/stable.txt)/linux_64/akamas
sudo mv akamas_cli /usr/local/bin/akamas
chmod 755 /usr/local/bin/akamas

You can now run the Akamas CLI following by running the akamas command.

In some installations, the /usr/local/bin folder is not present in the PATH environment variable. This prevents you from using akamas without specifying the complete file location. To fix this issue you can add an entry to the PATH system environment variable or move the executable to another folder in your PATH.

Auto-completion

To enable auto-completion on Linux systems with a bash shell (requires bash 4.4+), run the following commands:

curl -O https://s3.us-east-2.amazonaws.com/akamas/cli/$(curl -s https://s3.us-east-2.amazonaws.com/akamas/cli/stable.txt)/linux_64/akamas_autocomplete.sh
mkdir -p ~/.akamas
mv akamas_autocomplete.sh ~/.akamas
echo '. ~/.akamas/akamas_autocomplete.sh' >> ~/.bashrc
source ~/.bashrc

Windows

To install the Akamas CLI on Windows run the following command from Powershell:

Invoke-WebRequest "https://s3.us-east-2.amazonaws.com/akamas/cli/$($(Invoke-WebRequest https://s3.us-east-2.amazonaws.com/akamas/cli/stable.txt | Select-Object -Expand Content) -replace '\n', '')/win_64/akamas.exe" -OutFile akamas.exe

You can now run the Akamas CLI by running .\akamas in the same folder.

To invoke the akamas CLI from any folder, create a akamas folder (such as C:\Program Files\akamas), and move there the akamas.exe file. Then, add an entry to the PATH system environment variable with the value C:\Program Files\akamas. Now, you can invoke the CLI from any folder, by simply running the akamas command.

The Akamas CLI can be accessed by simply running the akamascommand.

Verify the CLI

You can verify that the CLI was installed correctly by running this command:

akamas version

which should show an output similar to this one

Akamas CLI: 2.9.1
Akamas platform: 3.5.2

At any time, you can see available commands and options with:

akamas --help

For the full list of Akamas commands please refer to the section CLI reference.

Before starting the installation, make sure the requirements are met.

Configure the registry

If your cluster is in an air-gapped network or is unable to reach the Akamas image repository, you need to copy the required images to your private registry.

The procedure described here leverages your local environment to upload the images. Thus, to interact between the Akamas and private registry, it requires Docker to be installed and configured.

Transfer the Docker images

The offline installation requires you to pull the images and migrate them to your private registry. In the following command replace the chart version to download the related list of images:

curl -sO  http://helm.akamas.io/images/1.5.4/image-list

Once the import is complete, you must re-tag and upload the images. Run the following snippet, replacing <REGISTRY_URL> with the actual URL of the private registry:

NEW_REGISTRY="<REGISTRY_URL>"

while read IMAGE; do
    REGISTRY=$(echo "$IMAGE" | cut -d '/' -f 1)
    REPOSITORY=$(echo "$IMAGE" | cut -d ':' -f 1 | cut -d "/" -f2-)
    TAG=$(echo "$IMAGE" | cut -d ':' -f 2)

    NEW_IMAGE="$NEW_REGISTRY/$REPOSITORY:$TAG"
    echo "Migrating $IMAGE to $NEW_IMAGE"

    docker pull "$IMAGE"
    docker tag "$IMAGE" "$NEW_IMAGE"
    docker push "$NEW_IMAGE"
done <image-list

This process could last several minutes, once the upload is complete, you can proceed with the next steps.

Create the configuration file

Akamas on Kubernetes is provided as a set of templates packaged in a chart archive managed by Helm.

To proceed with the installation, you must create a Helm Values file, called akamas.yaml in this guide, containing the mandatory configuration values required to customize your application. The following template contains the minimal set required to install Akamas:

# Akamas customer name. Must match the value in the license (required)
akamasCustomer: <CUSTOMER_NAME>

# Akamas administrator password. If not set a random password will be generated
akamasAdminPassword: <ADMIN_PASSWORD>

# The URL that will be used to access Akamas, for example 'http://akamas.kube.example.com' (required)
akamasBaseUrl: <INSTANCE_HOSTNAME>


global:
  imageRegistry: gitlab-runner-new.dev.akamas.io

elasticsearch:
  image: gitlab-runner-new.dev.akamas.io/akamas/elastic/elasticsearch
  
kibana:
  image: gitlab-runner-new.dev.akamas.io/akamas/elastic/kibana
  
airflow:
  images:
    airflow:
      repository: gitlab-runner-new.dev.akamas.io/akamas/airflow_service
      tag: 2.8.0
    pgbouncer:
      repository: gitlab-runner-new.dev.akamas.io/akamas/airflow_service
      tag: ~
    pgbouncerExporter:
      repository: gitlab-runner-new.dev.akamas.io/akamas/airflow_service
      tag: ~
  webserver:   
    extraInitContainers:
      - name: wait-logstash
        image: gitlab-runner-new.dev.akamas.io/akamas/utils:0.1.5
        command:
          - "sh"
          - "-c"
          - "until ./wait-for-it.sh -h logstash -p 9600 -t 120 -e _node/pipelines -j '.pipelines|length' -r 10 ; do echo Waiting for Logstash; sleep 10; done; echo Connected"
        resources:
          limits:
            cpu: 100m
            memory: 50Mi
          requests:
            cpu: 10m
            memory: 50Mi
  scheduler:
    podAnnotations:
      k8s.akamas.com/imageName: gitlab-runner-new.dev.akamas.io/akamas/airflow_service
    env:
      - name: CONTAINER_NAME
        value: airflow
      - name: SERVICE
        value: airflow
      - name: LOGTYPE
        value: airflow
      - name: IMAGE_NAME
        value: gitlab-runner-new.dev.akamas.io/akamas/airflow_service
      - name: AIRFLOW_CONN_HTTP_SYSTEM
        value: "http://:@system:8080"
      - name: AIRFLOW_CONN_HTTP_CAMPAIGN
        value: "http://:@campaign:8080"
      - name: AIRFLOW_CONN_HTTP_ORCHESTRATOR
        value: "http://:@orchestrator:8080"
      - name: KEYCLOAK_ENDPOINT
        value: "http://keycloak:8080"

    extraInitContainers:
      - name: wait-logstash
        image: gitlab-runner-new.dev.akamas.io/akamas/utils:0.1.5
        command:
          - "sh"
          - "-c"
          - "until ./wait-for-it.sh -h logstash -p 9600 -t 120 -e _node/pipelines -j '.pipelines|length' -r 10 ; do echo Waiting for Logstash; sleep 10; done; echo Connected"
        resources:
          limits:
            cpu: 100m
            memory: 50Mi
          requests:
            cpu: 10m
            memory: 50Mi

Replace in the file the following placeholders:

• CUSTOMER_NAME: customer name provided with the Akamas license

• ADMIN_PASSWORD: initial administrator password

• INSTANCE_HOSTNAME: the URL that will be used to expose the Akamas installation, for example https://akamas.k8s.example.com when using an Ingress, or http//:localhost:9000 when using port-forwarding. Refer to Accessing Akamas for the list of the supported access methods and a reference for any additional configuration required.

• REGISTRY_URL: the URL for the private registry used in the transfer process above

Configure the authentication

This section describes how to configure the authentication to your private registry. If your registry does not require any authentication, skip directly to the installation section.

To authenticate to your private registry, you must manually create the Secret required to pull the images. If the registry uses basic authentication, you can create the credentials in the namespace by running the following command:

kubectl create secret docker-registry registry-token \
  --namespace akamas \
  --docker-server=<REGISTRY_URL> \
  --docker-username=<USER> \
  --docker-password=<PASSWORD>

Otherwise, you can leverage any credential already configured on your machine by running the following command:

kubectl create secret docker-registry registry-token \
  --namespace akamas \
  --from-file=.dockerconfigjson=<PATH/TO/.docker/config.json>

Define Size

Akamas can be installed in three sizes Small, Medium, and Large as explained in the cluster prerequisite section. By default, the chart installs the Small size. If you want to install a specific size add the following snippet to your values.yaml file.

Medium

#Medium
airflow:
  config:
    core:
      parallelism: 102
  scheduler:
    resources:
      limits:
        cpu: 2500m         
        memory: 21000Mi    
      requests:
        cpu: 1000m         
        memory: 21000Mi   

Large

#Large
airflow:
  config:
    core:
      parallelism: 202
  scheduler:
    resources:
      limits:
        cpu: 2500m         
        memory: 28000Mi    
      requests:
        cpu: 1000m         
        memory: 28000Mi    
telemetry:
  parallelism: 50

Start the installation

If the host you are using to install akamas can reach helm.akamas.io you can follow the instructions in the online installation guide. Otherwise, follow the instructions below to download the chart content locally.

From a machine that can reach the endpoint, run the following command to download the chart:

helm pull --repo http://helm.akamas.io/charts --version '1.5.4' akamas

The command downloads the latest version chart version as an archive named akamas-<version>.tgz. The file can be transferred to the machine where the installation will be run. Replace akamas/akamas with the download package in the following commands.

If you wish to see and override the values that Helm will use to install Akamas, you may execute the following command.

helm show values akamas-<version>.tgz

Now, with the configuration file you just created (and the new variables you added to override the defaults), you can start the installation with the following command:

helm upgrade --install \
  --create-namespace --namespace akamas \
  -f akamas.yaml \
  akamas akamas-<version>.tgz

This command will create the Akamas resources within the specified namespace. You can define a different namespace by changing the argument --namespace <your-namespace>

An example output of a successful installation is the following:

Release "akamas" does not exist. Installing it now.
NAME: akamas
LAST DEPLOYED: Thu Sep 21 10:39:01 2023
NAMESPACE: akamas
STATUS: deployed
REVISION: 1
NOTES:
Akamas has been installed

NOTES:
Akamas has been installed

To get the initial password use the following command:

kubectl get secret akamas-admin-credentials -o go-template='{{ .data.password | base64decode }}'

Check the installation

To monitor the application startup, run the command kubectl get pods. After a few minutes, the expected output should be similar to the following:

NAME                           READY   STATUS    RESTARTS   AGE
airflow-6ffbbf46d8-dqf8m       3/3     Running   0          5m
analyzer-67cf968b48-jhxvd      1/1     Running   0          5m
campaign-666c5db96-xvl2z       1/1     Running   0          5m
database-0                     1/1     Running   0          5m
elasticsearch-master-0         1/1     Running   0          5m
keycloak-66f748d54-7l6wb       1/1     Running   0          5m
kibana-6d86b8cbf5-6nz9v        1/1     Running   0          5m
kong-7d6fdd97cf-c2xc9          1/1     Running   0          5m
license-54ff5cc5d8-tr64l       1/1     Running   0          5m
log-5974b5c86b-4q7lj           1/1     Running   0          5m
logstash-8697dd69f8-9bkts      1/1     Running   0          5m
metrics-577fb6bf8d-j7cl2       1/1     Running   0          5m
optimizer-5b7576c6bb-96w8n     1/1     Running   0          5m
orchestrator-95c57fd45-lh4m6   1/1     Running   0          5m
store-5489dd65f4-lsk62         1/1     Running   0          5m
system-5877d4c89b-h8s6v        1/1     Running   0          5m
telemetry-8cf448bf4-x68tr      1/1     Running   0          5m
ui-7f7f4c4f44-55lv5            1/1     Running   0          5m
users-966f8f78-wv4zj           1/1     Running   0          5m

At this point, you should be able to access the Akamas UI using the endpoint specified in the akamasBaseUrl, and interact through the Akamas CLI with the path /api.

If you haven't already, you can update your configuration file to use a different type of service to expose Akamas' endpoints. To do so, pick from the Accessing Akamas the configuration snippet for the service type of your choice, add it to the akamas.yaml file, update the akamasBaseUrl value, and re-run the installation command to update your Helm release.

Installing telemetry providers

During online installation, a set of out-of-the-box telemetry providers are automatically installed. For offline installation, this step has to be executed manually. To install the telemetry providers required for your environment proceed to Integrating Telemetry Providers section.

Running Akamas on OpenShift requires some Helm configurations to be applied.

The installation is provided as a set of templates packaged in a chart archive managed by . Custom values are applied to ensure Akamas complies with the default restricted-v2 security context constraints.

OpenShift requirements

OpenShift version 4.x.

Installation

The installation can be done offline and online as described in the section . Choose the one that better suits your cluster access policies.

The following snippet must be added to the akamas.yaml to install Akamas on OpenShift.

Access Akamas - Ingress to route

Once the Helm command is invoked, ensure the routes have been created by running:

The output must list the Akamas routes with different paths.

Toolbox

The toolbox optional component requires privileged access to run on OpenShift; the toolbox uses a dedicated service account, named toolbox by default. You can grant privileged access by issuing the following command.

The Akamas CLI allows users to invoke commands against the Akamas dedicated machine (Akamas Server). The Akamas CLI can also be installed on a different system than the Akamas Server.

Prerequisites

Linux and Windows operating systems are supported for installing Akamas CLI.

Installation steps

The Akamas CLI can be installed and configured in two simple steps:

Refer to the section to modify the CLI ports the Akamas Server is listening to. Section provides instructions on how to interact with Akamas via a proxy server.

The Akamas CLI supports interacting with the API server through an HTTP/HTTPS proxy server.

To enable access via an HTTP proxy, set the environment variable HTTP_PROXY. From the following snippet, replace proxy_ip and proxy_port with the desired values.

Then, run the akamas command to verify access.

Access through an HTTPS proxy can be set by using the environment variable HTTPS_PROXY instead of HTTP_PROXY.

The CLI is used to interact with an akamas server. To initialize the configuration of the Akamas CLI you can run the command:

and follow the wizard to provide the required information such as the server IP.

Here is a summary of the configuration wizard options.

This configuration can be changed at any time (see how to ).

After this step, the Akamas CLI can be used to login to the Akamas server, by issuing the following command:

and providing the credentials as requested.

The CLI configuration contains the information required to communicate with the akamas server. It can be easily created and updated with a configuration wizard. This page describes the main options of the Akamas CLI and how to modify them. If your Akamas instance is installed with Kubernetes, ensure the UI service is .

API Address

The CLI, as well as the UI, interacts with the akamas server via APIs. The apiAddress configuration contains the information required to communicate with the server.

Docker

The Akamas Server provides different listeners to interact with APIs:

• an HTTP listener on port 80 under the path /akapi

• an HTTP listener on port 8000

• an HTTPS listener on port 443 under the path /akapi

• an HTTPS listener on port 8443

Depending on your networking setup you can either use the listeners on ports 80 and 443 which are also used for the UI or directly interact with the API gateway on ports 8000 and 8443. If you are unsure about your network setup we suggest you start with the HTTPS listener on port 443.

For improved security, it is recommended to configure CLI communications with the Akamas Server over HTTPS. Notice that you need to have a valid certificate installed on your Akamas server (at least a self-signed one) to enable HTTPS communication between CLI and the Akamas Server.

Changing CLI protocol

The CLI can be configured either directly via the CLI itself or via the YAML configuration file akamasconf.

Using the CLI

Issue the following command to change the configuration of the Akamas CLI:

and then follow the wizard to provide the required CLI configuration:

• enable HTTPS communications:

• enable HTTP communications:

Please notice that by default Akamas CLI expects a valid SSL certificate. If you are using a self-signed certificate or a not valid one you can set the Verify SSL variable to false. This will mimic the behavior of accepting an invalid HTTPS certificate on your favorite browser.

Using the akamasconf file

Create a file and name it akamasconf to be located at the following locations:

• Linux: ~/.akamas/akamasconf

• Windows: C:\Users\<username>\.akamas (where C: is the drive where the OS is installed)

The file location can be customized by setting an $AKAMASCONF environment variable.

Here is an example akamasconf file provided as a sample:

Akamas might collect anonymized usage information on running optimizations. Collection and tracking are disabled by default and can be manually enabled.

Docker installation

External tracking is managed through the following environment variables:

• AKAMAS_TRACKER_URL: the target URL for all tracking info.

• AKAMAS_TRACKING_OPT_OUT: when set to 1, disables anonymous data collection.

Tracking for a running instance can be enabled by editing the AKAMAS_TRACKING_OPT_OUT variable in the docker-compose.yaml file.

To enable tracking set the variable to the following value:

AKAMAS_TRACKING_OPT_OUT=0

Then issue the command:

docker compose up -d

Kubernetes installation

External tracking is managed through the field trackingOptOut in the Values file. To enable tracking set trackingOptOut to 0 as in the following example and upgrade the installation:

awsAccessKeyId: "YOUR_ACCESSKEY_ID"
awsSecretAccessKey: "YOUR_SECRET_ACCESS_KEY"

trackingOptOut: 0

Akamas allows dumping log entries from a specific service, workspace, workflow, study, trial, and experiment, for a specific timeframe and at different log levels.

Akamas CLI for logs

Akamas logs can be dumped via the following CLI command:

akamas log

This command provides many filters which can be retrieved with the following command:

akamas log --help

which should return

Usage: akamas log [OPTIONS] [MESSAGE]

  Show Akamas logs

Options:
  -d, --debug                     Show extended error messages if present.
  --page-size INTEGER             Number of log lines to be retrieved NOTE:
                                  This argument is mutually exclusive with
                                  arguments: [dump, no_pagination].
  --no-pagination                 Disable pagination and print all logs NOTE:
                                  This argument is mutually exclusive with
                                  arguments: [dump, page_size].
  --dump                          Print the logs without pagination and
                                  formatting NOTE: This argument is mutually
                                  exclusive with arguments: [page_size,
                                  no_pagination].
  -f, --from [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S|%Y-%m-%dT%H:%M:%S.%f|%Y-%m-%d %H:%M:%S.%f|[-]nw|[-]nd|[-]nh|[-]nm|[-]ns]
                                  The start timestamp of the logs
  -t, --to [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S|%Y-%m-%dT%H:%M:%S.%f|%Y-%m-%d %H:%M:%S.%f|[-]nw|[-]nd|[-]nh|[-]nm|[-]ns]
                                  The end timestamp of the logs
  -s, --study TEXT                UUID or name of the Study
  -e, --exp INTEGER               Number of the experiment
  --trial INTEGER                 Number of the trial
  -y, --system TEXT               UUID or name of the System
  -W, --workflow TEXT             UUID or name of the Workflow
  -l, --log-level TEXT            Log level
  -S, --service TEXT              Akamas service
  --without-metadata              Hide metadata
  --sorting [ASC|DESC]            Sorting order of the timestamps
  -ws, --workspace TEXT           UUID or name of the Workspace to visualize.
                                  When empty, system logs will be returned
                                  instead
  --help                          Show this message and exit.

For example, to get the list of the most recent Akamas errors:

akamas log -l ERROR

which should return something similar to:

       timestamp                         system                  provider    service                                                                                   message
==============================================================================================================================================================================================================================================================
2022-05-02T15:51:26.88    -                                      -          airflow     Task failed with exception
2022-05-02T15:51:26.899   -                                      -          airflow     Failed to execute job 2 for task Akamas_LogCurator_Task
2022-05-02T15:56:29.195   -                                      -          airflow     Task failed with exception
2022-05-02T15:56:29.215   -                                      -          airflow     Failed to execute job 3 for task Akamas_LogCurator_Task
2022-05-02T16:01:55.587   -                                      -          license     2022-05-02 16:01:47.426 ERROR 1 --- [           main] c.a.m.utils.rest.RestHandlers            :  has failed with returning a response:
                                                                                        {"httpStatus":400,"timestamp":"2022-05-02T16:01:47.413638","error":"Bad Request","message":"The following metrics: 'spark.spark_application_duration' were not found
                                                                                        in any of the components of the system 'analytics_cluster'","path":null}
2022-05-02T16:01:55.587   -                                      -          license     2022-05-02 16:01:47.434 ERROR 1 --- [           main] c.a.m.MigrationApplication               : Unable to complete operation. Mode: RESTORE. Cause: A request to a
                                                                                        downstream service CampaignService has failed: 400 : [{"httpStatus":400,"timestamp":"2022-05-02T16:01:47.413638","error":"Bad Request","message":"The following
                                                                                        metrics: 'spark.spark_application_duration' were not found in any of the components of the system 'analytics_cluster'","path":null}]
2022-05-02T16:01:55.678   -                                      -          license     2022-05-02 16:01:47.434 ERROR 1 --- [           main] c.a.m.MigrationApplication               : Unable to complete operation. Mode: RESTORE. Cause: A request to a
                                                                                        downstream service CampaignService has failed: 400 : [{"httpStatus":400,"timestamp":"2022-05-02T16:01:47.413638","error":"Bad Request","message":"The following
                                                                                        metrics: 'spark.spark_application_duration' were not found in any of the components of the system 'analytics_cluster'","path":null}]
2022-05-02T16:01:55.678   -                                      -          license     2022-05-02 16:01:47.426 ERROR 1 --- [           main] c.a.m.utils.rest.RestHandlers            :  has failed with returning a response:
                                                                                        {"httpStatus":400,"timestamp":"2022-05-02T16:01:47.413638","error":"Bad Request","message":"The following metrics: 'spark.spark_application_duration' were not found
                                                                                        in any of the components of the system 'analytics_cluster'","path":null}
2022-05-02T16:12:10.261   -                                      -          license     2022-05-02 16:05:53.209 ERROR 1 --- [           main] c.a.m.services.CampaignService           : de9f5ff9-418e-4e25-ae2c-12fc8e72cafc
2022-05-02T16:32:07.216   -                                      -          license     2022-05-02 16:31:37.330 ERROR 1 --- [           main] c.a.m.services.CampaignService           : 06c4b858-8353-429c-bacd-0cc56cc44634
2022-05-02T16:38:18.522   -                                      -          campaign    Internal Server Error: Object of class [com.akamas.campaign_service.entities.campaign.experiment.Experiment] with identifier
                                                                                        [ExperimentIdentifier(workspace=ac8481d3-d031-4b6a-8ae9-c7b366f027e8, study=de9f5ff9-418e-4e25-ae2c-12fc8e72cafc, id=2)]: optimistic locking failed; nested exception
                                                                                        is org.hibernate.StaleObjectStateException: Row was updated or deleted by another transaction (or unsaved-value mapping was incorrect) :
                                                                                        [com.akamas.campaign_service.entities.campaign.experiment.Experiment#ExperimentIdentifier(workspace=ac8481d3-d031-4b6a-8ae9-c7b366f027e8,
                                                                                        study=de9f5ff9-418e-4e25-ae2c-12fc8e72cafc, id=2)]

Viewing platform logs

By default akamas cli only shows logs of the current workspace. In order to see platform logs for events such as installation or optimization packs or telemetry providers you can specify the -ws option with an empty workspace name such as:

akamas logs -ws ' -S license

Running Akamas' studies requires a valid license.

To install a license get in touch with Akamas Customer Service to receive:

• the Akamas license file

• your "customer name" to configure in the variable AKAMAS_CUSTOMER for Docker installations or akamasCustomer for Kubernetes installations

• the URL to configure in the AKAMAS_BASE_URL variable for Docker installations

• login credentials

Once you have this information, you can issue the following commands:

cd <your bundle files location>
akamas install license <license file you have been provided>

kubectl get secret -n <NAMESPACE> akamas-admin-credentials -o go-template='{{.data.password | base64decode}}'

The following sections describe the procedure to upgrade your Akamas instance.

Checking Akamas services

To check the status of the Akams services please run akamas status -d to identify which service is not able to start up correctly

Here is an example of output:

Checking Akamas services on http://localhost:8000
 service	 status
=========================
analyzer       	UP
campaign       	UP
metrics        	UP
optimizer      	UP
orchestrator   	UP
system         	UP
telemetry      	UP
license        	UP
log            	UP
users          	UP
OK

Akamas offers, as an additional container, a toolbox that contains the Akamas CLI executable, along with some other useful command-line tools such as kubectl, Helm, vim, docker cli, jq, yq, git, gzip, zip, OpenSSH, ping, cURL, and wget. It can be executed along akamas services, in the same network, for docker-compose installation, or in the akamas namespace for Kubernetes installations.

This toolbox aims to:

• allow users to interact with Akamas without the need to install Akamas CLI on their systems

• provide the Akamas' workflows with an environment where to run scripts and persist artifacts when no other options (e.g. a dedicated host) are available

Docker compose installation

By setting the following options in the .env file, you can configure your toolbox by enabling SSH password authentication (only key-based authentication will be available otherwise) and by setting a login password:

ALLOW_PASSWORD=true
CUSTOM_PASSWORD=yourPassword

To start the toolbox container just issue the following command:

docker compose --profile toolbox up -d

If you want to keep the toolbox running also after a complete restart you can also add the following line to your .env file: COMPOSE_PROFILES=toolbox

Accessing the toolbox on Docker

To access the toolbox on docker you can issue the following command:

docker exec -it toolbox bash

You will be provided with a shell inside the toolbox where you can interact with Akamas. Please read the work folder section below for more information on how to persist scripts and data on the toolbox upon restart and upgrades.

Kubernetes installation

Follow the usual guide for installing Akamas on Kubernetes but make sure to override the following variable (its default value is false) in your akamas.yaml file or in the file values-files/my-values.yaml (can be created if missing):

Follow the usual guide for installing Akamas on Kubernetes, adding the following variables to the values file:

toolbox:
  enabled: true
  sshPassword:
    # enable SSH password authentication. If 'false', only key-based access
    # will be allowed
    enabled: false
    # configure the password for the toolbox user. If not provided, an
    # autogenerated password will be used
    override:
  # Optionally you can also specify custom resource limits
  resources:
    limits:
      cpu: 300m
      memory: 300Mi
    requests:
      cpu: 100m
      memory: 300Mi

Then, you can launch the usual helm upgrade --install ... command to run the pod, as described in the#start-the-installation (online) or #start-the-installation (offline) sections.

Service Account

By default, the toolbox uses a dedicated service account to allow for more granularity and control over permissions.

The service account will be created automatically upon first installation. If you need to use an existing service account you can specify its configuration in the values file using the following snippet.

toolboox:
 # extra lines in between #
 serviceAccount:
    create: true      # Automatically create the SA if it does not already exist
    name: toolbox     # Name of the SA to use for the toolbox   

Accessing the toolbox on Kubernetes

When it's deployed to Kubernetes, you may access this toolbox in two ways:

• via kubectl

• via SSH command

Kubectl access

Accessing is as simple as:

kubectl exec -it deployment/toolbox -- bash

SSH access

For this type of access, you need to retrieve the SSH login password (if enabled) or key. To fetch them, run the following commands:

# Get the password
kubectl exec deployment/toolbox -- cat /home/akamas/password
# Get the key
kubectl exec deployment/toolbox -- cat /home/akamas/.ssh/id_rsa

With this info, you can leverage the toolbox to run commands in your workflows, like in the following example:

name: hello-workflow
tasks:
  - name: Say Hello
    operator: Executor
    arguments:
      command: echo 'Hello Akamas'
      host:
        hostname: toolbox
        username: akamas
        password: d48020ab71be6a07

You can also access the toolbox by port-forwarding from your local machine (on port 2222 in our example). Run the following kubectl command:

kubectl port-forward service/toolbox 2222:22

On another terminal, run:

ssh akamas@localhost -p 2222

and answer yes to the question, then insert the akamas password to successfully SSH access the toolbox (see example below):

$ ssh akamas@localhost -p 2222
The authenticity of host '[localhost]:2222 ([127.0.0.1]:2222)' can't be established.
ED25519 key fingerprint is SHA256:34GXnmRz1YjWr2TTpUpJmRoHYck0NzeAxni2L857Exs.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '[localhost]:2222' (ED25519) to the list of known hosts.
akamas@localhost's password:
Welcome to Ubuntu 20.04.6 LTS (GNU/Linux 5.10.178-162.673.amzn2.x86_64 x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage

This system has been minimized by removing packages and content that are
not required on a system that users do not log into.

To restore this content, you can run the 'unminimize' command.

The programs included with the Ubuntu system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Ubuntu comes with ABSOLUTELY NO WARRANTY, to the extent permitted by
applicable law.

akamas@toolbox-6dd8b7f898-8xwzf:~$

Work directory

A typical kubernetes scenario is Akamas running from inside a namespace and a customer application running from inside another namespace. In such a scenario you will probably need to create an Akamas workflow (running from the akamas namespace) that applies a new configuration on the customer application (running in the customer namespace) then Akamas collects new metrics for a period of time and then calculates a new configuration based on the score of the previous configuration.

What follows is a typical workflow example that:

• uses a FileConfigurator to create a new helm file that applies the new configuration computed by Akamas on a single service named adservice.FileConfigurator recreates a new adservice.yaml file by using the template adservice.yaml.templ. Just make sure that adservice.yaml.templ contains namespace: boutique (the customer namespace, in our example)

• uses an Executor that launches kubectl apply with the new helm file adservice.yaml you just saved to apply the new configuration

• uses another Executor to wait for the new configuration to be rolled out by launching kubectl rollout status

• waits for half an hour to observe the changes in metrics

If you need to store Akamas artifacts, scripts, or any other file that requires persistence, you can use the /work directory, which persists across restarts. This is the default working directory at login time.

To configure an external identity provider you first need to access the Keycloak administration console. Follow the instructions in .

In the akamas realm, navigate to the Identity providers section.

From here on, the steps required to proceed with the configuration vary depending on the provider you are integrating with. Select yours from the guides below:

In case you need to limit the count of user session logins for this provider, follow this guide

The Keycloak administration console is exposed on the /auth page of your installation; for example, https://app.akamas.io/auth.

Now log into the Administration Console using the admin user. The password for such a user can be retrieved in different ways, depending on the installation method:

• Kubernetes. A custom password can be specified during the installation by providing a value keycloak.adminPassword in the helm chart. If this value was left unspecified, you can retrieve the auto-generated password with the following command:

Note that you might need to provide the namespace in which Akamas has been installed using the flag -n namespace

• Docker.

  A custom password can be specified during the installation by providing a value for the variable KEYCLOAK_ADMIN_PASSWORD in the environment or the docker-compose file. if during the installation you didn't specify the value, you can retrieve the auto-generated password with the following command:

Akamas realm

Once logged in, select the akamas realm from the dropdown menu and navigate to the Identity providers section.

The following guide uses the same chart repository and helm release names. Before starting the upgrade, you may find it helpful to look at the section Useful Commands.

Online

Start by updating the local chart repository:

helm repo update akamas

Start online upgrade

Ensure your kubectl configuration points to the namespace where Akamas is installed or specify it with the --namespace parameter. To start the upgrade to the latest version:

helm upgrade akamas akamas/akamas

You can specify an older chart version using the --version parameter. Refer to Listing Akamas chart versions for discovering the published chart versions.

If you need to specify a different Values file from the latest installation, start from the last one used. If you do not have it stored, it can be retrieved as specified in Retrieving the Values file.

Offline

Before starting the upgrade, check Configure the registry to add new docker images.

If you can not reach helm.akamas.io from the machine where the installation will be run, run the following commands from another client (see the installation guide for a full explanation).

helm repo update akamas
helm pull akamas/akamas

Then, you can start the upgrade in the same way as for the Online version. If you are using the downloaded chart package, transfer the package and replace akamas/akamas with the downloaded tgz archive.

Useful commands

Listing Akamas chart versions

Akamas' versions can be listed by running the following command:

helm search repo akamas/akamas --versions

It is always suggested to install and upgrade to the latest chart version. The App Version field refers to the Akamas version. To ease the release process multiple chart versions may refer to the same App Version.

Retrieving the Values file

In case you do not have access to the Values file used during the last installation/upgrade, you can still get it by running:

helm get values akamas -o yaml > akamas-values.yaml

Such a command is useful only if you need to change some of the parameters during the upgrade, otherwise the old Values file is kept by Helm.

Akamas server backup

The process of backing up an Akamas server can be divided in two parts, that is system backup and otherwise start Akamas. Backup can be performed in any way you see fit: they’re just regular files so you can use any backup tool.

System backup

System services are hosted on AWS ECR repo so the only thing that fully defines a working Akamas application is the docker-compose.yml file. Performing a backup of the Akamas application is as simple as copying this single file to your backup location. you may schedule any script that performs this weekly or at any frequency you see fit

User data backup

You may list all existing Akamas studies via the Akamas CLI command:

akamas list study

Then you can export all existing studies one by one via the CLI command

akamas export study <UUID>

where UUID is the UUID of a single study. This command exports into a single archive file (tar.gz). These archive files can be backed up to your favorite backup folder.

Akamas server recovery

Akamas server recovery involves recovering the system backup, restarting the Akamas service then re-importing the studies.

System Restore

To restore the system you must recover the original docker-compose.yml then launch the command

docker compose up &

from the folder where you placed this YAML file and then wait for the system to come up, by checking it with the command

akamas status -d

User data restore

All studies can be re-imported singularly with the CLI command (referring to the correct pathname of the archive):

akamas import study archive.tgz

This page provides a walkthrough to configure Google as an external identity provider for Akamas users.

Configure the App registration

To integrate Akamas with your Google Workspace, you first need a project with a dedicated OAuth client. Log in to your Google Developer Console, and navigate to the "Credentials" page of "API & Services".

Configure the Consent Screen

If the "Credentials" page displays a warning box reminding you to configure the consent screen, you first need to create an app. Click the enclosed button to start the wizard.

Follow the wizard to configure the consent screen according to your company's policies. For more details, refer to Configure the OAuth consent screen on the official documentation.

Once the configuration is complete, return to the "Credentials" page.

Create the OAuth client

Click the "Create Credentials" link on top, and select "OAuth Client ID".

Configure the client as follows:

• "Application Type": select "Web application"

• "Name": populate with the name of the new client

• "Authorized redirect URIs": leave it blank, as you will fill it in a later step

Once you click "Create" the console will show you a confirmation pop-up containing the client's configuration. Note the Client ID and the Client Secret.

Create the Identity provider

Access the Identity providers section for the "akamas" realm in the Keycloak administration console, as described on the page Configure an external identity provider, and select "Google" to start creating the new provider.

Configure the following fields using the values from the OAuth client you just created:

• "Client ID": fill in the id of the client

• "Client Secret": fill in the secret of the client

To complete the configuration, note the "Redirect URI" value and click "Add".

Complete the app registration

Back to the Google Developer Console, on the "Credentials" page, open the newly created client and add the URI from the previous step to the list of "Authorized redirect URIs".

Configure the default Akamas roles

The final setup step is to instruct Akamas to associate the default roles with the users automatically. This way, users will be added to the default workspace with read and write permissions the first time they log in.

On the Keycloak console, on the provider's details page, navigate to "Mappers":

Now, add the following configurations.

User role

• Name: User role

• Mapper type: Hardcoded role

• Role: USER

Default Workspace Read

• Name: Default Workspace Read

• Mapper type: Hardcoded role

• Role: WS_ac8481d3-d031-4b6a-8ae9-c7b366f027e8_R

Default Workspace Write

• Name: Default Workspace Write

• Mapper type: Hardcoded role

• Role: WS_ac8481d3-d031-4b6a-8ae9-c7b366f027e8_W

Test the integration

Visit the installation's login page to check that the new authentication method is displayed and works correctly.

If you have configured ore or more Identity Providers, you can also limit the number of concurrent user sessions. First, access the Keycloak admin console with the instructions provided on the page Accessing Keycloak admin console.

Click on the "create flow" button, provide a name, and then select the flow type "Basic Flow" and click on create.

Now click on "add execution"

A dialog pops up with a list of possible actions, filter the results with the limit keyword.

Select "User session count limiter" and click on "Add".

Set this new step as "Required" from the drop-down then click on the cog icon to edit its properties

Give it a meaningful alias and type in the maximum concurrent session value you desire. Select the behavior "Deny new session" from the drop-down list. Type in a valid message in the textbox "Optional custom error message" and click on "Save".

Now go to the identity provider page and click on the Identity provider you want to limit.

Scroll down to the bottom, click on the "Post login flow" dropdown, and select the new step you just created then click on the "Save" button.

This page provides a walkthrough to configure Azure Active Directory as an external identity provider for Akamas users.

Configure the App registration

To integrate Akamas with your Active Directory, you first need a dedicated App registration in your Azure Organization. If you want to use an existing registration, skip to Get the client configuration; to create a new one, refer to the following sub-section.

Create a new App registration

To create a new registration, navigate to "App registrations" in your Azure portal and select "New registration" and specify the following:

• a name for the application

• the account type that best suits your use case

Complete the creation by clicking on "Register".

Get the client configuration

On the "Overview" page of the application, note the following values:

• Application (client) ID

• OpenID Connect metadata document (found in the "Endpoints" side panel)

Furthermore, in the "Certificates & secrets" section, create a new Client secret and note its value.

With these values, we can now complete the provider configuration in the Keycloak console.

Create the Identity provider

Access the Identity providers section for the "akamas" realm in the Keycloak administration console, as described on the page Configure an external identity provider, and select "OpenID Connect v1.0" to start creating the new provider.

Here, specify an alias for the client ("microsoft" in our case) and optionally the display name used in the login page ("Microsoft").

In the "OpenID Connect settings" section, configure the following fields using the values from the app registration in the Azure portal:

• "Discovery endpoint": populate with the URL of the "OpenID Connect metadata document". This box should become green upon successful validation.

• "Client ID": populate with the "Application (client) ID" from the app's overview page

• "Client Secret": populate with the value of the generated secret

Complete the configuration by clicking "Add". You will land on the detail page of the new provider: here, copy the value of the redirect URI.

Complete the app registration

Back to the app registration in the Azure portal, navigate to the "Authentication" section. Add the "Web" platform (if not already present).

Finally, add to the list of redirect URIs the one from the previous step.

You have now configured Akamas to delegate to Azure your users' login.

Configure the default Akamas roles

The final setup step is to instruct Akamas to associate the default roles with the users automatically. This way, users will be added to the default workspace with read and write permissions the first time they log in.

On the Keycloak console, on the provider's details page, navigate to "Mappers":

Now, add the following configurations.

User role

• Name: User role

• Mapper type: Hardcoded role

• Role: USER

Default Workspace Read

• Name: Default Workspace Read

• Mapper type: Hardcoded role

• Role: WS_ac8481d3-d031-4b6a-8ae9-c7b366f027e8_R

Default Workspace Write

• Name: Default Workspace Write

• Mapper type: Hardcoded role

• Role: WS_ac8481d3-d031-4b6a-8ae9-c7b366f027e8_W

Test the integration

Visit the installation's login page to check that the new authentication method is displayed and works correctly.

First, access the Keycloak admin console with the instructions provided on the page Accessing Keycloak admin console.

On the Authentication page, select the "direct grant flow" and scroll the "User session count limiter" entry.

On the row "User session count limiter", click on the cog icon. From here you can choose the maximum concurrent sessions for each user, and the behavior when the maximum number is reached. Select "Deny new session" to deny new accesses. if previous sessions are not properly terminated, you may need to delete them from the Keycloak console under the Users section.

Creating a system is the first step in optimizing your application.

A system is a representation of your application. It might be a complete representation of different layers, a single microservice, a batch job, or any IT system that you want to optimize.

A system can be used to fully model an application and then run multiple optimization initiatives or contain just the elements that are used for a specific optimization study.

The system is identified by a name, which in our example is "Online Boutique", and can be extended with a description to make it easily recognizable.

Components

The core elements of a system are the components. A component represents the fundamental element of an IT system, often composed of various layers or entities. It serves as a black-box definition of an entity involved in optimization, eliminating the need for intricate details in modeling.

A component comprises the following properties:

• Name: A distinct identifier within the context of the system.

• Description: A clarification of the component's purpose or function.

• Component type: An identification of the underlying technology or technology stack of the component.

• Properties: A set of additional properties that hold information about the component's configuration or telemetry (e.g. the IP used to reach an API or the username to connect to a server via SSH).

Akamas allows users to model their IT systems without the need to focus on technological aspects by providing several out-of-the-box component types to support system and component modeling.

Component types are platform entities (i.e.: shared among all the users) that contain key information about specific technologies such as parameters that can be tuned and key metrics.

Akamas includes off-the-shelf component types for the most popular technologies such as Containers, Linux Hosts, AWS EC2 instances, Web Applications, Spark, and runtimes such as JVM, Node, and Go.

Creating the Online Boutique system

Recalling our example of the Online Boutique application, we decided, for the moment, to model just the elements that are included in the optimization initiative. We have also decided not to model the entire Kubernetes cluster as we are not interested in optimizing and monitoring it at this stage.

We have mapped the JVM and the Pod to the respective component types and mapped the Kubernetes service to the Web Application component type. You can read more about these component types in their documentation reference.

To model our system we used the component types coming from these optimization packs:

The following picture shows our choice of components starting from the architectural diagram.

Creating the system with the CLI

To create this system in Akamas you can use the following YAML file.

Create the file system.yaml and run the following command.

Now you can start adding components. The following three YAML files represent the three components of our Online Boutique system.

Create the files and run the following command for each file.

Note that, since components are bound to a specific system, we need to provide as an argument to the creation command also the name of the system Online Boutique that we created a few moments ago.

As a security measure, Akamas lets you enforce a limit on the number of concurrent sessions per user, by default, this is set to terminate the oldest sessions and keep only a restricted number alive. If you wish to change the behavior limit, you can do so by configuring the Akamas realm in Keycloak.

The section explains how to properly configure users stored in Keycloak. The page explains how to apply the same limit for users managed by an Identity Provider.

To optimize a new application on Akamas you have to follow four steps shown in the following picture and described in the next sections by means of a simple example.

As depicted in the picture above, to optimize a new application you should:

• Create a system that models the key parts of your application (e.g. containers, runtimes, APIs) that will be interested in the optimization initiative.

• Set up the integration with a monitoring tool via telemetry providers so that Akamas can gather metrics about the performance of your application.

• Create a workflow that allows Akamas to configure your application (e.g. write a configuration file, relaunch a process).

• Define the optimization study according to your goal and SLOs so that Akamas knows what you want to achieve.

These steps relate to how Akamas integrates with your environment and apply to both offline and live optimization studies.

Example Application