Comment on page
Management container/pod
Akamas provides a Management Container (also referred to as Management Pod, when deployed on Kubernetes) that contains 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, wget, psql, and k9s. It runs in the same network as akamas services, for docker-compose installation, or in the akamas namespace for Kubernetes installations.
This management container aims to:
- allowing users to interact with Akamas without the need to install Akamas CLI on their systems
- providing the Akamas' workflows with an environment where to run scripts and persist artifacts when no other options (e.g. a dedicated host) are available
Just add the following block of code inside the
services:
block of your Akamas docker-compose.yml after editing the following environment variables:ALLOW_PASSWORD
: when set totrue
, enable SSH password authenticationCUSTOM_PASSWORD
: specify the login password. If not provided, a random one will be generated
management-container:
image: 485790562880.dkr.ecr.us-east-2.amazonaws.com/akamas/management-container:1.2.2
container_name: management-container
environment:
- BASH_ENV=/home/akamas/.bashrc
- ALLOW_PASSWORD=true
- CUSTOM_PASSWORD=your_password
expose:
- 22
volumes:
- /var/run/docker.sock:/var/run/docker.sock
networks:
- akamas
restart: unless-stopped
Launch
docker compose up -d
as described in Start Akamas (online) or Run installation (offline) to run the management container.Follow the usual guide for installing Akamas on Kubernetes, adding the following variables to your
akamas.yaml
file:managementPod:
enabled: true
sshPassword:
# enable SSH password authentication. If 'false', only key-based access
# will be allowed
enabled: false
# configure the password for the management-pod user. If not provided, an
# autogenerated password will be used
override:
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.When it's deployed to Kubernetes, you may access this management pod in two ways:
- via
kubectl
- via SSH command
NOTE: both methods require
kubectl
to be installed and configured for this cluster.Accessing is as simple as:
kubectl exec -it deploy/management-pod -- bash
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 deploy/management-pod -- cat /home/akamas/password
# Get the key
kubectl exec deploy/management-pod -- cat /home/akamas/.ssh/id_rsa
At this point, you should launch this command to port-forward the management port to your local terminal (number 2222 can be any other number: it should be an unused port on your machine):
kubectl port-forward service/management-pod 2222:22 &
then, on another terminal, you may launch:
ssh akamas@localhost -p 2222
and answer
yes
to the question, then insert the akamas
password to successfully SSH access the management pod (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@management-pod-6dd8b7f898-8xwzf:~$
If you need to store Akamas artifacts, scripts, or any other file that needs persistence, you can use the
/work
directory, which persists across restarts. This is the default folder at login time. It contains the akamas_password
file mentioned above, the Kubernetes and SSH configuration files, which will be symlinked to your home folder.When running Akamas from a kubernetes cluster, the suggested patterns are:
- to use the management pod to store all YAML resource files needed to create all systems, components, telemetry instances, workflows, and studies. These files should be saved in a subfolder inside the persisted
/work
folder. - use the management pod as a worker machine whenever you need to connect to an internal machine in the same Kubernetes namespace to perform some tasks. The important thing to note is that to successfully connect to the management-pod from other resources such as workflow tasks or telemetry instances, you must use the hostname
management-pod
. This is crucial: it's not the pod name such asmanagement-pod-6dd8b7f898-8xwzf
. Just usehostname: management-pod
or the workflow/telemetry instance will fail.
A typical kubernetes scenario is Akamas running in a namespace different from the customer application. 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 while and then calculates a new configuration based on the score of the previous configuration.
What follows is a typical workflow example:
- 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 newadservice.yaml
file by using the templateadservice.yaml.templ
. Just make sure that adservice.yaml.templ containsnamespace: boutique
(the customer namespace, in our example) - uses an Executor that launches
kubectl apply
with the new helm fileadservice.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
name: adservice
tasks:
- name: configure
operator: FileConfigurator
arguments:
source:
hostname: management-pod
username: akamas
password: <your-management-pod-password>
# instead of password you can an SSH key file such as /work/akamas/key.rsa
# key: <your-key-file>
path: adservice.yaml.templ
target:
hostname: management-pod
username: akamas
password: <your-management-pod-password>
# instead of password you can an SSH key file such as /work/akamas/key.rsa
# key: <your-key-file>
path: adservice.yaml
- name: apply
operator: Executor
arguments:
timeout: 5m
host:
hostname: management-pod
username: akamas
password: <your-management-pod-password>
# instead of password you can an SSH key file such as /work/akamas/key.rsa
# key: <your-key-file>
command: kubectl apply -f adservice.yaml
- name: verify
operator: Executor
arguments:
timeout: 5m
host:
hostname: management-pod
username: akamas
password: <your-management-pod-password>
# instead of password you can an SSH key file such as /work/akamas/key.rsa
# key: <your-key-file>
command: kubectl rollout status --timeout=5m deployment/adservice -n boutique;
- name: observe
operator: Sleep
arguments:
seconds: 1800
Similarly to the workflow example above, if your telemetry instance needs to connect to some internal machine to create/process some local file (this may happen with a CSV provider, for example), you should use the address of the management pod (which is exactly
management-pod
), authType password
and provide akamas password in auth
field. See example below:# CSV Telemetry Provider Instance
provider: CSV File
config:
address: management-pod
authType: password
username: akamas
auth: <your-management-pod-password>
remoteFilePattern: /work/monitoring/result-*.csv
componentColumn: COMPONENT
timestampColumn: TS
timestampFormat: YYYY-MM-dd'T'HH:mm:ss
metrics:
- metric: cpu_util
datasourceMetric: user%
Last modified 8d ago