opentf-agent 1.1.2

OpenTestFactory Orchestrator Agent

opentf-agent

This package is part of the OpenTestFactory framework.

Overview

An agent is a process that runs on an execution environment. That process will contact the orchestrator at regular intervals, looking for some orders to execute.

If there is a pending order, the agent will do as asked and send the result back to the orchestrator.

There can be any number of agents talking with a given orchestrator. But, typically, on a given execution environment, there is at most one agent running.

Not all execution environments have agents running on them. If the execution environment can be accessed via SSH, this may be used instead.

Installation

The OpenTestFactory agent is a Python application that is installed in the execution environment. It requires Python 3.7 or higher. It works on Linux, MacOS, and Windows.

As it is a simple script it may also work on other operating systems. It only has one external dependency, the well-known requests library (it will be installed if not already present on the execution environment).

To install it, use the following command:

pip3 install --upgrade opentf-agent

You can test your installation by running the following command:

opentf-agent --help

Usage

Summary

$ opentf-agent --help
usage: opentf-agent [-h] --tags TAGS --host HOST [--port PORT]
                    [--path_prefix PATH_PREFIX] [--token TOKEN]
                    [--encoding ENCODING] [--script_path SCRIPT_PATH]
                    [--workspace_dir WORKSPACE_DIR] [--name NAME]
                    [--polling_delay POLLING_DELAY]
                    [--liveness_probe LIVENESS_PROBE] [--retry RETRY]
                    [--debug]

OpenTestFactory Agent

optional arguments:
  -h, --help            show this help message and exit
  --tags TAGS           a comma-separated list of tags (e.g. windows,robotframework)
  --host HOST           target host with protocol (e.g., https://example.local)
  --port PORT           target port (default to 24368)
  --path_prefix PATH_PREFIX
                        target context path (default to no context path)
  --token TOKEN         token
  --encoding ENCODING   encoding on the console side (defaults to utf-8)
  --script_path SCRIPT_PATH
                        where to put temporary files (defaults to current directory)
  --workspace_dir WORKSPACE_DIR
                        where to put workspaces (defaults to current directory)
  --name NAME           agent name (defaults to "test agent")
  --polling_delay POLLING_DELAY
                        polling delay in seconds (default to 5)
  --liveness_probe LIVENESS_PROBE
                        liveness probe in seconds (default to 300 seconds)
  --retry RETRY         how many times to try joining host (default to 5,
                        0 = try forever)
  --debug               whether to log debug information.

Required parameters

There are two required parameters, --tags and --host.

--tags is a comma-separated list of tags. One of those tags MUST be one and only one of linux, macos, or windows. There may be any number of other tags.

--host is the orchestrator this agent will register to. It is a fully qualified domain name (or an IP address), and must start with a protocol, typically https://.

Optional parameters

If the port the orchestrator listen to for agent registration differs from the standard one (24368), you can use the --port option to adjust it.

If the orchestrator does not have its own domain name but used a shared fully qualified name, you can specify its path prefix using the --path_prefix option. For example, if the orchestrator is listening on https://example.com/foo/bar, you can specify --path_prefix foo/bar.

If the orchestrator requires a token, you can use the --token option to specify it.

If you intend to have multiple agents, you can give a name to some or all your agents, by using the --name option.

If your execution environment console does not use UTF8 as its encoding, you can specify the used encoding using the --encoding parameter.

By default, scripts and workspaces are created in the current directory. You can change this by using --script_path and --workspace_dir, respectively.

By default the agent will query the orchestrator every 5 seconds. You can adjust this by using the --polling_delay option.

By default the orchestrator considers the agent available for handling jobs if it has been seen in the last 300 seconds. You can adjust that delay by using the --liveness_probe option.

Stopping the agent

You can stop a running agent by killing it or interrupting it (^C). It will try to deregister from the orchestrator.

If the deregistration is successful, there will be a Agent successfully deregistered message in the console.

If the deregistration fails, the orchestrator may still consider the agent to be available for a limited amount of time (as specified by --liveness_probe), which may cause jobs targeting a compatible execution environment to time-out.

Examples

Example 1

Assuming there is an OpenTestFactory orchestrator running on orchestrator.example.com, with a known token stored in the TOKEN environment variable, the following command will register the Windows-based execution environment and will possibly receive commands targeting windows and/or robotframework:

chcp 65001
opentf-agent --tags windows,robotframework --host https://orchestrator.example.com/ --token %TOKEN%

The agent will poll the orchestrator every 5 seconds and will execute the received commands.

The chcp command sets the console to Unicode. It is Windows-specific. It is not mandatory but may be needed depending on the test framework available in the execution environment.

Temporary files will be generated in the current directory, as well as workspace directories.

Example 2

Assuming again the existence of an OpenTestFactory orchestrator running on orchestrator.example.com, listening for agent registrations on port 12345, with a known token stored in the TOKEN environment variable.

The following command will register the Linux-based execution environment and will poll the orchestrator every seconds. Il will accept jobs targeting linux, and/or junit, and/or robotframework.

Scripts will be temporarily stored on /tmp, and workspaces will be allocated on /var/opentf/workspace.

opentf-agent \
  --name "all in one execution environment" \
  --tags linux,junit,cypress \
  --host https://orchestrator.example.com \
  --port 12345 \
  --token $TOKEN \
  --script_path /tmp \
  --workspace_dir /var/opentf/workspace \
  --polling_delay 1

Troubleshooting

You can list the registered agents on a given orchestrator by running the following command:

curl \
  -H "Authorization: bearer $TOKEN" \
  https://orchestrator.example.com:24368/agents

You can deregister a rogue agent on a given orchestrator by running the followig command:

curl \
  -X DELETE \
  -H "Authorization: bearer $TOKEN" \
  https://orchestrator.example.com:24368/agents/<agent_id>

where <agent_id> is the UUID of the agent as shown by the previous command.

License

Copyright 2021 Henix, henix.fr

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.