To interact with your Akamas instance you need the UI and API Gateway to be accessible from outside the cluster. This means you need to expose the ui and kong service respectively (although a minimal configuration only requires exposing the ui service, since it can forward requests to the API Gateway through the path /akapi).

Kubernetes offers different options to expose a service outside of the cluster. The following is a list of the supported ones, with examples of how to configure them to work in your chart release:

• Port Forwarding

• LoadBalancer

• Ingress

• NodePort

Port Forwarding

By default, Akams uses Cluster IPs for its services, which only allow communication inside the cluster. Still, you can leverage Kubectl's port-forward to create a private connection and expose any internal service on your local machine.

This solution is suggested to perform quick tests without the need of exposing the application, or in scenarios where cluster access to the public is not allowed.

To make the Akamas UI accessible on http://localhost:8000, run the following command:

kubectl port-forward service/ui 8000:http

To interact with the Akamas CLI you can use the URL http://localhost:8000/akapi, or expose the kong service in the same way.

Refer to the official kubernetes documentation for more details about port-forwarding.

Load Balancer

Load Balancers expose services outside the cluster. This solution is often used with clusters managed by cloud providers such as Amazon EKS or Google Kubernetes Engine (GKE).

You can expose the Akamas UI through a Load Balancer by adding the snippet below to the akamas.yaml file from the previous section, and re-running the install command to update the configuration.

ui:
  service:
    type: "LoadBalancer"

To get the address of the load balancer run the command:

kubectl get svc ui -o 'custom-columns=NAME:metadata.name,TYPE:spec.type,HOSTNAME:status.loadBalancer.ingress[].hostname'

For more details on Load Balancers refer to the official kubernetes documentation.

Ingress

An Ingress is a Kubernetes object that provides service access, load balancing, and SSL termination to kubernetes services.

You can expose the Akamas UI through an Ingress by adding the snippet below to the akamas.yaml file from the previous section. After adding to className one of the ingress controllers available on the cluster, re-run the install command to update the configuration.

ui:
  ingress:
    enabled: true
    className: "<class-name>"
    hosts:
      - host: "<dns-name>"
        paths:
          - path: /
            pathType: Prefix

You can also configure a certificate on the Ingress: refer to HTTPS configuration section for instructions.

Refer to the official kubernetes documentation for more details on Ingresses.

NodePort

Node Ports make services accessible on specific ports of any node of the cluster.

You can expose the Akamas UI through a NodePort by adding the snippet below to the akamas.yaml file from the previous section, and re-running the install command to update the configuration.

ui:
  service:
    type: "NodePort"
    http:
      nodePort: "30010"

The Akamas UI will be accessible on any cluster node at http://<cluster-node>:30010. You can also omit the http.nodePort field and let Kubernetes automatically select a random port.

Refer to the official kubernetes documentation for more information on Node Ports.

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

• Cluster requirements

• Software requirements

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.

This page describes the requirements that should be fulfilled by the user when installing or managing an Akamas installation on Kubernetes. The software listed 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 to set up the client.

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

Helm

Installing Akamas requires or higher. To check the version run:

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 host running the Elasticsearch pod. 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. \

Kubernetes version

Running Akamas requires a cluster running Kubernetes version 1.23 or higher.

Resources requirements

Akamas can be deployed in three different sizes depending on the number of concurrent optimization studies that will be executed. If you are unsure about which size is appropriate for your environment we suggest you start with the small one and upgrade to bigger ones as you expand the optimization activity to more applications.

The tables below report the required resources both for requests and limits that should be available in the cluster to use Akamas.

Small

The small tier is suited for environments that needs to support up to 10 concurrent optimization studies

Storage requirements

The cluster must provide the definition of a Storage Class so that the application installation can leverage Persistent Volume Claims to dynamically provision the volumes required to persist data.

For more information on this topic refer to Kubernetes' official documentation.

Permissions

To work properly, Akamas needs to manage some resources inside the Namespace. For this reason, it is recommended to run Akamas in a dedicated Namespace.

To manage resources, Akamas uses a ServiceAccount bound to the application's pods, which must be created either manually by the cluster administrator or automatically by the provided Helm chart.

This snippet describes the namespaced required permissions for the service account:

- apiGroups: ["batch"]
  resources:
    - jobs
  verbs: ["get", "list", "create", "delete", "patch", "update"]
- apiGroups: [""]
  resources:
    - configmaps
  verbs: ["get", "list", "create", "delete", "patch", "update"]
