FileConfigurator Operator

The FileConfigurator operator allows configuring systems tuned by Akamas by interpolating configuration parameters into files on remote machines.

The operator performs the following operations:

  1. It reads an input file from a remote machine containing templates for interpolating the configuration parameters generated by Akamas

  2. It replaces the values of configuration parameters in the input file

  3. It writes the file with replaced configuration parameters on a specified path on another remote machine

Access on remote machines is performed using SFTP (SSH).

Templates for configuration parameters

The FileConfigurator allows writing templates for configuration parameters in two ways:

  • specify that a parameter should be interpolated directly:

${component_name.parameter_name}
  • specify that all parameters of a component should be interpolated:

${component_name.*}

Suffix or prefix for interpolated parameters

It is possible to add a prefix or suffix to interpolated configuration parameters by acting at the component-type level:

Notice that any parameter that does not contain the FileConfigurator element in the operators' attribute is ignored and not written.

name: Component Type 1
description: My Component type
parameters:
- name: x1
  domain:
    type: real
    domain: [-5.0, 10.0]
  defaultValue: -5.0
  # Under this section, the operator to be used to configure the parameters is defined
  operators:
    FileConfigurator:
      # using this OPTIONAL confTemplate property is possible to interpolate the parameter value with a prefix and a suffix
      confTemplate: "PREFIX${value}SUFFIX"

In the example above, the parameter x1 will be interpolated with the prefix PREFIX and the suffix SUFFIX, ${value} will be replaced with the actual value of the parameter at each experiment.

Example

Let's assume we want to apply the following configuration:

component1.param1: 1024
component1.param2: Category1
component2.param3: 7
component2.param4: 35.4

where component1 is of type MyComponentType and MyComponentType is defined as follows:

name: MyComponentType
description: "MyComponentType
parameters:
- name: param1
  domain:
    type: real
    domain: [-5.0, 10.0]
  defaultValue: -5.0
  # Under this section, the operator to be used to configure the parameters is defined
  operators:
    FileConfigurator:
      # using this OPTIONAL confTemplate property, it is possible to interpolate the parameter value with a prefix and a suffix
      confTemplate: "X1:${value}MB"
...

A template file to interpolate only parameter component1.param1 and all parameters from component2 would look like this:

myexecutable.sh -PARAM ${component1.param1} -PARAMS ${component2.*}

The file after the configuration parameters are interpolated would look like this:

myexecutable.sh -PARAM X1:1024MB -PARAMS 7 35.4

Note that the file in this example contains a bash command whose arguments are constructed by interpolating configuration parameters. This represents a typical use case for the File Configurator: to construct the right bash commands that will configure a system with the new configuration parameters computed by Akamas.

Configuration Template Override

Some configuration files may require formatting the parameter value using a template different from the one provided by default in the componentType. For this reason, it is possible to override the configuration template of each parameter at the workflow task level.

To handle these situations, it is possible to override the configuration template at the workflow level. The override can be applied to all components of a certain componentType or just to a specific component using the optional component tag.

Example:

name: Configure Benchmark
operator: FileConfigurator
arguments:
  confTemplate:
    ComponentType.param1: ${value}

In this example, the param1 parameter for all components of type MyComponentType will be configured using the ${value} template.

Operator arguments

NameTypeValue RestrictionsRequiredDefaultDescription

source

Object

should have a structure like the one defined in the next section

no, if the Component whose name is defined in component has properties that map to the ones defined within source

Information relative to the source/input file to be used to interpolate optimal configuration parameters discovered by Akamas

target

Object

should have a structure like the one defined in the next section

no, if the Component whose name is defined in component has properties that map to the ones defined within target

Information relative to the target/output file to be used to interpolate optimal configuration parameters discovered by Akamas

component

String

should match the name of an existing Component of the System under test

no

The name of the Component whose properties can be used as arguments of the operator

confTemplate

Object

a map where keys are in the form componentType.parameter and values are the related new templates

no

The values of new parameter templates

ignoreUnsubstitutedTokens

Boolean

no

False

Behavior of the operator regarding leftover tokens in the target file. When False, FileConfigurator fails. When True , FileConfigurator succeeds regardless of leftover tokens

source and target structures and arguments

Here follows the structure of either the source or target operator argument

NameTypeValue restrictionsRequiredDefaultDescription

hostname

String

should be a valid SSH host address

yes

SSH endpoint

username

String

yes

SSH login username

password

String

cannot be set if key is already set

no

SSH login password

sshPort

Number

1≤sshPort≤65532

no

22

SSH port

key

String

cannot be set if password is already set

no

SSH login key, provided directly its value or the path of the file to import from. The operator supports RSA and DSA Keys

path

String

should be a valid path

yes

The path of the file to be used either as the source or target of the activity to applying Akamas computed configuration parameters using files

Get operator arguments from component

The component argument can be used to refer to a component by name and use its properties as the arguments of the operator. In case the mapped arguments are already provided to the operator, there is no override.

In this case, the operator replaces in the template file only tokens referring to the specified component. A parameter bound to any component will cause the substitution to fail.

Component property to operator argument mapping

Component propertyOperator argument

hostname

source->hostname target->hostname

username

source->username target->username

sshPort

source->sshPort target->sshPort

password

source->password target->password

key

source->key target->key

sourcePath

source->path

targetPath

target->path

Examples

Configure parameters for an Apache server with explicit source and target machine information

name: RemoteConfOperatorTestStandalone
operator: FileConfigurator
arguments:
  source:
    hostname: template-server
    username: akamas-user1
    password: akamas-password1
    path: /templates/frontend-httpd.conf
  target:
    hostname: frontend-server
    username: akamas-user2
    password: akamas-password22
    path: /etc/httpd/httpd.conf

Configure parameters for an Apache server with information taken from a Component

name: RemoteConfOperatorTestStandalone
operator: FileConfigurator
arguments:
  component: apache-server-1

where the apache-server-1 component is defined as:

name: apache-server-1
description: The Apache server instance
componentType: Apache Server 2.4

properties:
  hostname: apache.akamas.io
  username: ubuntu
  key: key.pem
  sourcePath: templates/httpd.conf.template
  targetPath: /etc/httpd/httpd.conf

Last updated