Agent Installation Guidelines
  • 14 Nov 2022
  • 10 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Agent Installation Guidelines

  • Dark
    Light
  • PDF

Installation and Deployment Guidelines

Note

Starting with release 22.11 the container image names have been shortened to the format agent-AGENTTYPE-PLATFORM:RELEASE, example:
agent-throughput-amd64:r22.11

See section "Agent Installation" below for updated docker pull strings

Requirements on Runtime Environment


The sensor: agents are containerized test functions that require a container environment in order to run.
Currently, we recommend Docker 20.10.0 or later on AMD64/x86-64 or ARM64 linux systems, and management of containers using Kubernetes, Docker CLI commands or Docker-Compose. Kubernetes control of container lifecycle is supported with helm charts for all agents.

Agent Typical Resource Consumption


For containers, the amount of RAM, CPU and disk is rarely provisioned strictly by the container environment. Instead, the usage is typically monitored and the environment can be configured to alert on overutlization of a certain resource.

As a guideline, the sensor: agents will under typical usage consume up to:

Agent CPU RAM Disk
actuate 0.15 0.3GB 250MB
throughput 1 0.1GB 250MB
transfer 0.1 0.1GB 250MB
trace 0.1 0.1GB 250MB

The logging from agents is through standard stdout mechanism, and it is up to the container environment to apply restrictions on how much data should be logged, and for how long. Keeping large amounts of logs will certainly increase the disk space used for the agents.

Agent Connectivity Requirements


In order to operate, the agent must be able to connect to a roadrunner instance using TCP on port 55777 (default port). This connection is referred to as the MANAGEMENT_PROXY and is used for management of the agent, and is authenticated using a secret provided in a YAML file to the agent upon start.

Secondly, the agent will communicate with a roadrunner on TCP port 55888 (default) to sent measurement data and metrics. This is refered to as the DATA_GATEWAY.

agentComms.png

If you don't have a roadrunner instance up and running for agents, follow these instructions to set one up:
Roadrunner creation and installation for agents

Lastly, the agent needs connectivity to the test destination. This may be a reflector, responder, service or another agent - all depending on the test type and configuration. Each agent type has different connectivity requirements for their test traffic.

Summary of connections required to be opened through any firewalls in between

Path Direction protocol port
Agent management Agent to roadrunner tcp 55777
Agent metrics data reporting Agent to roadrunner tcp 55888
Roadrunner Roadrunner to Analytics tcp 443
Agent test traffic Agent to reflector or other agent tcp/udp configurable

Note that all connections agent-roadrunner-analytics are "outbound", which means that it is supported to use NAT/PAT firewalls between each of these components, as all connections are initiated from the edge towards the central location. (Agent->Roadrunner and Roadrunner->Analytics cloud)

Agent Installation


The sensor: agents are provided as packages directly loadable into the Docker environment. To load an agent into your Docker environment, use the docker pull command for the appropriate agent:

x86/AMD versions

actuate x86_64 or amd64:

sudo docker pull gcr.io/sky-agents/agent-actuate-amd64:r22.11
Previous 22.07 version:
sudo docker pull gcr.io/sky-agents/skylight-agent-actuate-amd64:r22.07

throughput x86_64 or amd64:

sudo docker pull gcr.io/sky-agents/agent-throughput-amd64:r22.11
Previous 22.07 version:
sudo docker pull gcr.io/sky-agents/skylight-agent-throughput-amd64:r22.07

trace x86_64 or amd64:

sudo docker pull gcr.io/sky-agents/agent-trace-amd64:r22.11
Previous 22.07 version:
sudo docker pull gcr.io/sky-agents/skylight-agent-trace-amd64:r22.07

transfer x86_64 or amd64:

sudo docker pull gcr.io/sky-agents/agent-transfer-amd64:r22.11
Previous 22.07 version:
sudo docker pull gcr.io/sky-agents/skylight-agent-transfer-amd64:r22.07

ARM 64-bit versions

actuate arm64:

sudo docker pull gcr.io/sky-agents/agent-actuate-arm64:r22.11

