API DocumentationProduct Documentation
Product Documentation

Create and Install a Tetra Hub

Suggest Edits

To set up a Tetra Hub, you must first create one in the Tetra Data Platform (TDP) user interface. Then, download the preconfigured installer and install the Hub on a local machine or a virtual machine (VM) on your network.

📘

NOTE

After installation, Hub automatically activates and connects to the TDP. You can then configure the Hub’s data connectors through the TDP user interface based on your organization’s requirements. For more information, see Add a Connector to a Tetra Hub.

Prerequisites

To create and install a Tetra Hub, the following is required:

  • TetraScience administrator or organization owner credentials
  • A dedicated network server or VM that meets Tetra Hub system requirements
  • Administrator access to the dedicated Tetra Hub machine

Step 1: Create a Tetra Hub

To create a Tetra Hub, do the following:

  1. Sign in to the TDP with admin or organization owner credentials.
  2. In the left navigation menu, choose Data Sources. Then, choose Hubs (v2). The Hubs page appears.
  3. Select the upper right Create New Hub button. The Create Hub page appears.
  4. Enter the following information:
    • For NAME, enter a name for the new Tetra Hub.
    • (Optional) For DESCRIPTION, enter a short description of the Tetra Hub.
    • (Optional) For Show parent proxy settings, move the toggle to the right and configure proxy settings for your Tetra Hub, if required. For more information, see Tetra Hub Proxy Settings.
  5. Choose Create. A Hub Details page appears that lists the Tetra Hub that you created.

📘

NOTE

You must install a Tetra Hub on a local machine or a virtual machine (VM) on your network before you can connect it to the TDP.

Step 2: Install a Hub

To install a Tetra Hub, do the following:

  1. On the Hub Details page, choose Install Hub. An Install a Hub popup appears.
  2. Get the preconfigured Tetra Hub installation script by choosing one of the following options:
    • Download Installation Script
      -or-
    • Copy Installation Script
  3. Transfer the installation script to your dedicated Tetra Hub environment.
  4. In your dedicated Tetra Hub environment, open a new terminal session. Then, navigate to the root account by running the following command:

sudo su

  1. Open an installer file in a text editor. For example, to open the nano text editor, you can run the following command:

nano installer.sh

  1. In the text editor, enter the installation script. Then, save the changes and exit the text editor.
  2. Make the file runnable by running the following command:

chmod +x installer.sh

  1. Run the installation script by running the following command:

./installer.sh

  1. The installer asks Is the Hub server behind a proxy? If you're not using a proxy, leave the prompt blank and press return.
    -or-
    If you're using a proxy, enter Yes and press return. The installer prompts you to provide proxy settings.

Proxy Prompt Example

No proxy settings detected in environment variables. Is the Hub server behind a proxy?
 Enter "Yes" to confirm the server is behind a proxy. Default is "No": Yes

Additional Proxy Settings Example

 Enter http_proxy value: http://hostname:port
 Enter https_proxy value: http://hostname:port
 Enter no_proxy value: 169.254.169.254
  1. (Optional) Add basic authentication settings, if required. To configure basic authentication, add the username and password to the http_proxy and https_proxy lines in the Additional Proxy Settings Example.

Basic Authentication Settings Example

 Enter http_proxy value: http://username:password@hostname:port
 Enter https_proxy value: http://username:password@hostname:port
 Enter no_proxy value: 169.254.169.254

📘

NOTE

After installation, the Tetra Hub automatically activates and connects to the TDP. When the Hub initially connects to the TDP (either during installation or a reboot), the Hub’s Health status displays as INITIALIZING in the TDP UI for up to five minutes until the Hub's initial metrics and proxy status are gathered. Then, the Hub’s status changes to Online.

Troubleshoot Hub Installation Issues

The following are known and possible issues that can occur during the Tetra Hub installation process, along with workarounds for each.

Why Did My Hub Installer Report TDP Access or Certificate Errors?

During installation, the Tetra Hub install script validates the certificate of the TDP endpoint it will reverse proxy to for Agent connections. If your TDP's certificate is not signed by a publicly trusted Certificate Authority like AWS, your customer success manager (CSM) can help you store the public key chain for the certificate in Amazon Simple Storage Service (Amazon S3) or the /etc/hub/tdp.pem folder on the Tetra Hub host server.

If the Tetra Hub can't reach the TDP endpoint or validate the endpoint's certificate, the Hub installer will return either a TDP Access or Certificate error. To resolve the issue, contact your CSM and share Hub installation script's output. They will help you reconfigure the Hub's Transport layer Security (TLS) validation.

Why Did the Amazon ECS Container Agent Startup Fail and Log an AccessDenied Error in CloudWatch Logs During Hub Installation?

When installing a Tetra Hub on a host server that already has an AWS Systems Manager registration key, the Amazon ECS container agent startup fails. An AccessDenied error is then logged in the agent’s Amazon CloudWatch Logs. To resolve the issue, do one of the following based on the TDP version that you're using.

For TDP v.3.6.x

The Hub installer automatically detects the issue and provides instructions to fix it.

For TDP v3.5.x

As a workaround, customers can move the existing SSM registration key to a backup location prior to Hub installation, so that the installer won’t detect it.

To move an existing SSM registration key to a backup location, run the following command in the host server’s terminal:

mv /var/lib/amazon/ssm/Vault/Store/RegistrationKey 
/var/lib/amazon/ssm/Vault/Store/RegistrationKey-backup-$(date +%s)

Why Does Hub Installation Fail When Using RHEL?

Tetra Hub installation fails on host servers that use Red Hat Enterprise Linux (RHEL) unless the server has access to Yellow Dog Updater, Modified (YUM) package manager.

To provide the host server access to YUM package manager, do the following:

For Servers Running In Amazon EC2

If the host server is running in an Amazon Elastic Compute Cloud (Amazon EC2) instance, do one of the following:

For Servers Running Outside Amazon EC2

If the host server is running outside of Amazon EC2, you must register the server with Red Hat. For instructions, see Chapter 25. Register Your System and Apply Subscriptions in the Red Hat Installation Guide.

Updated 5 months ago