Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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 logs can be dumped via the following CLI command:
This command provides many filters which can be retrieved with the following command:
which should return
For example, to get the list of the most recent Akamas errors:
which should return something similar to:
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:
If you plan to upgrade your Akamas instance, please verify the upgrade path with the Akamas support team. To ensure rollback in case of upgrade failure, it is suggested to backup your studies (see section ).
To start with the upgrade, on the Akamas server navigate to the same folder where the docker-compose.yml and .env file are stored (see section ). Now you can download the latest version compose file:
You can point to a specific version. As an example to download the artifact for version 3.2.2:
If the old docker-compose has been changed and it is still needed in the newer Akamas version, make sure to migrate such changes from docker-compose.yml.bak to the docker-compose.yml .
Ensure your .env file is up to date with the required variables, by comparing your version with the one at .
Then log in to AWS with the following command:
If the login succeeds, then you can start the upgrade by running:
Wait for a few minutes and check the Akamas services are running the command:
The expected output should be like the following (repeat the command after a minute or two if the last line is not "OK" as expected):
If you plan to upgrade your Akamas instance, please verify the upgrade path with the Akamas support team. To ensure rollback in case of upgrade failure, it is suggested to back up your studies (see 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 .
Start by updating the local chart repository:
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:
You can specify an older chart version using the --version parameter. Refer to 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 .
Before starting the upgrade, check 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 for a full explanation).
Akamas' versions can be listed by running the following command:
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.
In case you do not have access to the Values file used during the last installation/upgrade, you can still get it by running:
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.
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 following sections describe the procedure to upgrade your Akamas instance.
If you plan to upgrade your Akamas instance, please verify the upgrade path with the Akamas support team. To ensure rollback in case of upgrade failure, it is suggested to backup your studies (see section ).
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:
Once logged in, select the akamas realm from the dropdown menu and navigate to the Identity providers section.
Akamas stores all its logs into an internal Elasticsearch instance: some of these logs are reported to the user in the GUI in order to ease the monitoring of workflow executions, while other logs are only accessible via CLI and are mostly used to provide more context and information to support requests.
Audit access can be performed by using the CLI in order to extract logs related to UI or API access. For instance, to extract audit logs from the last hour use the following commands:
UI Logs
API Logs
Notice: to visualize the system logs unrelated to the execution of workflows bound to workspaces, you need an account with administrative privileges.
Akamas can be configured to store access logs into files to ease the integration with external logging systems. Enabled this feature ensures that, when the user interacts with the UI or the API, Akamas will report detailed access logs on the internal database and in a file in a dedicated log folder. To ease log rolling and management every day, Akamas will create a new file named according to the pattern access-%{+YYYY-MM-dd}.log.
To enable this feature you should:
Create a logs folder next to the Akamas docker-compose.yml file
Edit the docker-compose.yml file by modifying the line FILE_LOG: "false" to FILE_LOG: "true"
If Akamas is already running issue the following command
otherwise, start Akamas first.
To enable this feature you should go to your Akamas chart folder, edit your values file (typically values-flies/my-values.yaml), and add the following section (if a logstash: section is already present, add the new values to it):
then perform installation or update as usual with:
in this specific case, the logs will be stored in a dedicated volume attached to the logstash pod, under the folder /akamas/logs/.
To list them you can use the command:
To read a logfile you can use the command (replace LOGFILENAME.log with the actual name):
To copy them to your local machine you can use:
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 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
You may list all existing Akamas studies via the Akamas CLI command:
Then you can export all existing studies one by one via the CLI command
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 involves recovering the system backup, restarting the Akamas service then re-importing the studies.
To restore the system you must recover the original docker-compose.yml then launch the command
from the folder where you placed this YAML file and then wait for the system to come up, by checking it with the command
All studies can be re-imported singularly with the CLI command (referring to the correct pathname of the archive):
This section is a collection of different topics related to how to manage the Akamas Server.
This section covers some topics on how to manage the Akamas Server:
Then, you can start the upgrade in the same way as for the . If you are using the downloaded chart package, transfer the package and replace akamas/akamas with the downloaded tgz archive.
This documentation aims to guide users through common troubleshooting steps and how to retrieve essential support information to diagnose and resolve issues effectively.
When encountering issues with Akamas, gathering detailed support information is crucial for diagnosing and solving problems. This information includes platform logs data from the Java Flight Recorder (JFR), which provide insights into the system's operations and the nature of any encountered issues.
Platform logs in Akamas offer a comprehensive view of all system activities, errors, and operational messages. These logs are essential for a deep dive into the specifics of any encountered issues. To retrieve platform logs you can issue the following command from the akamas cli.
Note that the --from argument allows you to specify a timeframe for the log extraction. If you know the issue have been occurred in a specific time frame you can limit the extraction to that period.
The logs will be written to a file named log.out which can be shared with Akamas support agents for further investigations.
Akamas natively integrates Java Flight Recorder, a powerful tool for monitoring and recording the behavior of the Java runtime used to execute core Akamas services. Depending on the installation method (Docker or Kubernetes) accessing the JFR data requires different steps.
When running Akamas on Docker, JFR data is stored in a dedicated volume on the host. The volume is named perf. Each service writes its performance data in a dedicated subfolder of that volume.
Use the following command on the Akamas host to extract the data of a specific service:
The command will move all required files to a local folder named perf which can be shared with the support team.
To extract the data for all services issue the following command
When running in a Kubernetes cluster, each service writes its performance data in a dedicated volume backed by a persistent volume claim to make it resilient to pod restarts.
To extract the data of a specific service follow these steps:
Identify the name of the pod running the service with the command kubectl get pods | grep <service>
Copy the content of the /perf folder inside the main container of the pod to a local directory with the following command
Here is an example of a complete extraction for the service named campaign
This data can help Akamas support teams or your internal IT department to pinpoint the root cause of problems and identify appropriate solutions.
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 Local Users explains how to properly configure users stored in Keycloak. The page Identity Provider users explains how to apply the same limit for users managed by an Identity Provider.
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 Google as an external identity provider for Akamas users.
You will need a Google account with the privileges required to create app registrations.
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".
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.
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.
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".
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".
If you change the hostname of the Akamas installation, then you will need to update or add the configured redirect URI registration for the integration to work correctly.
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
Visit the installation's login page to check that the new authentication method is displayed and works correctly.
This page provides a walkthrough to configure Azure Active Directory as an external identity provider for Akamas users.
You will need an Azure account with the Application.ReadWrite.All permission, required to create app registrations in your Azure AD tenant.
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.
​​Multiple Akamas instances can share the same app registration. It implies that any AD user added to a registration could access all the associated Akamas instances.
If you need to manage accesses with finer granularity, create a dedicated registration for each Akamas installation.
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".
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.
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.
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.
When changing the hostname of the Akamas installation, you need to update the redirect URI configured in the app registration. Skipping this step will block any login attempt with the following error:
The redirect URI 'https://...' specified in the request does not match the redirect URIS configured for the application '...'.
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
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.