throughput arm64:

sudo docker pull gcr.io/sky-agents/agent-throughput-arm64:r22.11

trace arm64:

sudo docker pull gcr.io/sky-agents/agent-trace-arm64:r22.11

transfer arm64:

sudo docker pull gcr.io/sky-agents/agent-transfer-arm64:r22.11

Downloading and exporting agent container as a file

If the agent needs to be installed on a host that has no internet access, the pulled image can be exported using docker save to a tar.gz file:

sudo docker save gcr.io/sky-agents/agent-actuate-amd64:r22.11 | gzip > agent-actuate-amd64.r22.11.tar.gz

This Docker image tar.gz file can then be loaded on the target plaform using docker load command:

sudo docker load -i agent-actuate-amd64.r22.11.tar.gz

Once loaded, the agent image should be present in the output from docker images:

sudo docker images

The output should show that the image has been loaded:

REPOSITORY                             TAG                 IMAGE ID            CREATED             SIZE
agent-actuate-docker          yy.mm_nnnn           4fab523db717        1 week ago        222MB

Agent Startup


For an agent to be started and ready to perform tests, it needs a couple of configuration parameters to be defined:

  • An external port mapping for the built-in RFC5357 TWAMP-light reflector (actuate agent only, and is not needed if no reflection is required)
  • A secrets YAML file containing an agent UUID and initial key for authentication
    OR
    A token provided to the agent via environment variable
  • IP address or FQDN, and port where it can find a roadrunner agent management service

These parameters can be supplied inside a Docker-Compose file, or specified as environment variables on the command line when starting the container with docker run.

Additional configuration parameters

Optionally, additional parameters can be defined like an agent name, an interface binding or additional logging options. These additional parameters are described in the documentation for each individual sensor: agent.

Define a new agent in the orchestration API

Important

When quering and changing configuration through the orchestration API it is highly recommended to use a dedicated service account for this task and not an individual user account. Agents use JWT tokens for authentication and these will expire if the user account is deleted.

Each agent needs to have a definition, or configuration, in the orchestration system to be accepted and controllable.
To add a new agent to the orchestration use the API calls as outlined below. Four configuration attributes need to be set:

  • agentId - a unique UUID identifying this agent
  • agentName - a string of unicode characters
  • gateway server - IP address or FQDN to roadrunner
  • gateway port - port used for metrics data streaming (default 55888)

To generate a UUID for your agent, use the built-in UUID generator in linux,

$ uuidgen
ae311d23-5ca7-fake-8317-25example54a

or an online service like UUID Generator.

Create a configuration object like the one below:

{"data": 
{
    "type": "agentConfigs",
    "attributes": {
        "agentId": "ae311d23-5ca7-fake-8317-25example54a",
        "dataGateway": {
            "server": "192.168.0.4",
            "port": 55888
        },
        "identification": {
            "agentName": "demo-agent-12345"
        }
    }
}
}

Then, POST it to the orchestration service to register this new agent:

POST
{{your-tenant-name}}/api/orchestrate/v3/agents/configuration

Step 2 - Grab secret from orchestration API and create the secrets file

As described in the previous sections, each agent needs an authentication token to be able to register to the orchestration and get managed. To retrieve the initial token, either use the agent control UI Using the agent control user interface or use the API towards the orchestration service to define this agent and get the secret.

The API call requires only a unique agent ID to register this agent and return the secrets token.

Registering the agent with the orchestration, and generating the secret for authentication is then done by POST:ing the UUID to the orchestration API:

POST
{{your-tenant-name}}/api/orchestrate/v3/agents/ae311d23-5ca7-fake-8317-25example54a/secrets

The output from the POST will be the initial secret for this agent, and should be placed in a file for use by the agent when launching. An example secret is shown below:

