Comment on page
Resource management commands
This page describes all commands that allow Akamas resources to be managed with their options (see also common options available for all commands).
Command | Description |
|---|---|
build a resource from a file or directory | |
create a resource from a file | |
delete a resource | |
list a set of resources | |
describe a resource | |
update a resource | |
install a resource from a file | |
uninstall a resource | |
start a study | |
stop a study | |
export a study | |
import a study |
The following table describes the common options available for all commands:
Option | Short option | Type | Description |
|---|---|---|---|
--debug | -d | Flag | Print detailed information in case of errors |
--workspace | -w | String | Overrides the workspace defined in the configuration file when interacting with resources such as systems, workflows and studies |
--help | | Flag | Print command line help |
The Akamas CLI allows using a set of alias or shortcuts for many resources.
Any resource can be specified using either the singular or plural form. Furthermore, the shortcuts listed below are available:
1
component [comp, co, components, cmp]
2
system [systems, sys, sy]
3
component-type [ctype, comp-type, ct, component-types]
4
optimization-pack [optimization-packs, op, opt-pack, opack]
5
metric [metr, metrics, me]
6
parameter [parameters, pa, param, par]
7
study [st, studies, sty]
8
workflow [wf, wkfl, workflows, wo]
9
telemetry-instance [ti, tel-instance, telemetry-instances, tel-inst]
10
telemetry-provider [telemetry-providers, tel-prov, tp, tel-provider]
11
kpi [kpis]
12
workspace [workspaces, ws]
13
trial [tr, trials]
14
user [us, users]
15
license [licenses, lic]
16
experiment [experiments, exp]
17
log [logs]
18
step [steps]
You can print the list of available aliases with the following command
akamas list alias
This command builds either a new optimization pack or a new scaffolding hierarchy.
// build optimization pack
akamas build optimization-pack <folder-with-resource-files>
// build scaffolding
akamas build scaffold <folder-with-resource-files>
In this case, you supply a folder with a specific hierarchy: the needed folders are
metrics, component-types and parameters, and each of them contains a set of yaml resource files listing the supported resources. Then the command akamas build optimization-pack FOLDER_NAME creates a full JSON file with all the optimization pack contents inside it.In this case, you supply two folders: one for variables, named
variables and one for templates named templates. The variables folder must contain one yaml file for each desired output set and the templates folder should hold all generic templates that can contain variable parameters specified in the variables file.This command is available since version 2.8.0 of the cli
For example, the
variables folder could contain two files named test.yaml and prod.yaml. The contents of these files are:test.yaml
study:
name: my study
k8s:
namespace: online-boutique
deployment: adservice
container: server
k8s_deployment: test
prod.yaml
study:
name: Production study
k8s:
namespace: online-boutique-prod
deployment: adservice-prod
container: server-prod
k8s_deployment: prod
Then suppose that the template folder contains some YAML files and one of them the is following file named
template-study.yaml:template-study.yaml
kind: study
name: {{ study.name }}
system: {{ k8s.deployment }}
workflow: {{ k8s.deployment }}
goal:
name: Cost
objective: minimize
function:
formula: (({{ k8s.container }}.container_cpu_limit)/1000)*29 + (((({{ k8s.container }}.container_memory_limit)/1024)/1024)/1024)*3
When launching the command
akamas build scaffold SCAFFOLDING_DIR_NAME/, a new folder outputis created inside SCAFFOLDING_DIR_NAME along with two sub-folders test and prod. Each sub-folder now contains the templates rendered with the values set in the variables files. The akamas create entity command makes it easier to create bulk entities.Create the Akamas resource described in the provided YAML file.
akamas create <resource-type> <resource-file> [<parent-resource-id>|<parent-resource-name>]
You can also use the generic resource type
entity to create most of the resources with a YAML file in a single command. The supported resources are component, system, optimization-pack, study, workflow, telemetry-instance and telemetry-provider. In order to use this feature, adding the kind key is required. Also, the system key must be added when the resource is required to be attached to a system (telemetry instance and system component).For example, to create a new telemetry instance, you should add the following:
kind: telemetry-instance
system: SYSTEM_NAME
to your YAML file, then you can use the
akamas create entity <filename.yaml> command instead of akamas create telemetry-instance <filename.yaml> SYSTEM_NAME.Similarly, to create a new telemetry-provider (which does not need the
system attribute), you just need to specify the kind to your yaml file:kind: telemetry-provider
This also works for optimization packs. For standard optimization packs provided by akamas you need to write a YAML file such as:
kind: optimization-pack
name: OPTIMIZATION_PACK_NAME
If you want to install a custom optimization pack, you can also supply a JSON file. In this case, there is no need to specify the
kind attribute.Finally, if you supply a folder to the command
akamas create entity, it will process all files inside this folder and create all the needed resources. You can, for example, use one of the output folders created by the command akamas build scaffold.Delete an Akamas resource, identified by UUID or name.
akamas delete [options] <resource-type> <resource-id|resource-name> [<parent-resource-id>|<parent-resource-name>]
with the following options:
Option | Short option | Type | Description |
|---|---|---|---|
--force | -f | Flag | Force the deletion of the resource(s) |
Similarly to the create command, you can use the generic resource type
entity to delete the supported resources. See the section Create entity command for instructions on the supported resources and the additional required fields.All resources created with the command
akamas create entity <folder> can also be deleted by using the opposite command akamas delete entity <folder>. The only difference is that the command akamas delete entity has an additional flag --complete. When supplied, it deletes all supported objects including optimization packs and telemetry providers. When the --complete flag is missing, however, optimization packs and telemetry providers are not deleted.List the resources for the selected type with their id, name, and description. Additional resource-specific fields can be shown.
akamas list [flags] <resource-type> <resource-id|resource-name> [<parent-resource-id>|<parent-resource-name>]
with the following options:
Option | Short option | Type | Values | Default | Description |
|---|---|---|---|---|---|
--no-pagination | -no-pag | Flag | | | Show all resources without pagination |
--use-seconds | -u-s | Flag | | | If durations should be output in seconds |
--sort-asc,
--sort-desc | -s-asc, -s-desc | Flag | | | Sort items by creation time |
--output | -o | Choice |
| table | Switch the output to table (default), json or yaml |
Describe an Akamas resource with all its fields.
akamas describe [flags] <resource-type> <resource-type> <resource-id|resource-name> [<parent-resource-id>|<parent-resource-name>]
with the following options:
Option | Short option | Type | Values | Default | Description |
|---|---|---|---|---|---|
--output | -o | Choice |
| table | Switch the output to table (default), json or yaml |
Notice that this command does not support the resource type System.
Update an Akamas resource, identified by UUID or name.
akamas update <resource-type> <resource-id|resource-name>
with the following options:
Option | Short option | Type | Values | Default | Description |
|---|---|---|---|---|---|
--output | -o | Choice |
| table | Switch the output to table (default), json or yaml |
Install a License or an Optimization Pack
akamas install <resource-type> <file>
with the following options:
Option | Short option | Type | Description |
|---|---|---|---|
--force | -f | Flag | Force the installation of the resource |
Uninstall a License or an Optimization Pack
akamas uninstall <resource-type> <id>
with the following options:
Option | Short option | Type | Description |
|---|---|---|---|
--force | -f | Flag | Force the uninstall of the resource |
Start the execution of a Study.
akamas start study <id>|<name>
Stop the execution of a Study. Once stopped, the execution cannot be resumed.
akamas stop study <id>|<name>
To export a study, the study name or the study UUID can be used from the command line.
An optional filename can be specified, with a relative or absolute path:
akamas export study <UUID>|"<NAME>" [FILENAME]
The exported information will be saved in tar.gz format.
The following entities are exported:
- The Study
- The Steps of the Study
- The Experiments of the Study
- The Trials of the Study
- The Workflow to which the Study refers
- The Timeseries collected during the study run
- The System to which the Study refers
- The Component related to the Study's System
- The ComponentType of each Component
- The Metrics definitions of each ComponentTypes
- The Parameters definitions of each ComponentTypes
Notice: this operation can require a long time, depending on the quantity of data to be collected. During this time the CLI will wait for Akamas to send the exported package. Do not interrupt the CLI during this phase, as otherwise, the process will need to be restarted from the beginning.
Notice: please make sure that you have installed the latest versions of the optimization packs before starting the import: this way, the import procedure will bind the studies to the latest optimization packs version (i.e. the installed ones) instead of importing the (possibly) old ones from the source system.
Use the following command to import a study into an existing Akamas instance:
akamas import study FILENAME
Where FILENAME refers to the file of a previously exported study.
When imported, the following entities will have a new UUID:
- Study
- Workflow
- System
- Component
- ComponentType
- Metrics
- Parameters
In case a resource that is being imported has the same name as an existing one, the existing entity will not be deleted. The existing entity (with its UUID) will be used instead of the imported one.
All steps, experiments, and trials will maintain the same id and, therefore, the same execution order as the original exported study.
Notice: this operation can require a long time. If the CLI shows a timeout error or if the operation is interrupted, the import will continue on the Akamas server.
Last modified 29d ago