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. Then, enable the Agent's queue in the TDP.

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.

🚧

IMPORTANT

Before deploying the Agent, you must enable the Agent's queue in the TDP. The Agent will not function properly without an enabled command queue.

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.

3. Transfer the Tetra HTTP Relay Agent image to your host server.
4. Load the image by running the following command in the server's local terminal: sudo docker load -i $PATH_TO_IMAGE
5. 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).
6. 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 URL to route HTTP requests to. This value must include the protocol (for example, http://proxy.company.com:8080).
   • $HTTPS_PROXY: The proxy server URL to route HTTPS requests to. This value must include the protocol (for example, http://proxy.company.com:8080).
   • $NO_PROXY: The host names that should not go through any proxy server, if you have one set up.
   • $NODE_TLS_REJECT_UNAUTHORIZED: Set to 0 to disable SSL/TLS certificate validation. Use only in development or when working with self-signed certificates. For production deployments, it's recommended to properly configure certificates instead.
7. 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-$ORG_SLUG-$AGENT_ID # 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=<...> # e.g., http://proxy.company.com:8080
HTTPS_PROXY=<...> # e.g., http://proxy.company.com:8080
NO_PROXY=<...> # e.g., localhost,127.0.0.1,.company.com
NODE_TLS_REJECT_UNAUTHORIZED=<...> # set to 0 to disable SSL certificate validation (not recommended for production)

# 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 \
  -e NODE_TLS_REJECT_UNAUTHORIZED=$NODE_TLS_REJECT_UNAUTHORIZED \
  --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 Agent returns any errors, review the Troubleshooting section in the Tetra HTTP Relay Agent User Guide (v1.0.x). It provides steps to resolve common issues.