agentConfig:
    identification:
        agentId: ae311d23-5ca7-fake-8317-25example54a
        authenticationToken: eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZGlhbi5jb20iLCJzdWIiOiJhcGl1c2VyQG55ZGVsbC5zZSIsImV4cCI6MTYyAksIOwKNywiYXVkIjoiIiwidG9rZW5JRCI6MTM0OCwidGVuYW50SUQiOiJjODRhZWUzNC04ODhjLTRmMDYtYmFmMy00NGZkMmNhM2JkM2UifQ.mUu5ZrsfjIWipzf5zqOpA4PUqWbu_CSWaSEmPC3wygv4

For the examples below, this secret is saved in a file called
/home/agentuser/ae311d23-5ca7-fake-8317-25example54a.yaml

Alternative Step 2 - token as environment variable instead of secrets file

In some cases it may be more suitable to provide the security token as an environment variable when launching the agent. If using this method, define the environment variable AGENT_AUTHENTICATION_TOKEN set to the token generated in step 1, example:

AGENT_AUTHENTICATION_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZGlhbi5jb20iLCJzdWIiOiJhcGl1c2VyQG55ZGVsbC5zZSIsImV4cCI6MTYyAksIOwKNywiYXVkIjoiIiwidG9rZW5JRCI6MTM0OCwidGVuYW50SUQiOiJjODRhZWUzNC04ODhjLTRmMDYtYmFmMy00NGZkMmNhM2JkM2UifQ.mUu5ZrsfjIWipzf5zqOpA4PUqWbu_CSWaSEmPC3wygv4

If using this method, note that the AGENT_ID also needs to be set through environment variable, since it cannot be fetched from the secrets file when not using a secrets file.

Step 3 - Launch an agent

Below are examples of two different methods to launch an actuate agent. The throughput agent is launched in the exact same way, with the exception of the TWAMP reflection port which is not needed for the throughput agent.

Both launch methods described below will open UDP for TWAMP reflection on port 4000 (internal is always 862), connect towards a roadrunner on 10.11.12.13:55777/tcp and define the secrets file as /home/agentuser/3dfe3705-42f3-fake-80bb-59a218a0900e.yaml

It is considered good practice to use the agent UUID as part of the file name for the secret so that if you deploy several agents on the same host they get their own secrets file.

See Agent secrets file options for other metods of providing the authentication secret to the agent

Step 3.a Launch agent using Docker-Compose

To use Docker-Compose, the configuration parameters should be put in a YAML file. AGENT_ID and access token is fetched from the secrets file defined.

Example for actuate agent:

version: '3'
services:
  twamp-sender-service:
    container_name: "my-actuate-container"
    image: "gcr.io/sky-agents/agent-actuate-amd64:r22.11"
    ports:
      - "4000:862/udp"
    hostname: "my-agent"
    restart: "always"
    environment:
            AGENT_MANAGEMENT_PROXY: "10.11.12.13"
            AGENT_MANAGEMENT_PROXY_PORT: "55777"
    volumes:
      - /home/agentuser/ae311d23-5ca7-fake-8317-25example54a.yaml:/run/secrets/secrets.yaml

Example for throughput agent:

version: '3'
services:
  tcp-agent-service:
    container_name: "my-throughput-container"
    image: "gcr.io/sky-agents/agent-throughput-amd64:r22.11"
    hostname: "my-agent"
    restart: "always"
    environment:
            AGENT_MANAGEMENT_PROXY: "10.11.12.13"
            AGENT_MANAGEMENT_PROXY_PORT: "55777"
    volumes:
      - /home/agentuser/ae311d23-5ca7-9921-fake-25example54a.yaml:/run/secrets/secrets.yaml

The agent can now be launched using the docker-compose up command:

sudo docker-compose up

If the agent configuration was placed in a file named something other than docker-compose.yml, then this needs to be specified on the command line:

sudo docker-compose -f mycomposefile.yml up

Step 3.b Launch agent on command line

Same setup, but using command line with environment variable options (--env) and port maps (-p)

Example for actuate agent:

sudo docker run -d -p 4000:862/udp \
--env AGENT_MANAGEMENT_PROXY="10.11.12.13" \
--env AGENT_MANAGEMENT_PROXY_PORT="55777" \
-v /home/agentuser/ae311d23-5ca7-fake-8317-25example54a.yaml:/run/secrets/secrets.yaml \
gcr.io/sky-agents/agent-actuate-amd64:r22.11

