Deploy a Trustgrid Node in AWS

Standing up a Trustgrid node in AWS uses a published Amazon Machine Image (AMI). Each node has two network interfaces — a WAN interface for control plane communication and TLS/UDP tunnel traffic, and a LAN interface for internal data traffic.

Prerequisites

The Trustgrid AMI is published in us-east-1, us-east-2, us-west-1, and us-west-2. Deploying in other regions requires working with Trustgrid Support to copy the AMI into the target region.

You will also need:

• A VPC with a public subnet for the WAN interface and a private subnet for the LAN interface.
• An available Elastic IP in the region — one EIP is associated with the WAN interface during provisioning.
• An SSH key pair in the target region for troubleshooting if required.

Instance Type

Additional x86_64 instance types may work but have not been tested. ARM-based instances (Graviton) are not supported. Contact Trustgrid Support if a different type is believed necessary.

Networking

The WAN interface lives in the public subnet and must allow outbound access to the Trustgrid control plane. See Network Requirements for All Nodes for the full list of required IPs and ports.

The LAN interface lives in the private subnet and is used for internal data traffic and, in clustered deployments, for inter-node communication on the cluster heartbeat port (typically TCP 9000).

The following table summarizes the security group rules required across both interfaces:

AWS Network Firewall and UDP Tunnels

If nodes are deployed behind an AWS Network Firewall and UDP tunnels are used, explicit rules must be added in both directions. Unlike TCP, AWS Network Firewall does not maintain UDP connection state during maintenance events. If the first packet the firewall sees after a maintenance event arrives from the opposite direction of the original flow (e.g., a gateway initiating a keepalive back toward an edge node), it will not recognize the tuple as an established session and will block it.

Gateway node — required rules:

Edge node — required rules:

Security

Source/destination check must be disabled on both interfaces of every Trustgrid node. The CloudFormation and Terraform deployment paths configure this automatically; for Remote Registration deployments it must be disabled manually after the instance is launched.

An IAM role is only required if the node will be deployed as part of an HA cluster using one of the failover mechanisms below. Each tutorial documents the specific permissions required:

• IP Failover — ec2:AssignPrivateIpAddresses on the LAN ENI.
• Route Failover — ec2:DescribeRouteTables, ec2:CreateRoute, ec2:DeleteRoute on the LAN route table.

Deployment Methods

Choose one of the following methods to deploy and register the node.

Terraform

The trustgrid-infra-as-code repository provides purpose-built Terraform modules for deploying Trustgrid nodes in AWS. These modules encapsulate the EC2 instance, two ENIs, EIP, source/destination check, and IAM wiring.

CloudFormation

In this path, you create the node in the Trustgrid portal first to obtain a license key, then pass the key as a parameter to the CloudFormation stack. The node registers automatically with the Trustgrid control plane on first boot.

Step 1: Add the Node and Obtain a License Key

In the Trustgrid portal, go to the Nodes page, click Add Node, enter a name for the node, and click Create License. The portal generates a license key — copy it to your clipboard or click Download License to save it locally. See Adding Node Appliances for the full walkthrough with screenshots.

Step 2: Launch the CloudFormation Stack

Open the CloudFormation template in the AWS console:

https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3.amazonaws.com/tg-dev-public/cf-trustgrid-node.json

Change the region= query parameter in the URL to the region you are deploying in. All template fields are required.

When creating the stack, check the box acknowledging that AWS CloudFormation may create IAM resources — this is required because the template creates an instance profile for the EC2 instance.

The CloudFormation template configures an encrypted EBS volume. If you supply a custom IAM role, it must include access to the default EBS KMS key:

{
  "Effect": "Allow",
  "Action": [
    "kms:Decrypt",
    "kms:DescribeKey",
    "kms:ReEncrypt*",
    "kms:GenerateDataKey*"
  ],
  "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:alias/aws/ebs"
}

Once registration is complete, the node appears as online in the portal and is ready to manage like any other.

Remote Registration

In this path, you launch an EC2 instance from the Trustgrid AMI without a license key and then register the node using the Trustgrid remote registration utility over SSH. Use this approach if you need to register a node without pre-generating a license key from the portal.

Step 1: Launch the EC2 Instance

Launch an EC2 instance from the Trustgrid AMI in the target region. The AMI is published with a name prefixed trustgrid-node-prod — search the AMI catalog by that prefix and select the most recent version. Configure the instance with:

• The instance type from Instance Type above.
• A primary network interface in the public subnet with the WAN security group attached and an Elastic IP associated.
• A secondary network interface in the private subnet with the LAN security group attached.
• Source/destination check disabled on both interfaces.
• An IAM instance profile attached if the node will participate in an HA cluster — see Security for the permissions required by IP Failover or Route Failover.
• The SSH key pair for the region.

Step 2: Register via the EC2 Serial Console

Once the instance is running, open the EC2 Serial Console for the instance from the AWS console and log in to the Trustgrid local console utility. From there, initiate the remote registration process — the console will generate a short activation code that someone with Trustgrid portal access can use to license the node.

See Remote Registration for full instructions.

High Availability

High availability for a Trustgrid cluster in AWS is achieved using one of two failover mechanisms. Either mechanism can support L3 or L4 traffic patterns.

• IP Failover — Claims a secondary private IP on the active member’s LAN ENI. Does not require route-table changes.
• Route Failover — Updates AWS route-table entries to point overlay CIDRs at the active member’s ENI.

Use Case Tutorials

• HA L4 Cluster in AWS — Using the cluster IP on L4 connectors and services so the cluster presents a stable IP across member failover.
• HA Wireguard Cluster — Fronting Wireguard listeners with an AWS Network Load Balancer.