API DocumentationProduct Documentation
Product Documentation

Tetra HTTP Relay Agent Installation Guide (v1.0.x)

Suggest Edits

This guide shows how IT Administrators can install and configure Tetra HTTP Relay Agent versions 1.0.x.

To configure the Agent after it's installed, see the Tetra HTTP Relay Agent User Guide (v1.0.x).

Install and Configure a Tetra HTTP Relay Agent

To install and run Tetra HTTP Relay Agent v1.0.x, do the following.

Step 1: Provision a Server with Network Access to Your Target System(s) and the TDP

As a light-weight, elastic, containerized application, the provisioning requirements for the Agent's host server are flexible. The following are considered minimum requirements:

  • Any operating system that's compatible with Docker (a Linux base, such as Ubuntu, is recommended for cost, supportability, and compatibility reasons)
  • Any supported version of the Tetra Data Platform (TDP)
  • Docker version 20.10.21 or higher (compatibility with lower versions is possible, but untested)
  • Outbound internet access to the TDP
  • At least one vCPU with a processing speed greater than two GHz
  • At least one GB MEM dedicated to the Agent
  • Enough disk space to accommodate Docker, an approximately 250MB image, and associated container logs (log volume will correlate to runtime length and usage of the agent, but default Docker settings will capture approximately one gigabyte of logs per year, plus approximately 6.5 megabytes of logs per 1,000 commands processed by the Agent)

Step 2: Create a New Tetra HTTP Relay Agent in the TDP

To create a new Tetra HTTP Relay Agent, follow the instructions in Create a New Agent.

When you select the Agent Type, make sure that you choose [User Defined Agent]. Then, after you choose Create Agent on Platform, choose Not Now and follow the remaining steps in this guide.

Step 3: Set Up the Host Server

To set up the Agent's host server, do the following:

  1. Make sure that Docker version 20 or higher is installed on the host server.
  2. Reach out to your TetraScience Customer Success Manager for a copy of the Tetra HTTP Relay Agent image. Convenience scripts to start and verify operation of the Agent are also available on request.

📘

NOTE

It is a security best practice to confirm the tag, IMAGE ID, and checksum of the HTTP Relay Agent image before deploying it.

  1. Transfer the Tetra HTTP Relay Agent image to your host server.
  2. Load the image by running the following command in the server's local terminal: sudo docker load -i $PATH_TO_IMAGE
  3. Collect the following required runtime parameters to configure your agent:
    • $ORG_SLUG: The org slug for your Tetra HTTP Relay Agent in The TDP. You can get the org slug for your agent on the Agents page in the TDP.
    • $AGENT_ID: The Agent ID of your User Defined Agent. You can get the Agent ID on the Agents page in the TDP.
    • $JWT: A service user auth token with administrator privileges. To create a service user token, see Add a Service User.
    • $API_TARGET: The base URL for your TetraScience deployment. If not known, ask your TetraScience Customer Success Manager (CSM).
  4. Collect the following optional runtime parameters to configure your agent:
    • $SECURE_COMMAND_KEY: The encryption key used to decrypt secure commands. Deployments that use Tetra Data Pipelines to send secure commands to the HTTP Relay Agent will save this as a Shared Secret in the TDP. This secret allows the Agent to parse the associated TetraScience.Connector.http.Request.V2 commands. Agents without the $SECURE_COMMAND_KEY will mark incoming TetraScience.Connector.http.Request.V2 commands as failed. For more information, see the Tetra HTTP Relay Agent User Guide (v1.0.x).
    • $HTTP_PROXY: The proxy server host name to route HTTP requests to.
    • $HTTPS_PROXY: The proxy server host name to route HTTPS requests to.
    • $NO_PROXY: The host names that should not go through any proxy server, if you have one set up.
  5. Determine your local Docker logging configuration. The default Docker logging configuration persists logs in a convenient-to-access format, but risks exhausting the hard drive (persistent storage) of the host machine for long-running agent containers. The script below uses the local logging driver with default settings to ensure system stability for long-running agent containers. For more information, see Configure logging drivers in the Docker documentation. The Tetra HTTP Relay Agent logs after the Agent init step is persisted in AWS.

Step 4: Configure and Run the Agent

📘

NOTE

