Installing the toolbox

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.