Categories: ADMIN GUIDE CLOUD

Agent configuration

Agent endpoint

The agent exposes a REST service to the Controller, which is consumed by the controller to execute Keywords. The endpoint of this service is called agent endpoint. The agent endpoint is configured automatically at agent startup and is communicated to the controller at registration. If required, the endpoint can be tweaked as follow:

Agent port

Per default the agent lets the system find a free port automatically at startup to listen on. If required you can set the agent port explicitly using the parameter agentPort. The agent service would then run on that specific port.

For example :

# Configure the agent to listen on port 8080
agentPort: 8080

Agent host

Per default the hostname of the agent endpoint is determined automatically at agent startup. If required you can set the agent hostname explicitly using the parameter agentHost.

For example :

# Configure the agent to be called by the controller using the hostname agent-host.mynetwork.net
agentHost: agent-host.mynetwork.net

Agent URL

Per default the URL of the endpoint which is communicated to the controller is built as follow: http://<agentHost>:<agentPort>. If required (if your agent is behind a proxy for instance), you can set the URL of the agent endpoint explicitly using the parameter agentUrl:

For examples :

agentUrl: https://myAgentHost:7000
agentUrl: http://192.168.10.50:8888

SSL

Per default the agent exposes its service as plain HTTP. If required you can enable SSL for the agent service using the parameter ssl.

Before enabling SSL for the agent service you will need a valid SSL certificate for your agent endpoint. You can either use a self-signed certificate or obtain it from a certificate authority (CA).

In both cases you’ll get following files:

  • the private key file (.key)
  • the certificate file (.cert)

The agent requires the certificate in a Java KeyStore in JKS format. To generate the JKS KeyStore based on your .key and .cert files, follow the steps described here

As soon as you have your certificate in JKS format as a .jks file you can enable SSL for the agent service using following parameters:

ssl: true
keyStorePath: /path/to/cert.jks
keyStorePassword: '<password>' // The password for the key store used at key store generation
keyManagerPassword: '<password>' // The password for the specific key within the key store used at key store generation

Agent tokens

As described here in more detail, Keywords are executed on so-called agent tokens. On agent can emit multiple groups of agent tokens. The token groups are configured using the parameter tokenGroups. Each token group has its own number of tokens (capacity) and attributes. The following paragraphs explain the configuration of token groups.

Capacity

The number of agent tokens emitted by a token group is defined by the parameter capacity. This parameter defines how many tokens have to be made available to the controller for Keyword execution and thus defines the maximal number of parallel keyword executions to be allowed on the agent for a specific group. Set this value according to the resources of your agent:

For example :

# Defines 1 token group with 200 tokens
tokenGroups:
- capacity: 200
  tokenConf:
    attributes:
    properties:

Attributes

As described here, specific agent tokens can be selected for execution using so-called agent attributes. The agent attributes are defined as key-value pairs in the parameter tokenConf.attributes.

For example, we could define a pool of “Windows” agents by setting an “OS” attribute like below :

tokenGroups:
- capacity: 1
  tokenConf:
    attributes:
      OS: Windows

On that example, the OS attribute can be used to route the workload on specific machines hosting this agent, enabling the ability to choose where to run test plans (see this link)

Configuration placeholders

Placeholders can be used in AgentConf.yaml and AgentConf.json to define dynamic values that have to be set at startup outside the configuration file.

For instance, you might want to set the gridHost at startup. You could achieve this using a placeholder like this in your AgentConf.yaml:

  • gridHost: ${myGridHost}

and set the variable myGridHost in the startup script startAgent.bat(sh|command):

“%JAVA_PATH%java.exe” %JAVA_OPTS% -cp “..\lib*;” step.controller.ControllerServer -config=../conf/step.properties -myGridHost=http://mygridhost.net:8081

Agent cleanup configuration

There are 2 caching mechanism in place with automatic cleanup provided out of the box. While their configuration is distinct, it is important to understand that files stored in the file manager cannot be cleanup as long as they are used by the execution context cache. The default configuration is meant for optimal performance, reducing the timeToLive can decrease the execution throughput as well as increase the resource consumption on both the agent and controller (network, CPU and memory).

File Manager cleanup configuration

When the controller needs to transfer files to an agent for the execution of keywords, these file are cached locally on the agents to improve performance. This cache is automatically cleaned up, but following properties can be customized in the agent configuration to tweak this behaviour.

fileManagerConfiguration:
# enable or disable the cleanup (true by default)
enableCleanup: true
# define file that are eligible for cleanup based on their last access time (default 1440 minutes).
# When set to 0, files are cleaned up as soon as they're not used anymore without waiting for the clean up job (also see execution context cache cleanup)
cleanupTimeToLiveMinutes: 1440
# define the frequency of the cleanup job in minutes (default 60)
cleanupFrequencyMinutes: 60

Execution context cache cleanup configuration

For the execution of Keywords on the Java agent, the keywords package (JAR files) must be loaded in the context of the agent process. For performance reason, these package are cached in the so-called execution context cache. This cache is automatically cleaned up, but following properties can be customized in the agent configuration to tweak this behaviour.

executionContextCacheConfiguration:
# enable or disable the cleanup (true by default)
enableCleanup: true
# define file that are eligible for cleanup based on their last access time (default 1440 minutes).
# When set to 0, files are cleaned up as soon as they're not used anymore without waiting for the clean up job (also see execution context cache cleanup)
cleanupTimeToLiveMinutes: 1440
# define the frequency of the cleanup job in minutes (default 60)
cleanupFrequencyMinutes: 60

Agents kubernetes probes

If you are running Kubernetes or any other platform for managing containerized workloads and services, you could use:

  • the /running API endpoint as a liveness probe (the Agent process is running)
  • the /registered API endpoint as a readiness probe (the Agent has successfully registered to the Step GRID)

Below an example of what your Kubernetes manifest could contain:

livenessProbe:
  httpGet:
    path: /running
    port: 12345
  initialDelaySeconds: 5
  periodSeconds: 5
readinessProbe:
  httpGet:
    path: /registered
    port: 12345
  initialDelaySeconds: 10
  periodSeconds: 5

Exposing JVM metrics for prometheus endpoints

It is possible to expose the default JVM metrics using the Prometheus format by adding the below parameter to your Agent configuration file:

exposeMetrics: true

The metrics will then be exposed under the /metrics path on the same port the Agent is running.

See Also