To set up a Tetra Hub v2, 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 v2 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 v2, 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 v2

To create a Tetra Hub v2, do the following:

1. Sign in to the TDP with admin or organization owner credentials.
2. In the left navigation menu, select the hamburger menu. A drop-down list appears.
3. Choose Data Sources. Then, choose Hubs. The Hubs page appears.
4. Select the upper right Create New Hub button. The Create Hub page appears.
5. 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.
6. 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 Hub v2

To install a Tetra Hub v2, 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

5. 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

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

chmod +x installer.sh

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

./installer.sh

9. 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

10. (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 incorrectly displays as CRITICAL for a short time in the TDP UI. After the TDP receives the Hub’s initial metrics and proxy status, the Hub’s status displays as Online. No action is needed, and no alarms or notifications are generated.

Troubleshoot Hub v2 Installation Issues

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

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

When installing a Tetra Hub v2 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 v2 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 Did the Amazon ECS Instance Registration Process Fail During Hub v2 Installation?

The Tetra Hub v2 installation script doesn’t detect an existing Amazon Elastic Compute Cloud (Amazon EC2) instance role on a host server if there is one. If there is an existing AWS Identity and Access Management (IAM) role, the Hub’s Amazon ECS service will attempt to use it. The Hub’s Amazon ECS instance registration process fails when this happens.

As a workaround, customers can detach the Amazon EC2 IAM role from the Amazon EC2 instance, and then rerun the Hub installation script. For more information, see Detach an IAM role in the AWS documentation.

📘

NOTE

A fix for this issue is currently in development and testing for a future TDP v3.6.x patch release.