Tetra HTTP Relay Agent Installation Guide (v1.0.x)
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)
- ts-sdk-python v1.3.0 or higher
- 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:
- Make sure that Docker version 20 or higher is installed on the host server.
- 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.
- Transfer the Tetra HTTP Relay Agent image to your host server.
- Load the image by running the following command in the server's local terminal:
sudo docker load -i $PATH_TO_IMAGE
- 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).
- 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 associatedTetraScience.Connector.http.Request.V2
commands. Agents without the$SECURE_COMMAND_KEY
will mark incomingTetraScience.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.
- 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 Agentinit
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.
- 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
init
SucceededThe 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 includeECONREFUSED
,ETIMEDOUT
, andENOTFOUND
. Manually logging into the host machine and verifying connectivity to the target machine, target port, and target system with command line tools likecurl
,wget
,nc
, orping
will reveal more information. Executingwget
commands from the docker container usingdocker 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
, or503
, then there may be issues in the connection between the HTTP Relay Agent and the proxy service, if one is in use. Inspecting theheaders
andbody
of the command response may yield more information. - If commands sent to the agent are failing and have a
statusCode
like401
or403
, then the requestor may have provided inappropriate authentication details to the HTTP Relay Agent.
Updated about 15 hours ago