The -d option makes Docker launch the container in the background, in "detached" mode.

Step 3.c Launch agent without secrets file

Same setup, but using command line with environment variable options (--env) and port maps (-p)

Example for actuate agent:

sudo docker run -d -p 4000:862/udp \
--env AGENT_ID="ae311d23-5ca7-fake-8317-25example54a"
--env AGENT_AUTHENTICATION_TOKEN="eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZGlhbi5jb20iLCJzdWIiOiJhcGl1c2VyQG55ZGVsbC5zZSIsImV4cCI6MTYyAksIOwKNywiYXVkIjoiIiwidG9rZW5JRCI6MTM0OCwidGVuYW50SUQiOiJjODRhZWUzNC04ODhjLTRmMDYtYmFmMy00NGZkMmNhM2JkM2UifQ.mUu5ZrsfjIWipzf5zqOpA4PUqWbu_CSWaSEmPC3wygv4"
--env AGENT_MANAGEMENT_PROXY="10.11.12.13" \
--env AGENT_MANAGEMENT_PROXY_PORT="55777" \
-v /home/agentuser/ae311d23-5ca7-fake-8317-25example54a.yaml:/run/secrets/secrets.yaml \
gcr.io/sky-agents/agent-actuate-amd64:r22.11

The -d option makes Docker launch the container in the background, in "detached" mode.


Note: Tokens expire after 14 days, so if using this method you need to generate a new token after that period of time if you need to restart or set up a new agent. Started and running agents re-negotiate token well before the expiry happens, so as long as you dont destroy the container you will still be able to stop and start agents. docker-compose down destroys the container so use graceful stop instead.

Step 3 - Check that the agent is running

To check that the agent has started, use the docker ps command:

$ docker ps
CONTAINER ID        IMAGE                                     COMMAND             CREATED             STATUS                 PORTS                                          NAMES
437d53381d83        agent-actuate-docker:yy.mm_nnn   "/sbin/monitor"     5 weeks ago         Up 5 weeks (healthy)   0.0.0.0:4000->862/udp,  my-agent

The output shows for how long the agent has been running, and the UDP port mapping informs that port 4000 is mapped on the host IP for TWAMP reflection.

Agent Launch Parameters

When launching an agent it accepts a number of parameters that define the instatiation of the container. The mandatory ones, like AGENT_MANAGEMENT_PROXY, have been described in the previous sections. Below is the full list of supported parameters, that can be provided as environment variables through the container instantiation when starting the agent.

Configuration Comment
AGENT_ID Optional, UUID for the agent. Is fetched from secret file if not provided
AGENT_MANAGEMENT_PROXY Mandatory, points to IP address or FQDN of the Agent Orchestration
AGENT_MANAGEMENT_PROXY_PORT Optional, defaults to 55777
AGENT_SOURCE_INTERFACE Optional
AGENT_MEASUREMENT_NETNS Optional, defines which namespace (VRF) to attach to for measurement
AGENT_REFLECTORS_DEFAULT_STATE agent: actuate only, set to "true" if agent should always start up with TWAMP and UDP reflectors enabled
AGENT_AUTHENTICATION_TOKEN Optional, set to value of your authenticationToken if not using a secrets file
AGENT_INNER_IPC_PORT Optional, auto-selected. Use this if there are namespace issues when launching more than one agent on the same host
AGENT_SECRETS_PATH Defines where the agent looks for its authentication secrets inside the container, the default path is “/run/secrets/secrets.yaml”

The agent is now ready to be configured using the orchestration API, see Working with the agents control API for more information on using the API, or agent orchestration API reference for full details.

© 2022 Accedian Networks Inc. All rights reserved. Accedian®, Accedian Networks®,  the Accedian logo™, Skylight™, Skylight Interceptor™ and per-packet intel™, are trademarks or registered trademarks of Accedian Networks Inc. To view a list of Accedian trademarks visit: http://accedian.com/legal/trademarks/. 


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.