- apiGroups: [""]
  resources:
    - pods
  verbs: ["get", "list", "patch", "update", "watch"]
- apiGroups: [""]
  resources:
    - pods/log
  verbs: ["get"]
- apiGroups: [""]
  resources:
    - secrets
  verbs:
    - get
    - create
    - patch

Networking

Networking requirements depend on how users interact with Akamas. Services can be exposed via Ingress, LoadBalancers, NodePorts, or using kubectl as a proxy. Refer to Accessing Akamas for a more detailed description of the available options.

Before starting the installation, make sure the are met.

Create the configuration file

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

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

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

This minimal configuration is enough to have Akamas up and running on your cluster, even though the endpoint will only be accessible through Kubectl's .

The page provides some configuration examples using different types of services: edit the akamas.yaml file using the strategy that best suits your needs, or continue directly with the next sections and configure the endpoints at a later time.

Start the installation

Add the Akamas' repository to the Helm client with the following command:

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

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:

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:

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:

At this point, you should be able to access the Akamas UI on http://localhost:8000 and the Akamas CLI http://localhost:8000/akapi by running Kubectl's port forwarding command:

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 default repository, you need to mirror the required images on a private repository.

The procedure described here leverages your local environment to upload the images, so it requires that Docker is installed and configured to interact with the private registry.

Obtain the Docker images

Get in contact with Akamas Customer Services to get the latest versions of the Akamas artifacts. This will include:

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

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

Upload the Docker images

The offline installation mode requires importing the shipped Docker images into your local environment. Run the following command in the same directory where the tar file is stored:

cd '<IMAGES_ARCHIVE_LOCATION>'
docker image load -i images.tar.gz

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

REGISTRY='<REGISTRY_URL>'
for image in `docker images | awk '/485790562880.dkr.ecr.us-east-2.amazonaws.com/ {print $1 ":" $2}'`; do
  newImage="${image/485790562880.dkr.ecr.us-east-2.amazonaws.com/${REGISTRY}}"
  docker tag ${image} ${newImage}
  docker push ${newImage}
done

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 need to create a file, called akamas.yaml in this guide, containing the mandatory configuration values required to customize your application. The following template contains the minimal set of values 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>

registry: <REGISTRY_URL>
postgresql:
  image:
    registry: <REGISTRY_URL>
elasticsearch:
  image: <REGISTRY_URL>/elasticsearch
kibana:
  image: <REGISTRY_URL>/kibana

This minimal configuration is enough to have Akamas up and running on your cluster, even though the endpoint will only be accessible through Kubectl's port forwarding.

The page Accessing Akamas provides some configuration examples using different types of services: edit the akamas.yaml file using the strategy that better suits your needs, or continue directly with the sections and configure the endpoints at a later time.

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>

Start the installation

From a machine that can reach the endpoint, add the Akamas' repository to the Helm client with the following command:

helm repo add akamas http://helm.akamas.io/charts

If you can not reach helm.akamas.io from the machine where the installation will be run, pull the chart by running:

helm pull akamas/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/akamas

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/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: Wed Apr  5 11:40:19 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 on http://localhost:8000 and the Akamas CLI http://localhost:8000/akapi by running Kubectl's port forwarding command:

kubectl port-forward service/ui 8000:http

Mind that, before logging in, you need to configure the Akamas CLI and install a valid license.

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, and re-run the installation command to update your Helm release.

HTTPS configuration can be set in the Akamas services (UI and Kong) or in the Ingress definition.

Certificate in the Ingress

Declare the certificate secret by adding a tls section to the Ingress definition:

ui:
  ingress:
    enabled: true
    className: "<class-name>"    # ingress class name

    hosts:
      - host: "example.company.com"
        paths:
          - path: /
            pathType: Prefix

    tls:
      - secretName: "<secret name>"  # secret name containing the certificate and key data
        hosts:
          - "example.company.com"

You can apply the same configuration to the kong service to add a certificate to the API Gateway.

For more information regarding the TLS definition refer to the official documentation.

Certificate in the Akamas services

To add a certificate to both the UI and API Gateway you need to generate the akamas.key and akamas.pem files, and create a secret in Akamas' namespace with the following command:

kubectl create secret generic certificate --from-file=akamas.key --from-file=akamas.pem

To complete the update, restart the deployments:

kubectl rollout restart deployment ui kong

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.