This page explains how to install, configure and run a Step agent.

Installation

Java agent

The Step agent requires at least Java 11 installed in order to run. Depending on your platform, make sure to install at least Java JDK 11 on the machine(s) running Step component(s).

The latest version of the Community Edition of the Step agent can be downloaded from our Github repository at : Step.

The latest version of the Enterprise Edition of the Step agent can be downloaded from our FTP by enterprise customers at : Step Enterprise (credentials are provided upon requests)

In both cases, extract the Step agent archive using any un-archiver tool that support the zip format.

If you are only interested in Step Java agent installation, you can now jump to the Folder Structure Section.

NodeJS agent

To install the Node.js agent, you have to run the following npm command:

npm install -g step-node-agent

Please note that this command have to be executed with the user that will run the agent.

If you are only interested in Step NodeJS agent installation, you can now jump to the Folder Structure Section.

.NET agent

The .NET version of the Step agent is only available with the Enterprise Edition of Step. It can be downloaded from our FTP server by enterprise customers at Step Enterprise (credentials are provided upon requests).

As of Step 3.17, we provide four distributions of the .NET agents, supporting multiple frameworks and operating systems:

• The net5.0 agent is available for Windows, Linux and OSX and is provided as self-contained zip files for each of these runtimes (“step-enterprise-agent-net5-runtime-step_version.zip”).

• The net4.x agent (step-enterprise-agent-net4-….zip), available only on windows and using the latest stable version of the net4.X framework for compatibility support.

To install an agent, extract the chosen archive in an empty folder and configure it as described in below sections.

The following options are available when starting the StepAgent executable:

• -config: mandatory, specify the configuration file to use
• -gridHost: optional, allow to override the grid host
• -agentPort: optional, allow to override the agent port
• -agentHost: optional, allow to override the agent host
• -agentUrl: optional, allow to override the agent url

Windows agents

For windows agents, you may need to execute the following command line as Administrator to allow the agent to listen on the configured agent port. Per default the agent port is set to 8098 for the .NET agent (see below for more details concerning the configuration of the agent port).

netsh http add urlacl url=http://+:8098/ sddl=D:(A;;GX;;;S-1-1-0)

Linux and OSX agents

For the net5.0 agent on macOS and Linux, it is necessary to add your hostname in the system file /etc/hosts.

Example: ‘127.0.0.1 hostname’.

You may validate the configuration using the command

nslookup hostname

Folder Structure

Below the description of the agent structure folder :

agent/
─ bin : contains startup scripts
─ conf : contains configuration files
─ log : default location for the log files
─ ext : default location for external software binaries and libraries (java only)
─ lib : contains dependencies libraries (java only)

Basic Configuration

The configuration files of the agent can be found under agent/conf. This folder contains following data:

conf/
├── AgentConf.yaml
├── AgentConf.json

Since Step 3.16 both JSON and YAML formats are supported for the configuration of the agent. The default configuration format is YAML. If you want to use the legacy JSON format (AgentConf.json) for the configuration you have to modify the start script located under agent/bin (see below) accordingly.

All the agent parameters are documented in the YAML file directly. The following paragraphs explain these parameters in more detail.

Grid endpoint

At startup the agent registers itself into the controller’s grid using the grid endpoint exposed by the controller. The grid endpoint to be used is defined by the parameter gridHost.

Change this parameter according to the hostname of your controller and its grid port. Per default the contoller is configured to use the port 8081. Please refer to the configuration of the controller for more details concerning the configuration of the grid.

For example :

• Configure the agent to connect to the port 8081 of the grid host called controller

gridHost: http://controller:8081

Advanced 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

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)
  cleanupJobEnabled: true
  # define file that are eligible for cleanup based on their last access time (default 120 minutes) 
  cleanupLastAccessTimeThresholdMinutes: 120 
  # define the frequency of the cleanup job in minutes (default 60)
  cleanupIntervalMinutes: 60

Startup

Startup scripts can be found under agent/bin and contains the following :

bin
├── logback.xml
├── startAgent.bat
├── startAgent.command
└── startAgent.sh

• Windows: execute startAgent.bat
• Linux: make startAgent.sh executable and execute it
• Mac OS: make startAgent.command executable and execute it.

Going in the Step UI to Status -> Agents will show you that your agent is now connected and ready to receive requests from the Controller:

Installation as a Service (optional, Windows only)

In order to install the agent as a Windows service, follow below steps :

• download nssm at https://nssm.cc/download
• open a new command prompt as Administrator and navigate to the nssm executable location
• execute the following command :
  nssm install
• nssm gui will open, you can now specify the “startAgent.bat” location and the service name, then click on “Install service” :

• You should then be prompted that the service installation has been successful :

• you can double-check into Windows service list that the service has been properly installed and then you can start it :

Installation checks

Running process

Depending on your platform, they are various ways to check if the Agent is running :

• Windows: open the Task Manager and look for the Agent processes
• Linux: execute below command and check that a PID is returned :

ps -efl | grep Agent

• Mac OS: open the Activity Monitor and look for the Agent processes

Log file

The Agent log file will be created on first startup under the log folder. (You can change the log file location by editing the bin/logback.xml file). A successful startup should display the following entry into the log file:

2017-09-26 13:22:40,639 INFO [main] o.e.j.s.Server [Server.java:379] Started @1326ms 

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.