It's recommended that you document your runtime/deployment script(s), in case the Agent must be restarted or reconfigured.

  1. Start the agent by running the docker run $IMAGE_NAME command in the host server's local terminal. Make sure that the required environmental variables are passed to the Agent container by using the following convenience script or the one provided by your Customer Success Manager (CSM), which you should edit based on your specific deployment needs.
# required agent parameters
# replace <...> with your parameter value
API_TARGET=<...>
ORG_SLUG=<...>
JWT=<...>
AGENT_ID=<...>

CONTAINER_NAME=ts-agent-http-relay # set to a human-readable-name
IMAGE_NAME=<...> # Name or ID of the image from TetraScience e.g. ts-agent-http-relay:v1.0.0

# optional parameters. May be be left unset or otherwise not passed to the container
SECURE_COMMAND_KEY=<...> # if unset, should not be passed to the agent
HTTP_PROXY=<...> 
HTTPS_PROXY=<...> 
NO_PROXY=<...> 

# review this run command and determine if changes must be made for, e.g.
#  - logging
#  - network
#  - environmental variables
#  - monitoring
#  - up-time
#  - secure commands
sudo docker run \
  --name $CONTAINER_NAME \
  -e http_proxy=$HTTP_PROXY \
  -e https_proxy=$HTTPS_PROXY \
  -e no_proxy=$NO_PROXY \
  -e API_TARGET=$API_TARGET \
  -e ORG_SLUG=$ORG_SLUG \
  -e AGENT_ID=$AGENT_ID \
  -e JWT=$JWT \
  -e SECURE_COMMAND_KEY=$SECURE_COMMAND_KEY \
  --net=host \
  --restart=always \
  --ulimit core=0 \
  --log-driver 'local' \
  -d \
  $IMAGE_NAME

Verify the Installation and Monitor the Agent

Step 1: Verify that the Agent Container is Running

To verify that the Agent Container is running, run the following command in the local host server's terminal:

sudo docker ps -a

Step 2: Verify Agent init Succeeded

The Agent will initialize and start polling the TDP Command Service within a minute. If Docker logging is enabled, the following command will allow you to inspect your agent's recent logs:

sudo docker container logs ${CONTAINER_ID}

Healthy Agent activity after initialization includes polling for commands, posting health statuses to the TDP, and refreshing the Agent configuration from TDP. The Agent will appear online* on the [Agents** page in the TDP](https://developers.tetrascience.com/docs/centralized-configuration-of-tetra-data-platform-components#access-the-agents-page) within a few minutes of initialization.

Step 3: Identify and Resolve Any Errors

  • If the container is unhealthy (for example, if it has entered an exit-restart loop), then inspect the Agent's logs for more details. The initial Agent configuration may be incorrect, potentially because the environmental variables passed to the container aren't valid.
    • In some cases, configurations that aren't valid are detected prior to initialization. Descriptive error messages are provided.
    • Inspecting the log messages will provide details about configurations that aren't valid (for example, failing to authenticate to the TDP, because either the $ORG_SLUG and $JWT aren't valid or the Agent doesn't have the ability to communicate with the TetraScience API because of host machine network restrictions.
  • If the Agent errors concern communicating with the Amazon Simple Queue Service (SQS) queue, then Enable the Agent's Queue. If the queue is enabled, then review the host's networking configuration to ensure communication with the TDP.
  • If the Agent errors indicate that the Agent is disabled, then Enable the Agent's Connection.
  • If commands sent to the agent are failing without a statusCode in the response, then there may be issues with network connectivity to the target system. Common error messages in these responses could include ECONREFUSED, ETIMEDOUT, and ENOTFOUND. Manually logging into the host machine and verifying connectivity to the target machine, target port, and target system with command line tools like curl, wget, nc, or ping will reveal more information. Executing wget commands from the docker container using docker exec -it $COMMAND can reveal if the deployment's Docker networking configuration is blocking the request.
  • If commands sent to the agent are failing and have a status code like 407, 502, or 503, then there may be issues in the connection between the HTTP Relay Agent and the proxy service, if one is in use. Inspecting the headers and body of the command response may yield more information.
  • If commands sent to the agent are failing and have a statusCode like 401 or 403, then the requestor may have provided inappropriate authentication details to the HTTP Relay Agent.

Updated 8 days ago